A2A Integration
Carry verifiable evidence through the Linux Foundation Agent-to-Agent Protocol (A2A v0.3.0) metadata. PEAC evidence attaches to TaskStatus, Message, and Artifact objects via a registered extension URI.
Built on the Evidence Carrier Contract.
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:
1. Agent Card
Check capabilities.extensions[] for the PEAC extension URI. This is the primary discovery mechanism.
2. Well-Known
Fetch /.well-known/peac-issuer.json from the agent's origin for issuer configuration and JWKS resolution.
3. Header Probe
If the Agent Card does not declare the extension, check for PEAC-Receipt headers in HTTP responses as a fallback.
Transport Constraints
| Constraint | Value |
|---|---|
| Embed size limit | 64 KB |
| Carrier placement | metadata[extensionURI].carriers[] |
| receipt_ref format | sha256:<64 hex chars> |
| receipt_jws format | JWS Compact Serialization |
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: booleanPlacement in A2A Objects
Evidence can be attached to any A2A object that carries a metadata field:
| A2A Object | Use Case |
|---|---|
TaskStatus | Evidence for task lifecycle transitions |
Message | Evidence for individual agent messages |
Artifact | Evidence for generated outputs and deliverables |
Links
Verifier Resolution
After extracting a carrier from A2A metadata, verify the receipt by resolving the issuer: receipt iss claim to /.well-known/peac-issuer.json to jwks_uri to JWKS to public key. The receipt_ref integrity check (sha256(receipt_jws) == receipt_ref) runs before signature verification.