adk-server

HTTP server and A2A protocol for Rust Agent Development Kit (ADK-Rust) agents.

Overview

adk-server provides HTTP infrastructure for the Rust Agent Development Kit (ADK-Rust):

• REST API - Standard HTTP endpoints for agent interaction
• A2A Protocol - Agent-to-Agent communication (JSON-RPC 2.0)
• SSE Streaming - Server-Sent Events for real-time responses
• Web UI - Built-in chat interface for testing
• RemoteA2aAgent - Connect to remote agents as sub-agents
• Auth Bridge - Flow authenticated identity from HTTP headers into agent execution
• Artifacts - Binary artifact storage and retrieval per session
• Debug/Tracing - Trace inspection and graph visualization endpoints

Installation

[dependencies]
adk-server = "0.5.0"

Or use the meta-crate:

[dependencies]
adk-rust = { version = "0.5.0", features = ["server"] }

Quick Start

Basic Server

use adk_server::{create_app, ServerConfig};
use std::sync::Arc;

let config = ServerConfig::new(
    Arc::new(SingleAgentLoader::new(Arc::new(agent))),
    Arc::new(InMemorySessionService::new()),
);

let app = create_app(config);

let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
axum::serve(listener, app).await?;

Security Configuration

Configure CORS, timeouts, and other security settings:

use adk_server::{ServerConfig, SecurityConfig};
use std::time::Duration;

// Development mode (permissive CORS, detailed errors)
let config = ServerConfig::new(agent_loader, session_service)
    .with_security(SecurityConfig::development());

// Production mode (restricted CORS, sanitized errors)
let config = ServerConfig::new(agent_loader, session_service)
    .with_security(SecurityConfig::production(vec!["https://myapp.com".to_string()]));

// Or configure individual settings
let config = ServerConfig::new(agent_loader, session_service)
    .with_allowed_origins(vec!["https://myapp.com".to_string()])
    .with_request_timeout(Duration::from_secs(60))
    .with_max_body_size(5 * 1024 * 1024)  // 5MB
    .with_error_details(false);

Optional Services

let config = ServerConfig::new(agent_loader, session_service)
    .with_artifact_service(Arc::new(artifact_service))
    .with_memory_service(Arc::new(memory_service))
    .with_span_exporter(Arc::new(span_exporter))
    .with_request_context(Arc::new(my_auth_extractor));

Runner Configuration Passthrough

ServerConfig can now forward runner-level compaction and prompt-cache settings:

let config = ServerConfig::new(agent_loader, session_service)
    .with_compaction(compaction_config)
    .with_context_cache(context_cache_config, cache_capable_model);

This applies to both the standard SSE runtime endpoints and the A2A runtime controller.

A2A Server

use adk_server::create_app_with_a2a;

let app = create_app_with_a2a(config, Some("http://localhost:8080"));

// Exposes:
// GET  /.well-known/agent.json  - Agent card
// POST /a2a                      - JSON-RPC endpoint
// POST /a2a/stream               - SSE streaming

Remote Agent Client

use adk_server::RemoteA2aAgent;

let remote = RemoteA2aAgent::builder("weather_agent")
    .description("Remote weather service")
    .agent_url("http://weather-service:8080")
    .build()?;

// Use as sub-agent
let coordinator = LlmAgentBuilder::new("coordinator")
    .sub_agent(Arc::new(remote))
    .build()?;

Auth Bridge

Flow authenticated identity from HTTP requests into agent execution:

use adk_server::auth_bridge::{RequestContextExtractor, RequestContextError};
use adk_core::RequestContext;
use async_trait::async_trait;

struct MyExtractor;

#[async_trait]
impl RequestContextExtractor for MyExtractor {
    async fn extract(
        &self,
        parts: &axum::http::request::Parts,
    ) -> Result<RequestContext, RequestContextError> {
        let auth = parts.headers
            .get("authorization")
            .and_then(|v| v.to_str().ok())
            .ok_or(RequestContextError::MissingAuth)?;
        // validate token, build RequestContext ...
        todo!()
    }
}

let config = ServerConfig::new(agent_loader, session_service)
    .with_request_context(Arc::new(MyExtractor));

When configured, the extracted RequestContext flows into InvocationContext, making scopes available to tools via ToolContext::user_scopes(). Session and artifact endpoints enforce user_id authorization against the authenticated identity.

API Endpoints

Health

Apps

Sessions

Runtime

Artifacts

Debug and Tracing

UI Protocol

Runtime endpoints support protocol negotiation via:

• request body field uiProtocol / ui_protocol
• header x-adk-ui-protocol (takes precedence)
• request body field uiTransport / ui_transport
• header x-adk-ui-transport (takes precedence)

Supported runtime profile values: adk_ui (default), a2ui, ag_ui, mcp_apps.

Current support is intentionally tiered:

• a2ui is a draft-aligned hybrid subset exposed through protocol-aware UI tool payloads.
• ag_ui is a hybrid subset: the default stream remains the generic ADK wrapper, but clients can opt into protocol_native transport plus AG-UI run input fields on /api/run_sse.
• mcp_apps is a compatibility subset with ui:// resource registration plus additive initialize / message / update-model-context bridge helpers, notification polling, list-changed host flows, and runtime request fields, not a full browser postMessage host bridge yet.

Runtime transport values:

• legacy_wrapper (default) preserves the existing generic ADK SSE envelope.
• protocol_native is currently available for ag_ui only.

Use /api/ui/capabilities instead of assuming full upstream protocol parity.

For MCP Apps tool responses, adk-server::ui_types now exposes a canonical additive helper:

• McpUiBridgeSnapshot for typed host/app bridge state that can be promoted into tool responses
• McpUiToolResult for the shared tool-result envelope
• McpUiToolResultBridge for typed bridge metadata (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Use McpUiBridgeSnapshot::build_tool_result(...) as the preferred constructor path when promoting framework bridge state into an MCP Apps tool response. resourceUri and inline html fallbacks remain available for compatibility-oriented hosts.

For embedded-host mappings, the additive HTTP bridge corresponds to MCP Apps host/app methods as follows:

• ui/initialize -> /api/ui/initialize
• ui/message -> /api/ui/message
• ui/update-model-context -> /api/ui/update-model-context
• notifications/resources/list_changed -> /api/ui/notifications/resources-list-changed
• notifications/tools/list_changed -> /api/ui/notifications/tools-list-changed
• queued host notifications -> /api/ui/notifications/poll

A2A Endpoints

Web UI

Security

The server applies the following security layers automatically:

• CORS (configurable allowed origins)
• Request body size limits (default 10MB)
• Request timeouts (default 30s)
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Request ID tracking via x-request-id header
• User ID authorization on session/artifact/debug endpoints when auth is configured

Features

• Axum-based async HTTP server
• CORS support with configurable origins
• Embedded web UI assets
• Multi-agent routing via AgentLoader
• Health checks with component status
• OpenTelemetry trace integration
• Auth middleware bridge for identity propagation
• Artifact storage and retrieval
• A2A protocol with JSON-RPC 2.0

Related Crates

• adk-rust - Meta-crate with all components
• adk-runner - Execution runtime
• adk-cli - CLI launcher
• adk-telemetry - OpenTelemetry integration
• adk-artifact - Artifact storage
• adk-auth - Authentication (JWT bridge)
• adk-ui - UI protocol support

License

Apache-2.0

Part of ADK-Rust

This crate is part of the ADK-Rust framework for building AI agents in Rust.