HTTP client for consuming remote A2A agents.
Provides discovery, synchronous messaging, SSE streaming, and task management using the A2A JSON-RPC protocol over HTTP.
Quick Start
# Discover an agent
{:ok, card} = A2A.Client.discover("https://agent.example.com")
# Create a client and send a message
client = A2A.Client.new(card)
{:ok, task} = A2A.Client.send_message(client, "Hello!")
# Stream a response
{:ok, stream} = A2A.Client.stream_message(client, "Count to 5")
Enum.each(stream, &IO.inspect/1)Convenience Overloads
All functions that accept a %A2A.Client{} also accept a URL string
or %A2A.AgentCard{}:
{:ok, task} = A2A.Client.send_message("https://agent.example.com", "Hello!")
{:ok, task} = A2A.Client.send_message(card, "Hello!")Options
Functions that send messages accept these options:
:task_id— continue an existing task (multi-turn):context_id— set the context ID:configuration—MessageSendConfigurationmap:metadata— arbitrary metadata map:headers— additional HTTP headers:timeout— HTTP request timeout in ms
Summary
Functions
Cancels a task by ID via tasks/cancel.
Discovers an agent by fetching its agent card.
Retrieves a task by ID via tasks/get.
Creates a new client struct.
Sends a message to an agent via message/send.
Sends a message and returns a stream of decoded SSE events.
Types
@type t() :: %A2A.Client{req: Req.Request.t(), url: String.t()}
@type target() :: t() | A2A.AgentCard.t() | String.t()
Functions
@spec cancel_task(target(), String.t(), keyword()) :: {:ok, A2A.Task.t()} | {:error, term()}
Cancels a task by ID via tasks/cancel.
Options
:headers— additional HTTP headers:timeout— HTTP request timeout in ms
Examples
{:ok, task} = A2A.Client.cancel_task(client, "tsk-abc123")@spec discover( String.t(), keyword() ) :: {:ok, A2A.AgentCard.t()} | {:error, term()}
Discovers an agent by fetching its agent card.
Sends GET /.well-known/agent-card.json and decodes the response
into an %A2A.AgentCard{}.
Options
:headers— additional HTTP headers:timeout— HTTP request timeout in ms:agent_card_path— custom discovery path (default:"/.well-known/agent-card.json")
Examples
{:ok, card} = A2A.Client.discover("https://agent.example.com")
card.name #=> "my-agent"@spec get_task(target(), String.t(), keyword()) :: {:ok, A2A.Task.t()} | {:error, term()}
Retrieves a task by ID via tasks/get.
Options
:history_length— number of history entries to include:headers— additional HTTP headers:timeout— HTTP request timeout in ms
Examples
{:ok, task} = A2A.Client.get_task(client, "tsk-abc123")@spec new( A2A.AgentCard.t() | String.t(), keyword() ) :: t()
Creates a new client struct.
Accepts a URL string or %A2A.AgentCard{}. Options are forwarded to
Req.new/1 for customizing the HTTP client (headers, timeouts, etc.).
Examples
client = A2A.Client.new("https://agent.example.com")
client = A2A.Client.new(card, headers: [{"authorization", "Bearer token"}])@spec send_message(target(), A2A.Message.t() | String.t(), keyword()) :: {:ok, A2A.Task.t()} | {:error, term()}
Sends a message to an agent via message/send.
Returns {:ok, task} on success or {:error, reason} on failure.
The message can be a string, an %A2A.Message{}, or a list of parts.
Options
:task_id— continue an existing task:context_id— set the context ID:configuration—MessageSendConfigurationmap:metadata— arbitrary metadata map:headers— additional HTTP headers:timeout— HTTP request timeout in ms
Examples
{:ok, task} = A2A.Client.send_message(client, "Hello!")
{:ok, task} = A2A.Client.send_message(client, "More info", task_id: task.id)@spec stream_message(target(), A2A.Message.t() | String.t(), keyword()) :: {:ok, Enumerable.t()} | {:error, term()}
Sends a message and returns a stream of decoded SSE events.
Uses message/stream to receive server-sent events. Returns
{:ok, stream} where the stream yields decoded structs
(%A2A.Task{}, %A2A.Event.StatusUpdate{}, %A2A.Event.ArtifactUpdate{},
or %A2A.Message{}).
Options
Same as send_message/3.
Examples
{:ok, stream} = A2A.Client.stream_message(client, "Count to 5")
Enum.each(stream, fn
%A2A.Event.StatusUpdate{final: true} -> :done
event -> IO.inspect(event)
end)