Skip to Content

Ark API

REST API service for managing ARK resources. Provides native ARK endpoints, OpenAI-compatible endpoints, and includes the A2A Gateway for agent-to-agent communication.

Installation

Install via helm:

helm install ark-api \
    ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-api \
    --namespace default \
    --create-namespace

For local development:

# From project root
make ark-api-dev
 
# Or from service directory
cd services/ark-api
devspace dev

Configuration

Key environment variables:

VariableDescriptionDefault
PORTServer port8000
AUTH_MODEAuthentication mode (open, basic, sso, hybrid)open
CORS_ORIGINSAllowed CORS origins (comma-separated)http://localhost:3000
ARK_A2A_AGENT_CARD_PORTPort advertised in agent cardsUses PORT (8000)
ARK_A2A_AGENT_CARD_HOSTHost advertised in agent cardslocalhost
ARK_A2A_AGENT_CARD_PROTOCOLProtocol advertised in agent cardshttp
ARK_A2A_AGENT_CARD_PATHOptional path prefix for agent card URLsEmpty (root path)

See the Helm chart values  for complete configuration options.

API Endpoints

Native ARK APIs

  • Agents: /v1/namespaces/{namespace}/agents
  • Teams: /v1/namespaces/{namespace}/teams
  • Queries: /v1/namespaces/{namespace}/queries
  • Models: /v1/namespaces/{namespace}/models
  • Evaluators: /v1/namespaces/{namespace}/evaluators
  • Evaluations: /v1/namespaces/{namespace}/evaluations
  • Secrets: /v1/namespaces/{namespace}/secrets
  • API Keys: /v1/api-keys
  • Resources: /v1/resources - Generic access to any Kubernetes resource

See ARK APIs Reference and Resources API for complete API documentation.

OpenAI-Compatible APIs

  • Models: /openai/v1/models
  • Chat Completions: /openai/v1/chat/completions

A2A Gateway

The A2A Gateway exposes ARK agents via the A2A Protocol  for standardized agent-to-agent communication. All ARK agents in Kubernetes are automatically discovered and exposed.

Endpoints:

  • GET /agents - List all available agents
  • GET /agent/{agent-name}/.well-known/agent-card.json - Get agent card
  • GET /agent/{agent-name}/* - Dynamic A2A protocol routes

Example:

# List agents
curl http://localhost:8000/agents
 
# Get agent card
curl http://localhost:8000/agent/<agent-name>/.well-known/agent.json

Service Proxy

Proxy requests to other services deployed in your namespace. For example, the File Management features in Ark proxy requests from the dashboard directly to the filesystem server. Proxy APIs use the authentication policies configured for the tenant.

  • GET /v1/proxy/services - List available services
  • * /v1/proxy/services/{service_name}/{path} - Proxy to a cluster service
  • GET,POST,OPTIONS /v1/proxy/a2a/{a2a-server} - Proxy to an a2a server
  • GET,POST,OPTIONS /v1/proxy/a2a/{a2a-server}/{path} - Proxy to interact with an a2a server
  • GET,POST,OPTIONS /v1/proxy/mcp/{mcp-server} - Proxy to an mcp server
  • GET,POST,OPTIONS /v1/proxy/mcp/{mcp-server}/{path} - Proxy to interact with a mcp server

In order to connect with A2A Server or MCP Server you can use the following dev tools:

  • A2A Inspector : for connecting to A2A via proxy (digit the full path at agent-card)
  • MCP Inspector : for connecting to MCP via proxy (use Streamable HTTP and Direct connection)

Authentication

ARK API supports multiple authentication modes:

  • open: No authentication (development only)
  • basic: API key authentication only
  • sso: OIDC/JWT authentication only
  • hybrid: Both OIDC and API key authentication (recommended for production)

See Authentication Guide for complete configuration details.

Last updated on
Quickstart