A2A Gateway

ARK includes an integrated Agent-to-Agent Gateway (A2AGW) that implements the A2A Protocol  for ARK agents, enabling standardized agent-to-agent communication.

ARK also supports Agent Hosting, which allows users to host their existing LangChain, CrewAI, AutoGen, or other agent code and expose agents to the ARK cluster using the A2A protocol.

Note: At present, ARK only supports text-based responses from the A2A server. Other response formats (e.g., images, audio, structured JSON) are not yet supported.

Overview

What the Gateway Does

The A2A Gateway serves as a dynamic API gateway that:

• Discovers ARK agents in the Kubernetes cluster
• Exposes them via the A2A protocol at /agent/{agent-name}/
• Provides agent discovery endpoints
• Handles protocol translation between ARK and A2A formats

A2A Use Case

The gateway enables agents to:

• Discover other agents’ capabilities through standardized agent cards
• Communicate using a common protocol regardless of implementation
• Execute tasks on remote agents with streaming responses
• Build multi-agent workflows with consistent interfaces

Architecture

Core Components

1. Registry (registry.py)

   • Connects to Kubernetes API via ARK SDK
   • Converts ARK Agent resources to A2A AgentCards
   • Extracts skills from agent annotations

2. Manager (manager.py)

   • Maintains dynamic routing table
   • Polls registry every 30 seconds (3s in dev mode)
   • Uses thread-safe ProxyApp pattern for atomic route updates
   • Prevents race conditions during agent changes

3. Execution (execution.py)

   • Implements A2A AgentExecutor interface
   • Creates ARK queries for agent task execution
   • Handles streaming responses from agents

Request Flow

1. Client requests /agent/{name}/execute
2. FastAPI routes to ProxyApp at /agent/*
3. ProxyApp forwards to current Starlette app
4. Starlette routes to agent’s A2AStarletteApplication
5. A2AStarletteApplication uses ARKAgentExecutor
6. ARKAgentExecutor creates ARK Query for execution

Key Design Decisions

• ProxyApp Pattern: Ensures atomic route updates without affecting in-flight requests
• Periodic Sync: Automatically discovers new agents without restarts
• ARK Integration: Leverages native Kubernetes resources for agent management

Installation

make ark-api-a2a-install

Configuration

Environment variables for the A2A Gateway:

• ARK_A2A_LISTEN_PORT (default: 7184) - Port used in agent card URLs
• ARK_A2A_LISTEN_HOST (default: localhost) - Host used in agent card URLs
• ARK_A2A_LISTEN_PROTOCOL (default: http) - Protocol scheme for agent card URLs

Managing A2A Servers

Basic Operations

# List A2A servers
kubectl get a2aservers
 
# View details
kubectl describe a2aserver langchain-agents
 
# Delete an A2A server
kubectl delete a2aserver langchain-agents

Usage

Once an A2A Server is created and ready, you can query the generated agents like any other ARK agent:

# Query an agent from the A2A server
fark agent langchain-agents-weather-reporter "What's the weather like today?"
 
# List all agents (including A2A-generated ones)
kubectl get agents

Agent Hosting with A2A Servers

Agent hosting allows you to integrate existing agent frameworks with ARK using the A2A protocol.

How Agent Hosting Works

1. Create A2A Server: Deploy your agents using the A2A protocol
2. Register with ARK: Create an A2AServer resource pointing to your service
3. Automatic Discovery: ARK discovers agents and creates Agent resources
4. Query Execution: Users can query the agents through the dedicated A2A execution engine

Example A2AServer for Agent Hosting

apiVersion: ark.mckinsey.com/v1prealpha1
kind: A2AServer
metadata:
  name: my-langchain-agents
spec:
  address:
    valueFrom:
      serviceRef:
        name: my-a2a-service
        port: "8080"
  description: "My hosted LangChain agents"

Generated Agent Resources

The A2AServer controller automatically creates Agent resources with the reserved ‘a2a’ execution engine:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: my-langchain-agents-research-agent
  labels:
    a2a/server: "my-langchain-agents"
  ownerReferences:
  - apiVersion: ark.mckinsey.com/v1prealpha1
    kind: A2AServer
    name: my-langchain-agents
spec:
  description: "Performs research tasks"
  prompt: "You are Research Agent. Performs research tasks"
  executionEngine:
    name: "a2a"

Supported Frameworks

Agent hosting works with any framework that can implement the A2A protocol:

• LangChain - Python and JavaScript agents
• CrewAI - Multi-agent systems
• AutoGen - Conversational AI agents
• Custom implementations - Any HTTP service implementing A2A protocol

Samples

See the samples/agent-hosting directory for complete examples:

• LangChain Weather Agent: Weather forecasting with NWS API tools

A2A Annotations

Created agents include these annotations:

• ark.mckinsey.com/a2a-server-name: The name of the A2A server that created this agent
• ark.mckinsey.com/a2a-server-address: The resolved address of the A2A server
• ark.mckinsey.com/a2a-server-skills: JSON representation of agent skills discovered from the A2A server

Next Steps

A2A Servers enable integration with external agent systems. For more advanced features, explore:

• Services - Additional ARK services
• Observability - Monitoring your agents