External Agent (A2A) Step

Call an agent that runs outside Airia and speaks the Agent2Agent (A2A) protocol, from inside an agent workflow.

Use the External Agent (A2A) step to send text to an agent that runs outside Airia and get its answer back as the step output. The remote agent must speak the Agent2Agent (A2A) protocol and publish an agent card.

When to use this step

Hand a task to a partner's or another team's agent and use the reply in later steps
Stream a remote agent's answer to the chat while it is still being written
Reuse an agent you cannot rebuild in Airia

Authentication for external agents is coming soon. Until then, the step sends no credentials, so it works only with agents that accept unauthenticated requests.

Before you start

You need:

The full URL of the remote agent's card. Airia fetches exactly the URL you give it and does not add a path such as /.well-known/agent-card.json.
Permission to manage agents in the project.
A card that lists at least one supported interface with a URL.

The card URL must be reachable from the public internet. Airia refuses addresses it cannot fetch, such as local or private network addresses. Only http and https are allowed, the response must be smaller than 1 MiB, and the server must answer within 30 seconds.

Import the agent card

Open the import dialog

Open the project, go to its Agents tab, open the menu next to Add a New Agent, and choose Import External Agent. The option is only on a project's Agents tab, not on the list of all agents.

Enter the card URL

In Add External Agent, enter the Agent URL and select Discover Agents.

Pick the agents

Airia shows how many agents it found and lists each one with its name, version, description, and provider. Select one or more agents and choose Add Agent (or Add Agents).

The dialog accepts a single card, a list of cards, or an object with an agents field. Each card needs a name, description, version, capabilities, skills, and at least one supported interface with a URL, a protocol binding, and a protocol version. Cards that use an older style with only a top-level url are not supported.

Each imported card also creates an agent in the project, with the card's name. It appears in the Agents list with an External badge and has a published flow of Input, External Agent and Output steps. The External Agent step in that flow is titled Agent Card.

Importing is a one-time read. Airia does not refresh a card after you add it, and there is no way to edit or delete an imported card. Deleting the agent that the import created does not remove the card.

Add the step to an agent

Open the agent in the builder.
In the Agents category of the item drawer, drag External Agent (A2A) onto the canvas.
The Available External Agents list opens when you drop the step. To reopen it, use Add, or the refresh icon once an agent is chosen. Search by agent name and select the agent. After selecting, use See details to read the card.
Connect the step. It accepts zero or one incoming connection.

The step has one setting, the agent you selected. There is no streaming toggle, and there is no credential field until authentication arrives.

The details dialog shows the card's skills, version, provider, response types, the full card JSON, and whether it supports streaming and push notifications. This is for information only. It does not change how Airia calls the agent. The API Key row says Configured when the card lists a security scheme. That does not mean Airia holds a credential for the agent.

How Airia calls the agent

Airia uses the first interface listed on the card and sends one text message to its URL.

What is sent: one user message with a single text part. The text is the output of the step before it. If nothing is connected, the text is empty.
Message id: every call carries a message id. If a step is retried, Airia resends the same id so the remote agent can recognize the repeat. Each new run, and each new loop iteration, sends a new id.
Not sent: files, structured data, earlier messages, or task and context ids.

Streaming

Airia streams the answer only when all of these are true:

The chat stream is active.
The next step is an Output step.
The run delivers output asynchronously.
The card says it supports streaming.

Otherwise Airia makes one request and waits for the full reply. Runs started by event triggers use the one-request mode.

What becomes the step output

The step output is plain text. Airia keeps only the text parts of what the remote agent sends. File and data parts are ignored.

Reply from the remote agent	Text Airia keeps
A message	The message text
A task	The text of the task's artifacts. The task's status message is not used.
An artifact update (streaming)	The text of that artifact
A status update (streaming)	The text of the status message, if there is one

When streaming, Airia appends the text of every event to one buffer, forwards it to the chat as it arrives, and returns the whole buffer as the step output.

When Airia makes one request, it does not look at the task state. A task that comes back as failed, rejected, canceled, input required, or auth required does not raise an error. The step returns whatever artifact text there is, which may be empty. A completed task whose answer is only in its status message also returns empty text.

When streaming, a remote state of completed marks the end of the answer in the chat. Airia keeps reading until the remote agent closes the connection. A state of failed, rejected, or auth-required shows an error in the chat stream. A state of submitted, input-required, canceled, or unknown fails the step.

Retries

The step has no retry setting in the builder. When the step is inside a loop with Retry on error turned on, a failed attempt is retried. Only timeouts and temporary server errors (such as 429, 500, 502, 503 and 504) are retried, and a retry sends the same message id.

Separately, Airia retries the network request itself up to three times when the connection fails or the server returns a temporary error. Those retries resend the same request, so a step can take several seconds to fail when the agent is unreachable.

Use the answer in later steps

Later steps read the remote agent's answer as text:

{{Steps.<YourStepName>.Value}}: the text the remote agent returned.

Spaces in the step name become underscores. For the step an import creates, that is {{Steps.Agent_Card.Value}}.

Example

Ask a partner's agent and summarize its answer for the user.

Input: the user's question.
External Agent (A2A): sends the question to the partner's agent.
AI Model: prompt Summarize this answer in three bullet points: {{Steps.Agent_Card.Value}}.
Output: returns the summary.

Limits

Text only, in both directions.
No credentials or custom headers are sent to the external agent yet. Authentication is coming soon.
No multi-turn conversations. A remote agent that asks for more input cannot be answered.
Only the first interface on the card is used, with no fallback to others.
Push notifications, the authenticated extended card, and card signatures are not used.
Security schemes on the card are stored and shown but not applied when the step runs.
Stopping a run does not send a cancel request to the remote agent. The remote task may keep running.
Other A2A clients cannot call Airia agents over the A2A protocol.

Where else you will see external agents

In the Agents list, agents created from an imported card show an External badge.
Imported cards are included when you export an agent and are recreated when you import it.
Red teaming has its own External Agent dialog that can import the same kind of card.

Troubleshooting

Symptom	Fix
Discovery says the address is blocked	Use a publicly reachable URL. Localhost and private addresses are refused.
Discovery fails with an HTTP error or timeout	Open the URL in a browser. It must return the card as JSON within 30 seconds and be under 1 MiB.
"Invalid external agents response format"	The response is not a supported card shape. Check the required fields above.
The run returns no output, and the execution log says the step "has no supported interface"	The card has no entry with a URL under supported interfaces. Import a card that lists one.
The step fails with "Name or service not known"	Airia cannot reach the host in the card's first interface. Check that the agent's address is public and correct.
The step returns empty text	The remote agent put its answer in a status message or a non-text part. Airia keeps only artifact text from a task and text parts.
The remote agent rejects the call	The agent likely requires authentication, which is coming soon to this step. Until then, use an agent that accepts unauthenticated requests.

HTTP Request Step for calling a service that does not speak A2A