Skip to main content

A2A API Reference

Detailed specification of the A2A (Agent-to-Agent Protocol) endpoints provided by the AGENTIC STAR Marketplace edition. External agents and applications that support A2A call registered Agents and published workflows (projects). Both A2A 0.3 and 1.0 are supported.

Where A2A is available

A2A is available only in environments where an administrator has opened the inbound endpoints (MCP and A2A) and set the standard token endpoint. Otherwise the endpoints return 404 Not Found. For how to open them, see the Helm Values Reference in the Build section.

Base URL​

All requests are sent to the following base URL. Replace <your-domain> with the domain of your environment.

Marketplace
https://<your-domain>

Endpoints​

Each registered Agent and each published workflow has its own endpoint and Agent Card. There is no endpoint that lists them.

MethodEndpointDescription
POST/api/v1/a2a/agents/{agentId}/A2A JSON-RPC endpoint of a registered Agent
GET/api/v1/a2a/agents/{agentId}/.well-known/agent-card.jsonIts Agent Card
POST/api/v1/a2a/projects/{projectId}/A2A JSON-RPC endpoint of a published workflow
GET/api/v1/a2a/projects/{projectId}/.well-known/agent-card.jsonIts Agent Card
  • As in the Agent Card's url and supportedInterfaces, the endpoint URL ends with / (it works without it as well)
  • Getting an Agent Card also requires a token. The token rules are the same as in "Authentication" below
  • agentId is the ID of an Agent the administrator registered in the admin console. Check it with your administrator
  • projectId is the ID of a workflow the project owner published over A2A. Check it with the owner. Only workflows whose publishing settings have the name and description of the A2A card can be called

Protocol: JSON-RPC 2.0 (blocking sends use application/json; streaming uses SSE)

Agent Card​

There are two forms of the Agent Card. With the request header A2A-Version: 1.0, you get an Agent Card in the 1.0 form only; without the header, or with any other value, you get a single Agent Card that carries the fields of both 0.3 and 1.0.

ItemRegistered AgentPublished workflow
Name and descriptionThe name and description of the A2A card written in the admin console; if not written, the Agent's display name and descriptionThe name and description of the A2A card written in the project's publishing settings
SkillsThe skills of the A2A card; if not written, one skill from the name and descriptionThe skills of the A2A card; if not written, one skill from the name and description
StreamingSupported (streaming: true)Not supported (streaming: false)
Input and output modesAs set on the A2A card; text/plain if not setInput text/plain and application/json, output text/plain

Authentication​

All requests (including getting an Agent Card) must include the Authorization: Bearer <access_token> header. The following two kinds of tokens can be used. The Marketplace edition applies no scope restrictions.

TokenHow to get itWhere it appears in the Agent Card
A system integration (service account) tokenClient Credentials flow of the standard token endpoint (https://<auth-domain>/api/v1/oauth/token) (Authentication API Reference)tokenUrl of oauth2ClientCredentials
A user token of an application (sign-in from an external tool)Authorization Code flow (Authentication Guide)oauth2AuthorizationCode, only in environments where the entrance for sign-in from an external tool is open
  • Sign-in from an external tool is available only in environments where an administrator has opened its entrance (API Setup Guide)
  • A user token obtained in any other way (such as the token used when signing in to the Main Screen) gets 404 Not Found
  • A missing or invalid token gets 401 Unauthorized

Versions and Methods​

The request header A2A-Version decides the version (not sent or 0.3 is 0.3, 1.0 is 1.0, anything else is -32009). Method names and the shape of streaming events follow the A2A specification and are the same as in the SaaS edition. The task shape is the same as in the SaaS edition for the registered Agent endpoint; for the published workflow endpoint, a task is one run (see the sections below). See "Versions", "JSON-RPC Methods", and "Task Shape" in the A2A API Reference (SaaS edition).

Registered Agent Endpoint​

POST /api/v1/a2a/agents/{agentId}/ sends a task to that registered Agent. Versions, methods, task shape, where a message goes, listing, canceling, and resubscribing are the same as A2A in the SaaS edition, with the following differences.

ItemMarketplace edition
Available methodsSend, streaming, get, cancel, and resubscribe (0.3 and 1.0), and list (ListTasks on 1.0)
Task shapeThe whole conversation on 0.3, one request on 1.0 (same as the SaaS edition)
Task ID on 1.0An ID per registered Agent. Sending it to another Agent's endpoint returns -32001 (Task Not Found)
metadata of a messageagentMode, agentLevel, reportMode, and personaKey are not used (sending them has no effect)
Attached filesContent parts (base64) only; URL parts are not supported
Answering a questionThe same contextId on 0.3, the same taskId on 1.0 (same as the SaaS edition)

Where a message goes (the combination of taskId and contextId), listing, canceling, and resubscribing work the same as in the SaaS edition.

Published Workflow Endpoint​

POST /api/v1/a2a/projects/{projectId}/ runs the published workflow once (a run). One message starts one run, and a task is a run.

Who can call it​

  • A system integration (service account) token
  • Among users who signed in from an external tool, the owners of that project. A member who is not an owner is rejected with owner_only, and someone who is not a member with project_not_found

Input​

Message partsInput to the run
Text parts (one or more)A string joining them with line breaks
Exactly one data part (whose content is a JSON object)That object
Text and data mixed, two or more data parts, or data that is not an object-32602 (INVALID_INPUT)
File parts-32005 (files are not supported)

The input must be 8,000 characters or less as JSON and 16 KB or less in UTF-8 (about 5,000 Japanese characters). Beyond that, the response is -32602 (PAYLOAD_TOO_LARGE).

Sending​

SettingResponse
configuration.returnImmediately: true on 1.0, or configuration.blocking absent or false on 0.3Returns the task of the started run (submitted on 0.3, TASK_STATE_SUBMITTED on 1.0) right away
Otherwise (waiting)Waits until the run finishes and returns the task in its final state. By default it waits at most 2 hours; beyond that the response is -32603 (EXECUTION_TIMEOUT). The run keeps going, so follow it with get (GetTask / tasks/get). Sending it again as a new message starts another run
  • When the same caller sends again with the same messageId and the same input, no new run starts and the earlier run is returned. With the same messageId and different input, the send is rejected
  • A send with taskId is rejected (each message starts a new run). If that run exists the response is -32004, otherwise -32001
  • contextId is always the projectId. Sending another value returns -32602 (CONTEXT_NOT_FOUND)

Task states​

Run state0.31.0
RunningworkingTASK_STATE_WORKING
Waiting for review (a review request a person decides in the AGENTIC STAR screen)workingTASK_STATE_WORKING
CompletedcompletedTASK_STATE_COMPLETED
FailedfailedTASK_STATE_FAILED
RejectedrejectedTASK_STATE_REJECTED
CanceledcanceledTASK_STATE_CANCELED

status.message holds the run's summary (if there is none, the output summary of the step that finished last; if neither exists, it is absent). Artifacts (artifacts) and history (history) are not returned.

Getting and listing​

  • params.id of get (tasks/get / GetTask) is the task ID (the run ID) returned when you sent the message
  • List (ListTasks on 1.0) returns the runs that the caller started in that project. You can filter by state (status) and time (statusTimestampAfter), the page size (pageSize) is 1 to 100 (default 50), and pageToken reads the next page. The state may lag behind get by up to about 1 minute

What is not supported​

OperationResponse
Cancel (tasks/cancel / CancelTask)-32004
Streaming (message/stream / SendStreamingMessage) and resubscribing (tasks/resubscribe / SubscribeToTask)-32004 (no run is started)
Push notification configuration-32003

Errors​

The error codes are the same as in the SaaS edition (A2A API Reference (SaaS edition) — Error Codes). Scopes are not checked, so MISSING_SCOPE is not returned, and personaKey is not used, so INVALID_PERSONA_KEY is not returned either. The ones specific to the Marketplace edition are below. The detail code is in error.data.code on 0.3 and in error.data[].metadata.code on 1.0.

CaseEndpoint (POST)Agent Card (GET)
The registered Agent does not exist or is disabled-32602 (agent_not_found)404 (agent_not_found)
The workflow is not published or does not exist, or the caller is not a member-32602 (project_not_found)404 (project_not_found)
A member who is not an owner-32600 (owner_only)403 (owner_only)
The input to a published workflow is not in an accepted form-32602 (INVALID_INPUT)—
The input to a published workflow is too long-32602 (PAYLOAD_TOO_LARGE)—
The list of registered Agents has never been read, or the list of published workflows cannot be read-32603 (with guidance to wait and retry)503

A project that is not published, does not exist, or is a cycle all return the same project_not_found, without telling which. Agent Card errors use the same error format as the REST API.

See Also​