- Home
- 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.
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.
# 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
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.
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?" }
]
}'
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);
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.
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
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.
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
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.
curl -N "http://localhost:4747/api/v1/stream?run=<run-id>&tokens=0" \
-H "Authorization: Bearer $SHIVA_AGENTS_TOKEN"
// 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
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.
{
"mcpServers": {
"shiva-agents": {
"type": "http",
"url": "http://localhost:4747/mcp",
"headers": { "Authorization": "Bearer ${SHIVA_AGENTS_TOKEN}" }
}
}
}
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.
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", ... },
# ...
# ]
# }
One page of endpoints.
| Surface | Endpoint | Use it for |
|---|---|---|
| OpenAI-compatible | POST /v1/chat/completions | Call any agent as a model from any OpenAI client |
| Tasks | POST /v1/tasks · GET /v1/tasks/<id> | Start work in the background and poll for the result |
| Webhooks | POST /hooks/<id> | Trigger a workflow from another system, once per Idempotency-Key |
| Live stream | GET /api/v1/stream | Follow runs, events and tokens as they happen |
| MCP | POST /mcp | Use agents from MCP clients; agents also use outside MCP tools |
| A2A | GET /.well-known/agent-card.json · POST /a2a | Let agents on other platforms discover and call yours |
| Traces | GET /api/v1/runs/<id>/otel | Export a run as OTLP/JSON spans, OpenTelemetry GenAI conventions |
| Public | GET /api/public/stats · /library | The live numbers and library on this website |
No npm runtime dependencies. Node.js 24 runs the TypeScript source directly, with SQLite built in.
A strict Content-Security-Policy, loopback-only until you set a token, and an SSRF guard on every agent fetch.
npm run dev, then open localhost:4747/app/. Full setup.