A2A - Consumer Guide

The simplest possible local A2A agent. Define your agent’s capabilities in agent-card.json, disable operation auth for local-only use, and let the route handle business logic:

Do not use validateAuth=false for agents exposed to an untrusted network. See Authentication for authenticated operation serving.

The agent card (agent-card.json) declares your agent’s identity and capabilities:

The component supports the HTTP+JSON and JSONRPC protocol bindings. The legacy aliases rest and jsonrpc are also accepted and normalized to the v1.0 binding names. The protocolVersion, defaultInputModes, and defaultOutputModes fields are part of the A2A v1.0 card shape.

For simple or test agents, the card identity fields can be built from URI parameters - no JSON file needed. Because parameter-built cards do not include security schemes, these local-only examples set validateAuth=false:

The component generates the /.well-known/agent-card.json response dynamically from the parameters. URI parameters only cover the agent identity fields above; use an agent card file or an agentCard bean for capabilities, skills, security schemes, supported interfaces, and other card metadata.

By default, the consumer uses the REST binding (HTTP+JSON with colon-notation paths like /message:send). To use JSON-RPC 2.0 (single POST / endpoint), set protocolBinding to JSONRPC. The legacy aliases rest and jsonrpc are also accepted.

This example is local-only because it disables operation auth. Keep validateAuth=true and configure a card security scheme for network-exposed agents.

The REST binding exposes separate HTTP routes for the operation-serving methods listed in Consumer REST API Paths. The JSON-RPC binding exposes a single dispatcher and handles SendMessage, SendStreamingMessage, GetTask, ListTasks, CancelTask, SubscribeToTask, and the push notification config operations. Extended agent cards are outside the Preview scope for this first release.

REST requests and responses use application/a2a+json. JSON-RPC requests and responses use application/json. Streaming operations produce text/event-stream.

The component supports OAuth 2.0, OpenID Connect, API key, and HTTP bearer security schemes. OAuth 2.0 and OpenID Connect use the oauthProfile option and the camel-oauth SPI; HTTP bearer can use either an OAuth profile or the static bearerToken option.

securityRequirements follows A2A v1.0 semantics: multiple requirement objects are alternatives (OR), while multiple schemes inside one requirement must all be satisfied together (AND). The list array contains required scopes. The legacy A2A draft field security is accepted on input and converted to securityRequirements; new cards should use securityRequirements.

Agents can emit progressive status updates during processing using the ${a2a:emit()} Simple language function. Clients receive these as Server-Sent Events (SSE).

For SendStreamingMessage and SubscribeToTask, the agent card must explicitly set capabilities.streaming=true. If the capabilities object is missing, or streaming is omitted or false, the consumer returns UnsupportedOperationError (HTTP 405 for REST, JSON-RPC -32004 for JSON-RPC).

Each ${a2a:emit('message')} emits an SSE status event with TASK_STATE_WORKING state. The final setBody is automatically delivered as the completed response.

You can also emit with an explicit state:

Camel routes can group related work with the a2aSubTask EIP and emit progress updates before, after, or when the grouped steps fail. This is a regular Camel route step, not a YAML-only extension, and it can be used from Camel’s model-based DSLs when camel-a2a is on the classpath. The emitBefore, emitAfter, and emitOnError fields are optional and are evaluated as Simple expressions against the current Exchange. The nested steps behave like normal Camel route steps: in YAML they are configured under steps, and in Java DSL they are added after .a2aSubTask() until .end(). If the nested steps fail, emitOnError can access the original exception, for example with $\{exception.message}, and the original exception continues to propagate through the route. Failures while evaluating the emitBefore, emitAfter, or emitOnError Simple expressions are route failures. Failures while storing or notifying the resulting A2A progress event are best-effort: they are logged at debug level and do not stop nested work, fail an otherwise successful exchange, or replace the original nested-step exception. By default, emitting progress outside an active A2A task context is a no-op. Set failIfNoTaskContext=true when a route should fail instead if the current Exchange does not carry an active A2A task. An active task context is normally created by an A2A consumer while it is processing a task. Use stable id values on long-lived sub-tasks so route tracing and route-structure views keep stable node names.

The route examples in this section are local-only because they disable operation auth. Keep validateAuth=true and configure a card security scheme for network-exposed agents.

The same route step is also available from Java DSL:

For advanced use cases, A2AProgress also supports emitting structured artifacts and intermediate messages:

The consumer supports two SSE streaming patterns:

SSE streaming parameters:

For long-running operations, enable returnImmediately to return a SUBMITTED task immediately. The route processes in the background, and clients poll with GetTask:

The asyncTimeout parameter (default: 300,000 ms / 5 minutes) controls how long the background processing can run before the task is marked FAILED.

The consumer manages the task lifecycle automatically: SUBMITTED → WORKING → COMPLETED (or FAILED on error / timeout).

returnImmediately resolution priority (highest wins):

SendMessageRequest.configuration is modeled as SendMessageConfiguration. The consumer interprets returnImmediately, blocking, and historyLength; unknown fields are retained for protocol extensions and future A2A options. configuration.historyLength limits the task history returned by synchronous SendMessage task responses.

Agents that use returnImmediately can deliver updates via webhooks. Clients register a webhook URL via CreateTaskPushNotificationConfig, and the component’s built-in PushNotificationDispatcher sends status updates to registered URLs.

The agent card should declare push notification support so clients can discover the feature:

Progress updates emitted via ${a2a:emit()} or A2AProgress.emit() are automatically dispatched to all registered webhooks.

Push notification dispatch features:

Control concurrent task processing and queue overflow:

Behavior by processing path:

The error response follows the A2A error model: REST returns HTTP 429 with ServerBusyError; JSON-RPC returns code -32000 in the JSON-RPC error envelope.

On shutdown, queued tasks are marked FAILED and subscribers are notified.

The consumer enforces maxPayloadSize (default 6,291,456 bytes / 6 MiB) on incoming request bodies. Requests exceeding this limit receive HTTP 413 (REST) or a JSON-RPC error.

To enable CORS (required when browsers call your agent directly), set the REST configuration:

The consumer automatically adds Access-Control-* headers (including A2A-specific headers like A2A-Version and A2A-Extensions) and registers OPTIONS preflight handlers for all A2A paths.

The agent card can advertise protocol extensions in capabilities.extensions. For protected operation routes, clients can request extensions with the A2A-Extensions HTTP header as a comma-separated list of extension URIs.

The consumer validates requested extensions against the resolved agent card. If any requested URI is not advertised, or if a card extension marked required=true is not requested, the request fails before route processing with UnsupportedExtensionError. Accepted extension URIs are exposed to the route as the CamelA2AExtensions header and exchange property, and are echoed in the A2A-Extensions response header.

Routes can branch directly on CamelA2AExtensions. For reusable behavior, register one or more org.apache.camel.component.a2a.extension.A2AExtensionHandler beans in the Camel registry. A handler is matched by extension URI and is invoked before and after route processing when that extension is negotiated. The handler receives the full AgentExtension declaration from the agent card, including params.

When using the default REST protocol binding, the consumer registers these HTTP endpoints:

All paths are prefixed with basePath if configured. When using JSON-RPC binding, a single POST / endpoint dispatches based on the JSON-RPC method field.

The built-in ListTasks consumer applies contextId, status, statusTimestampAfter, pageSize, pageToken, includeArtifacts, and historyLength. pageSize defaults to 50 and is capped at 100. pageToken values returned by the consumer are opaque cursor tokens containing a snapshot of the filtered task IDs for that listing. Clients must send the token back unchanged with the same filters; numeric offsets are rejected.

REST binding responses use the A2A v1.0 error wrapper with an error object. The ErrorInfo.reason detail maps back to these component error names:

REST binding returns these error responses as application/a2a+json with an error object containing the HTTP status, status name, message, and a google.rpc.ErrorInfo detail reason such as TASK_NOT_FOUND or VERSION_NOT_SUPPORTED.

JSON-RPC binding returns JSON-RPC error envelopes as application/json. Parse errors use -32700, invalid requests use -32600, unknown methods use -32601, invalid parameters use -32602, internal errors use -32603, capacity and authorization errors use -32000, missing tasks use -32001, non-cancelable terminal tasks use -32002, push notification support errors use -32003, unsupported operations use -32004, unsupported content types use -32005, invalid agent responses use -32006, extension negotiation failures use -32008, and unsupported A2A versions use -32009.