Using the API

Savant exposes two communication channels: the A2A protocol (recommended) for agent-to-agent communication, and the REST API for administrative operations.

A2A Protocol (Recommended)

The A2A protocol is the primary way to communicate with Savant. It uses JSON-RPC 2.0 over HTTP.

Send a Message

curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-001",
        "role": "user",
        "parts": [{"kind": "text", "text": "What agents are registered?"}]
      }
    }
  }'

Stream a Response

curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "stream",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-002",
        "role": "user",
        "parts": [{"kind": "text", "text": "Analyze the code in /src"}]
      }
    }
  }'

Returns an SSE stream with TaskStatusUpdateEvent, Message, and TaskArtifactUpdateEvent events.

Invoke a Capability

Send a DataPart with the capability name and arguments:

curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-003",
        "role": "user",
        "parts": [{
          "kind": "data",
          "data": {
            "capability": "check_stock",
            "args": {"product_id": "SKU-1234"}
          }
        }]
      }
    }
  }'

Using the SDK (Easier)

The RemoteAgent class wraps all of this:

import { RemoteAgent } from '@svantic/sdk';

const remote = await RemoteAgent.connect('http://localhost:3000');

// Simple message
const answer = await remote.send('What agents are registered?');

// Streaming
for await (const event of remote.send_stream('Analyze the code')) { ... }

// Capability invocation
const result = await remote.invoke_capability('check_stock', { product_id: 'SKU-1234' });

REST API

Administrative endpoints for session management, MCP configuration, and guardrails.

Agent Management

Register requires a JWT from POST /auth/get_token (credentials go only there). The register body is agent_type, instance_id, url, and optionally tools / mcp_servers — not client_id / client_secret. Success response: { "ok": true, "tenant_id": "..." }.

# 1) Obtain a JWT (client_id / client_secret only here)
TOKEN=$(curl -s -X POST http://localhost:7000/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"acme","client_secret":"secret","agent_type":"my-service"}' \
  | jq -r '.token')

# 2) Register (Bearer token — no credentials in body)
curl -X POST http://localhost:3000/agents/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_type":"my-service","instance_id":"pod-1","url":"http://my-service:4000","tools":[],"mcp_servers":{}}'

# List registered agents
curl -X POST http://localhost:3000/agents/list

# Deregister an agent
curl -X POST http://localhost:3000/agents/deregister \
  -H "Content-Type: application/json" \
  -d '{"agent_type": "my-service", "instance_id": "pod-1"}'

Sessions

# Authenticate first
TOKEN=$(curl -s -X POST http://localhost:7000/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"acme","client_secret":"secret","agent_type":"my-agent"}' \
  | jq -r '.token')

# Create a session (auto-attaches internal agents)
curl -X POST http://localhost:3000/sessions/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"session_id": "sess-001"}'

# Invite a remote agent into the session
curl -X POST http://localhost:3000/sessions/sess-001/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_type": "transcript-link"}'

# Close a session (destroys internal agents, unbinds all)
curl -X POST http://localhost:3000/sessions/sess-001/close \
  -H "Authorization: Bearer $TOKEN"

# List sessions
curl -X POST http://localhost:3000/sessions/list

# Get session history
curl -X POST http://localhost:3000/sessions/get \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess-001"}'

MCP Servers

# Register MCP servers
curl -X POST http://localhost:3000/config/mcp/register \
  -H "Content-Type: application/json" \
  -d '{
    "servers": {
      "chrome-devtools": {
        "command": "npx",
        "args": ["-y", "@anthropic/chrome-devtools-mcp"]
      }
    }
  }'

# List MCP servers
curl -X POST http://localhost:3000/config/mcp/list

# Remove an MCP server
curl -X POST http://localhost:3000/config/mcp/remove \
  -H "Content-Type: application/json" \
  -d '{"name": "chrome-devtools"}'

Guard Approvals

# List approvals
curl -X POST http://localhost:3000/guard/list

# Grant approval
curl -X POST http://localhost:3000/guard/approve \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc", "scope": "session"}'

# Deny approval
curl -X POST http://localhost:3000/guard/deny \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc"}'

# Revoke a permanent approval
curl -X POST http://localhost:3000/guard/revoke \
  -H "Content-Type: application/json" \
  -d '{"key": "file-access-/etc"}'

Admin / Dashboard

# Event bus statistics
curl -X POST http://localhost:3000/admin/stats

# Recent events (filters in POST body)
curl -X POST http://localhost:3000/admin/events/recent \
  -H "Content-Type: application/json" \
  -d '{"category": "agent", "limit": 50}'

# Live event stream (SSE)
curl -N -X POST http://localhost:3000/admin/events/stream

# All registered agents
curl -X POST http://localhost:3000/admin/agents

# Agents in a specific session
curl -X POST http://localhost:3000/admin/sessions/agents \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess-001"}'

# Tenant list
curl -X POST http://localhost:3000/admin/tenants

Endpoint Conventions

Savant uses HTTP POST for all API operations. Exceptions: A2A discovery (GET /.well-known/agent-card.json), BFF health (GET /health), and a few BFF GETs for read-only endpoints.

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

Using the api

Using the API

A2A Protocol (Recommended)

Send a Message

Stream a Response

Invoke a Capability

Using the SDK (Easier)

REST API

Agent Management

Sessions

MCP Servers

Guard Approvals

Admin / Dashboard

Endpoint Conventions

Further Reading

​Using the API

​A2A Protocol (Recommended)

​Send a Message

​Stream a Response

​Invoke a Capability

​Using the SDK (Easier)

​REST API

​Agent Management

​Sessions

​MCP Servers

​Guard Approvals

​Admin / Dashboard

​Endpoint Conventions

​Further Reading

Using the API

A2A Protocol (Recommended)

Send a Message

Stream a Response

Invoke a Capability

Using the SDK (Easier)

REST API

Agent Management

Sessions

MCP Servers

Guard Approvals

Admin / Dashboard

Endpoint Conventions

Further Reading