@agenticprimitives/a2a

Part of Agentic Primitives — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. Developer kit · All packages

Agent-to-agent calls gated by the same delegations as everything else. Agent discovery and identity are being settled right now — ERC-8004 went to mainnet, agent naming services launched, agent cards are becoming the lingua franca of discovery. What none of that settles is authority: when agent A sends agent B a task, what proves A was allowed to ask, for exactly that skill, within exactly those limits? This package answers with the agenticprimitives delegation primitive — the same EIP-712, caveat-constrained, on-chain-revocable grant that authorizes a web session, an MCP tool, and an on-chain spend. One delegation model, everywhere; A2A is not the exception.

Part of agenticprimitives — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.

Concretely: an async, delegation-authorized Agent-to-Agent task transport. Any claimed agent sends any other an asynchronous, delegation-scoped task and collects the result by poll, push, or stream. Built on the @agenticprimitives/fulfillment Task substrate; specified in spec 269.

What ships

All five implementation waves have landed:

• Task runtime core — newTaskRecord, applyTransition (fail-closed via canTaskTransition), dispatchTask, the TaskStore port + an in-memory reference implementation, and the SkillHandler contract. Unknown skill → rejected, never silently dropped.
• Delegation-auth gate — authorizeA2aMessage: delegate === requester, timestamp window, target + skill scoping via caveats, on-chain isRevoked + ERC-1271 injected fail-closed, signed message, single-use message-id. Plus buildA2aGrantCaveats and hashA2aMessage.
• Agent surface — createA2aAgent (message/send → authorize + persist; tasks/get + tasks/cancel with party auth; alarm-driven processDue; agent card) + JSON-RPC 2.0 handlers (dispatchA2aRpc / handleA2aRpcBody) + the A2aWireAdapter client over an injected transport.
• Vault body residency + signed push — message and artifact bodies live in the assignee's vault; only hashes/refs appear in task state. Terminal results are delivered as signed push envelopes (deliverPush / verifyPushEnvelope) with bounded retry, or streamed via SSE framing, or polled via tasks/get.
• Two-agent acceptance harness — the happy path, delegation-gate denials at the agent surface, a cross-vault entitlement deposit, and the auth-required round-trip via resubmit, all exercised in test/harness.test.ts.

import { newTaskRecord, dispatchTask, buildSkillRegistry, createInMemoryTaskStore } from '@agenticprimitives/a2a';

Boundary

The core is transport-agnostic — no Cloudflare coupling in src/. The Durable Object-backed TaskStore adapter (createDurableObjectTaskStore) ships as the ./cloudflare subpath. See ADR-0034. mcp-runtime is a consumer of this package, not the owner — no back-edges.

How it's different

The competing pattern is A2A protocol SDKs and agent-framework messaging — transports that move tasks but treat authorization as someone else's problem (a bearer token, a shared secret, an allow-list). Three things this package does that they structurally cannot:

• No task without a verifiable grant. A task record is only created when the delegation gate verifies the grant; task.permissionGrantRef pins the delegation hash, and an on-chain revocation fails the task in flight, closed.
• Authorization is not identity. The caveats and assignee decide what may happen; the signed token proves who asked. A delegator never reaches another principal's namespace, and no claimed agent holds a long-lived signing key — KMS/session signers only.
• Bodies stay in the vault. Task state carries hashes and refs; payloads live in the assignee's vault with its own access control. The transport never becomes the data store.

Because the gate is the same delegation primitive used across the substrate, "this agent may invoke that agent's summarize skill until Friday, revocable instantly" is one grant — verifiable on chain, auditable end to end.

Validation

pnpm --filter @agenticprimitives/a2a typecheck
pnpm --filter @agenticprimitives/a2a test

Status

Testnet/pilot-ready. Production launch is gated on the public checklist in the root README.md — including third-party contract audit and governance key rotation. Track every security finding live in docs/audits/findings.yaml. The runtime runs end to end in the demo apps against Base Sepolia (ERC-1271 + isRevoked checks bound to chain).

License

UNLICENSED (internal monorepo, not published).

The pairwise asker

A service that wants to know a returning person without learning who she is declares the card extension AP_PAIRWISE_ASKER_EXTENSION_URI (pairwiseAskerCardExtension(audience)). The card decides the asker's form: when sendSubjectAskOverWire finds the extension it sends { pairwise, audience } — a per-service pseudonym from the pairwiseSubjectFor port — and no credential, no session, no address. A card that declares the extension and a sender with no pseudonym to give is refused, never answered with the credentialed form. validatePairwiseSubjectAsk refuses an asker that carries anything beyond its subject and audience; routedAskOf reads either form.

Reference

Boundary (ADR-0034). This package is the transport-agnostic core: the task runtime over a TaskStore port, the SkillHandler contract and dispatcher, the A2aWireAdapter client, the delegation-auth gate and the scoped-grant caveat builders. The Cloudflare TaskStoreDO (a Durable Object TaskStore with alarm()) ships as the ./cloudflare subpath. It diverges from spec 245's placement under mcp-runtime on purpose: mcp-runtime is a consumer (the receiving gate and the a2a→mcp delivery leg), not the owner. Spec 269 W1–W5 are the record (runtime, gate, createA2aAgent, the Cloudflare store, vault body residency, signed push and SSE, the two-agent acceptance harness test/harness.test.ts).

The wire (spec 372). src/standard/ (imported as @agenticprimitives/a2a/standard) is A2A 1.0 as the official TCK tests it: PascalCase methods, proto-JSON shapes, A2A-Version, ErrorInfo on every A2A error, SSE, push. There is no second set of method names. createStandardA2aServer({card, executor, principal?, canSeeTask?, beforeSend?, onCancel?}) is fetch-shaped; the executor emits events through ctx. Authority rides as an extension: a SendMessage carrying AP_DELEGATED_TASK_EXTENSION is a delegation-authorized task (standard/delegated.ts), and createAgentBackedServer puts the runtime behind it with every gate it always had. The Authorization header says who is CALLING (caller.ts); the envelope's signature says who AUTHORED the message; a relay may carry a message it did not write, so the two are never collapsed. canSeeTask answers a non-party TaskNotFound. tck/sut.mjs + scripts/run-a2a-tck.sh run the TCK in CI; ./conform (ap conform a2a <url>) probes a live agent's card and binding.

Promoted from the runtime (spec 399 §4). standard/mount.ts: withStandardCardFields, isRuntimeTaskId, runtimeBackedTaskStore, principalBySchemes (Bearer = person, A2A-Session = agent, never each other's fallback), delegatedDispatch, settlementForReplyKind, settleTask. subject-hop.ts: sendSubjectAskOverWire (resolves through the card, digest pin), subjectAskOf, subjectAnswerOf, handoffOf, SUBJECT_ANSWER_ARTIFACT; spec 433's subjectAnswerEnvelope / subjectAnswerArtifact; standard/app-delegation.ts (appDelegationAsk). wire-verify.ts: verifyDelegationWire, the delegate-key tail every A2A service repeats (identity, caveats, revocation, signature).

Agent-card audiences (spec 338 §8). agentCard(forAudience?) projects by SkillHandler.exposure (public, authenticated, private, service-only; omitted means public). Passing an audience is not authenticating one: createCardAudienceResolver verifies a signed challenge (nonce consumed before the signature is read, x-ap-* headers) and degrades to public on any failure; privateViewPolicy is a separate injected decision. Visibility is disclosure, not authorization.