Skip to content

Chat API Reference

The chat router is a FastAPI router factory that wires three HTTP endpoints onto your application. Import it from jarviscore.integrations.chat.

from jarviscore.integrations.chat import create_chat_router

app.include_router(
    create_chat_router(kernel=my_kernel),
    prefix="/api/v1",
)

The kernel argument must be a jarviscore.kernel.kernel.Kernel instance. The router is stateless: the same Kernel can be shared across multiple router mounts or agent instances.


create_chat_router

def create_chat_router(
    kernel,
    prefix: str = "",
    tags: Optional[List[str]] = None,
    on_behalf_of: Optional[Callable[[Request], OnBehalfOf | Person | str | None]] = None,
) -> APIRouter
Parameter Type Default Description
kernel Kernel required The Kernel that executes chat messages
prefix str "" Additional route prefix appended inside the router (independent of app.include_router(prefix=...))
tags List[str] ["chat"] FastAPI OpenAPI tag list
on_behalf_of callable None Whom each chat is for, from your own sign-in: a function of the request (sync or async) returning an OnBehalfOf, a Person, a person key or None. Raise HTTPException there to refuse. The chat then uses that person's credentials, within their mandate, and every record names them. A None result means the chat is for no one: the deployment's own identity. acting_for, mandate and scopes in the request's context are always dropped. With a resolver, each conversation (workflow_id) belongs to whoever started it: continuing it, streaming it (/chat/stream) or reading its history (/chat/history) as anyone else is refused with 403

Returns an APIRouter ready for app.include_router().

Raises ImportError if fastapi is not installed.


POST /chat

Send a natural language message to the agent and receive a synchronous answer.

The Kernel routes the task automatically based on its content: research and factual questions go to ResearcherSubAgent, coding tasks to CoderSubAgent, browser navigation to BrowserSubAgent, and communication tasks to CommunicatorSubAgent.

Trace events stream in real time on GET /chat/stream/{workflow_id} while the POST is in flight.

Request body

{
  "message": "string",
  "workflow_id": "string | null",
  "agent_id": "string | null",
  "system_prompt": "string | null",
  "context": "object | null"
}
Field Type Required Default Description
message str Yes : Natural language task or question
workflow_id str No auto-generated (chat_<12hex>) Workflow identifier; supply your own to correlate with the SSE stream
agent_id str No "chat" Agent identity passed to the Kernel
system_prompt str No "" System prompt prepended to the Kernel call
context dict No {} Arbitrary key-value context forwarded to the Kernel. workflow_id and step_id are merged in automatically; acting_for, mandate and scopes are dropped (whom a chat is for comes from on_behalf_of)

Response body

HTTP 200 on success. HTTP 500 with {"error": "...", "workflow_id": "..."} on Kernel exception.

{
  "workflow_id": "string",
  "step_id": "string",
  "status": "string",
  "answer": "string",
  "sources": [],
  "tokens": {},
  "elapsed_ms": 0.0
}
Field Type Description
workflow_id str Workflow identifier (use this to open the SSE stream)
step_id str Step identifier, formatted as step_<unix_timestamp>
status str "success", "failure", or "yield": taken directly from output.status
answer str Final answer text. Taken from output.summary, falling back to str(output.payload)[:2000]
sources List[dict] Citation sources extracted from researcher output. Each entry is {"title": "...", "url": "...", "source": "..."}. Capped at 10 entries
tokens dict Token usage from output.metadata["tokens"]. Keys depend on the provider
elapsed_ms float Wall-clock milliseconds from request receipt to response

GET /chat/stream/{workflow_id}

Server-Sent Events stream for a running or completed workflow. Returns Content-Type: text/event-stream.

Response headers set by the router:

Cache-Control: no-cache
X-Accel-Buffering: no
Connection: keep-alive

Behaviour

On connect, the stream replays all buffered events from Redis for the given workflow_id (catch-up for clients that connect after the POST has started). It then subscribes to the Redis PubSub channel trace_events:{workflow_id} and forwards new events until a step_complete event is received or the client disconnects.

The stream closes automatically after 300 seconds of inactivity. A heartbeat comment (: heartbeat) is sent every iteration to keep proxies from closing the connection.

When Redis is not configured, the stream returns a single error event and closes.

Event format

Each SSE message data field is a JSON object:

{
  "workflow_id": "string",
  "step_id": "string",
  "type": "string",
  "timestamp": "string",
  "data": {}
}
type value Description
thinking Internal reasoning token from the Kernel's OODA loop. data.thought contains the text
tool_start A sub-agent tool call has begun. data contains the tool name and arguments
tool_result A tool call has completed. data contains the result
llm_request An LLM call is being made
llm_response An LLM call has returned
step_complete The workflow step is done. data.summary contains the final answer. The client should close the stream after receiving this event
timeout The 300-second stream timeout was reached
error An internal error occurred. data.message contains the description

Client example

const es = new EventSource(`/api/v1/chat/stream/${workflowId}`)
es.onmessage = (e) => {
    const event = JSON.parse(e.data)
    if (event.type === 'thinking')      renderThought(event.data.thought)
    if (event.type === 'tool_start')    renderToolCall(event.data)
    if (event.type === 'tool_result')   renderToolResult(event.data)
    if (event.type === 'step_complete') {
        renderAnswer(event.data.summary)
        es.close()
    }
}

GET /chat/history/{workflow_id}/{step_id}

Returns the full buffered trace event log for a completed workflow step. Useful for replaying a conversation trace in a UI without maintaining an SSE connection.

Path parameters

Parameter Description
workflow_id Workflow identifier from the POST /chat response
step_id Step identifier from the POST /chat response

Response body

HTTP 200 on success. HTTP 500 with {"error": "..."} if the trace cannot be read.

{
  "events": []
}

events is a list of trace event objects in the same format as the SSE stream messages.

Redis is optional. Events are read from Redis when available and otherwise from trace files in the .jarviscore/traces/ directory.


Further Reading