# A2A, AG-UI, and A2UI Integration Protocols in Routa: A Complete Technical Guide

> Explore Routa's A2A, AG-UI, and A2UI integration protocols. Learn how JSON-RPC, SSE streaming, and declarative JSON enable seamless agent and UI interactions in this technical guide.

- Repository: [Fengda Huang/routa](https://github.com/phodal/routa)
- Tags: deep-dive
- Published: 2026-05-26

---

**Routa implements three distinct protocol surfaces—A2A for agent-to-agent interoperability via JSON-RPC, AG-UI for real-time SSE streaming of ACP session updates to web clients, and A2UI for declarative JSON-based dashboard generation—each normalized into domain-level calls through specific adapter patterns in the `phodal/routa` codebase.**

The `phodal/routa` repository provides a unified architecture for agent orchestration where all external interactions are treated as **protocol surfaces** normalized into domain-level calls. These three protocols enable seamless cross-agent coordination, real-time UI streaming, and rich dashboard rendering while maintaining consistent routing and persistence mechanisms.

## A2A Protocol: Agent-to-Agent Interoperability

The **A2A (Agent-to-Agent)** protocol enables Routa agents to invoke remote A2A-compatible agents and track their task lifecycle through JSON-RPC communication. This protocol handles the outbound flow from Routa to external agent endpoints.

### Core Implementation

The A2A implementation resides in `src/core/a2a/` and consists of three critical components:

- **[`src/core/a2a/a2a-outbound-client.ts`](https://github.com/phodal/routa/blob/main/src/core/a2a/a2a-outbound-client.ts)** – Implements the JSON-RPC workflow including Agent Card fetching, `SendMessage` and `GetTask` operations, and retry logic
- **[`src/core/a2a/a2a-task-bridge.ts`](https://github.com/phodal/routa/blob/main/src/core/a2a/a2a-task-bridge.ts)** – Maps Routa internal `AgentStatus` to A2A task states and registers remote tasks in the local task registry
- **[`src/core/a2a/types.ts`](https://github.com/phodal/routa/blob/main/src/core/a2a/types.ts)** – Defines shared TypeScript interfaces including `A2AOutboundClientOptions` and RPC request/response shapes

### Triggering Remote Agents

To invoke a remote A2A agent, use the `getA2AOutboundClient` singleton and call `sendMessageAndWait`:

```typescript
import { getA2AOutboundClient } from "@/core/a2a";
import type { A2ATask } from "@/core/a2a/a2a-task-bridge";

async function invokeRemoteAgent(url: string, prompt: string): Promise<A2ATask> {
  // Resolve the singleton outbound client
  const client = getA2AOutboundClient();

  // Fetch Agent Card, send RPC request, and poll until terminal state
  const task = await client.sendMessageAndWait(url, prompt);

  // Returned task conforms to Routa's A2ATask shape
  return task;
}

```

The `sendMessageAndWait` method internally handles the complete A2A workflow: fetching the Agent Card from the remote URL, determining the correct RPC endpoint, sending the initial message, and polling the task status until completion.

## AG-UI Protocol: Real-Time UI Streaming

The **AG-UI (Agent-Generated UI)** protocol translates ACP (Agent Communication Protocol) session updates into **SSE (Server-Sent Events)** compatible streams. This enables web clients to consume real-time agent activity including tool calls, reasoning blocks, and run status updates.

### Event Adaptation Architecture

The protocol centers on the `RoutaToAGUIAdapter` class in [`src/core/ag-ui/event-adapter.ts`](https://github.com/phodal/routa/blob/main/src/core/ag-ui/event-adapter.ts), which performs stateful mapping of ACP notifications to `AGUIBaseEvent` types:

- **`TEXT_MESSAGE_START`** and **`TEXT_MESSAGE_CONTENT`** events for streaming text
- **`TOOL_CALL_START`** and **`TOOL_CALL_RESULT`** events for tool execution visualization
- Session lifecycle events indicating turn completion or errors

### SSE Endpoint Implementation

The API route at [`src/app/api/ag-ui/route.ts`](https://github.com/phodal/routa/blob/main/src/app/api/ag-ui/route.ts) creates an ACP session and pipes adapter events to the client:

```typescript
import { RoutaToAGUIAdapter, AGUIEventType } from "@/core/ag-ui/event-adapter";

function handleSessionUpdate(notification: SessionUpdateNotification) {
  const adapter = new RoutaToAGUIAdapter("thread-123", "run-456");
  const aguiEvents = adapter.convert(notification);

  // Events are flushed as SSE text/event-stream data
  aguiEvents.forEach(ev => {
    console.log(`[${ev.type}]`, ev);
  });

  // Flush open streams when run completes
  if (notification.update.sessionUpdate === "turn_complete") {
    adapter.flush();
  }
}

```

Client-side components like [`src/client/components/ag-ui-trace-panel.tsx`](https://github.com/phodal/routa/blob/main/src/client/components/ag-ui-trace-panel.tsx) subscribe to this SSE endpoint to render live chat-like experiences with full tool-call visualization.

## A2UI Protocol: Declarative Dashboard Interface

The **A2UI (Agent-to-User Interface)** protocol provides a **declarative JSON schema (v0.10)** that allows agents to emit rich UI components—including tables, charts, forms, and cards—without generating raw HTML. This enables dashboard-style interfaces rendered entirely from JSON messages.

### Component Rendering Pipeline

The A2UI implementation in `src/client/a2ui/` follows a message-to-surface pipeline:

- **[`src/client/a2ui/types.ts`](https://github.com/phodal/routa/blob/main/src/client/a2ui/types.ts)** – Complete TypeScript definitions for the A2UI v0.10 specification
- **[`src/client/a2ui/renderer.tsx`](https://github.com/phodal/routa/blob/main/src/client/a2ui/renderer.tsx)** – React renderer that converts `A2UIMessage` arrays into `A2UISurface` maps and then into React elements
- **[`src/client/a2ui/dashboard-generator.ts`](https://github.com/phodal/routa/blob/main/src/client/a2ui/dashboard-generator.ts)** – Helper utilities that transform workspace data (tasks, agents, statistics) into valid A2UI message sequences

### Generating Dashboards

To render an A2UI dashboard, generate messages using the dashboard generator and pass them to the viewer component:

```tsx
import { A2UIViewer } from "@/client/a2ui";
import { generateDashboardA2UI } from "@/client/a2ui/dashboard-generator";
import type { DashboardData } from "@/client/a2ui/dashboard-generator";

const data: DashboardData = {
  agents: [{ id: "a1", name: "CodeBot", status: "idle" }],
  tasks: [{ id: "t1", title: "Build", state: "queued" }],
};

// Generate A2UI message list representing the UI structure
const messages = generateDashboardA2UI(data);

// Render via the A2UI viewer component
export default function Dashboard() {
  return <A2UIViewer messages={messages} />;
}

```

The renderer processes these messages through `processA2UIMessages` to build interactive surfaces that support user feedback (such as button clicks) back to the originating agent.

## How the Protocols Integrate

These three protocol surfaces serve distinct but complementary roles within Routa's architecture:

1. **A2A** operates as the *backend-to-backend* bridge, enabling Routa-native agents to orchestrate external agents through the `A2ATask` registry and JSON-RPC workflows

2. **AG-UI** functions as the *real-time streaming* layer, surfacing ACP session activity—including tasks initiated via A2A—through SSE endpoints for immediate UI consumption

3. **A2UI** serves as the *structured description* layer for rich dashboards, allowing agents to declaratively specify complex UI layouts rendered client-side by the React renderer

All three protocols share the same **domain services** (`RoutaSystem` in [`src/core/routa-system.ts`](https://github.com/phodal/routa/blob/main/src/core/routa-system.ts)) and rely on the protocol-adapter pattern. This normalization ensures consistent routing, persistence, and eventing whether a task originates from native ACP sessions, A2A remote calls, or A2UI dashboard interactions.

## Summary

- **A2A** enables cross-agent interoperability through JSON-RPC Agent Cards and task polling, implemented in `src/core/a2a/`
- **AG-UI** streams ACP updates as SSE events via the `RoutaToAGUIAdapter` in [`src/core/ag-ui/event-adapter.ts`](https://github.com/phodal/routa/blob/main/src/core/ag-ui/event-adapter.ts)
- **A2UI** provides declarative JSON schemas for dashboard generation, rendered by the React components in `src/client/a2ui/`
- All protocols normalize external interactions into Routa's internal domain model through the `RoutaSystem` service layer

## Frequently Asked Questions

### What is the difference between AG-UI and A2UI?

**AG-UI** is a real-time streaming protocol that converts ACP session updates into SSE events for live chat-like interfaces, while **A2UI** is a declarative JSON protocol for generating static dashboard layouts with tables, charts, and forms. AG-UI handles temporal activity streams; A2UI handles spatial UI composition.

### How does A2A handle authentication with remote agents?

According to the implementation in [`src/core/a2a/a2a-outbound-client.ts`](https://github.com/phodal/routa/blob/main/src/core/a2a/a2a-outbound-client.ts), the A2A client fetches the remote Agent Card to discover authentication requirements and RPC endpoints. The client supports configurable options through `A2AOutboundClientOptions` for handling credentials and retries, though specific authentication mechanisms depend on the remote agent's published capabilities.

### Can these protocols be combined in a single workflow?

Yes. A typical integrated workflow might use **A2A** to invoke a remote specialized agent, **AG-UI** to stream the remote agent's progress to a web interface in real-time, and **A2UI** to render a summary dashboard of the completed task. All three share the same task registry and domain services, enabling seamless coordination.

### Where are the protocol type definitions located in the Routa codebase?

**A2A** type definitions are in [`src/core/a2a/types.ts`](https://github.com/phodal/routa/blob/main/src/core/a2a/types.ts), **AG-UI** types are in [`src/core/ag-ui/event-adapter.ts`](https://github.com/phodal/routa/blob/main/src/core/ag-ui/event-adapter.ts) (exporting `AGUIBaseEvent` and related interfaces), and **A2UI** schema definitions are in [`src/client/a2ui/types.ts`](https://github.com/phodal/routa/blob/main/src/client/a2ui/types.ts) containing the complete v0.10 specification TypeScript mappings.