A2A Agent Card and Interface Specification: [Agent name]

Specification for an AI agent exposed to other agents over the Agent2Agent (A2A) protocol: identity and metadata, skills, capabilities, protocol bindings, security schemes, supported operations, task lifecycle, messages, parts and artifacts, streaming and push notifications, errors, versioning and discovery, an example Agent Card, security considerations and a conformance checklist. Written against the A2A Protocol Specification 1.0.1 (May 2026, a patch release of 1.0.0 from March 2026 with an unchanged a2a.proto; the protocol version used on the wire is 1.0), whose normative definition is the a2a.proto file in the specification repository. A2A is a Linux Foundation project and, since August 2026, a hosted project of the Agentic AI Foundation. Check the current release at a2a-protocol.org before you start. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Purpose and scope
2. Protocol baseline and governance
3. Agent identity and metadata
4. Interfaces and protocol bindings
5. Capabilities and extensions
6. Skills
7. Security schemes and authentication
8. Supported operations
9. Task lifecycle and states
10. Messages, parts and artifacts
11. Streaming and push notifications
12. Error handling
13. Versioning, discovery and caching
14. Example Agent Card
15. Security considerations
16. Conformance checklist
17. Glossary and references

1. Purpose and scope

[Describe what the agent offers and to whom.] Example: The Invoice Reconciliation Agent matches supplier invoices against purchase orders and goods receipts for business customers of [Company], and returns a reconciliation report. It is called by customers' procurement agents and by our own finance assistant. It does not approve or pay invoices.

2. Protocol baseline and governance

3. Agent identity and metadata

4. Interfaces and protocol bindings

Binding notes to verify:

• JSON-RPC: JSON-RPC 2.0 over HTTP; method names equal the operation names (for example SendMessage); streaming uses Server-Sent Events (text/event-stream).
• HTTP+JSON: resource-style paths such as POST /message:send and GET /tasks/{id}; streaming uses Server-Sent Events.
• gRPC: service A2AService in package lf.a2a.v1; streaming uses server-streaming RPCs.
• Tenant: when tenant is set on an interface, requests carry the same opaque value; do not use it as the only isolation control.

5. Capabilities and extensions

Clients activate extensions per request with the A2A-Extensions header (a comma-separated list of extension URIs). If an extension is marked required: true, clients that do not support it receive ExtensionSupportRequiredError.

6. Skills

Skill examples (the examples field):

• reconcile-invoice: Example: "Reconcile invoice INV-2026-0042 from Example Office Supplies against PO-77120."
• explain-mismatch: Example: "Why did line 3 of INV-2026-0042 not match?"
• batch-reconcile: Example: "Reconcile all invoices received in September 2026 for supplier SUP-0193."

7. Security schemes and authentication

Authentication rules:

• [Example: Access tokens must have this agent as audience and a lifetime of 15 minutes or less.]
• [Example: The tenant is derived from the token, never from message content.]
• [Example: GetExtendedAgentCard requires a valid token from a scheme in the public card; it returns the batch-reconcile skill only to callers with invoices:reconcile.]
• [Example: When a task needs a credential the caller has not supplied, the task moves to TASK_STATE_AUTH_REQUIRED with a message explaining what is needed; the credential itself is obtained out of band.]

8. Supported operations

Each HTTP+JSON path also has a tenant-prefixed form (for example /{tenant}/message:send in the specification's path templates) when an interface uses tenant.

8.1 Example request (JSON-RPC)

A client starts a reconciliation with a structured data part:

{
  "jsonrpc": "2.0",
  "id": "req-7",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "9f1c2e7a-4b1d-4c55-9a43-1d0f8e2b6c10",
      "role": "ROLE_USER",
      "parts": [
        {"text": "Reconcile this invoice against its purchase order."},
        {"data": {"invoiceId": "INV-2026-0042", "purchaseOrderId": "PO-77120"}, "mediaType": "application/json"}
      ]
    },
    "configuration": {"acceptedOutputModes": ["application/json"], "returnImmediately": true}
  }
}

9. Task lifecycle and states

The diagram drops the TASK_STATE_ prefix for readability. Direct Message replies (no task) are used for: [Example: explain-mismatch answers under 2 seconds]. Related tasks share a contextId; a follow-up may list earlier tasks in referenceTaskIds.

10. Messages, parts and artifacts

10.1 Accepted input parts

10.2 Artifacts returned

Artifact and message extensions lists name any extension URIs that contributed content. Do not place secrets or other tenants' data in metadata.

11. Streaming and push notifications

12. Error handling

Standard JSON-RPC errors (for example -32602 invalid params and -32603 internal error) are used for malformed requests. Map authentication failures to HTTP 401 and authorization failures to 403 on HTTP bindings.

13. Versioning, discovery and caching

13.1 Discovery

13.2 Versioning policy

• Agent version follows semantic versioning: removing a skill, an interface or an accepted media type, or adding a required security requirement, is a major change.
• New protocol versions are added as new supportedInterfaces entries before old ones are removed; old interfaces stay for [6] months.
• Clients send A2A-Version: 1.0; requests for unsupported versions get VersionNotSupportedError.

13.3 Signing and caching

14. Example Agent Card

The public card for the worked example, with one interface per binding and the security scheme wrapped by its type key:

{
  "name": "Invoice Reconciliation Agent",
  "description": "Matches supplier invoices to purchase orders and goods receipts and reports mismatches. Use it when an invoice must be checked before approval.",
  "supportedInterfaces": [
    {"url": "https://agent.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"},
    {"url": "https://agent.example.com/a2a/rest", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}
  ],
  "provider": {"organization": "Example Finance Services Ltd", "url": "https://www.example.com"},
  "version": "1.0.0",
  "documentationUrl": "https://docs.example.com/agents/invoice-recon",
  "capabilities": {"streaming": true, "pushNotifications": true, "extendedAgentCard": true},
  "securitySchemes": {
    "oauth": {
      "oauth2SecurityScheme": {
        "description": "Client credentials for partner agents",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.example.com/oauth2/token",
            "scopes": {"invoices:read": "Read reconciliation results", "invoices:reconcile": "Start reconciliation tasks"}
          }
        },
        "oauth2MetadataUrl": "https://auth.example.com/.well-known/oauth-authorization-server"
      }
    }
  },
  "securityRequirements": [{"schemes": {"oauth": {"list": ["invoices:read"]}}}],
  "defaultInputModes": ["application/json", "text/plain", "application/pdf"],
  "defaultOutputModes": ["application/json", "text/plain"],
  "skills": [
    {
      "id": "reconcile-invoice",
      "name": "Reconcile invoice",
      "description": "Matches one invoice to its purchase order and receipts and returns matched lines and mismatches.",
      "tags": ["invoice", "reconciliation", "procurement"],
      "examples": ["Reconcile invoice INV-2026-0042 from Example Office Supplies against PO-77120."],
      "inputModes": ["application/pdf", "application/json"],
      "outputModes": ["application/json"],
      "securityRequirements": [{"schemes": {"oauth": {"list": ["invoices:reconcile"]}}}]
    },
    {
      "id": "explain-mismatch",
      "name": "Explain mismatch",
      "description": "Explains in plain language why an invoice line did not match.",
      "tags": ["invoice", "explanation"],
      "examples": ["Why did line 3 of INV-2026-0042 not match?"],
      "inputModes": ["application/json", "text/plain"],
      "outputModes": ["text/plain"]
    }
  ],
  "signatures": [
    {"protected": "[base64url JWS protected header]", "signature": "[base64url signature]"}
  ]
}

15. Security considerations

16. Conformance checklist

17. Glossary and references

References:

• Agent2Agent (A2A) Protocol Specification 1.0.1, https://github.com/a2aproject/A2A/blob/v1.0.1/docs/specification.md
• A2A specification repository and a2a.proto, https://github.com/a2aproject/A2A (release v1.0.0, March 2026; patch v1.0.1, May 2026)
• Agentic AI Foundation announcement of A2A as a hosted project, August 2026, https://aaif.io/blog/a2a-joins-aaif
• OWASP Top 10 for Agentic Applications for 2026, https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
• RFC 7515 JSON Web Signature; RFC 8785 JSON Canonicalization Scheme; RFC 9111 HTTP Caching

Standard and licence note

Based on the Agent2Agent (A2A) Protocol Specification 1.0.1 and its a2a.proto definition, published by the A2A project under the Linux Foundation and licensed under Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0). Field, enum, operation and error names are reproduced exactly so that implementations interoperate; all explanatory text is original and requirements are summarised rather than quoted. The OWASP reference in section 15 is a citation only. Check a2a-protocol.org for the current release and the normative wording before implementing. Template licence: MIT.