Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

A2A Quickstart

Three focused mini-guides to get your JACS agent working with A2A.

GuideWhat You'll DoTime
1. ServePublish your Agent Card so other agents can find you2 min
2. Discover & TrustFind remote agents and assess their trustworthiness2 min
3. ExchangeSign and verify A2A artifacts with chain of custody3 min

Single-page version: See the A2A Quick Start at the repo root for a 10-line journey.

JACS for A2A Developers

Already using the A2A protocol? Here's what JACS adds -- and what stays the same.

What Stays the Same

  • Agent Cards currently export the legacy v0.4.0 shape, preserving fields such as name, description, skills and url. Interoperability with current released A2A peers remains unproven; this guide does not claim current wire compatibility.
  • Discovery publishes the native six-document well-known set, including /.well-known/agent-card.json. The bundled routers do not implement message/task or remote-signing endpoints; callable services require separate host implementation and authorization.
  • JSON-RPC transport is untouched. JACS works alongside A2A, not instead of it.

What JACS Adds

A2A AloneWith JACS
Agent Card has no signatureAgent Card is JWS-signed + JWKS published
Artifacts are unsigned payloadsArtifacts carry jacsSignature with signer ID, algorithm, and timestamp
Trust is transport-level (TLS)Trust is data-level -- signatures persist offline
No chain of custodyparent_signatures link artifacts into a verifiable chain
No standard trust policyopen / verified / strict policies built in

Minimal Integration (Add JACS to Existing A2A Code)

If you already serve an Agent Card, adding JACS provenance takes two steps:

Step 1: Add the JACS extension to your Agent Card's capabilities:

{
  "capabilities": {
    "extensions": [{
      "uri": "urn:jacs:provenance-v1",
      "description": "JACS cryptographic document signing",
      "required": false
    }]
  }
}

Step 2: Sign artifacts before sending them:

from jacs.client import JacsClient

client = JacsClient.quickstart(name="my-agent", domain="my-agent.example.com")
# Wrap your existing artifact payload
signed = client.sign_artifact(your_existing_artifact, "artifact")
# Send `signed` instead of the raw artifact

Receiving agents that don't understand JACS will ignore the extra fields. Receiving agents that do understand JACS can verify the signature and assess trust.

Dual Key Architecture

JACS generates two key pairs per agent:

  • A native JACS root (pq2025 by default, or ring-Ed25519) for JACS documents and compatibility-key authorization.
  • A persisted P-256 / ES256 compatibility key for RFC 8785-canonicalized Agent Card JWS signatures.

The native root signs the published compatibility binding, so strict verifiers can connect the ES256 card key to an explicitly trusted JACS identity.

Troubleshooting FAQ

Q: pip install jacs[a2a-server] fails. A: The a2a-server extra requires Python 3.10+ and adds FastAPI + uvicorn. If you only need signing (not serving), use pip install jacs with no extras.

Q: discover_and_assess returns jacs_registered: false. A: The remote agent's Agent Card does not include the urn:jacs:provenance-v1 extension. This is normal for non-JACS A2A agents. With the open trust policy, they are still allowed; with verified, they are rejected.

Q: Verification returns valid: true but trust.allowed: false. A: The card signature may be correct while identity policy still rejects it. For strict, import the full native self-signed agent document and explicit native public key through an authenticated out-of-band channel with a2a.trust_a2a_agent(agent_document_json, public_key_pem). Passing the self-advertised Agent Card is rejected.

Q: sign_artifact raises "no agent loaded". A: Call JacsClient.quickstart(name="my-agent", domain="my-agent.example.com") or JacsClient(config_path=...) before signing. The client must have a loaded agent with keys.

Q: Agent Card export returns empty skills. A: Skills are part of the signed Agent Card. Configure them on the agent before generating or mounting discovery documents; servers reject post-signing skill overrides.

Q: My existing A2A client doesn't understand the JACS fields. A: This is expected. JACS fields (jacsId, jacsSignature, jacsSha256) are additive. Non-JACS clients should ignore unknown fields per JSON convention. If a client rejects them, strip JACS fields before sending by extracting signed["payload"].

Q: How do I verify artifacts from agents I've never seen before? A: Use JACS_KEY_RESOLUTION to configure key lookup. Set JACS_KEY_RESOLUTION=local,hai to check your local cache first, then the HAI key service. For offline-only verification, set JACS_KEY_RESOLUTION=local.

Next Steps