Agent Card Reference

Agent card structure

The agent card is a JSON document declaring an agent's identity, capabilities, and how to interact with it.

Core fields

AgentInterface

AgentCapabilities

AgentSkill

Example agent card

{
  "name": "Travel Planner Agent",
  "description": "Books flights, hotels, and creates travel itineraries",
  "supported_interfaces": [
    {
      "url": "https://travel-agent.example.com/a2a",
      "protocol_binding": "jsonrpc",
      "protocol_version": "1.0"
    }
  ],
  "provider": {
    "organization": "TravelCo",
    "url": "https://travelco.example.com"
  },
  "version": "2.1.0",
  "capabilities": {
    "streaming": true,
    "push_notifications": true,
    "extended_agent_card": false
  },
  "security_schemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "security_requirements": [
    { "bearer": [] }
  ],
  "default_input_modes": ["text/plain"],
  "default_output_modes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "flight-search",
      "name": "Flight Search",
      "description": "Search and book flights between any two airports",
      "tags": ["travel", "flights", "booking"],
      "examples": ["Find flights from SFO to JFK on March 20"]
    },
    {
      "id": "hotel-booking",
      "name": "Hotel Booking",
      "description": "Search and reserve hotel rooms",
      "tags": ["travel", "hotels"],
      "examples": ["Book a hotel near Times Square for 3 nights"]
    }
  ]
}

Discovery strategies

1. Well-known URI (recommended for public agents)

Host agent card at https://{domain}/.well-known/agent-card.json per RFC 8615.

2. Curated registries (enterprise)

Central service maintains agent card collections. Clients query by skills, tags, or capabilities. Provides centralized governance and capability-based discovery.

3. Direct configuration (dev/testing)

Hardcoded details, config files, or environment variables. Simple but inflexible.

Extended agent cards

When capabilities.extended_agent_card is true, the server offers a GetExtendedAgentCard operation that returns additional capabilities visible only to authenticated clients. This allows agents to expose sensitive skills or detailed configurations after credential exchange.

Security schemes

Caching

• Servers should include Cache-Control headers with appropriate max-age
• Servers should include ETag headers for conditional requests
• Clients should honor HTTP caching semantics
• Use conditional requests (If-None-Match) rather than unconditional re-fetching

Protocol Bindings Reference

A2A defines a three-layer architecture: a canonical data model (Protocol Buffers), abstract operations (binding-independent), and protocol bindings. All three bindings are functionally equivalent.

JSON-RPC 2.0 Binding

All methods are prefixed with a2a. and sent as HTTP POST to the agent endpoint.

Methods

Service parameters

Passed in the params object alongside method-specific params:

{
  "jsonrpc": "2.0",
  "method": "a2a.sendMessage",
  "id": "req-1",
  "params": {
    "message": { ... },
    "a2a-version": "1.0",
    "a2a-extensions": "urn:example:ext1,urn:example:ext2"
  }
}

Streaming

For sendStreamingMessage and subscribeToTask, the server responds with Content-Type: text/event-stream (SSE). Each event is a JSON-encoded StreamResponse wrapper.

gRPC Binding

Service definition

service A2AService {
  // Unary RPCs
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
  rpc GetTask(GetTaskRequest) returns (Task);
  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
  rpc CancelTask(CancelTaskRequest) returns (Task);
  rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard);
  rpc CreateTaskPushNotificationConfig(...) returns (PushNotificationConfig);
  rpc GetTaskPushNotificationConfig(...) returns (PushNotificationConfig);
  rpc ListTaskPushNotificationConfigs(...) returns (...);
  rpc DeleteTaskPushNotificationConfig(...) returns (google.protobuf.Empty);

  // Server-streaming RPCs
  rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse);
  rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse);
}

Service parameters

Transmitted via gRPC metadata headers:

• a2a-version: Protocol version
• a2a-extensions: Comma-separated extension URIs

HTTP+JSON/REST Binding

RESTful endpoints using standard HTTP methods.

Endpoints

Query parameters for listing

Service parameters

Passed as HTTP headers:

• A2A-Version: 1.0
• A2A-Extensions: urn:example:ext1,urn:example:ext2

Multi-tenant support

For multi-tenant deployments, a tenant path parameter can prefix all endpoints: /tenants/{tenant}/messages, /tenants/{tenant}/tasks/{id}, etc.

StreamResponse wrapper

All streaming operations return StreamResponse objects, each containing exactly one of:

TaskArtifactUpdateEvent includes append (boolean) and last_chunk (boolean) fields for incremental artifact streaming.

Task States and Lifecycle Reference

Task object

Task states

                    +-> completed (terminal)
                    |
submitted -> working +-> failed (terminal)
                    |
                    +-> canceled (terminal)
                    |
                    +-> rejected (terminal)
                    |
                    +-> input-required (interrupted) -> working (on new message)
                    |
                    +-> auth-required (interrupted) -> working (on auth)

State descriptions

State transitions

• Active states can transition to any other state
• Interrupted states transition back to working when the client responds
• Terminal states are final - no further transitions allowed
• Servers must reject cancelTask for tasks already in terminal states

Multi-turn conversation flow

1. Client sends sendMessage with initial request
2. Server creates task in submitted state, moves to working
3. Server transitions to input-required if it needs clarification
4. Client sends follow-up sendMessage with same task_id and context_id
5. Server resumes processing (working)
6. Repeat until task reaches a terminal state

The context_id is server-generated on the first interaction. Clients must preserve and reuse it for related follow-up messages. Servers must reject requests with mismatched context_id/task_id pairs.

History and pagination

The history_length parameter on getTask and sendMessage controls how many historical messages are returned:

Artifacts

Push notification payloads

When push notifications are configured, the server sends webhooks with these event types:

TaskStatusUpdateEvent

Sent when a task's state changes.

{
  "task_id": "task-abc-123",
  "context_id": "ctx-xyz",
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [{ "text": "Task completed successfully" }]
    }
  },
  "metadata": {}
}

TaskArtifactUpdateEvent

Sent when an artifact is created or updated.

{
  "task_id": "task-abc-123",
  "context_id": "ctx-xyz",
  "artifact": {
    "artifact_id": "art-001",
    "name": "search-results",
    "parts": [{ "text": "Found 3 matching flights..." }],
    "append": false,
    "last_chunk": true
  }
}

• append: true means this chunk should be appended to the existing artifact
• last_chunk: true means no more chunks will follow for this artifact

Push notification configuration

{
  "url": "https://client.example.com/webhook",
  "token": "unique-config-id",
  "authentication": {
    "scheme": "bearer",
    "credentials": "secret-token"
  }
}

Authentication options for webhooks

Management operations

• createTaskPushNotificationConfig - Register a new webhook
• getTaskPushNotificationConfig - Get config by ID
• listTaskPushNotificationConfigs - List all configs for a task
• deleteTaskPushNotificationConfig - Remove a webhook config

Update delivery mechanisms