copilotkit--copilotkit/skills/copilotkit-integrations/references/integrations/a2a.md

# A2A (Agent-to-Agent) Integration

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).

## A2A Middleware

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.

### Architecture

```
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)
```

### Prerequisites

- Node.js 18+
- Python 3.10+
- Google API key + OpenAI API key

### Next.js Route (app/api/copilotkit/[[...slug]]/route.ts)

```typescript
import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";
import { HttpAgent } from "@ag-ui/client";
import { A2AMiddlewareAgent } from "@ag-ui/a2a-middleware";
import { handle } from "hono/vercel";

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,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);
```

Key patterns:

- `A2AMiddlewareAgent` from `@ag-ui/a2a-middleware` wraps the orchestrator
- `agentUrls` lists all A2A-compatible agent endpoints
- `orchestrationAgent` is the main agent that receives requests from the UI
- `instructions` guide the orchestrator on how to use the specialized agents
- The middleware automatically injects the `send_message_to_a2a_agent` tool

> The shipped `a2a-middleware` example subclasses `A2AMiddlewareAgent` to recreate an isolated middleware agent per run (overriding `runAgent`/`clone`) so concurrent threads don't share orchestrator state. The flat construction above is the pedagogical baseline; reach for the per-run subclass pattern when serving multiple concurrent users.
>
> Cross-reference: the `runtime` skill documents an alternate single-agent A2A path using `A2AAgent` from `@ag-ui/a2a` (connecting directly to one A2A server). Use `A2AMiddlewareAgent` from `@ag-ui/a2a-middleware` (shown here) when orchestrating multiple A2A agents from one chat.

### Adding New Agents

1. Create a new Python agent implementing the A2A protocol
2. Register its URL in `agentUrls`
3. Update the middleware `instructions` to describe the new agent
4. Add a dev script to `package.json`

---

## A2A + A2UI

A2UI (Agent-to-UI) enables agents to render UI components declaratively. The agent defines UI components in its prompt, and CopilotKit renders them.

### Prerequisites

- Python 3.12+
- Node.js 20+
- Gemini API key

### Key Difference from Standard Integrations

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.

### Frontend

The main `page.tsx` is minimal -- the agent drives the UI:

```tsx
// 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
```

### Resources

- [A2UI + CopilotKit Documentation](https://docs.copilotkit.ai/a2a)
- [A2UI Specification](https://a2ui.org)
- [A2UI Composer](https://a2ui-editor.ag-ui.com) -- visual tool for creating A2UI components

---

## MCP Apps

MCP Apps integrate Model Context Protocol servers as middleware on a `BuiltInAgent`:

```typescript
import {
  CopilotRuntime,
  BuiltInAgent,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
import { handle } from "hono/vercel";

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 },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);
```

Key patterns:

- Uses `BuiltInAgent` from `@copilotkit/runtime/v2` (not an external agent)
- `MCPAppsMiddleware` adds MCP server tools to the agent
- Multiple MCP servers can be added in the `mcpServers` array
- Each server needs `type`, `url`, and `serverId`