---
title: "Agent Framework"
description: "MCP tools, decision framework, and natural language interface for autonomous LLM operation."
---

The Agent Framework is the interface between the LLM and the fund. It provides the MCP tools for every autonomous action, a decision framework with guardrails, and a natural language interface for complex operations.

## MCP Tool Expansion

The existing 44 MCP tools cover trading operations. The autonomous layer adds fund management tools:

### Fund Management Tools

| Tool | Description |
|---|---|
| `fund_status` | NAV, returns, risk metrics, capital available |
| `fund_report` | Generate PDF/CSV fund report |
| `allocate_capital` | Move capital between strategies |
| `fund_drawdown` | Current drawdown vs. limits |

### Strategy Management Tools

| Tool | Description |
|---|---|
| `deploy_strategy` | Launch strategy from template + parameters |
| `stop_strategy` | Gracefully stop a running strategy |
| `list_strategies` | All strategies with health, P&L, state |
| `promote_strategy` | Move from staging to live |
| `scale_strategy` | Adjust capital allocation |
| `ab_test` | Start A/B test between two strategy variants |

### Research Tools

| Tool | Description |
|---|---|
| `scan_opportunities` | Scan markets, return ranked by fitness |
| `research_market` | Deep analysis of a single market |
| `backtest_hypothesis` | Backtest a strategy idea, return results |
| `resolution_status` | Check resolution status of active markets |
| `market_universe` | Current universe with fitness scores |

### Risk Tools

| Tool | Description |
|---|---|
| `risk_dashboard` | Current VaR usage, limits, correlations |
| `stress_test_fund` | Run fund-level stress scenarios |
| `risk_budget_status` | Per-strategy risk budget utilization |
| `execution_quality` | Fill rates, slippage, adverse selection |

### Explainability Tools

| Tool | Description |
|---|---|
| `fund_explain` | Full fund state: overview, regime, risk, strategies, decisions, alerts, hypotheses, alpha factors |
| `fund_explain_strategy` | Single strategy deep dive: performance, execution, decay, promotion, hypotheses |
| `fund_explain_risk` | Full risk analysis: tail risk, Greeks, correlations, stress, VaR, limits, attribution |
| `fund_full_snapshot` | Everything in one call |

### Intelligence Tools

| Tool | Description |
|---|---|
| `fund_hypotheses` | Active trading hypotheses with lifecycle state, confidence, edge estimates |
| `fund_regime` | Current market regime with confidence and recent transitions |
| `fund_alpha_model` | Alpha model factor report: per-factor ICs, significance, weights |
| `fund_decisions` | Recent autonomous decisions with reasoning, confidence, outcome |
| `fund_decay_report` | Alpha decay tracking: edge erosion, half-life, retirement recommendations |

### Operations Tools

| Tool | Description |
|---|---|
| `fund_alerts` | Recent alerts with counts by category |
| `fund_ledger` | Double-entry journal entries, balance sheet, income statement |
| `fund_promotion_status` | Strategy promotion stages and history |

## Decision Framework

Every autonomous decision goes through guardrails to prevent runaway behavior.

### Confidence Thresholds

Different actions require different minimum confidence levels:

| Action | Min Confidence | Rationale |
|---|---|---|
| Add market to universe | 0.3 | Low-stakes, just tracking |
| Deploy strategy (staging) | 0.5 | Paper mode, no capital at risk |
| Promote to live (small capital) | 0.7 | Real money, but limited |
| Scale up capital | 0.8 | Increasing exposure |
| Activate kill switch | 0.5 | Better safe than sorry |
| Retire strategy | 0.6 | Reversible, can redeploy |

### Escalation Rules

When the LLM should escalate to a human:

| Condition | Action |
|---|---|
| Trade notional > threshold | Route to approval workflow |
| Confidence < minimum for action | Log decision, wait for human |
| Unusual market conditions | Alert + pause |
| Multiple strategy failures | Alert + reduce exposure |
| Fund drawdown approaching limit | Alert + require human confirmation |

### Rate Limiting

Prevent runaway decision loops:

```python
# Configure rate limits
decision_limits = DecisionLimits(
    max_deploys_per_hour=3,
    max_capital_changes_per_day=10,
    max_kill_switch_activations_per_day=2,
    cooldown_after_loss=300,  # 5 min cooldown after a strategy is retired
)
```

### Decision Audit Trail

Every autonomous decision is logged with full reasoning:

```json
{
  "decision_id": "d-abc123",
  "timestamp": "2026-03-13T14:30:00Z",
  "action": "deploy_strategy",
  "parameters": {
    "template": "market_maker",
    "market": "will-x-win",
    "capital": 5000
  },
  "reasoning": "Market has 0.87 fitness score, LLM forecast edge of 0.08, backtest Sharpe 1.6 over 45 trades, robustness p=0.02",
  "confidence": 0.75,
  "outcome": "deployed",
  "strategy_id": "s-def456"
}
```

## Natural Language Interface

The LLM translates natural language commands into tool calls:

| Natural Language | MCP Tool(s) |
|---|---|
| "Deploy a market maker on the top 5 political markets" | `scan_opportunities` -> `deploy_strategy` x5 |
| "Reduce crypto exposure by 50%" | `list_strategies` -> `scale_strategy` for each |
| "What's our biggest risk right now?" | `risk_dashboard` + `correlation_matrix` |
| "Why did we lose money yesterday?" | `fund_report` + `execution_quality` + `decision_log` |
| "Backtest momentum on election markets" | `scan_opportunities` -> `backtest_hypothesis` |

## Dry-Run Mode

For maximum safety, the LLM can operate in dry-run mode where it proposes actions and a human approves them in batches:

```python
# Configure operating mode
agent = AutonomousAgent(
    fund=fund,
    mode="dry_run",  # "dry_run" | "supervised" | "autonomous"
)

# LLM proposes actions
proposals = agent.propose()
# [
#   {"action": "deploy_strategy", "params": {...}, "reasoning": "..."},
#   {"action": "scale_strategy", "params": {...}, "reasoning": "..."},
# ]

# Human reviews and approves
agent.approve(proposals[0].id)
agent.reject(proposals[1].id, reason="too concentrated")
```

### Operating Modes

| Mode | Behavior |
|---|---|
| **Dry-run** | LLM proposes, human approves each action |
| **Supervised** | LLM executes low-risk actions, escalates high-risk |
| **Autonomous** | LLM executes all actions within guardrails |
