skills/copilotkit-integrations/references/integrations/a2a.md
CopilotKit supports multi-agent architectures via two A2A patterns: A2A Middleware (orchestrating multiple agents from different frameworks) and A2A + A2UI (agents that render UI components declaratively).
The A2A Middleware pattern enables a frontend to communicate with multiple specialized agents built with different frameworks. An orchestrator coordinates the agents, and the middleware injects a send_message_to_a2a_agent tool.
Next.js UI (CopilotKit)
| AG-UI Protocol
A2A Middleware
| A2A Protocol
+---> Research Agent (LangGraph, port 9001)
+---> Analysis Agent (ADK, port 9002)
^
|
Orchestrator (ADK, port 9000)
import {
CopilotRuntime,
ExperimentalEmptyAdapter,
copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { HttpAgent } from "@ag-ui/client";
import { A2AMiddlewareAgent } from "@ag-ui/a2a-middleware";
import { NextRequest } from "next/server";
export async function POST(request: NextRequest) {
const researchAgentUrl =
process.env.RESEARCH_AGENT_URL || "http://localhost:9001";
const analysisAgentUrl =
process.env.ANALYSIS_AGENT_URL || "http://localhost:9002";
const orchestratorUrl =
process.env.ORCHESTRATOR_URL || "http://localhost:9000";
// Connect to orchestrator via AG-UI Protocol
const orchestrationAgent = new HttpAgent({ url: orchestratorUrl });
// A2A Middleware wraps orchestrator and injects send_message_to_a2a_agent tool
const a2aMiddlewareAgent = new A2AMiddlewareAgent({
description: "Research assistant with 2 specialized agents",
agentUrls: [researchAgentUrl, analysisAgentUrl],
orchestrationAgent,
instructions: `
You are a research assistant that orchestrates between 2 specialized agents.
- Research Agent (LangGraph): Gathers and summarizes information
- Analysis Agent (ADK): Analyzes research findings
When the user asks to research a topic:
1. Research Agent - gather information
2. Analysis Agent - analyze the findings
3. Present the complete research and analysis
`,
});
const runtime = new CopilotRuntime({
agents: {
a2a_chat: a2aMiddlewareAgent,
},
});
const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
runtime,
serviceAdapter: new ExperimentalEmptyAdapter(),
endpoint: "/api/copilotkit",
});
return handleRequest(request);
}
Key patterns:
A2AMiddlewareAgent from @ag-ui/a2a-middleware wraps the orchestratoragentUrls lists all A2A-compatible agent endpointsorchestrationAgent is the main agent that receives requests from the UIinstructions guide the orchestrator on how to use the specialized agentssend_message_to_a2a_agent toolagentUrlsinstructions to describe the new agentpackage.jsonA2UI (Agent-to-UI) enables agents to render UI components declaratively. The agent defines UI components in its prompt, and CopilotKit renders them.
In A2A + A2UI, most of the UI is generated by the agent rather than defined in React components. The agent sends declarative component descriptions (calendars, inboxes, forms, etc.) which are rendered by CopilotKit's A2UI renderer.
The main page.tsx is minimal -- the agent drives the UI:
// Most UI comes from the agent via A2UI declarative components
// To see/edit the components, look in agent/prompt_builder.py
// Generate new components with the A2UI Composer: https://a2ui-editor.ag-ui.com
MCP Apps integrate Model Context Protocol servers as middleware on a BuiltInAgent:
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
const middlewares = [
new MCPAppsMiddleware({
mcpServers: [
{
type: "http",
url: "http://localhost:3108/mcp",
serverId: "threejs",
},
],
}),
];
const agent = new BuiltInAgent({
model: "openai/gpt-4o",
prompt: "You are a helpful assistant.",
});
for (const middleware of middlewares) {
agent.use(middleware);
}
const runtime = new CopilotRuntime({
agents: { default: agent },
});
Key patterns:
BuiltInAgent from @copilotkit/runtime/v2 (not an external agent)MCPAppsMiddleware adds MCP server tools to the agentmcpServers arraytype, url, and serverId