This release is a pre-release and may not be stable for production use.
Agent-DID × Google A2A Integration
Roadmap item: F2-02 — Google A2A proof-of-concept
Agent-DID as the identity layer for the A2A (Agent2Agent) protocol, version 1.0 (specification v1.0.1). This integration provides DID-based cryptographic identity for A2A agent discovery, request signing, and mutual authentication.
What This Solves
The A2A protocol is auth-agnostic — it defines how agents communicate (JSON-RPC 2.0 over HTTPS) and discover each other (Agent Cards), and declares authentication through standard schemes (OAuth 2.0, OpenID Connect, API keys, mTLS) without a per-agent cryptographic identity. This creates a gap:
| A2A Gap | What Agent-DID Provides |
|---|---|
| No native cryptographic identity | DID anchored to the agent's model, prompt, and capabilities |
| Agent Card has no identity bound to a DID | Agent-DID extension in capabilities.extensions and an A2A §8.4 card signature by a DID key |
| Request authenticity depends on external auth | Ed25519 HTTP Message Signatures on every JSON-RPC request |
| No standard for mutual agent authentication | DID-based verification of the counterparty agent |
Features
- A2A 1.0 Agent Cards —
supportedInterfaces(JSON-RPC, protocol version1.0), skills, capabilities,securitySchemes; the agent's identity goes in the Agent-DID extension (https://agent-did.org/a2a/identity/v1,params.didandparams.keyIds), markedrequiredwhenrequire_signed_requests=True - OAuth client credentials scheme — optional
oauth2SecurityScheme(clientCredentials) for authorization servers that accept DID client assertions (AgentDidA2AOAuthClientCredentials) - Request Signing — sign outgoing
SendMessage/GetTaskrequests using Agent-DID HTTP Signatures, withA2A-Version: 1.0andA2A-Extensionsnaming the Agent-DID extension - Request Verification — verify incoming signed requests using the sender's DID
- Signed AgentCards — sign the card for the identity composition contract (A2A 1.0 §8.4 JWS) and check incoming requests against the sender's signed card
- JSON-RPC Helpers — Pydantic models for JSON-RPC 2.0 and the A2A 1.0
Message,PartandTaskobjects (text_message,parse_send_message_result) - Observability — structured, sanitized event emission for signing, verification, and card generation
- Secure Defaults — sensitive fields redacted, private network targets blocked, extra config fields rejected
Identity Composition Contract
The canonical A2A identity invariant for this repository is documented in RFC-001-A2A-Identity-Composition-Contract.md, co-drafted with APS during Public Review.
The contract defines how two identity surfaces compose:
- Identity-at-rest: the published AgentCard and its DID-published key material.
- Identity-in-motion: the per-request HTTP signature and its
keyid.
An A2A verifier must treat those surfaces as a single trust boundary: the per-request signing key must compose with the AgentCard and DID document key material, and the signing key must be authorized for the operation context described in §6.3 of the contract.
The integration implements the contract with the SDK:
signed_agent_card_json(agent_url=...)returns the card with an Agent-DID extension incapabilities.extensions(the agent DID and the keys it publishes: the signing key and the other activeassertionMethodkeys) and asignaturesentry by the signing key. The signature follows A2A 1.0 §8.4 (JWS,EdDSA, over the RFC 8785 form of the card withoutsignaturesand without default values, §8.4.1). The tests cross-check it with the official A2A Python SDK (a2a-sdk1.3):a2a-sdkverifies the cards this integration signs, and the SDK verifies cardsa2a-sdksigns.a2a-sdk1.3 also drops emptyREQUIREDmembers and empty messages before it verifies; the cards built here never contain them.verify_request_against_card(..., agent_card=card)verifies the card's signatures, the request's HTTP signature, and that the request'skeyidis a key the card publishes. A rejection carries the contractreason(rotation_window_closed,emergency_revoked,key_purpose_violation,tampered,card_keyid_mismatch,format_drift,did_document_unresolvable,request_rejected) and thestagethat failed.
The card does not change when the agent's keys do: sign and serve it again after adding, retiring or rotating a key.
Installation
cd integrations/a2a
python -m pip install -e ".[dev]"
Requires the Python SDK installed in dev mode:
cd sdk-python
python -m pip install -e ".[dev]"
Quick Start
from agent_did_sdk import AgentIdentity, AgentIdentityConfig, CreateAgentParams, InMemoryAgentRegistry, LocalKeySigner
from agent_did_a2a import A2ASkill, create_agent_did_a2a_integration, text_message
# Create identity
AgentIdentity.set_registry(InMemoryAgentRegistry())
identity = AgentIdentity(AgentIdentityConfig(controller_signer=LocalKeySigner.generate()[0]))
runtime = await identity.create(
CreateAgentParams(name="MyAgent", core_model="gpt-4.1", system_prompt="...")
)
# Create A2A integration
integration = create_agent_did_a2a_integration(
agent_identity=identity,
runtime_identity=runtime,
)
# Signed A2A 1.0 Agent Card for /.well-known/agent-card.json
card = await integration.signed_agent_card_json(
agent_url="https://my-agent.example.com/a2a",
skills=[A2ASkill(id="task-1", name="My Skill", description="Does something useful", tags=["demo"])],
)
# Sign an outgoing SendMessage request
signed = await integration.send_message(
target_url="https://remote-agent.example.com/a2a",
request_id=1,
message=text_message("Hello"),
)
# Verify an incoming request. A valid signature only proves which DID signed it:
# accept only the senders (or the controllers of senders) you trust.
is_valid = await integration.verify_request(
method="POST",
url="https://my-agent.example.com/a2a",
headers=incoming_headers,
body=incoming_body,
allowed_controllers=["did:webvh:...:partner.example.com:organizations:partner"],
)
# Or learn who signed and decide yourself
from agent_did_a2a import verify_a2a_request_detailed
result = await verify_a2a_request_detailed(
agent_identity=identity, method="POST", url=url, headers=incoming_headers, body=incoming_body
)
if result.ok:
print(result.did, result.key_id, result.controllers)
# Identity composition: serve a signed card, and check requests against the sender's card
signed_card = await integration.signed_agent_card_json(agent_url="https://agents.example.com/my-agent/a2a", skills=skills)
composition = await integration.verify_request_against_card(
method="POST", url=url, headers=incoming_headers, body=incoming_body, agent_card=sender_card
)
if not composition.ok:
print(composition.stage, composition.reason)
Examples
| Example | Description |
|---|---|
| a2a_agent_did_discovery.py | Agent publishes a signed A2A 1.0 Agent Card and a client checks it |
| a2a_mutual_auth_demo.py | A signed SendMessage checked against the sender's signed card |
Running Tests
cd integrations/a2a
python -m pytest tests/ -q
Full quality gates:
python -m ruff check src/ tests/ examples/
python -m mypy src/
python -m pytest tests/ -q
tests/test_a2a_sdk_interop.py needs the a2a-sdk[signing] dev dependency; CI sets AGENT_DID_REQUIRE_A2A_SDK=1 so it fails instead of skipping when it is missing.
Architecture
┌─────────────────────────────────────────────────────────┐
│ Agent A (Client) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AgentDidA2AIntegration │ │
│ │ → signed card → /.well-known/agent-card.json │ │
│ │ → sign_request() → Signature + Signature-Input │ │
│ │ → send_message() → signed SendMessage POST │ │
│ └─────────────────────┬───────────────────────────┘ │
├─────────────────────────┼───────────────────────────────┤
│ HTTPS + Ed25519 HTTP Message Signatures │
├─────────────────────────┼───────────────────────────────┤
│ Agent B (Server) ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AgentDidA2AIntegration │ │
│ │ → verify_request() → validate Signature header │ │
│ │ → resolve DID → fetch sender's public key │ │
│ │ → ✓ authenticated → process A2A task │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
How It Fits With A2A
A2A 1.0 declares authentication through securitySchemes; none of its scheme types (API key, HTTP auth, OAuth 2.0, OpenID Connect, mTLS) describes HTTP Message Signatures. The integration therefore uses A2A's extension mechanism (§4.6):
- The Agent Card lists the Agent-DID extension in
capabilities.extensions, with the agent DID and the keys the card publishes, and a JWS signature by one of those keys - A client activates the extension with
A2A-Extensions: https://agent-did.org/a2a/identity/v1and signs each request (Signature,Signature-Input,Agent-DID) - The receiving agent resolves the sender's DID, verifies the signature and, with the sender's card, that the signing key is one the card publishes (identity composition contract)
This is complementary to the card's securitySchemes: an agent can also require an OAuth 2.0 token (for example client credentials with a DID client assertion) or mTLS.
License
Metadata
Release files for agent-did-a2a 1.0.0rc5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_did_a2a-1.0.0rc5.tar.gz | 29.3 kB | With provenance | Details for agent_did_a2a-1.0.0rc5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_did_a2a-1.0.0rc5-py3-none-any.whl | Python 3 | none | any | Details for agent_did_a2a-1.0.0rc5-py3-none-any.whl |
Total release size: 50.9 kB
Release files / agent_did_a2a-1.0.0rc5.tar.gz
| Download URL | agent_did_a2a-1.0.0rc5.tar.gz |
|---|---|
| Size | 29.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a487eeab4644a37777e45265cd4b2cc4d97ad5c3aa3506d413850d800c4dc8f
|
|
BLAKE2b-256 checksum How to use checksums |
ba09e84484b11f39d1e2f27a49faae3c0f41a9e92bbe4f99ab1cb71e7f1caab4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / agent_did_a2a-1.0.0rc5-py3-none-any.whl
| Download URL | agent_did_a2a-1.0.0rc5-py3-none-any.whl |
|---|---|
| Size | 21.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d08115e9596ebeca5b2d4cfc000d64a8526eaae3a480613ba8f55d43a4c4303
|
|
BLAKE2b-256 checksum How to use checksums |
aed6ea519851cf658a4e47521b181c2811c8f53703275e721f9099e8a2ba0f13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for agent-did-a2a 1.0.0rc5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_did_a2a-1.0.0rc5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.