agentrisk

AgentRisk

Risk guardrails for AI trading agents. Your agent proposes; your policy decides.

AgentRisk sits in front of trade execution: it analyzes portfolio risk, checks each proposed trade against a policy you write, and manages that policy. The core is deterministic (same inputs, same verdict), transparent (policies are plain YAML you can read and edit), and fail-closed (invalid input or a missing policy blocks, never a silent pass).

AgentRisk never recommends trades and never executes them. A PASS means a trade did not break the rules you wrote, not that it is safe or profitable. See DISCLAIMER.md.

Quickstart

The fastest path for a Claude agent is the Claude Code plugin. It installs the Agent Skill and registers the MCP server in one step (via uvx, so there is nothing else to install):

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

For any other MCP client, register the server yourself:

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

Then ask questions in plain English and the agent translates them into three tool calls:

Tool	Question it answers	Returns
analyze_portfolio_risk	What risk am I holding?	Concentration, exposure, and policy-compliance report
check_trade_risk	Should this trade go through?	PASS / WARN / BLOCK with a one-line reason
generate_risk_policy	What are my rules?	A human-readable YAML policy (create, update, show)

The plugin path needs uv for uvx. See examples/claude_desktop.md for a two-minute Claude Desktop setup.

Agent Skill

For Claude agents, AgentRisk ships an optional Agent Skill that encodes the discipline the guardrail depends on: before any order reaches a broker, classify the trade, call check_trade_risk, respect the verdict, and record the result, in that order. The plugin above installs it with the server. To install just the skill:

• Claude Code or Claude Desktop: copy skills/agentrisk/ into ~/.claude/skills/.
• claude.ai: upload skills/agentrisk/SKILL.md as a skill.

The enforcement contract

AgentRisk returns advice. It cannot physically stop an order, so your integration must gate execution on the verdict:

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

If you call the broker regardless of the verdict, you have a logger, not a guardrail. See the integration guide.

Using the library directly

The three tools are also a pure Python library, with no network calls and no LLM in the core:

pip install agentrisk

Every parameter, return field, and error case is in the tool reference.

What it checks

• Concentration caps on single names, sectors, themes, and asset classes, evaluated on the simulated post-trade portfolio.
• Asset-class rules (allow, warn, or block) for crypto, options, and margin.
• Order sanity: max order size, minimum cash floor, insufficient-funds detection.
• Restricted symbols and data quality (stale snapshots warn, invalid ones block).

The policy reference covers every field and the safety behaviors: fail closed, exits are never trapped, only breach-worsening trades block, and the one-time bypass.

Documentation

Doc	Contents
Concepts	The mental model and the agent/AgentRisk division of labor
Architecture	The module layout and how a call flows through the core
Policy reference	Every policy field and the check behavior it drives
Tool reference	Parameters, outputs, and error cases for all three tools
CLI reference	The agentrisk command: policy, check, analyze
Integration guide	The enforcement contract, broker MCP pairing, audit log
Threat model	What AgentRisk can and cannot protect against
Classification data	The open taxonomy and how to contribute corrections

Roadmap

Next is deterministic stress scenarios, ETF look-through, and behavioral limits (v0.2), then options analytics, broker snapshot adapters, short positions, and multi-currency (v0.3). Trade recommendations, signals, execution, and telemetry are permanently out of scope. See the milestones.

Contributing

Classification-data corrections and new deterministic checks are especially welcome. See CONTRIBUTING.md, and keep the core pure: no network, no LLM calls, no hidden state.

License

MIT. See LICENSE.