Agent Channel

AI agent interaction and streaming

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"
}

Field	Type	Required	Description
prompt	string	Yes	Natural language instruction for the agent
taskId	string	No	Client-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"
}

Field	Type	Required	Description
provider	string	No	LLM provider name
model	string	No	Model identifier

abort

Cancel a running agent task.

{
  "channel": "agent",
  "type": "abort",
  "taskId": "task-abc-123"
}

Field	Type	Required	Description
taskId	string	Yes	Task 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"
}

Field	Type	Required	Description
toolCallId	string	Yes	ID of the tool call to respond to
result	string	Yes	User’s response

approve

Approve a permission request from the agent (e.g., before running a destructive command).

{
  "channel": "agent",
  "type": "approve",
  "requestId": "perm-789"
}

Field	Type	Required	Description
requestId	string	Yes	Permission request to approve

reject

Reject a permission request from the agent.

{
  "channel": "agent",
  "type": "reject",
  "requestId": "perm-789"
}

Field	Type	Required	Description
requestId	string	Yes	Permission 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..."
}

Field	Type	Description
content	string	Incremental 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..."
}

Field	Type	Description
content	string	Internal 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..."
  }
}

Field	Type	Description
toolCallId	string	Unique identifier for this tool call
toolName	string	Name of the tool being invoked
args	object	Arguments 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"
}

Field	Type	Description
toolCallId	string	ID of the completed tool call
result	string or object	Tool 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?"
  ]
}

Field	Type	Description
questions	array of strings	Questions 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"
}

Field	Type	Description
summary	string	Summary of what was accomplished

error

The agent task failed.

{
  "channel": "agent",
  "type": "error",
  "message": "Failed to install dependencies: npm ERR! 404 Not Found"
}

Field	Type	Description
message	string	Error 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 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.