Mastra agents and the Client SDK now support the Agent-to-Agent (A2A) protocol by default. Run A2A agents as Mastra subagents, or invoke them via the Client SDK.
A2A is an open standard for delegating work to other A2A-enabled agents, regardless of framework, deployment vendor, or programming language.
Every A2A-enabled agent has an agent card, served at a .well-known URL, for example:
https://py.acme.com/api/a2a/.well-known/a2a-weather-agent/agent-card.jsonThe card describes the agent's capabilities and includes its execution endpoint:
{
"specVersion": "1.0",
"name": "Weather Agent",
"description": "A weather agent built with Google's Python ADK.",
"url": "https://py.acme.com/api/a2a/a2a-weather-agent", // execution endpoint
"provider": {
"organization": "Google",
"url": "https://github.com/google/adk-python"
},
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": false
},
"authentication": {
//...
},
"skills": [
//...
]
}Get started
There are two ways to interact with A2A-enabled agents using Mastra:
- Consuming A2A-enabled agents as subagents
- Sending requests to A2A-enabled agents using the Client SDK
Requires @mastra/core@1.33.1 and @mastra/client-js@1.18.1 or later, added in PR #16348.
Consuming A2A-enabled agents
Set up a remote agent with A2AAgent, passing in the .well-known card URL and any auth headers. Then attach it following Mastra's subagent pattern.
import { Agent } from "@mastra/core/agent";
import { A2AAgent } from "@mastra/core/a2a";
const a2aWeatherAgent = new A2AAgent({
url: "https://py.acme.com/api/a2a/.well-known/a2a-weather-agent/agent-card.json",
headers: {
"x-api-key": process.env.A2A_AGENT_API_KEY!
}
});
export const weatherAgent = new Agent({
id: "weather-agent",
name: "Weather Agent",
instructions: "Use the a2aWeatherAgent to provide weather information.",
model: "anthropic/claude-opus-4-6",
agents: {
a2aWeatherAgent
}
});Sending requests to A2A-enabled agents
The Client SDK works with A2A-enabled agents: Mastra agents, a Google ADK service, a LangChain agent, or anything that speaks the protocol.
Configure the MastraClient with your API's baseUrl and any auth headers. Use .getA2A() to get a reference to the agent, then call .sendMessageStream() to send requests and stream responses back.
import { MastraClient } from "@mastra/client-js";
const client = new MastraClient({
baseUrl: "https://py.acme.com/api/a2a/",
headers: {
"x-api-key": process.env.A2A_AGENT_API_KEY!
}
});
const agent = client.getA2A("a2a-weather-agent");
const stream = agent.sendMessageStream({
message: {
kind: "message",
role: "user",
messageId: crypto.randomUUID(),
parts: [{ kind: "text", text: "What's the weather in Prague?" }]
}
});For more information and full configuration options, see:
