a2a-client

A2A Client Implementation

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for client-side protocol requirements
2. Web-search site:github.com a2aproject a2a-python client or a2aproject a2a-js client for SDK client classes
3. Web-search site:github.com a2aproject a2a-samples client for reference client implementations
4. Fetch the target SDK README for client usage patterns

Conceptual Architecture

What an A2A Client Does

An A2A client is the requesting side that:

1. Discovers agents via Agent Cards (fetch /.well-known/agent-card.json)
2. Sends messages to create or continue tasks
3. Handles synchronous responses or SSE streams
4. Manages multi-turn conversations (handles input-required states)
5. Optionally configures push notifications for long-running tasks

Client Workflow

1. Discover agent → Fetch Agent Card
2. Check capabilities → Verify the agent can handle the task
3. Authenticate → Satisfy the agent's auth requirements
4. Send message → POST JSON-RPC to agent URL
5. Handle response → Process task result or continue conversation
6. Monitor → Poll, stream, or receive push notifications

Discovery

Before sending requests, the client must discover the target agent:

• Direct URL — Fetch {base_url}/.well-known/agent-card.json
• Registry lookup — Query an agent registry by skill tags or name
• Referral — Another agent provides the target agent's URL
• Configuration — Hard-coded agent URLs for known partners

Sending Messages

Two modes:

• Synchronous (message/send) — Send a message, wait for the complete response
• Streaming (message/stream) — Send a message, receive SSE events as the agent processes

Client Message Structure

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "request-id",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        { "kind": "text", "text": "Your task description" }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["text/plain", "application/json"]
    }
  }
}