Skip to content

INTEGRATIONS.md

Latest commit

 

History

History
96 lines (72 loc) · 5.58 KB

INTEGRATIONS.md

File metadata and controls

96 lines (72 loc) · 5.58 KB
Raw

Integrating AgentWorks

AgentWorks is the trust layer for agent-to-agent commerce: settlement, decentralized adjudication, and wallet-scoped spend-safety — infrastructure other agent frameworks build on, not a marketplace you have to join.

You don't adopt AgentWorks wholesale. You pick the pillar you need and integrate just that. There are three integration paths, from lightest to fullest. The Virtuals/ACP adapter (its own repo) is the reference implementation of path (a).

(a) Evaluation-as-a-service — the committee verdict

Use when another protocol already has escrow/settlement and just needs a trust-minimized verdict on a deliverable. Instead of a single evaluator (one point of trust), AgentWorks runs an M-of-N committee of independent LLM personas and returns one quorum decision. To the caller it looks like one confident evaluator.

The entire contract is one HTTP call (frozen):

POST {AGENT_API}/committee/verdict
  body : { "spec": string, "deliverable": string, "quorum"?: number }
  200  : { "accept": bool, "approve": int, "reject": int, "quorum": int,
           "reasons": [ { "member": string, "accept": bool, "reason": string } ] }

accept: true means the committee approves (pay the provider); false means reject (refund). Gate it with VERDICT_TOKEN if you expose it publicly. No wallet, no chain, no AgentWorks escrow involved — pure adjudication you map onto your own settlement.

Reference integration: the Virtuals/ACP adapter maps accept onto Virtuals ACP's session.complete / session.reject. Any framework integrates the same way — the endpoint is framework-neutral.

(b) Full-rail participant — settlement + adjudication on the AgentWorks escrow

Use when you want the whole rail: on-chain escrow, a sealed commit-reveal accept race (MEV-resistant), an M-of-N committee vote, a dispute window, and staked disputes escalating to a decentralized arbiter (UMA OOv3). Everything is non-custodial — you sign every transaction with your own wallet; AgentWorks never holds keys.

Two equivalent ways in:

1. The HTTP calldata rail (agents/server.py, /marketplace/*). Each endpoint returns unsigned calldata {contract_address, chain_id, steps:[{function, calldata, note}]} that you sign with any EVM wallet:

  • GET /marketplace/post-calldata — open + fund a job (createJob → approve → fund), salt-bound spec hash.
  • POST /marketplace/jobs — publish the human-readable listing (verified to reproduce the on-chain specHash).
  • GET /marketplace/jobs/{id}/calldata — sealed commit-reveal accept (provider).
  • POST /marketplace/jobs/{id}/deliver — store the deliverable on Irys + get submitWork calldata.
  • GET /marketplace/jobs/{id}/vote-calldata — a committee member casts a vote.
  • GET /marketplace/jobs/{id}/finalize-calldata · /fund-calldata · /refund-calldata.
  • GET /marketplace/jobs?status=open|all, /marketplace/jobs/{id}, /marketplace/jobs/{id}/committee — chain-authoritative discovery.

2. The MCP server (agents/mcp_server.py) — the same rail as tools for any MCP-capable agent (Claude Desktop/Code, etc.). An operator wires their own CAW wallet via env (MCP_WALLET_ID / MCP_API_KEY / MCP_ADDRESS / MCP_ROLE); the api_key never leaves the process, signing goes through the operator's TSS node. Tools: post_job, accept_job (commit+reveal), deliver_work, cast_vote, finalize, dispute, plus read-only discovery. See docs/MCP.md.

The escrow lifecycle either path drives: createJob(committee, quorum) → fund → commitAccept → revealAccept → submitWork → castVote ×N → Resolved (tentative) → finalize | dispute → resolveDispute | resolveTimeout | claimRefund. Contract ABIs + addresses: contracts/README.md; the calldata builders are agents/escrow_v4.py.

(c) Spend-safety — Pact-bounded wallets (orthogonal, additive)

Use regardless of whose escrow settles the job. ACP escrow (or any escrow) protects a job's funds; it does not bound what an agent's wallet can do. AgentWorks wraps each agent's wallet in a Cobo CAW scoped Pact — infrastructure-enforced spend limits the agent (or a prompt-injection) cannot exceed.

The role templates (agents/pacts.py) are the literal authority boundaries:

  • client_escrow_pact — may only call the escrow + USDC contracts, capped tx/24h.
  • provider_pact / evaluator_pact — may call the escrow (accept/deliver / castVote) but USDC is excluded — they can act but can never move escrowed funds.
  • disputer_pact — escrow + the bond currency (approve-only), for staked disputes.

Bind one on the operator's own wallet (via the MCP onboard tool or the Cobo app); enforcement then lives in CAW, not in application code. This is the wedge no one else in the ecosystem has — it composes with any of the paths above.

Which path do I want?

You have… You want… Path
Your own escrow/settlement A trust-minimized verdict on deliverables (a) verdict endpoint
Agents that need to transact The full on-chain settlement + dispute rail (b) calldata rail / MCP
Any agent handling funds Infra-enforced wallet spend limits (c) CAW Pact

Paths compose: a Virtuals agent can take a verdict from (a) and run its wallet under (c). Start with the one that removes your biggest trust assumption.

(A packaged TS/Python SDK + a versioned/OpenAPI'd API are on the roadmap; today these HTTP + MCP + ABI surfaces are the integration contract.)