> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/reference/agents.md).

# Agents

Gotts agents are autonomous executors that handle multi-step DeFi workflows. Each agent is defined as a Markdown file with YAML frontmatter in `packages/safe/agents/`. Agents coordinate via a strict delegation DAG — no cycles allowed.

## Agent Catalog (25 Core Agents)

### Execution (3)

| Agent                  | Model | Terminal | Description                                                   |
| ---------------------- | ----- | -------- | ------------------------------------------------------------- |
| `trade-executor`       | opus  | No       | Multi-step swap execution with safety delegation              |
| `liquidity-manager`    | opus  | No       | Add/remove/rebalance concentrated liquidity positions         |
| `cross-chain-executor` | opus  | No       | Cross-chain swaps via ERC-7683 intents with bridge monitoring |

### Research (5)

| Agent                 | Model  | Terminal | Description                                         |
| --------------------- | ------ | -------- | --------------------------------------------------- |
| `pool-researcher`     | sonnet | Yes      | Pool analysis: TVL, volume, fees, VPIN, LVR         |
| `token-analyst`       | opus   | Yes      | Token due diligence with risk rating system         |
| `opportunity-scanner` | opus   | No       | Scan LP, arbitrage, and emerging pool opportunities |
| `portfolio-analyst`   | opus   | No       | Cross-chain portfolio valuation and composition     |
| `pnl-analyst`         | sonnet | Yes      | P\&L computation with cost basis attribution        |

### Strategy (2)

| Agent           | Model | Terminal | Description                                        |
| --------------- | ----- | -------- | -------------------------------------------------- |
| `lp-strategist` | opus  | No       | LVR-informed LP range optimization and backtesting |
| `risk-assessor` | opus  | Yes      | Independent 7-dimension risk evaluation            |

### Development (3)

| Agent                   | Model | Terminal | Description                                      |
| ----------------------- | ----- | -------- | ------------------------------------------------ |
| `hook-builder`          | opus  | No       | V4 hook generation, testing, and deployment      |
| `integration-architect` | opus  | No       | Architecture blueprints for protocol integration |
| `integration-advisor`   | opus  | No       | Code snippets and integration guidance           |

### Infrastructure (2)

| Agent                | Model  | Terminal | Description                                          |
| -------------------- | ------ | -------- | ---------------------------------------------------- |
| `safety-guardian`    | opus   | Yes      | Transaction validation, spending limits, simulation  |
| `wallet-provisioner` | sonnet | Yes      | Wallet provisioning, session keys, ERC-8004 identity |

### Economy (8)

| Agent                     | Model  | Terminal | Description                                               |
| ------------------------- | ------ | -------- | --------------------------------------------------------- |
| `treasury-manager`        | opus   | No       | Treasury operations: conversion, LP, compounding          |
| `token-deployer`          | opus   | No       | Token launch pipeline with CCA and V4 pools               |
| `identity-verifier`       | sonnet | Yes      | ERC-8004 identity and reputation verification             |
| `protocol-fee-seeker`     | opus   | No       | TokenJar monitoring and Firepit burn execution            |
| `competition-participant` | opus   | No       | Competition discovery, planning, and execution            |
| `agent-service-broker`    | opus   | No       | A2A capability matching and payment settlement            |
| `strategy-optimizer`      | opus   | No       | Two-loop strategy optimization with Bayesian tuning       |
| `yield-scout`             | opus   | No       | Multi-source yield aggregation and sustainability scoring |

### Real-Time (2)

| Agent              | Model  | Terminal | Description                                   |
| ------------------ | ------ | -------- | --------------------------------------------- |
| `market-monitor`   | sonnet | No       | Real-time price, volume, and TVL alerts       |
| `position-monitor` | sonnet | Yes      | LP position monitoring with range exit alerts |

## Model Assignments

| Model      | Count | Agents                                                                                                                                                                                                                                                                                                                                                         | Rationale                                                     |
| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **opus**   | 19    | trade-executor, liquidity-manager, cross-chain-executor, token-analyst, opportunity-scanner, portfolio-analyst, lp-strategist, risk-assessor, hook-builder, integration-architect, integration-advisor, safety-guardian, treasury-manager, token-deployer, protocol-fee-seeker, competition-participant, agent-service-broker, strategy-optimizer, yield-scout | Complex reasoning, multi-step workflows, safety evaluation    |
| **sonnet** | 6     | pool-researcher, pnl-analyst, wallet-provisioner, identity-verifier, market-monitor, position-monitor                                                                                                                                                                                                                                                          | Structured calculations, threshold comparisons, status checks |

## Terminal Nodes (8)

Terminal agents never delegate to other agents. They are leaf nodes in the delegation DAG and must independently produce their results using only MCP tools.

1. **safety-guardian** — Most critical. All write operations must pass through it. Independent transaction validation with spending limits ($10K/tx, $50K/session, $100K/day).
2. **risk-assessor** — Independent 7-dimension risk evaluation. Cannot be influenced by the requesting agent.
3. **wallet-provisioner** — Setup-only. Provisions wallets, session keys, and ERC-8004 identity.
4. **pnl-analyst** — Computation-only. P\&L reports with cost basis attribution.
5. **pool-researcher** — Research-only. Pool metrics, VPIN, LVR, fee/LVR ratio analysis.
6. **token-analyst** — Research-only. Token due diligence with SAFE/CAUTION/WARNING/DANGER rating.
7. **identity-verifier** — Verification-only. Three-registry deep inspection (Identity, Reputation, Validation).
8. **position-monitor** — Alert-only. Monitors LP positions, never executes transactions.

## Delegation DAG

The delegation graph is a verified DAG (directed acyclic graph). No cycles are permitted. Maximum delegation depth is 3.

```
Level 0 (Entry points — invoked by skills):
  trade-executor ──→ safety-guardian, risk-assessor
  liquidity-manager ──→ safety-guardian, risk-assessor, pool-researcher
  cross-chain-executor ──→ safety-guardian, risk-assessor, trade-executor

Level 1 (Strategy/Economy — delegate to execution + research):
  treasury-manager ──→ trade-executor, liquidity-manager, risk-assessor
  token-deployer ──→ safety-guardian, liquidity-manager
  protocol-fee-seeker ──→ trade-executor, safety-guardian, risk-assessor
  competition-participant ──→ token-deployer, liquidity-manager, trade-executor, hook-builder
  agent-service-broker ──→ identity-verifier, trade-executor
  strategy-optimizer ──→ risk-assessor
  yield-scout ──→ risk-assessor, trade-executor
  lp-strategist ──→ pool-researcher, risk-assessor
  opportunity-scanner ──→ pool-researcher, token-analyst, risk-assessor
  portfolio-analyst ──→ pool-researcher, token-analyst, pnl-analyst
  market-monitor ──→ risk-assessor, liquidity-manager, opportunity-scanner

Level 2 (Terminal — never delegate):
  safety-guardian, risk-assessor, wallet-provisioner, pnl-analyst,
  pool-researcher, token-analyst, identity-verifier

Self-Contained (no delegation, not invoked as delegate):
  hook-builder, integration-architect, integration-advisor, position-monitor
```

### Depth Examples

* `competition-participant` → `token-deployer` → `safety-guardian` (depth 2)
* `market-monitor` → `opportunity-scanner` → `pool-researcher` (depth 2)
* `competition-participant` → `token-deployer` → `liquidity-manager` → `safety-guardian` (depth 3, maximum)

## Composition Patterns

Agents compose into multi-step workflows. Key patterns verified in CI:

1. **Research-to-Trade**: opportunity-scanner → pool-researcher → risk-assessor → trade-executor → safety-guardian
2. **Autonomous LP Management**: lp-strategist → pool-researcher → liquidity-manager → safety-guardian
3. **P\&L Reporting**: portfolio-analyst → pnl-analyst (terminal)
4. **Token Launch Pipeline**: token-deployer → liquidity-manager → safety-guardian
5. **Cross-Chain Arbitrage**: opportunity-scanner → risk-assessor → cross-chain-executor → trade-executor → safety-guardian
6. **Yield Discovery and Rotation**: yield-scout → risk-assessor → trade-executor → safety-guardian
7. **Self-Improvement Loop**: pnl-analyst → strategy-optimizer → risk-assessor
8. **Order Flow Intelligence**: pool-researcher → risk-assessor → lp-strategist
9. **Real-Time Alert Response**: market-monitor → risk-assessor → liquidity-manager → safety-guardian
10. **Token Launch (Full CCA)**: token-deployer → safety-guardian + liquidity-manager → safety-guardian

## Safety Rules

* Every write operation routes through `safety-guardian` before broadcast
* All execution agents (trade-executor, liquidity-manager, cross-chain-executor) delegate to safety-guardian
* Terminal nodes never delegate — enforced by DAG validation in CI
* No agent delegates to itself
* Maximum delegation depth is 3
* No transitive trust: agents independently verify all inputs via MCP tools

## Agent File Format

Each agent is a Markdown file with YAML frontmatter:

```yaml
---
description: One-sentence description for tool selection
model: opus | sonnet
allowed-tools: mcp__gotts_safe__tool1, Task(subagent_type:agent-name)
---
```

The file body includes sections: Role, Expertise, Available MCP Tools, Workflow, Delegation Rules, and Safety Constraints.

## MCP Tools for Agent Inspection

Three MCP tools expose agent metadata without reading files:

| Tool                   | Profile | Description                                           |
| ---------------------- | ------- | ----------------------------------------------------- |
| `get_agent_registry`   | data    | All 25 agents with categories, tools, delegation info |
| `get_delegation_graph` | data    | Full DAG as node + edge list with depth per node      |
| `get_safety_summary`   | data    | Spending limits, compliance matrix, veto triggers     |