内容
AgentRisk
](https://github.com/trycoin-ai/agentrisk/actions/workflows/ci.yml/badge.svg)](https://github.com/trycoin-ai/agentrisk/actions/workflows/ci.yml)
[](pyproject.toml)
[](LICENSE)
用于 AI 交易代理的风险防护。您的代理提出建议；您的策略做出决定。
AgentRisk 是一种风险基础设施，位于交易执行之前。它分析投资组合风险，验证拟议交易是否符合个人风险策略，并管理该策略。它有一条硬性底线：
> AgentRisk **从不推荐交易，从不执行交易**。它是一种防护措施，而不是交易机器人。`PASS` 表示交易并未违反您编写的规则 *，而并不意味着交易安全或盈利*。请参阅 [DISCLAIMER.md](DISCLAIMER.md)。
AgentRisk 由三个部分组成：一个纯 Python 库（无网络调用，无 LLM 调用，无 API 密钥），一个薄 [MCP](https://modelcontextprotocol.io) 服务器来包装它，以及一个可选的 [Agent Skill](#agent-skill)，用于教导 Claude 代理何时以及如何使用它们。任何支持 MCP 的代理（Claude 或您自己的）都可以调用三个工具：
| 工具 | 问题答案 | 返回值 |
| --- | --- | --- |
| `analyze_portfolio_risk` | 我持有多少风险？ | 集中度、暴露和策略合规性报告 |
| `check_trade_risk` | 该交易是否应该通过？ | `PASS` / `WARN` / `BLOCK`，附带一行原因 |
| `generate_risk_policy` | 我的规则是什么？ | 可读的 YAML 策略（创建、更新、显示） |
## 演示
每个工具都可以通过捆绑的 `agentrisk` CLI 从终端使用。
**在交易执行前检查交易。** 正常的购买通过，超限购买被阻止，允许用户批准的一次性绕过并记录。
**分析投资组合风险。** 按行业和主题的集中度、暴露情况，以及针对您的策略的合规性。
**创建风险策略。** 将普通规则转换为版本化的、可读的策略。
自己试试：
```bash
git clone https://github.com/trycoin-ai/agentrisk.git && cd agentrisk
pip install -e .
agentrisk policy init --preset balanced --max-position 25 --block crypto --block margin --warn options
agentrisk check buy 20 NVDA --at 120 --portfolio examples/sample_portfolio.json
agentrisk analyze examples/sample_port --focus tag:ai## 为什么
代理交易比代理风险管理发展得更快。每个可以下订单的代理都需要一个策略门控在前面。AgentRisk 旨在成为该门控的无聊、确定性、可检查的默认实现：
- **确定性。** 相同的快照，相同的交易，：每次都是字节相同的判决。核心中没有 LLM，因此都经过单元测试、金色测试和属性测试。
- **透明。** 策略是您可以阅读和手动编辑的 YAML。每个判决都会列出运行的检查、限制和确切的数字。
- **诚实 未分类的持有量时的数据和 v1 限制在输出本身中报告。判决本质上是咨询性的，文档明确说明了这一点。
## 安装
AgentRisk 从此存储库安装（后续将发布 PyPI 版本）：
```bash
# 直接从 GitHub
pipagentrisk[mcp] @ git+https://github.com/trycoin-ai/agentrisk.git"
# 或从检出
git clone https://github.com/-ai/agentrisk.git
cd agentrisk
pip install -[mcp]" # 删除 [mcp] 仅限库
```
需要 Python 3.10+。
##入门
```python
from agentrisk import generate_risk check_trade_risk
# 1. 创建策略。在代理中，代理将用户的言字段。
generate_risk "create", preset="balanced",
fields={"limits": {"max_single_position_pct":},
"asset_rules":": "warn", "margin": "block", "cryptoblock"}},
confirm)
# 2. 在执行拟议交易前检查import json
portfolio = json.load(open("examples/sample_port")) # NVDA 占 28.6%
result = check_trade_risk(
portfolio,
{"action": "buy", "symbol": "NVDA", "quantity": 20,
"order_type": "market", "estimated_price": 120},
)
# 3. 根据判决阻止执行。这是使其成为防护措施的步骤。
if not result.proceed:
print(result.summary)
# 被 AgentRisk 阻止：此交易会将 NVDA 增加到您投资组合的 31.4%，高于您的 25% 单一。
```
反事实销售减少了头寸并通过：
```text
风险。此销售减少了 NVDA 占您投资组合的 28.6% 至 20%，使其重新低于您的% 限制。
```
投资组合快照是一个普通的 JSON 对象；您提供头寸和价格，AgentRisk 不获取任何内容：
```json
{
"as_of": "2026-07-01T15:30:00Z",
cash": 8000,
"positions": [
{"symbol": "NVDA", "quantity": 200, " 120},
{"symbol": "MSFT", " 25, "price": 400}
]
}
```
使用样本投资组合运行完整的提出/检查/门控循环：
```bash
python examples/agent_loop.py
```
## 与 Claude Desktop 或任何 MCP一起使用
注册服务器并用普通英语提问；代理将问题转换为结构化工具调用。
```json
{
"mcpServers": {
"agentrisk": {
"commandagentrisk-mcp"
}
}
}
```
[examples/claude_desktop.md](examples/claude.md) 以了解两分钟设置，以及 [docs/integration-guidedocs/integration-guide.md) 以将 AgentRisk 与经纪人 MCP 服务器配在交易执行前检查交易。
## Agent Skill
对于 Claude 代理，AgentRisk 可选的 Agent Skill编码了防护措施所依赖的纪律：在任何订单到达人之前，分类拟议交易，调用 `checkisk`，尊重判决结果，并记录结果，按此顺序很薄且有解；工具文档字符串详细信息。
获取技能和 MCP 服务器的最快方法是 Claude Code，它也注册了服务器 `uvx`安装其他内容）：
```text
/plugin marketplace-ai/agentrisk
/plugin install agentriskrisk
```
或仅安装技能：
- **Claude Code 或 Claude Desktop：** 将 `skills/agent复制到 `~/.claude/skills/`，使其位于/.claude/skills/agentrisk/SKILL.md`。
- **claude.ai：** 上传 `skills/agentrisk/SKILL.md` 作为技能。
插件路径需要 [uv](https://docs.astral.sh/uv/) 安装以提供 `uvx`。
## 执行合同
AgentRisk 返回建议。它无法物理阻止订单，因此您的集成必须根据判决阻止执行：
```python
result = check_trade_risk(portfolio, trade)
if not result.proceed:
refuse(result.summary # BLOCK：永远不要调用经纪人 result.acknow_required:
confirm_with_user(result) # WARN：首先显示警告
else:
ade) #```
如果您无论判决调用经纪人拥有一个日志记录器措施。详细信息请参阅 [](docs/integration## 它检查的内容（v1）
- **集中度上限。单一头寸，按行业和资产类别划分，在模拟后交易投资进行评估。
-类别规则。** 允许、警告或阻止加密货币、期权和保证金。
健全性。**大小（百分比和绝对值）、最低现金储备、资金不足检测。
- **受限符号。** 永远和警告列表。
-。** 过时快照警告；无效快以阻止。
值得了解：
- **。** 没有策略或会产生 BLOCK，永远不会是无声的通过。
- **出口从不被困。** 销售永远不会被集中度或资产类别规则阻止，即使策略阻止购买该资产。
- **只有违反加剧的交易才会阻止。** 如果头寸已经超过其上限，则减少违规的交易会通过，并附有说明。
- **一次性绕过，非无。** 人类可以通过_trade_risk(override=[...])` 批准阻止的交易，无需更改策略。阻止分为多个级别调限制直接绕硬性禁止引导您策略；可行性绕过），并且每次都会记录。
##| 文档 | 内容 |
| --- |
| [概念](docs/concepts.md) | 思维模型和代理/AgentRisk 分工 |
| [架构](docs/architecture.md) | 模块布局和调用核心流程 |
| [策略参考](docs/policy-reference.md每个策略字段和驱动检查行为 |
| [](docs/tool-reference.md) | 参数、输出和工具的错误情况 |
| [CLI 参考](docs/cli.md) | `agentrisk` 命令：`policy`、`check`、`analyze` |
| [集成指南](docs/integration-guide.md) | 执行合同、经纪人 MCP 配对、审计日志 |
| [威胁模型](docs/threat-model.md) | AgentRisk 可以和不能保护的内容 |
| [分类数据](docs/classification-data.md) | 开放分类法以及如何贡献更正 |
## 路线图
- **v0.2**：确定性压力情景（“科技 -20%”）、重复风险检测的 ETF 、基于审计日志的行为限制（最大交易次数、周转率）。
- **v0.：期权分析（名义价值、最大损失 delta）、只读经纪人快照适配器的可选包、空头头寸、多币- **永远不会**：交易推荐、信号、遥测。
## 欢迎贡献，特别是分类正和新的确定性检查。参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。请保持核心纯净：无网络，无 LLM 调用，无隐藏状态。
## 许可证
MIT。参阅 [LICENSE](LICENSE)。
