1. How do I use AI Agent Studio?
  2. A2A API Overview

A2A API Overview

The API consists of three endpoints:

  1. GET /orchestrator/a2a/v1/{workflowCode}/.well-known/agent.json
  2. POST /orchestrator/a2a/v1/agents/search
  3. POST /orchestrator/a2a/v1/{workflowCode}

Together, these endpoints support the following actions:

  • Agent specific discovery
  • Registry-style agent search
  • Streaming and nonstreaming invocation and task retrieval
Endpoint When to use Request Response and how to use it Notes
Agent Card Discovery

GET /orchestrator/a2a/v1/{workflowCode}/.well-known/agent.json

 Use this endpoint when the client already knows the target workflow code or when registry search has already returned a workflow-specific agent-card URL.

The request is identified by:

workflowCode: the published workflow to discover

No request body is required.

The response is an agent card for the specified workflow-backed agent.

Clients must expect the card to provide the following details:

  • Agent identity information
  • Version information
  • Provider information
  • Authentication requirements
  • Capabilities such as streaming support
  • Default input and output modes
  • Skills associated with the agent

How to use the response

Clients must use the card to do these actions:

  • Confirm they've the correct agent
  • Inspect the advertised authentication and capability model
  • Determine the invocation path for subsequent calls
  • The card is agent-specific rather than host-wide
  • The card model is intentionally narrower than a richer full-specification A2A card
Registry Search

POST /orchestrator/a2a/v1/agents/search

Use this endpoint when the client needs discovery rather than direct lookup.

Here are some typical scenarios:

  • Browsing available agents
  • Searching by name or related query text
  • Paging through results

The request body supports the following options:

  • query: optional search text
  • skip: optional pagination offset
  • top: optional page size limit

The response is a registry-style result set containing these details:

  • Version metadata for the registry response
  • A collection of matching resources
  • A total count

Each resource points to an agent card.

How to use the response

Here's the recommended client flow:

  1. Call registry search
  2. Select a matching result
  3. Fetch that result's agent card
  4. Call the selected agent
  • This is a Fusion-specific registry-style endpoint, not a generic standards-level registry service
  • Results are agent-backed
  • Search success must not be treated as a guarantee that subsequent execution will be authorized in every case
Nonstreaming Invocation

POST /orchestrator/a2a/v1/{workflowCode}

Use this endpoint when the client wants a standard request/response interaction rather than an SSE stream.

This endpoint supports the following operations:

  • Starting asynchronous work from a message
  • Starting or resuming task-oriented work
  • Polling the latest state of an existing task

The request body supports the following request patterns:

  • message/send
  • message/stream
  • tasks/send
  • tasks/get

Request patterns

message/send

Use message/send to begin asynchronous work from a conversational message.

Typical request content includes these details:

  • A message object
  • Message parts
  • Optional context information
  • Optional metadata

message/stream

The response is returned as an SSE stream.

tasks/send

Use tasks/send to start or continue task-oriented execution.

Typical request content includes these details:

  • A task identifier when continuing or resuming work
  • A message payload
  • Optional context information
  • Optional metadata
tasks/get

Use tasks/get to retrieve the latest state of an existing task.

Typical request content includes these details:

  • The task identifier
  • Optional history preferences

The endpoint returns a JSON-RPC-style response whose result is task-oriented.

Clients must expect task-like responses representing these states:

  • Submitted
  • Working
  • Input-required
  • Completed
  • Failed

Completed and waiting tasks might include output artifacts.

For message/stream, clients must expect these responses:

  • An initial event representing the initial task snapshot
  • Additional events as task state changes
  • Completion of the stream when execution finishes

How to use the response

Here is a common client pattern:

  1. Call message/send or tasks/send
  2. Receive a task-shaped response
  3. Continue polling with tasks/get until the task reaches a terminal state

Use message/stream when streaming is preferred over polling

Prefer nonstreaming invocation plus tasks/get for these situations:

  • Polling is simpler for the client
  • The integration doesn't need live incremental updates
  • Even message/send is task-oriented in practice
  • Clients must expect asynchronous behavior rather than an immediate final answer
  • The message/stream behavior can be considered as repeated task snapshots over SSE
  • Clients must not assume a richer event-native A2A stream contract beyond the task-state s

API Task Lifecycle

The API is asynchronous by design. The typical client lifecycle includes these steps:

  1. Identify the target agent through direct card lookup or registry search.
  2. Call API using message/send, tasks/send, or message/stream.
  3. Receive a task-oriented result.
  4. Continue through polling or streaming until the task completes.
  5. Read final output from the resulting task state and artifacts.

Here are the available task states:

  • submitted
  • working
  • input-required
  • completed
  • failed

Clients must be prepared for a task to enter the input-required state before reaching completion.

Input and Output Expectations

Here are the input and output expectations for the API.

Inputs

The API is primarily text-oriented. Clients must assume the following inputs:

  • Text is the primary supported input mode
  • The most important request content is the message text
  • Metadata might be included when additional execution context is needed

Outputs

The API returns task-oriented outputs. Clients must expect the following outputs:

  • Task identifiers
  • Task state
  • Timestamps
  • Output artifacts when work completes or pauses for input
  • Optional history when requested

Usage Guidance

For most client integrations, here is the recommended usage pattern:

  1. Use registry search when discovery is needed.
  2. Fetch the agent card for the selected agent.
  3. Use message/send for standard asynchronous invocation.
  4. Use message/stream when live progress updates are preferred.
  5. Use tasks/get for polling-based status retrieval.

Error Handling and Client Expectations

Clients must handle the following classes of errors:

  • Authentication failures
  • Workflow-not-found cases
  • Invalid method usage
  • Task lookup failures
  • Authorization failures during processing or status retrieval

Clients must also assume that invalid or incomplete requests might fail when validating the request. Task retrieval might fail if the task doesn't belong to the specified agent or accessible user context.

Scope and Constraints

The API is intentionally narrower than the broader A2A protocol. Here are some of the important constraints:

  • The API is workflow-backed
  • The primary response model is task-oriented
  • Streaming is snapshot-based over SSE
  • Discovery is implementation-specific
  • Richer nontext and multipart input handling is limited
  • The broader A2A feature set is only partially implemented