Dashboard|

Agents API

The HTTP runtime every Cencori agent runs on: sessions, turns, tool calls, approvals, widgets and traces.

The Agents API is the runtime under everything agent-shaped in Cencori. The Agents SDK, Agent UI, Arcie, Embedded Agents and WhatsApp agents all run on it. Use it directly from any language.

ConceptWhat it is
Stored agentAn agent defined in Cencori (POST /v1/agents), run by id. See Stored agents
SessionOne conversation. Durable: its events are stored, so it can pause, resume and be replayed
TurnOne request in a session: input in, a streamed reply out
Tool callThe model asks for a function. Built-in and installed tools run on Cencori; yours pause the turn for you to run
ApprovalA paused tool call waiting for a person. Recorded in your governance ledger
WidgetUI the model shows, checked by Cencori (render_ui)
TraceEvery session in Observability → Traces

A run, end to end

 
POST /v1/sessions
CENCORI_API_KEY: csk_...
Content-Type: application/json
 
{
  "metadata": { "agent": "Support" },
  "turn": {
    "input": "Where is order 1042?",
    "model": "gpt-oss-120b",
    "instructions": "Help customers with their orders.",
    "tools": [{ "type": "function", "function": { "name": "get_order", "description": "Look up an order", "parameters": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] } } }],
    "pause_on_tool_calls": true
  }
}

Creating the session with its first turn saves a round trip: the reply streams back straight away, with the session id in the X-Cencori-Session-Id header.

event: turn.started
event: tool_call.started   data: {"tool":"get_order","arguments":{"id":"1042"},"action_id":"call_1"}
event: turn.paused         data: {"reason":"tool_results_required","action_id":"call_1","actions":[...]}

Run the tool yourself and send the result:

POST /v1/sessions/ses_.../approve
 
{ "action_id": "call_1", "tool_results": [{ "action_id": "call_1", "output": "{\"status\":\"shipped\"}" }] }

The turn resumes and streams the answer. If the model calls another tool, it pauses again.

See Tool calls and approvals for the full loop and Events for every event.

Endpoints
EndpointDoes
POST /v1/agentsStore an agent: model, instructions, tools, widgets
POST /v1/sessionsCreate a session, optionally with its first turn and a stored agent_id
POST /v1/sessions/:id/turnsSend a turn
POST /v1/sessions/:id/approveSend tool results (and approve) to resume a paused turn
POST /v1/sessions/:id/rejectDecline a paused tool call
GET /v1/sessions/:idThe session
GET /v1/sessions/:id/eventsIts event log
GET /v1/sessionsList sessions
DELETE /v1/sessions/:idDelete a session

Request and response details: Sessions API reference.

Turn options
FieldUse it for
inputThe user's message
model, instructionsAny catalog model; the system prompt
toolsFunction tools (yours) and built-in tools
pause_on_tool_callsPause on your tools so you can run them. Without it, calls are returned in the output
widgetsGive the model render_ui to answer with UI. See Widgets
response_formatStructured output (JSON Schema)
temperature, max_output_tokens, reasoning_effortModel settings
memoryGateway memory for an end user
userYour end user's id: quotas, billing, memory
metadataUp to 20 strings, shown in traces (agent names the agent)

Who can call it
  • Secret keys (csk_) from your server: everything.
  • Publishable keys (cpk_) from a browser, locked to your domains: run a stored agent, nothing else. See Stored agents.
  • Client tokens (ect_) from a browser: turns in their own sessions, and approvals if granted. See Browser access.
Did you like the content?