Agent cards
How a2a-wrapper builds and serves an A2A agent card for discovery. The agentCard config block, skills, version-aware responses, and optional JWS-signed cards.
An agent card is the public description of your agent. Clients fetch it to learn what the agent is called, what it can do, and where to send requests.
curl -s http://localhost:3000/.well-known/agent-card.json | jq .Configuring the card
The card is generated from the agentCard and server blocks of your config:
{
"agentCard": {
"name": "Claude Workspace Engineer",
"description": "A repository-scoped software engineering agent backed by Claude.",
"version": "1.0.0",
"protocolVersion": "0.3.0",
"streaming": true,
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "workspace-engineering",
"name": "Workspace Engineering",
"description": "Inspect, modify, and validate code within the configured workspace.",
"tags": ["code", "repository", "tests"]
}
]
},
"server": {
"port": 3030,
"hostname": "127.0.0.1",
"advertiseHost": "localhost",
"advertiseProtocol": "http"
}
}| Field | Purpose |
|---|---|
agentCard.name, description | What callers see first. Write them for orchestrators deciding whether to route work to you |
agentCard.skills | Advertised capabilities (id, name, description, tags, optional examples) |
server.port, server.hostname | Where the server listens. hostname defaults to 0.0.0.0, see the security guide |
server.advertiseHost, advertiseProtocol | The host and protocol written into the card's endpoint URLs. Set these when running behind Docker, a proxy or TLS |
advertiseHost only changes the URLs in the card. It does not restrict who can connect. Use hostname and your network for that.
Skills: card versus memory
Two similarly named concepts are easy to confuse:
agentCard.skillsis protocol metadata shown to callers. It describes what the agent can do at a high level, for discovery and routing.memory.skillsis instructions written into the agent's workspace for the model. It is never exposed externally.
See memory and skills.
Version-aware responses
The card endpoint reads the caller's A2A-Version header:
1.0returns the native v1.0 card withsupportedInterfaces[].0.3,0.3.0or no header returns a v0.3-shaped legacy card (url,protocolVersion: "0.3.0").
So old and new clients both work with no extra configuration. Details in protocol versions.
Signed agent cards
A2A v1.0 supports JWS-signed cards (RFC 7515). This is opt-in: pass ServerOptions.agentCardSigning, or set AgentCardConfig.signing with the private key read from an environment variable holding a JWK. The card's signatures field is then populated automatically. Unsigned cards simply omit it.
Trace extension
Cards declare the urn:x-a2a:trace:v1 extension, which tells orchestrators the agent can emit sideband trace artifacts. It is optional for callers to use.
Architecture
How a2a-wrapper is structured, from the shared core to the per-backend executors. The request path through the Express server, the executor, the session manager and the backend SDK.
Tasks and streaming
How a2a-wrapper agents execute A2A tasks. Task states, blocking versus streaming calls, buffered versus streamed artifacts, cancellation, and what happens to long-running background work.