API Transports

API Transports expose AgentVisor™ agents to external clients through protocol-specific endpoints on a shared HTTP server.

Transport vs Gateway

This page covers Transports - how external clients access AgentVisor agents (inbound). For how agents access external services (outbound), see:

• Gateways Overview - How agents access external services
• MCP Gateway - Agent access to external MCP servers

The Problem

AI agents must be accessible to diverse clients:

• AI assistants (Claude Desktop, Cursor) that discover and invoke tools
• Other AI agents that coordinate tasks across systems
• Web applications that orchestrate agent workflows
• Internal services that need programmatic agent access

Each client ecosystem has established protocols. Requiring clients to adopt a single protocol creates friction and limits adoption.

AgentVisor solves this by supporting multiple API transports - each speaking the native protocol of its target ecosystem while sharing common infrastructure.

Available Transports

Transport	Protocol	Endpoint	Use Case
OpenAPI/REST	HTTP	/	LangGraph Agent Protocol clients, web applications, programmatic access
MCP	JSON-RPC 2.0	/mcp	Claude Desktop, Cursor, MCP-compatible AI tools
A2A	JSON-RPC 2.0	/a2a	Google Agent-to-Agent Protocol clients, multi-agent systems

OpenAPI/REST Transport (Default)

The OpenAPI/REST transport implements the LangGraph Agent Protocol, providing:

• Thread and run management (/threads, /runs)
• Synchronous and asynchronous execution modes
• State streaming via Server-Sent Events
• OpenAPI specification at /openapi.json
• Swagger UI at /swagger-ui/

This is the primary transport for programmatic agent access.

MCP Transport

The MCP transport implements the Model Context Protocol, exposing AgentVisor as an MCP server. External clients (Claude Desktop, Cursor, IDEs, other agents) can both invoke actions (tools) and browse runtime state (resources).

Tools (tools/list, tools/call) — six categories, all enabled by default:

• agents — one auto-generated invocation tool per registered agent
• threads — create_thread, get_thread, update_thread, delete_thread, search_threads, copy_thread
• runs — get_run, list_runs, cancel_run, wait_for_run
• state — get_thread_state, update_thread_state, get_thread_history
• store — store_put, store_get, store_delete, store_search
• system — health_check, list_agents

Resources (resources/list, resources/read) — runtime state browsable via agentvisor:// URIs covering threads, checkpoints, agent schemas, and store items.

Categories can be selectively disabled via api.mcp.tools.<category> in configuration. See MCP Transport Guide for configuration and client setup.

A2A Transport

The A2A transport implements Google's Agent2Agent Protocol, enabling:

• Agent capability discovery via Agent Cards
• Task-based agent invocation
• Inter-agent communication for multi-agent workflows

See A2A Transport Guide for configuration and protocol details.

Shared Infrastructure

All transports share common infrastructure, ensuring consistent behavior:

┌──────────────────────────────────────────────────────────────────────┐
│  External Clients                                                    │
│                                                                      │
│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐  │
│  │  Web Apps       │    │  Claude Desktop │    │  A2A Agents      │  │
│  │  REST clients   │    │  Cursor         │    │  Other systems   │  │
│  └────────┬────────┘    └────────┬────────┘    └────────┬─────────┘  │
│           │                      │                      │            │
│       REST/HTTP            MCP (JSON-RPC)         A2A (JSON-RPC)     │
│           │                      │                      │            │
├───────────┼──────────────────────┼──────────────────────┼────────────┤
│  Shared HTTP Server (api.listen_addr)                                │
│           │                      │                      │            │
│  ┌────────▼────────┐    ┌────────▼────────┐    ┌────────▼────────┐   │
│  │ OpenAPI         │    │ MCP             │    │ A2A             │   │
│  │ Transport       │    │ Transport       │    │ Transport       │   │
│  │ /threads, /runs │    │ /mcp            │    │ /a2a            │   │
│  └────────┬────────┘    └────────┬────────┘    └────────┬────────┘   │
│           │                      │                      │            │
│           └──────────────────────┴──────────────────────┘            │
│                                  │                                   │
│                    ┌─────────────▼─────────────┐                     │
│                    │ Shared Components         │                     │
│                    │ • Authentication          │                     │
│                    │ • TLS                     │                     │
│                    │ • Thread/Run API          │                     │
│                    │ • Policy enforcement      │                     │
│                    └───────────────────────────┘                     │
└──────────────────────────────────────────────────────────────────────┘

Authentication

All transports share authentication configuration:

api:
  auth:
    enabled: true
    oidc_issuer: "https://auth.example.com"
    oidc_audience: "agentvisor"

When authentication is enabled, all transports require valid bearer tokens. The same token works across all endpoints.

TLS

All transports share TLS configuration:

api:
  tls:
    enabled: true
    cert_file: "/path/to/server.crt"
    key_file: "/path/to/server.key"

A single certificate secures all transport endpoints.

Policy Enforcement

All transport requests flow through the policy engine:

Client Request → Transport → Policy Engine → Agent Execution
                                  │
                         Evaluate principal,
                         agent, and action
                                  │
                          ALLOW or DENY

Policy decisions apply uniformly regardless of which transport received the request.

Configuration

Enable or disable transports independently in agentvisor.yaml:

api:
  listen_addr: ":8090"           # Shared HTTP server
  
  # Shared authentication
  auth:
    enabled: false               # Disable for development
  
  # Shared TLS
  tls:
    enabled: false               # Disable for development
  
  # Transport toggles
  openapi:
    enabled: true                # OpenAPI/REST (default: enabled)
  mcp:
    enabled: false               # MCP transport (default: disabled)
  a2a:
    enabled: false               # A2A transport (default: disabled)

Environment Variables

Variable	Default	Description
AGENTVISOR_API_LISTEN_ADDR	:8090	HTTP server address (shared)
AGENTVISOR_API_OPENAPI_ENABLED	true	Enable OpenAPI/REST transport
AGENTVISOR_API_MCP_ENABLED	false	Enable MCP transport
AGENTVISOR_API_A2A_ENABLED	false	Enable A2A transport
AGENTVISOR_API_AUTH_ENABLED	false	Enable authentication (shared)
AGENTVISOR_API_TLS_ENABLED	false	Enable TLS (shared)

Transport Selection

Choose transports based on your client ecosystem:

Client Type	Recommended Transport
Web applications	OpenAPI
LangGraph clients	OpenAPI
Claude Desktop	MCP
Cursor	MCP
MCP-compatible tools	MCP
A2A agents	A2A
Multi-agent orchestration	A2A
Custom integrations	OpenAPI

Multiple transports can be enabled simultaneously. Each provides a different interface to the same agents and capabilities.

Related Documentation

• MCP Transport Guide - Detailed MCP transport setup
• A2A Transport Guide - Detailed A2A transport setup
• Gateways - How agents access external services (opposite direction)
• Configuration Reference - Complete configuration options
• Architecture - System architecture overview