Test and troubleshoot A2A

Solutions for common errors when testing inbound or outbound A2A calls in Orchestrator, including authentication failures, missing agents, and timeouts.

Hinweis:

This functionality is in preview.

Test an A2A agent with direct calls before using it from a UiPath agent or an external client. Calling the agent yourself shows you the raw request and response, which tells you whether a problem is in the agent, in your authentication, or in the calling application.

Inbound and outbound calls fail for different reasons, so this page covers what applies to both directions first, then splits by direction. The URL you're calling identifies which half is yours:

• .../agenthub_/a2a/{folderKey}/{agentReleaseId} is inbound: an external client is calling a conversational agent deployed on the platform.
• .../agenthub_/a2a/remote/{folderKey}/{slug} is outbound: UiPath is calling an agent hosted elsewhere on the caller's behalf.

Test an agent with direct calls

The examples use cURL, but the same requests work from Postman, the A2A Python or .NET SDK (Software Development Kit), or a graphical A2A client.

Richtung	URL	Where to get it
Inbound	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	Automations > Processes > Copy A2A Card URL. {folderKey} is the key of the folder the agent is deployed in, and {agentReleaseId} is the release ID of the deployed conversational agent.
Ausgehend	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > A2A Agents, then Copy URL on the agent's row.

1. Set TOKEN to a bearer token and AGENT_URL to the URL for your direction.
2. Request the agent card first. A successful response confirms that the agent exists, the folder resolves for your identity, and your token is accepted:

   curl "$AGENT_URL/.well-known/agent-card.json" \
     -H "Authorization: Bearer $TOKEN"
   

3. Send a message to the JSON-RPC (JSON Remote Procedure Call) endpoint, which is the same address without the /.well-known/agent-card.json suffix:

   curl -X POST "$AGENT_URL" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "message/send",
       "params": {
         "message": {
           "role": "user",
           "messageId": "msg-1",
           "parts": [{"kind": "text", "text": "Hello"}]
         }
       }
     }'
   

The response carries a contextId. Including it on the next message continues the same conversation; the conversation ID, the task ID, and the contextId are the same value. message/stream returns the reply as an SSE (Server-Sent Events) stream: add -N to stop cURL from buffering, and -H "Accept: text/event-stream".

If an outbound call through UiPath fails, sending the same request directly to the remote agent, using the credentials the agent expects, tells you whether the problem is with UiPath or with the agent itself.

Errors common to both directions

401 Nicht autorisiert

The request reached UiPath, but the token wasn't accepted.

Ursache	Resolution
The token expired	Get a new token. Interactive login tokens expire after one hour; a Personal Access Token has a configurable expiration.
The token was issued for a different tenant	Check that the organization and tenant in the agent URL match those the token was issued for.
The header is malformed	The format is Authorization: Bearer <your-access-token>.
No token was sent	Every request, including the agent card request, must include a token.

Timeouts

Grenzwert	GiltFür	Was passiert?
15 minutes	Any single request through UiPath.	The request is cut off. Within that window, a streamed response continues for as long as both sides keep the connection open.
5 Minuten	One turn of an inbound conversation.	The turn fails. The task remains usable and the turn can be retried.
30 Sekunden	Starting the agent session behind an inbound turn.	As above.
5 Minuten	An outbound agent called as a tool from a UiPath agent.	The tool call fails, and the error text reaches the UiPath agent as tool output.

For work that runs longer than a single request allows, stream the response, or use A2A tasks: take the task identifier from the first response and poll for its result.

Protocol and card versions

Both directions select the A2A protocol version with the A2A-Version header, including on the agent card request. Set it to 1.0 for v1.0, or omit it for v0.3 (an empty or blank value is treated the same way).

Inbound, the value is matched exactly, so 1.0 is recognized and 1.0.0 isn't. The inbound endpoint accepts either wire format, whichever card you fetched, so the header there only changes which card you get.

Outbound, only the major and minor version are read, so 1.0 and 1.0.0 both select v1.0. UiPath forwards a request only to an endpoint that matches the requested version, so a request for a version the stored card can't satisfy is rejected with 400.

Inbound (external to UiPath)

There's nothing to register in this direction, so every failure happens on a call. tasks/get returns a conversation's current state and history. For what the direction requires, check Inbound (external to UiPath).

The folder or agent isn't found (404)

Meldung	Ursache	Resolution
Folder with key {folderKey} not found	The folder key is wrong, or names a folder the caller can't access.	Check the URL and the caller's folder access.
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	No conversational agent is deployed under that release ID in that folder.	Check the release ID against the agent's entry under Automations > Processes.

A folder key that resolves is cached for 30 minutes. A key that doesn't resolve isn't cached, so granting a user access to a folder takes effect on their next call. A folder that's been deleted, or whose access has been withdrawn, keeps resolving until its cached entry expires.

Only the agent card endpoint validates the release ID before responding, so request the agent card first when diagnosing. On message/send, an incorrect release ID isn't reported as clearly.

The caller is refused by the agent

Passing the folder lookup isn't the same as being authorized. For what the caller needs, check What the caller needs.

The conversation doesn't continue

Symptome	Ursache	Resolution
A follow-up message starts a fresh conversation	The contextId doesn't match a task UiPath holds.	Send taskId alongside contextId; an unrecognized ID is then reported as Task not found.
Task not found, for an ID that worked before	The task expired after seven days of inactivity, or the request went to a different folder or release ID.	Send the request to the folder and process the task was created under, or start a new task.
Cannot send a message to a task in a terminal state.	The task is completed, canceled, failed, or rejected.	Start a new task.
Task is in a terminal state and cannot be canceled.	The task has already reached a terminal state, and tasks/cancel only applies to a task that's still in progress.	No action needed. The task has already stopped.

Requests that aren't supported

These return a JSON-RPC error inside a successful HTTP response.

Request	Was Sie erhalten	Use instead
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	Track task IDs on the client
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream. The card advertises pushNotifications: false
The extended agent card	ExtendedAgentCardNotConfigured	The ordinary card

A negative historyLength on tasks/get is rejected with InvalidParams.

Outbound (UiPath to external)

A call in this direction is authenticated twice: once by the caller to UiPath, and once by UiPath to the agent. Most failures come from the second hop. Related calls are grouped in Traces by contextId. For setup, check Outbound (UiPath to external).

Saving an agent fails

Symptome	Ursache	Resolution
409 Conflict	Another agent in the folder already uses that name or slug.	Choose a different name or slug; both must be unique within the folder. The slug can't be changed after creation.
The agent card is required	Neither a card URL nor card JSON was supplied.	Supply one of them.
The agent card isn't valid	The JSON isn't a card object, or publishes no JSON-RPC endpoint.	Supply the card as published by the remote agent.
The agent card URL isn't valid	The URL has no scheme, or isn't reachable over the public internet.	Enter an absolute http or https URL, or set Connection type to Private (Relay).

The caller isn't allowed to use the agent (403)

Ursache	Resolution
The caller lacks the View permission on MCP Servers	Enable View on MCP Servers for the assigned role.
The caller isn't assigned to the folder	Assign the caller to the folder that contains the agent.
No license is available	Check Admin > Licenses.

Retrieving the agent card needs access to the folder but not the View permission on MCP Servers. If the card loads but sending a message returns 403, the missing permission is View on MCP Servers.

The agent isn't found (404)

Ursache	Resolution
The URL contains the agent's display name instead of its slug	Use the slug, not the display name.
The folder key is wrong	The agent is looked up in the folder named in the URL. Copy the URL from the agent's row.
The agent was deleted	Confirm it still appears in Agent Gateway > A2A Agents.

The request isn't allowed (400)

The request already passed through the platform's A2A proxy, and a request that arrives that way is refused so that calls can't loop. This happens when a UiPath A2A agent URL is registered as a remote agent. Register the remote agent's own address instead.

The stored card is missing or out of date

The stored card isn't fetched again on later calls, so a card that changes upstream keeps serving its earlier contents. To bring it up to date, open the agent, select Edit, and supply the current card. The same screen shows the card as the remote agent published it, before UiPath rewrites the advertised endpoints.

Two failures follow from a card that's missing or stale:

Symptome	Ursache	Resolution
404 on the agent card, 400 on message/send	No card is stored for the agent, so there's nothing to serve.	Open the agent in Agent Gateway > A2A Agents and supply the card.
400, no endpoint for the requested A2A version	No A2A-Version header was sent but the agent only supports v1.0; or 1.0 was sent and the agent only supports v0.3; or the card publishes no JSON-RPC endpoint; or the remote agent changed and the stored card no longer matches it.	Send or omit the header to match what the agent supports, or supply the current card. Remote A2A agents must expose a JSON-RPC endpoint; other interface types aren't supported.

502, UiPath can't reach or authenticate to the remote agent

UiPath answers 502 when the hop to the remote agent fails, either while you're saving the agent or while it's being called.

While saving, UiPath retrieves the agent card, and the agent isn't created if that fails:

Ursache	Resolution
The URL isn't reachable from UiPath	Confirm the URL resolves publicly, or use Private (Relay).
The agent requires authentication that isn't configured	Add the header or connection the agent expects, then save again.

On a call, a connection that's attached but can't provide a token fails the call, since the connection is then the only source of the Authorization header. Open User configurations on the agent's row and check the connection status (see Per-user connections for what each status means). An Inactive status means the connection is disabled, so check it in the Connections tab.

If credentials resolve but the agent still can't be reached:

Ursache	Resolution
The agent is on a private network	Set Connection type to Private (Relay).
The address can't be resolved, or the certificate isn't accepted	Check the endpoint published on the agent card, which is often a different host from the card URL.
The agent isn't running	Call the agent directly to confirm.
The agent moved	The stored card still points at the old address. Supply the current card.

A header that references an asset can't be resolved

A header value in the form %ASSETS/AssetName% is resolved before the request is sent, and if the asset can't be read the call fails without ever sending the unresolved value.

Ursache	Resolution
The asset doesn't exist in the agent's folder	Create it in Orchestrator, or reference an asset that does.
The caller can't read the asset	Grant the View permission on Assets.
The asset type isn't supported	A header must resolve to a single value, so key-value-list assets are rejected. For the types that work, check Referencing an Orchestrator asset.

The call times out (504)

On a direct call, the remote agent didn't begin responding in time. The limit applies to how long the agent takes to begin responding; once it starts, a stream can continue well beyond that point. Use message/stream, or return a task and poll for the result, for an agent that needs longer to start responding. If it keeps timing out, call it directly to confirm it's reachable and check its own logs.

The response is too large

Responses from a remote agent are subject to a size limit. A response that exceeds it is rejected, and a streamed response that grows past it is stopped part-way, after the calling application has already received some events. If an agent returns large content, have it return a reference such as a URL instead.

Calling an agent from a UiPath agent

When a registered agent is attached as a tool in Agent Builder or a Maestro flow, an error from the remote agent is returned to the UiPath agent as tool output, with a task state of error, and the run continues. The UiPath agent carries on with that text as its input, so an error looks like an ordinary tool result to the model. To diagnose a failing call, open Traces for the run and select the tool call for the agent; the trace records the message sent and the response or error returned.

UiPath agents call remote agents with message/send, so use that when you're reproducing what a UiPath agent does. Streaming is only available when you call the agent's UiPath URL yourself.

On this path the platform waits five minutes for the complete response, and output produced gradually doesn't extend that wait. For an agent that needs longer, have it return a task that's still in progress: the platform keeps the task between turns, so the UiPath agent can continue it on a later turn. A task that has already reached completed, canceled, failed, or rejected can't be continued, and the next call starts a new task within the same conversation.

If the stored card publishes neither a v1.0 JSON-RPC interface nor a usable v0.3 endpoint, the tool can't be created at all, and the run reports that no compatible endpoint is available. Open the agent, select Edit, and confirm the card exposes a JSON-RPC endpoint over http or https.

Calls succeed but behave unexpectedly

These are the failures where nothing errors, so there's no status code to go on.

Symptome	Ursache	Resolution
Calls use the wrong identity	A connection configured for the calling user takes precedence over the agent's default connection.	Check User configurations for a connection you didn't expect.
A configured Authorization header appears to be ignored	A connection is attached, and the connection provides that header.	Expected. Every other header you configured is still sent.
A connection you expect is missing from the list	Connections are filtered by the address published on the agent card, which is often a different host from the card URL you registered.	Check that the connection is enabled, and that it's in a shared folder or in the selected user's personal workspace.
A UiPath agent describes the remote agent's abilities incorrectly, or doesn't use it when expected	The tool description and the list of skills come from the stored agent card.	Bring the stored card up to date, then open the UiPath agent and confirm the updated description.
A call isn't grouped with the rest of its conversation in Traces	The first message of a conversation has no contextId yet.	No action needed. Later messages in the conversation are grouped.