# agentOps

> agentOps is a control plane for AI agents that spend money and act on
> external systems. It sits between your agent and the outside world:
> policy checks before an action runs, payment controls (x402 USDC) before
> a payment settles, human approval when policy requires it, and an audit
> trail after. You reach it as an MCP server over Streamable HTTP.

This file is written for an agent (or the code that configures one), not a
human. If you are an LLM or an agent framework reading this cold, follow
the Quickstart below in order — it is the complete, minimal path to a
working connection. Do not guess endpoint shapes or invent actions; the
runtime contract you fetch in Step 2 is the authoritative, current list.

## Quickstart

1. **Get a connection.** Prefer one of these (payment access starts **disabled**
   until a human funds/enables it):
   - **Phase 0 (operator paste):** A human issues MCP URL + bearer from the
     console (Agents → Connections) and pastes them into your MCP config.
   - **Phase 1 (invite):** If you were given an invite token, redeem it:
     `POST {API}/v1/agent-join/invite/redeem` with JSON
     `{ "token": "<invite>", "agent_name": "<optional>" }` → response
     `join.mcp_url` + `join.credential`.
   - **Phase 3 (open join):** Only if the deployment enabled open join
     (`GET {API}/v1/agent-join/open/status` → `open_join.enabled`). Then
     `POST {API}/v1/agent-join/open` with optional `{ "agent_name": "..." }`.
   `/llms.txt` never mints secrets itself. If none of the above apply, stop
   and ask a human for a credential or invite.
2. **Connect and onboard.** Open an MCP session against the URL from step 1
   (Streamable HTTP transport, `Authorization: Bearer <credential>` on
   every request), then call the `agentops.onboard` tool with no
   arguments. Its response is the **authoritative, versioned runtime
   contract** for your connection right now: which actions exist, which
   fields each one needs, and worked examples for each. Read that
   response, not this file, for the current action catalog — it is
   generated from the same policy action registry your requests are
   checked against, so it cannot drift from what's actually enforced.
3. **Check before you act.** For an external HTTP/API call or a tool call
   specifically, call `agentops.operation_check` — it is the same
   evaluation as `agentops.policy_check` scoped to exactly those two
   action types, so prefer it there; fall back to the more general
   `agentops.policy_check` for any other action the contract lists. You
   will get back one of: allowed (proceed), denied (stop, do not retry
   the same request), or an `approval_id` (a human must approve — poll
   `agentops.approval_status` for that id, waiting at least 2 seconds
   between polls and backing off further — e.g. doubling up to a ~30
   second cap — rather than polling in a tight loop; once it reports
   `approved`, call `agentops.approval_consume` immediately before you
   act — consuming is one-time and must happen right before, not stored
   for later).
4. **Do the governed thing.** For a payment to an external merchant, call
   `agentops.payment_x402` directly — it applies policy and payment
   controls itself and executes the payment; you do not need a separate
   policy_check first for that one call; it is documented in the contract
   as combining both. To pay **another agent in your own fleet** for a
   resource it serves, call `agentops.payment_intra_fleet` instead — it
   settles by drawing down your standing Permit2 delegation rather than
   Circle's x402 rails, is bounded by your delegation ceiling and treasury
   solvency rather than a policy check, and is **not idempotency-key
   safe**: do not retry it blindly after a timeout or crash, confirm the
   payment did not already land first. For a plain external HTTP/API
   request or a tool call, do the request only after policy_check clears it.
5. **Optional publish / on-chain identity (Phase 2).** After you have a
   credential, call `agentops.publish` with your public endpoint URL to list
   yourself (same as console Publish). Call `agentops.identity_register`
   only after a human has enabled payment access so an Arc wallet exists;
   otherwise it fails closed. Use `agentops.identity_status` to read the
   current ERC-8004 record.
6. **Record what happened, if not already implied.** `agentops.activity_record`
   and `agentops.operation_record` let you log completed non-financial
   actions for operator visibility when you took an action that wasn't
   itself an agentOps-mediated call.

## Tools (fetch the live list from `agentops.onboard`; names are stable)

- `agentops.onboard` — the runtime contract. Call first, no arguments.
- `agentops.policy_check` — evaluate an action against policy before doing it.
- `agentops.payment_x402` — execute a governed x402 USDC payment to an external merchant.
- `agentops.payment_intra_fleet` — pay another agent in your fleet via a Permit2 drawdown; not idempotency-key safe.
- `agentops.approval_status` — poll a pending human approval by id.
- `agentops.approval_consume` — consume an approved one-time approval, immediately before acting on it.
- `agentops.operation_check` — evaluate a non-financial action (tool call, external request) before doing it.
- `agentops.operation_record` — record a completed non-financial action.
- `agentops.activity_record` — record a concise activity event for operator visibility.
- `agentops.publish` — publish your public endpoint URL into marketplace metadata.
- `agentops.identity_status` — read ERC-8004 identity status on Arc.
- `agentops.identity_register` — register ERC-8004 identity (requires Arc wallet / payment access).

## Join HTTP APIs (no MCP credential yet)

- `POST /v1/agent-join/invite/redeem` — Phase 1 invite → `{ join: { mcp_url, credential, ... } }`
- `GET /v1/agent-join/open/status` — whether Phase 3 open join is enabled
- `POST /v1/agent-join/open` — Phase 3 open register (gated + rate-limited; payment off)

## What NOT to do

- Do not retry a `denied` policy decision with reworded arguments to see if
  it passes — it will not, and it looks like an attempt to route around
  governance.
- Do not consume an approval and then wait — consume it immediately before
  the action it authorizes.
- Do not call `agentops.payment_x402` speculatively to "check" a price or
  availability — it executes a real payment. Use `agentops.policy_check`
  or read the resource without payment first if you need to know terms.
- Do not hardcode the action catalog from this file or any other static
  doc — always read it from `agentops.onboard`'s live response.
- Do not retry `agentops.payment_intra_fleet` after a timeout or crash
  without first checking whether the payment already landed — unlike
  `agentops.payment_x402`, it has no idempotency key.

## Further reading

Public URLs on the AgentOps web origin (fetch these cold):

- `/llms.txt` — this file (canonical agent cold-start).
- `/skill.md` — longer step-by-step walkthrough with worked examples.
- `/` with `?audience=agent` — human landing page in Agent mode (structured
  summary of the same path).

For operators / implementers in the repo:

- `apps/mcp/examples/` — Google ADK example client for the MCP connection.
- `docs/batch-settlement-binding.md` — Permit2 payment rail binding.