API Reference

The agent runtime exposes three HTTP API surfaces: the A2A protocol for agent-to-agent communication, an MCP server for tool/prompt discovery by Claude Desktop and other MCP hosts, and a lightweight REST management API. All surfaces are served by a single Go binary on a configurable port (default :8080).

Authentication

When agent.security.require_auth = true, all A2A endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Task ownership is enforced — clients can only read or cancel tasks they created. Requests for another client's task return 404 (not 403) to avoid leaking task existence. The REST management API and MCP server are not covered by bearer auth; they should be placed behind a network perimeter in production.

A2A — Agent Discovery

Google A2A Protocol

The Agent Card describes the agent's capabilities, supported A2A version, skills, and authentication requirements. Any A2A-compatible client fetches this before initiating tasks.

GET /.well-known/agent.json

Return the AgentCard for capability discovery.

Response

{
  "name": "companies-researcher",
  "description": "Research companies using the knowledge graph",
  "version": "1.0.0",
  "url": "https://my-agent.example.com",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    { "id": "graph-search", "name": "Graph Search", "description": "..." }
  ],
  "authentication": { "schemes": ["bearer"] }
}

A2A — Tasks

Submit tasks and poll their lifecycle state. Tasks progress through: submitted → working → completed | failed | canceled.

POST /a2a auth

Submit a task and get a synchronous response (Task or Message). For streaming, use /a2a/stream.

Request body (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "Top 5 companies by revenue?" }]
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "task_01j...",
    "status": { "state": "completed" },
    "artifacts": [
      { "parts": [{ "type": "text", "text": "1. Apple — $394B ..." }] }
    ]
  }
}

POST /a2a/stream auth SSE

Submit a task and receive a Server-Sent Events stream of TaskStatusUpdateEvent and TaskArtifactUpdateEvent messages. Connection closes when the task reaches a terminal state.

Request body

Same JSON-RPC envelope as POST /a2a with method "message/stream"

SSE event stream

data: {"type":"TaskStatusUpdateEvent","taskId":"task_01j...","status":{"state":"working"}}
data: {"type":"TaskArtifactUpdateEvent","taskId":"task_01j...","artifact":{"parts":[{"type":"text","text":"1. Apple"}]}}
data: {"type":"TaskStatusUpdateEvent","taskId":"task_01j...","status":{"state":"completed"},"final":true}

GET /a2a/tasks/{id} auth

Poll the current state of a task by ID. Returns the full Task object including all artifacts.

Path parameters

id  string  Task ID returned from POST /a2a

Response

{ "id": "task_01j...", "status": { "state": "completed" }, "artifacts": [...] }

GET /a2a/tasks auth

List tasks for the authenticated client. Cursor-based pagination.

Query parameters

cursor  string  Pagination cursor from previous response
limit   int     Max results per page (default 20, max 100)

Response

{ "tasks": [...], "nextCursor": "eyJ..." }

DELETE /a2a/tasks/{id} auth

Cancel a running task. The task transitions to canceled state; any in-flight model call is interrupted via context cancellation.

Response

{ "id": "task_01j...", "status": { "state": "canceled" } }

MCP Server — Tools

MCP 2025-11-25 spec

When agent.mcp_server.enabled = true, the agent exposes itself as an MCP server at port 8081 (HTTP/SSE) or via stdio. MCP hosts (Claude Desktop, Cursor, etc.) discover tools and invoke them through the standard MCP JSON-RPC protocol.

RPC tools/list

Return all tools available to this agent (from toolbox + registered tools).

Response

{
  "tools": [
    {
      "name": "company_lookup",
      "description": "Look up a company by name or ID",
      "inputSchema": { "type": "object", "properties": { "name": { "type": "string" } } }
    },
    ...
  ]
}

RPC tools/call

Invoke a tool by name. The agent executes the tool and returns the result.

Request

{ "name": "company_lookup", "arguments": { "name": "Apple" } }

Response

{ "content": [{ "type": "text", "text": "{\"name\":\"Apple Inc.\",\"revenue\":\"$394B\"}" }] }

MCP Server — Prompts (Skills)

Skills are exposed as MCP Prompts, enabling MCP hosts to discover and inject skill context into their own conversations.

RPC prompts/list

List all skills registered with this agent as MCP prompts.

Response

{
  "prompts": [
    { "name": "graph-search", "description": "Search the knowledge graph...", "arguments": [] },
    { "name": "memory-recall", "description": "Recall entities from prior sessions", "arguments": [] }
  ]
}

RPC prompts/get

Retrieve the system prompt fragment for a skill. The MCP host can inject this into its own context.

Request

{ "name": "graph-search" }

Response

{
  "messages": [
    {
      "role": "user",
      "content": "When searching for companies:\n1. Use company_lookup for direct lookups..."
    }
  ]
}

REST Management API

Internal / local use

Lightweight management endpoints for tooling and health checks. Served on the same port as A2A. The OpenAPI spec for this surface is available at /openapi.json.

GET /api/agents

List all configured agents and their current status.

Response

{ "agents": [{ "id": "companies-researcher", "status": "running", "activeSessions": 3 }] }

PUT /api/agents/{id}

Hot-reload agent config without restarting the server. Skills and tools are re-resolved; active sessions drain gracefully.

Request body

{ "configPath": "./agent.toml" }

Response

{ "id": "companies-researcher", "status": "reloaded" }

GET /api/health

Liveness and readiness probe. Returns 200 when the server is up and all sidecars are healthy. Returns 503 if any required sidecar is down.

Response (healthy)

{
  "status": "ok",
  "sidecars": {
    "genai-toolbox": "running",
    "cypher-mcp":    "running",
    "graphrag":      "running"
  }
}

Response (degraded)

HTTP 503
{ "status": "degraded", "sidecars": { "graphrag": "stopped" } }

GET /openapi.json

OpenAPI 3.0 specification for the REST management API. Suitable for import into Salesforce External Services or any OAS-compatible tool.

Response

OpenAPI 3.0 JSON document describing all /api/* endpoints