# Agent integration guide — structure

## 1. Safety contract

Agents begin in read-only mode. They must not sign, broadcast, deploy, spend, set `pilotReady`, activate a route, mutate a cap, enroll a partner, or submit a governance proposal from this guide. Version is explicit; V2 is the default for writes.

## 2. Required configuration (all blocked initially)

- Chain/RPC and finality policy
- Verified manifest reference, target ABI, and code hash
- Explicit protocol version (`v2` default; `v3` only after gate completion)
- Approved read endpoint/method allowlist
- Data classification, purpose, evidence-reference policy, and retention handling
- Rate limits, retry behavior, error handling, and human escalation contact

## 3. Read flow

1. Fetch manifest and verify schema/status; reject if `pilotReady` is true unexpectedly or a required field is missing.
2. Resolve only verified read targets and ABI methods; record chain/block/finality/source error state.
3. Present version/status labels faithfully. Never turn missing data, an RPC error, or an unverified address into a zero/healthy result.
4. Return minimal data. Redact/separate sensitive evidence and never copy it into on-chain/public metadata.

## 4. Write-intent handoff (not execution)

When a user asks for a write, the agent may prepare a human-review packet containing exact version, action class, manifest reference, proposed target/method/arguments, maximum-loss/cap decision reference, privacy classification, and rollback impact. It must then stop. The designated human/governance process supplies approvals and executes separately.

## 5. V2/V3 migration behavior

Show V2 position/withdrawal information first. Do not combine a V2 withdrawal with V3 funding. Require a separate explicit V3 selection, current gate evidence, and post-state reconciliation. On any failure, preserve the V2 path and escalate.

## 6. Tests to implement after integration

- Read-only requests cannot invoke a mutating ABI method.
- Default write version is V2; V3 needs an explicit selection.
- Unknown/missing finality or data-source error fails closed.
- PII/secret patterns are rejected from on-chain/public fields.
- A proposal packet cannot include more than one action class.
- V2 route and withdrawal regression fixtures remain green.
