Skip to main content

​
Overview

The agent channel carries AI agent prompts, streaming responses, and tool interactions. The agent processes natural language prompts, executes tools in the workspace, and streams results back to the client.

​
Client to Server Messages

​
prompt

Start a new agent task with a natural language prompt. 
{
  "channel": "agent",
  "type": "prompt",
  "prompt": "Create a REST API with Express that has CRUD endpoints for users",
  "taskId": "task-abc-123"
}
FieldTypeRequiredDescription
promptstringYesNatural language instruction for the agent
taskIdstringNoClient-generated task identifier for tracking

​
settings

Configure agent behavior for the current session. 
{
  "channel": "agent",
  "type": "settings",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250929"
}
FieldTypeRequiredDescription
providerstringNoLLM provider name
modelstringNoModel identifier

​
abort

Cancel a running agent task. 
{
  "channel": "agent",
  "type": "abort",
  "taskId": "task-abc-123"
}
FieldTypeRequiredDescription
taskIdstringYesTask to cancel

​
tool_response

Respond to a tool call that requires user input. 
{
  "channel": "agent",
  "type": "tool_response",
  "toolCallId": "tc-456",
  "result": "Yes, use PostgreSQL for the database"
}
FieldTypeRequiredDescription
toolCallIdstringYesID of the tool call to respond to
resultstringYesUser’s response

​
approve

Approve a permission request from the agent (e.g., before running a destructive command). 
{
  "channel": "agent",
  "type": "approve",
  "requestId": "perm-789"
}
FieldTypeRequiredDescription
requestIdstringYesPermission request to approve

​
reject

Reject a permission request from the agent. 
{
  "channel": "agent",
  "type": "reject",
  "requestId": "perm-789"
}
FieldTypeRequiredDescription
requestIdstringYesPermission request to reject

​
Server to Client Events

The agent streams events as it processes a task. Events arrive in order and represent the agent’s reasoning, tool use, and final output.

​
text

Streamed text output from the agent. 
{
  "channel": "agent",
  "type": "text",
  "content": "I'll create a REST API with Express..."
}
FieldTypeDescription
contentstringIncremental text content
Text events are streamed token-by-token. Concatenate all text events to build the full response.

​
thinking

Agent reasoning content (available for models that support extended thinking). 
{
  "channel": "agent",
  "type": "thinking",
  "content": "The user wants CRUD endpoints. I should create routes for GET, POST, PUT, DELETE..."
}
FieldTypeDescription
contentstringInternal reasoning text

​
tool_invocation

The agent is calling a tool. 
{
  "channel": "agent",
  "type": "tool_invocation",
  "toolCallId": "tc-456",
  "toolName": "write_file",
  "args": {
    "path": "/src/routes/users.ts",
    "content": "import { Router } from 'express';\n..."
  }
}
FieldTypeDescription
toolCallIdstringUnique identifier for this tool call
toolNamestringName of the tool being invoked
argsobjectArguments passed to the tool

​
tool_result

A tool call has completed. 
{
  "channel": "agent",
  "type": "tool_result",
  "toolCallId": "tc-456",
  "result": "File written: /src/routes/users.ts"
}
FieldTypeDescription
toolCallIdstringID of the completed tool call
resultstring or objectTool execution result

​
question

The agent is asking the user for input. 
{
  "channel": "agent",
  "type": "question",
  "questions": [
    "Which database would you like to use: PostgreSQL, MySQL, or SQLite?"
  ]
}
FieldTypeDescription
questionsarray of stringsQuestions the agent needs answered
Respond with a tool_response message to continue the agent’s task.

​
result

The agent task has completed. 
{
  "channel": "agent",
  "type": "result",
  "summary": "Created Express REST API with CRUD endpoints for users at /src/routes/users.ts"
}
FieldTypeDescription
summarystringSummary of what was accomplished

​
error

The agent task failed. 
{
  "channel": "agent",
  "type": "error",
  "message": "Failed to install dependencies: npm ERR! 404 Not Found"
}
FieldTypeDescription
messagestringError description

​
done

Stream is complete. No more events will be sent for this task. 
{
  "channel": "agent",
  "type": "done"
}

​
Conversation History

Agent conversation history is persisted to the agent_messages table in the database. On WebSocket reconnect, previous messages are replayed so the client can restore the conversation UI. History supports undo and truncation via soft-delete, allowing users to roll back the conversation to an earlier point and re-prompt from there.