A2A Integration

Install

pnpm add @peac/mappings-a2a

Agent Card Extension

Agents advertise PEAC evidence support in their Agent Card via the capabilities.extensions array. The extension URI is https://www.peacprotocol.org/ext/traceability/v1.

{
  "name": "Example Agent",
  "url": "https://agent.example",
  "capabilities": {
    "extensions": [{
      "uri": "https://www.peacprotocol.org/ext/traceability/v1",
      "description": "PEAC evidence traceability for agent interactions",
      "required": false
    }]
  }
}

Setting required: false allows non-PEAC agents to interoperate. Set to true only when evidence is mandatory for the workflow.

Evidence Carrier in Metadata

Evidence is carried in the metadata field of A2A objects (TaskStatus, Message, Artifact). The extension URI is the key, and the value contains a carriers array of PeacEvidenceCarrier objects.

{
  "metadata": {
    "https://www.peacprotocol.org/ext/traceability/v1": {
      "carriers": [{
        "receipt_ref": "sha256:abc123...",
        "receipt_jws": "eyJhbGciOi..."
      }]
    }
  }
}

Each carrier includes a receipt_ref (SHA-256 of the JWS) and the receipt_jws (compact JWS). The receipt_ref is verified at extraction: sha256(receipt_jws) == receipt_ref.

Discovery

PEAC evidence support is discovered through a 3-step process:

Transport Constraints

Attach and Extract

import { A2ACarrierAdapter } from '@peac/mappings-a2a';

const adapter = new A2ACarrierAdapter();

// Attach evidence to an A2A metadata object
const metadata = adapter.attach({}, {
  receipt_ref: 'sha256:abc123...',
  receipt_jws: 'eyJhbGciOi...',
});

// Extract evidence from A2A metadata
const carriers = adapter.extract(metadata);
// carriers: PeacEvidenceCarrier[]

// Validate transport constraints
const validation = adapter.validateConstraints(carriers);
// validation.valid: boolean

Placement in A2A Objects

Evidence can be attached to any A2A object that carries a metadata field:

Handoff Observation Records New in v0.14.1

Beyond carrying existing receipts, PEAC can now issue signed handoff observation records when a task transfers between agents. These records capture the observable boundary crossing — who initiated it, what was passed, and which agent accepted the task — as a portable, offline-verifiable signed record.

Handoff records use the org.peacprotocol/a2a-handoff extension namespace (15th extension group) with 10 registered type URIs covering task lifecycle events.

import { issueA2AHandoffRecord } from '@peac/mappings-a2a';

// Issue a signed handoff observation record
const record = await issueA2AHandoffRecord({
  eventKind: 'a2a-task-submitted',
  taskRef: 'sha256:abc123...', // opaque reference, no raw task ID
  upstreamAgentRef: 'did:key:z6Mk...',
  downstreamAgentRef: 'did:key:z6Ml...',
  signingKey: myKey,
  issuer: 'https://agent.example.com',
});

// record.jws is a portable signed Wire 0.2 record
// Can be verified offline by any party with the issuer's public key

Microsoft AGT / AAIF Compatibility

Microsoft's Agent-to-Agent Interoperability Framework (AAIF) and the Azure AI Foundry Agent toolkit (AGT) implement the Linux Foundation A2A protocol. Because PEAC's A2A mapping targets the A2A v1.0 specification directly, evidence carriers and handoff observation records work with AGT-based agents without any additional adapter.

Links