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

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 – Implements the JSON-RPC workflow including Agent Card fetching, SendMessage and GetTask operations, and retry logic
• 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 – 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:

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, 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 creates an ACP session and pipes adapter events to the client:

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 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 – Complete TypeScript definitions for the A2UI v0.10 specification
• 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 – 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:

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) 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
• 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, 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, AG-UI types are in src/core/ag-ui/event-adapter.ts (exporting AGUIBaseEvent and related interfaces), and A2UI schema definitions are in src/client/a2ui/types.ts containing the complete v0.10 specification TypeScript mappings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}