io.github.trycoin-ai/agentrisk
Risk guardrails for AI trading agents. Your agent proposes; your policy decides.
Open source Open in the app JSON README (API)
About
Risk guardrails for AI trading agents. Your agent proposes; your policy decides.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- trycoin-ai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Stars
- 2
- Last push
- 2026-08-16T23:15:28Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:35
- Updated
- 2026-08-29 04:01:35
- Origin id
io.github.trycoin-ai/agentrisk
README
# AgentRisk
[](https://github.com/trycoin-ai/agentrisk/actions/workflows/ci.yml)
[](https://pypi.org/project/agentrisk/)
[](pyproject.toml)
[](LICENSE)
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](DISCLAIMER.md).
## Quickstart
The fastest path for a Claude agent is the Claude Code plugin. It installs the Agent
Skill and registers the [MCP](https://modelcontextprotocol.io) server in one step
(via `uvx`, so there is nothing else to install):
```text
/plugin marketplace add trycoin-ai/agentrisk
/plugin install agentrisk@agentrisk
```
For any other MCP client, register the server yourself:
```json
{
"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](https://docs.astral.sh/uv/) for `uvx`. See
[examples/claude_desktop.md](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:
```python
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](docs/integration-guide.md).
## Using the library directly
The three tools are also a pure Python library, with no network calls and no LLM in
the core:
```bash
pip install agentrisk
```
Every parameter, return field, and error case is in the
[tool reference](docs/tool-reference.md).
## 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](docs/policy-reference.md) 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](docs/concepts.md) | The mental model and the agent/AgentRisk division of labor |
| [Architecture](docs/architecture.md) | The module layout and how a call flows through the core |
| [Policy reference](docs/policy-reference.md) | Every policy field and the check behavior it drives |
| [Tool reference](docs/tool-reference.md) | Parameters, outputs, and error cases for all three tools |
| [CLI reference](docs/cli.md) | The `agentrisk` command: `policy`, `check`, `analyze` |
| [Integration guide](docs/integration-guide.md) | The enforcement contract, broker MCP pairing, audit log |
| [Threat model](docs/threat-model.md) | What AgentRisk can and cannot protect against |
| [Classification data](docs/classification-data.md) | 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](https://github.com/trycoin-ai/agentrisk/milestones).
## Contributing
Classification-data corrections and new deterministic checks are especially welcome.
See [CONTRIBUTING.md](.github/CONTRIBUTING.md), and keep the core pure: no network,
no LLM calls, no hidden state.
## License
MIT. See [LICENSE](LICENSE).
<!-- mcp-name: io.github.trycoin-ai/agentrisk -->