1. Home
  2. Developers
Developers

Every agent is an API.

Agents speak the protocols your stack already uses: an OpenAI-compatible endpoint, tasks, webhooks, Server-Sent Events, MCP and A2A. No SDK to install, no proprietary wire format.

Base URL and auth

Local by default. Token when exposed.

A fresh install listens on 127.0.0.1:4747 and is open to that machine only. Bind it anywhere else and a token becomes mandatory: send it as Authorization: Bearer <token> or the sa_token cookie.

Webhooks authenticate with their own per-trigger secret. The agent card under /.well-known/ and the /api/public/ endpoints this site uses are open.

.envEvery variable lives in .env.example
# loopback by default; the phone reaches it through adb reverse
HOST=127.0.0.1
PORT=4747
# required whenever HOST is not loopback
SHIVA_AGENTS_TOKEN=change-me

# optional extra OpenAI-compatible provider, and its region for the residency guard
OPENAI_COMPAT_URL=
OPENAI_COMPAT_KEY=
OPENAI_COMPAT_REGION=us   # us | in | eu | local
OpenAI-compatible /v1

Call an agent like a model.

Set the model to agent:<key> and the request is answered by that agent, with its persona, memory, tools and governance, not by a bare model. The key is the agent’s id, or its role or name in lowercase-hyphen form: agent:collections-specialist.

GET /v1/models lists every agent, and live workflows as workflow:<id>. Streaming works. Anything that speaks the OpenAI chat format can use it: SDKs, IDE plugins, no-code tools.

bashAsk the GST specialist
curl http://localhost:4747/v1/chat/completions \
  -H "Authorization: Bearer $SHIVA_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:gst-indirect-tax-specialist",
    "messages": [
      { "role": "user", "content": "Which ITC claims this month need a second look?" }
    ]
  }'
jsSame thing with the OpenAI SDK
import OpenAI from "openai";

const shiva = new OpenAI({
  baseURL: "http://localhost:4747/v1",
  apiKey: process.env.SHIVA_AGENTS_TOKEN ?? "local", // any string on a loopback install
});

const reply = await shiva.chat.completions.create({
  model: "agent:collections-specialist",
  messages: [{ role: "user", content: "Who is more than 45 days overdue?" }],
});
console.log(reply.choices[0].message.content);
Tasks

Hand work off. Check back later.

Chat waits for the answer. Tasks don’t: POST /v1/tasks starts the work as a durable run and returns an id straight away. Give it an agent and a brief, or a workflow and its input.

Poll GET /v1/tasks/<id> for status and output. Anything above the agent’s autonomy level still waits for your approval.

bashStart a task, then check on it
curl http://localhost:4747/v1/tasks \
  -H "Authorization: Bearer $SHIVA_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "collections-specialist",
    "brief": "Draft reminders for invoices older than 45 days, in Hindi and English. Do not send."
  }'
# → { "id": "<task-id>", "object": "task" }

curl http://localhost:4747/v1/tasks/<task-id> \
  -H "Authorization: Bearer $SHIVA_AGENTS_TOKEN"
# → status, output, error, created_at, finished_at
Webhooks

Exactly once, even when they retry.

Add a Webhook trigger to any workflow and it gets its own URL and secret. Send an Idempotency-Key and the workflow fires once per key, however many times the sender retries.

bashFire the inbound lead router
curl -X POST http://localhost:4747/hooks/<trigger-id> \
  -H "X-Shiva-Secret: $HOOK_SECRET" \
  -H "Idempotency-Key: lead-2026-10-10-0042" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ritu", "company": "Example Traders", "message": "Need a demo next week" }'

# → { "ok": true, "run_id": "…", "duplicate": false }
# same key again → "duplicate": true, and no second run
Server-Sent Events

Watch the company think, live.

GET /api/v1/stream streams run events and model tokens. Filter with run, agent or types (a trailing * matches a prefix), drop tokens with tokens=0.

Reconnect with Last-Event-ID and missed events are replayed. A ping every 20 seconds keeps proxies from closing the connection.

bashFollow one run
curl -N "http://localhost:4747/api/v1/stream?run=<run-id>&tokens=0" \
  -H "Authorization: Bearer $SHIVA_AGENTS_TOKEN"
jsIn the browser
// same origin: the sa_token cookie authenticates EventSource
const es = new EventSource("/api/v1/stream?agent=<agent-id>");

es.addEventListener("event", (e) => log(JSON.parse(e.data)));   // steps, approvals, tasks
es.addEventListener("token", (e) => type(JSON.parse(e.data)));  // model output as it streams
Model Context Protocol

Both sides of MCP.

As a server at POST /mcp, Shiva Agents gives any MCP client tools to list agents and workflows, start runs, ask an agent, create tasks and search company memory. Your IDE assistant can ask your architect.

As a client, it connects outside MCP servers and gives their tools to your agents, each with a risk class, so governance applies to them too.

jsonMCP client configuration
{
  "mcpServers": {
    "shiva-agents": {
      "type": "http",
      "url": "http://localhost:4747/mcp",
      "headers": { "Authorization": "Bearer ${SHIVA_AGENTS_TOKEN}" }
    }
  }
}
Agent2Agent

Discoverable by other agents.

An A2A agent card at /.well-known/agent-card.json describes your company’s agents as skills, and a JSON-RPC endpoint at /a2a takes their tasks, so agents on other platforms can find and call yours.

bashFetch the card (response abridged)
curl http://localhost:4747/.well-known/agent-card.json

# {
#   "protocolVersion": "0.3.0",
#   "url": "http://localhost:4747/a2a",
#   "preferredTransport": "JSONRPC",
#   "provider": { "organization": "AskShiva", "url": "https://shivaagents.si" },
#   "skills": [
#     { "id": "research-analyst", "name": "Aanya — Research Analyst", ... },
#     ...
#   ]
# }
All surfaces

One page of endpoints.

SurfaceEndpointUse it for
OpenAI-compatiblePOST /v1/chat/completionsCall any agent as a model from any OpenAI client
TasksPOST /v1/tasks · GET /v1/tasks/<id>Start work in the background and poll for the result
WebhooksPOST /hooks/<id>Trigger a workflow from another system, once per Idempotency-Key
Live streamGET /api/v1/streamFollow runs, events and tokens as they happen
MCPPOST /mcpUse agents from MCP clients; agents also use outside MCP tools
A2AGET /.well-known/agent-card.json · POST /a2aLet agents on other platforms discover and call yours
TracesGET /api/v1/runs/<id>/otelExport a run as OTLP/JSON spans, OpenTelemetry GenAI conventions
PublicGET /api/public/stats · /libraryThe live numbers and library on this website
Zero dependencies

No npm runtime dependencies. Node.js 24 runs the TypeScript source directly, with SQLite built in.

Strict by default

A strict Content-Security-Policy, loopback-only until you set a token, and an SSRF guard on every agent fetch.

Run it now

npm run dev, then open localhost:4747/app/. Full setup.