Skip to main content
Create a streaming chat session with an AI agent that can execute tools and spawn subagents.

​
Request

​
model
string
required
The model to use for the agent. If not provided, uses the server’s default model (if configured). Format: provider/model-name (e.g., openai/gpt-4o-mini, anthropic/claude-3-5-sonnet-20241022)
​
messages
array
required
Array of conversation messages following the OpenAI message format.Each message has:
  • role - One of: system, user, assistant, tool
  • content - Message content (string or array of content parts for multimodal)
  • tool_calls - Tool calls made by assistant (for assistant role)
  • tool_call_id - ID of tool call this is responding to (for tool role)
​
context
string
Additional context to inject into the agent’s system prompt.
​
permissions
object
Tool execution permission rules.
​
mode
string
Execution mode. Options:
  • agent (default) - Standard agentic mode with tool execution
  • rlm - Reasoning Loop Mode for code execution with REPL
​
maxIterations
number
Maximum number of iterations for RLM mode (default: 10).
​
maxDepth
number
Maximum depth for recursive agent spawning in RLM mode (default: 2).

​
Example Request

curl -X POST http://localhost:4000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "List files in the current directory"
      }
    ],
    "permissions": {
      "allowlist": [
        {"tool": "bash", "params": {"command": "ls*"}}
      ]
    }
  }'

​
Response

Returns a Server-Sent Event stream with Content-Type: text/event-stream.

​
Connected Event

First event sent when connection is established:
​
type
string
Always "connected"
​
sessionId
string
Unique session identifier for this chat. Use this for relay requests.

​
Harness Start Event

​
type
string
Always "harness_start"
​
runId
string
Unique identifier for this agent run
​
agentId
string
ID of the agent emitting this event
​
parentId
string
Parent agent or tool call ID (if this is a subagent)
​
depth
number
Nesting depth for subagents
​
maxIterations
number
Maximum iterations allowed

​
Text Event

Streamed text content from the AI:
​
type
string
Always "text"
​
runId
string
Run identifier
​
id
string
Unique event ID
​
agentId
string
Agent identifier
​
parentId
string
Parent context ID
​
content
string
Text content chunk

​
Reasoning Event

Internal reasoning steps (for models that support extended thinking):
​
type
string
Always "reasoning"
​
runId
string
Run identifier
​
id
string
Unique event ID
​
agentId
string
Agent identifier
​
content
string
Reasoning content

​
Tool Call Event

Agent is invoking a tool:
​
type
string
Always "tool_call"
​
runId
string
Run identifier
​
id
string
Tool call ID (used to match with tool_result)
​
agentId
string
Agent identifier
​
name
string
Name of the tool being called
​
input
object
Tool input parameters

​
Tool Result Event

Result from tool execution:
​
type
string
Always "tool_result"
​
runId
string
Run identifier
​
id
string
Tool call ID (matches the tool_call event)
​
agentId
string
Agent identifier
​
name
string
Name of the tool that was executed
​
output
any
Tool output result

​
Relay Event

Permission request for tool execution:
​
type
string
Always "relay"
​
kind
string
Always "permission"
​
runId
string
Run identifier
​
id
string
Relay ID (use this to resolve the relay)
​
agentId
string
Agent identifier
​
toolCallId
string
ID of the tool call requiring permission
​
tool
string
Name of the tool requesting permission
​
params
object
Tool parameters for permission review

​
Usage Event

Token usage information:
​
type
string
Always "usage"
​
runId
string
Run identifier
​
agentId
string
Agent identifier
​
inputTokens
number
Number of input tokens used
​
outputTokens
number
Number of output tokens generated
​
cacheReadTokens
number
Tokens read from cache (if supported)
​
cacheCreationTokens
number
Tokens used to create cache (if supported)

​
Harness End Event

​
type
string
Always "harness_end"
​
runId
string
Run identifier
​
agentId
string
Agent identifier
​
reason
string
Why the harness ended: "final" or "max_iterations"
​
iterations
number
Number of iterations completed
​
totalUsage
object
Cumulative token usage for the entire run

​
Error Event

​
type
string
Always "error"
​
runId
string
Run identifier (if available)
​
agentId
string
Agent identifier
​
message
string
Error message

​
Example Response Stream

event: connected
data: {"type":"connected","sessionId":"01963a5c-7890-7abc-def0-123456789abc"}

event: harness_start
data: {"type":"harness_start","runId":"01963a5c-7891-7abc-def0-123456789abc","agentId":"01963a5c-7892-7abc-def0-123456789abc"}

event: text
data: {"type":"text","runId":"01963a5c-7891-7abc-def0-123456789abc","id":"msg_1","agentId":"01963a5c-7892-7abc-def0-123456789abc","content":"I'll list the files"}

event: tool_call
data: {"type":"tool_call","runId":"01963a5c-7891-7abc-def0-123456789abc","id":"call_abc123","agentId":"01963a5c-7892-7abc-def0-123456789abc","name":"bash","input":{"command":"ls"}}

event: tool_result
data: {"type":"tool_result","runId":"01963a5c-7891-7abc-def0-123456789abc","id":"call_abc123","agentId":"01963a5c-7892-7abc-def0-123456789abc","name":"bash","output":"file1.txt\nfile2.txt"}

event: harness_end
data: {"type":"harness_end","runId":"01963a5c-7891-7abc-def0-123456789abc","agentId":"01963a5c-7892-7abc-def0-123456789abc","reason":"final","iterations":1}

​
Error Responses

​
400 Bad Request

Returned when the request is malformed: 
{
  "error": "Invalid JSON body"
}
or 
{
  "error": "model and messages are required"
}

​
Notes

  • Each POST /chat creates a fresh AgentOrchestrator for that session
  • The orchestrator is automatically cleaned up when the SSE stream ends
  • Default tools available: agent (spawn subagents), bash, read, patch
  • Skills are automatically discovered from configured skill directories and injected into the system prompt
  • All events after the initial connected event include an agentId field

Build docs developers (and LLMs) love

Get started for freeTalk to us