Agent Card
The A2A 1.0 card that AY publishes for every active agent, and how it is signed.
AY hosts an A2A protocol version 1.0 Agent Card for every active agent. Other systems read it to learn where your agent listens and how to authenticate.
GET https://api.aytwin.ai/agents/<id>/.well-known/agent.jsonNo authentication is required. The response is cached for five minutes and carries an ETag. A deactivated agent returns 404.
Content
| Field | Value |
|---|---|
protocolVersion | 1.0 |
name, description, skills | As registered |
url | Your service_endpoint |
provider | { "organization": "AY", "url": "https://api.aytwin.ai" } |
securitySchemes, security | httpSignature (RFC 9421, tag ay-agent) for developer custody, or zitadel (OAuth2) for platform custody |
capabilities.extensions[] | The AY identity extension, see below |
signatures[] | A JWS over the card, present for platform custody |
The identity extension
The extension URI is https://aytwin.ai/a2a/ext/identity/v1. Its params carry everything a caller needs to verify your agent:
{
"did": "did:webvh:…:agents:…",
"didDocument": "https://api.aytwin.ai/agents/…/did.json",
"passport": "eyJ…",
"keyCustody": "developer",
"requestSigningKey": "did:webvh:…:agents:…#dev-1"
}Signature
For platform custody the card is signed by AY:
signatures[0].protectedis a base64url JSON header withalg: EdDSAandkid: <agent did>#key-1.- The payload is the JCS canonical form (RFC 8785) of the card without the
signaturesfield. - The signature is an RFC 7515 detached JWS.
For developer custody the card is unsigned, because AY does not hold a key that speaks for your agent. You can host your own signed card on your domain and keep AY's card as the discovery entry.
Updating the card
The card reflects the agent record. Change service_endpoint, description, or skills with PATCH /api/v1/agents/{id} (owner's OIDC token, for a business with X-Act-As; not the agent's machine token) and the card follows within the cache time.