HTTP API

Two APIs

Engine API

Stateless. Started by agentctl serve. Port 8090. Takes a message, returns a response. No session management.

Conversation API

Stateful. Started by agent-manager. Port 8100. Manages conversations, history, and SSE streaming. Also serves the widget.

Engine API

Base URL: http://localhost:8090

`GET /health`

{ "status": "ok", "system": "Enterprise Knowledge Assistant" }

`POST /invoke`

Send a message and get a response.

curl -X POST http://localhost:8090/invoke \
  -H "Content-Type: application/json" \
  -d '{ "message": "Where is my order #12345?" }'

Response:

{
  "system_name": "Enterprise Knowledge Assistant",
  "answer": "Your order #12345 shipped yesterday and is arriving Thursday.",
  "visited": ["router", "router/orders_agent"],
  "used_tools": [
    { "name": "get_order_status", "provider": "local", "status": "succeeded", "agent_id": "orders_agent" }
  ]
}

Two request headers are recognized:

X-Request-ID — adopted (after sanitization) as the request id for log correlation and echoed back in the X-Request-ID response header. Minted automatically when absent.
X-Session-ID — carried into the run as the conversation id for tracing metadata (e.g. the Langfuse session).

`POST /stream`

Same as /invoke but streams Server-Sent Events.

curl -X POST http://localhost:8090/stream \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello" }'

Events (fields with null values are omitted from each payload):

data: {"type": "answer_delta", "content": "Your ", "used_tools": []}
data: {"type": "answer_delta", "content": "order ", "used_tools": []}
data: {"type": "route", "route": ["router", "router/orders_agent"], "used_tools": []}
data: {"type": "final", "content": "Your order is on the way.", "route": ["router", "router/orders_agent"], "system_name": "Enterprise Knowledge Assistant", "used_tools": [], "input_tokens": 812, "output_tokens": 96}

On failure a {"type": "error", "detail": "..."} event is emitted.

Conversation API

Base URL: http://localhost:8100 Manages multi-turn conversations with history persisted in SQLite (or Postgres via DATABASE_URL).

`POST /conversations`

Create a new conversation. The body is optional; session_id and user_id may be supplied.

curl -X POST http://localhost:8100/conversations \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user-123" }'

Response:

{ "conversation_id": "0d5a…", "session_id": "0d5a…" }

`POST /conversations/{id}/messages`

Send a message. Prior history is assembled automatically.

curl -X POST http://localhost:8100/conversations/0d5a…/messages \
  -H "Content-Type: application/json" \
  -d '{ "message": "Where is my order?" }'

Response:

{
  "answer": "Your order shipped yesterday.",
  "visited": ["router", "router/orders_agent"],
  "used_tools": [
    { "name": "get_order_status", "provider": "local", "status": "succeeded", "agent_id": "orders_agent" }
  ]
}

Errors: 404 unknown conversation, 429 conversation token budget exceeded.

`POST /conversations/{id}/messages/stream`

Same as above but streams via SSE. Preferred by the widget. Each event carries an event: name matching its type; null fields are omitted.

curl -X POST http://localhost:8100/conversations/0d5a…/messages/stream \
  -H "Content-Type: application/json" \
  -d '{ "message": "Where is my order?" }'

Events:

event: answer_delta
data: {"type": "answer_delta", "content": "Your order "}

event: route
data: {"type": "route", "route": ["router", "router/orders_agent"]}

event: final
data: {"type": "final", "content": "Your order shipped yesterday.", "route": ["router", "router/orders_agent"], "system_name": "…"}

event: done
data: [DONE]

On failure an event: error with {"type": "error", "error": "..."} is emitted before done.

The event schema also declares tool_started / tool_succeeded / tool_failed types for per-tool progress; the engine does not emit them yet.

`GET /conversations/{id}/messages`

Retrieve message history for a conversation.

curl http://localhost:8100/conversations/0d5a…/messages

Response:

[
  { "role": "user", "content": "Where is my order?", "created_at": "2026-07-02T10:00:00Z" },
  { "role": "assistant", "content": "Your order shipped yesterday.", "created_at": "2026-07-02T10:00:03Z" }
]

Passing context to plugins

The HTTP layer currently forwards a deliberately small amount of caller context into the run:

X-Session-ID (Engine API) becomes the run’s conversation id, visible to tracing.
user_id (Conversation API request bodies) is attached to the run context and persisted with the conversation.

Populating run_context.auth_context (scopes, roles, inbound access token) from request headers is part of the security/context gate that is not wired up yet — see the roadmap. Hooks such as on_run_start can inject a modified RunContext in the meantime.

Get Started

Core Concepts

Features

Widget

Reference

Two APIs

Engine API

Conversation API

Engine API

`GET /health`

`POST /invoke`

`POST /stream`

Conversation API

`POST /conversations`

`POST /conversations/{id}/messages`

`POST /conversations/{id}/messages/stream`

`GET /conversations/{id}/messages`

Passing context to plugins

​Two APIs

Engine API

Conversation API

​Engine API

​GET /health

​POST /invoke

​POST /stream

​Conversation API

​POST /conversations

​POST /conversations/{id}/messages

​POST /conversations/{id}/messages/stream

​GET /conversations/{id}/messages

​Passing context to plugins

Two APIs

Engine API

`GET /health`

`POST /invoke`

`POST /stream`

Conversation API

`POST /conversations`

`POST /conversations/{id}/messages`

`POST /conversations/{id}/messages/stream`

`GET /conversations/{id}/messages`

Passing context to plugins