agentrisk

AgentRisk

为 AI 交易 Agent 提供风险护栏。Agent 提议，策略决策。

AgentRisk 位于交易执行流程之前：它会分析投资组合风险，依据你编写的策略检查每笔 拟议交易，并管理该策略。其核心具备确定性（输入相同，判定相同）、透明性（策略是 可供阅读和编辑的纯 YAML），并且默认拒绝（输入无效或缺少策略时会阻止交易，绝不 会悄然放行）。

AgentRisk 绝不会推荐或执行交易。PASS 表示交易没有违反你编写的规则，并不 表示交易安全或有利可图。请参阅 DISCLAIMER.md。

快速开始

对于 Claude Agent，最快的方式是使用 Claude Code 插件。它只需一步即可安装 Agent Skill 并注册 MCP 服务（通过 uvx，无需安装 其他内容）：

/plugin marketplace add trycoin-ai/agentrisk
/plugin install agentrisk@agentrisk

对于其他 MCP 客户端，请自行注册该服务：

{
  "mcpServers": {
    "agentrisk": {
      "command": "uvx",
      "args": ["--from", "agentrisk[mcp]", "agentrisk-mcp"]
    }
  }
}

然后用日常语言提问，Agent 会将问题转换为三次工具调用：

工具	回答的问题	返回内容
analyze_portfolio_risk	我当前承担着哪些风险？	集中度、风险敞口和策略合规报告
check_trade_risk	这笔交易应该执行吗？	PASS / WARN / BLOCK 及一行原因说明
generate_risk_policy	我的规则是什么？	人类可读的 YAML 策略（创建、更新、显示）

插件方式需要 uv 才能使用 uvx。两分钟即可完成 Claude Desktop 设置，详见 examples/claude_desktop.md。

Agent Skill

对于 Claude Agent，AgentRisk 提供可选的 Agent Skill，其中包含护栏所依赖的操作规范： 在任何订单送达经纪商之前，依次对交易分类、调用 check_trade_risk、遵循判定结果， 并记录结果。上述插件会同时安装该 Skill 和服务。若只需安装 Skill：

• **Claude Code 或 Claude Desktop：**将 skills/agentrisk/ 复制到 ~/.claude/skills/。
• **claude.ai：**将 skills/agentrisk/SKILL.md 上传为 Skill。

执行约定

AgentRisk 会给出建议，但无法从物理上阻止订单，因此你的集成必须依据判定结果来控制执行：

result = check_trade_risk(portfolio, trade)
if not result.proceed:
    refuse(result.summary)              # BLOCK: never call the broker
elif result.acknowledgements_required:
    confirm_with_user(result)           # WARN: surface warnings first
else:
    execute(trade)                      # PASS

如果无论判定结果如何，你都会调用经纪商接口，那么你实现的只是记录器，而不是护栏。 请参阅集成指南。

直接使用库

这三个工具也可作为纯 Python 库使用，核心部分不会发起网络调用，也不使用大模型：

pip install agentrisk

所有参数、返回字段和错误情况均收录在工具参考中。

检查内容

• 集中度上限：针对单个标的、行业、主题和资产类别进行检查，并根据模拟交易后的投资组合进行评估。
• 资产类别规则（允许、警告或阻止）：适用于加密货币、期权和保证金。
• 订单合理性：最大订单规模、最低现金余额、资金不足检测。
• 受限标的和数据质量（快照过时会触发警告，无效快照会阻止交易）。

策略参考涵盖所有字段和安全行为：默认拒绝、退出操作永不受阻、只有会加剧违规的交易才会被阻止，以及一次性绕过机制。

文档

文档	内容
概念	心智模型，以及 agent/AgentRisk 的分工
架构	模块布局，以及调用如何流经核心
策略参考	每个策略字段及其驱动的检查行为
工具参考	所有三个工具的参数、输出和错误情况
CLI 参考	agentrisk 命令：policy、check、analyze
集成指南	执行约定、代理 MCP 配对、审计日志
威胁模型	AgentRisk 能防护和无法防护的内容
分类数据	开放分类体系及如何贡献修正

路线图

接下来是确定性压力场景、ETF 穿透分析和行为限制 （v0.2），然后是期权分析、经纪商快照适配器、空头头寸和 多币种（v0.3）。交易建议、信号、执行和遥测 永久不在范围内。请参阅里程碑。

贡献

我们尤其欢迎修正分类数据和新增确定性检查。 请参阅 CONTRIBUTING.md，并保持核心纯粹：不联网、 不调用 LLM、不保留隐藏状态。

许可证

MIT。请参阅 LICENSE。