Protocols

Agent Runtimes supports multiple runtime and extension protocols. This page covers protocol selection, protocol capabilities, and extension-layer protocols for rich UI experiences.

Runtime Protocols

Runtime protocols define how clients and agents communicate.

Protocol Comparison

Feature	AG-UI	Vercel AI	ACP	A2A
Transport	HTTP/SSE	HTTP/SSE	WebSocket	HTTP/SSE
Streaming	✅	✅	✅	✅
Tool Calling	✅	✅	✅	✅
Per-Request Model Selection	✅	✅	✅	❌
Bidirectional Communication	❌	❌	✅	❌
Human-in-the-Loop	✅	❌	✅	❌
Inter-Agent Communication	❌	❌	❌	✅

AG-UI (Agent UI Protocol)

AG-UI is a lightweight protocol optimized for building interactive AI chat interfaces.

Features:

Simple HTTP/SSE-based communication
Built-in support for streaming responses
Tool calling with human-in-the-loop approval
Native support for frontend components

Use Cases:

Web chat applications
Interactive AI assistants
Applications requiring tool approval workflows

Endpoint: POST /api/v1/ag-ui/agents/{agent_id}/runs

// Frontend usage
const adapter = new AGUIAdapter({
  type: 'ag-ui',
  baseUrl: 'http://localhost:8888/api/v1/ag-ui/agents/demo',
});

Vercel AI Protocol

Compatible with Vercel's AI SDK, enabling seamless integration with Next.js and React applications.

Features:

Vercel AI SDK compatibility
Server-Sent Events (SSE) streaming
Tool calling support
Easy integration with existing Vercel projects

Use Cases:

Next.js applications
Projects already using Vercel AI SDK
Quick prototyping with familiar APIs

Endpoint: POST /api/v1/vercel-ai/agents/{agent_id}/chat

// Frontend usage
const adapter = new VercelAIAdapter({
  type: 'vercel-ai',
  baseUrl: 'http://localhost:8888/api/v1/vercel-ai/agents/demo',
});

ACP (Agent Client Protocol)

ACP is a WebSocket-based protocol providing rich bidirectional communication.

Features:

Full-duplex WebSocket communication
Session management
Permission request/grant workflow
Real-time streaming updates
Cancellation support

Use Cases:

Long-running agent tasks
Applications requiring bidirectional updates
Complex workflows with permission handling
Real-time collaborative experiences

Endpoint: WS /api/v1/acp/ws/{agent_id}

// Frontend usage
const adapter = new ACPAdapter({
  type: 'acp',
  baseUrl: 'ws://localhost:8888/api/v1/acp/ws/demo',
});

A2A (Agent-to-Agent Protocol)

A2A enables communication between AI agents using the Google A2A standard via fasta2a.

Features:

Inter-agent communication
Task delegation and result aggregation
Agent discovery via agent cards
Compatible with pydantic-ai agents

Use Cases:

Multi-agent systems
Orchestrating multiple specialized agents
Agent collaboration workflows

Endpoint: POST /api/v1/a2a/agents/{agent_id}/

// Frontend usage
const adapter = new A2AAdapter({
  type: 'a2a',
  baseUrl: 'http://localhost:8888/api/v1/a2a/agents/demo/',
});

A2A Limitations

Per-request model selection is not supported with A2A.

The A2A protocol uses pydantic-ai's to_a2a() method which binds the model at agent creation time. The model cannot be changed per-request. If you need per-request model selection, use AG-UI, Vercel AI, or ACP protocols instead.

See the A2A Limitations section for more details.

A2A Limitations

Per-Request Model Selection

The A2A protocol does not support changing the model on a per-request basis. This is due to:

Architecture: A2A uses fasta2a which converts pydantic-ai agents via to_a2a(). The model is fixed at agent creation.
Design Philosophy: A2A treats agents as services with fixed capabilities. The model is part of the agent's identity.

Workarounds:

Multiple Agents: Deploy separate A2A agents for each model:

# Create agent with GPT-4
gpt4_agent = Agent("openai:gpt-4o")
register_a2a_agent(PydanticAIAdapter(gpt4_agent), card_gpt4)

# Create agent with Claude
claude_agent = Agent("anthropic:claude-sonnet-4-5")
register_a2a_agent(PydanticAIAdapter(claude_agent), card_claude)

Use Different Protocol: Switch to AG-UI, Vercel AI, or ACP for per-request model selection.

Choosing a Protocol

Requirement	Recommended Protocol
Simple web chat	AG-UI or Vercel AI
Next.js / Vercel project	Vercel AI
Real-time bidirectional updates	ACP
Human-in-the-loop workflows	ACP or AG-UI
Multi-agent orchestration	A2A
Per-request model switching	AG-UI, Vercel AI, or ACP

Extension Protocols

Extension protocols enable rich user interfaces and inter-agent UX patterns.

A2UI (Agent-to-UI)

A2UI enables agents to communicate with user interfaces through a standardized protocol, allowing for rich interactive experiences.

Features

Bidirectional Communication — Agents can send UI updates and receive user inputs
Component Rendering — Agents can request specific UI components to be rendered
State Synchronization — Keep UI state in sync with agent state
Event Handling — Process user interactions and form submissions

Endpoints

Endpoint	Description
`/api/v1/a2ui/`	A2UI protocol endpoint
`/api/v1/a2ui/agents`	List A2UI-enabled agents

Usage

import { A2UIAdapter } from '@datalayer/agent-runtimes';

const adapter = new A2UIAdapter({
  agentId: 'my-agent',
  baseUrl: 'http://localhost:8765',
});

// Connect and receive UI events
adapter.connect((event) => {
  console.log('UI event:', event);
});

MCP-UI

MCP-UI provides a user interface layer for interacting with MCP (Model Context Protocol) servers and their tools.

Features

Tool Browser — Browse available tools from connected MCP servers
Tool Execution — Execute MCP tools with parameter input
Result Display — View tool execution results in formatted output
Server Status — Monitor MCP server connection status

Endpoints

Endpoint	Description
`/api/v1/mcp-ui/`	MCP-UI protocol endpoint
`/api/v1/mcp-ui/agents`	List MCP-UI enabled agents

Integration

MCP-UI is automatically registered for agents that have MCP toolsets enabled:

from agent_runtimes.transports import MCPUITransport

# Register an agent with MCP-UI
mcp_ui_adapter = MCPUITransport(agent)
register_mcp_ui_agent(agent_id, mcp_ui_adapter)

MCP Apps

MCP Apps is an extension to the Model Context Protocol that enables MCP servers to provide full application experiences, not just tools.

What are MCP Apps?

MCP Apps extend the traditional MCP model by allowing servers to:

Serve Full Applications — Complete UI experiences, not just API endpoints
Maintain State — Persistent application state across interactions
Handle Navigation — Multi-page application flows
Render Rich Content — HTML, forms, charts, and interactive elements

Integration with Agent Runtimes

Agent Runtimes includes the @mcp-ui/client and @modelcontextprotocol/ext-apps packages for MCP Apps support:

import { MCPAppsClient } from '@modelcontextprotocol/ext-apps';

const client = new MCPAppsClient({
  serverUrl: 'http://localhost:3000/mcp-app',
});

// Render app content
const content = await client.getContent('/dashboard');

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   Agent Runtimes UI                          │
│                  (React Components)                          │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│     A2UI      │   │    MCP-UI     │   │   MCP Apps    │
│   Protocol    │   │   Protocol    │   │   Protocol    │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    MCP Servers                               │
│              (Tools, Resources, Apps)                        │
└─────────────────────────────────────────────────────────────┘

Comparison

Feature	A2UI	MCP-UI	MCP Apps
Purpose	Agent-to-UI communication	MCP tool interface	Full applications
Interaction	Bidirectional events	Tool execution	App navigation
State	Session-based	Stateless	Persistent
Content	Structured events	Tool results	Rich HTML/UI
Best For	Chat UIs	Tool browsers	Dashboards

Getting Started

Enable A2UI

from agent_runtimes.routes import a2ui_router

app.include_router(a2ui_router, prefix="/api/v1")

Enable MCP-UI

from agent_runtimes.routes import mcp_ui_router

app.include_router(mcp_ui_router, prefix="/api/v1")

Enable MCP Apps

// In your React application
import { MCPAppsProvider } from '@mcp-ui/client';

function App() {
  return (
    <MCPAppsProvider>
      <YourComponent />
    </MCPAppsProvider>
  );
}

MCP Apps Blog Post
MCP Specification
A2A Protocol — Agent-to-Agent communication

Runtime Protocols​

Protocol Comparison​

AG-UI (Agent UI Protocol)​

Vercel AI Protocol​

ACP (Agent Client Protocol)​

A2A (Agent-to-Agent Protocol)​

A2A Limitations​

Per-Request Model Selection​

Choosing a Protocol​

Extension Protocols​

A2UI (Agent-to-UI)​

Features​

Endpoints​

Usage​

MCP-UI​

Features​

Endpoints​

Integration​

MCP Apps​

What are MCP Apps?​

Integration with Agent Runtimes​

Architecture​

Comparison​

Getting Started​

Enable A2UI​

Enable MCP-UI​

Enable MCP Apps​

Related Resources​

Runtime Protocols

Protocol Comparison

AG-UI (Agent UI Protocol)

Vercel AI Protocol

ACP (Agent Client Protocol)

A2A (Agent-to-Agent Protocol)

A2A Limitations

Per-Request Model Selection

Choosing a Protocol

Extension Protocols

A2UI (Agent-to-UI)

Features

Endpoints

Usage

MCP-UI

Features

Endpoints

Integration

MCP Apps

What are MCP Apps?

Integration with Agent Runtimes

Architecture

Comparison

Getting Started

Enable A2UI

Enable MCP-UI

Enable MCP Apps

Related Resources