Skip to main content

​
Overview

Request types represent messages sent from clients to agents that expect a response. Each request has a corresponding response type.

​
Initialize

Establishes the connection with a client and negotiates protocol capabilities.

​
InitializeRequest

​
protocolVersion
int
required
The protocol version the client supports
​
clientInfo
Implementation
Information about the client implementation
​
clientCapabilities
ClientCapabilities
Capabilities advertised by the client
​
_meta
Map<String, dynamic>
Optional metadata for the request

​
Authentication

​
AuthenticateRequest

Authenticates the client using the specified authentication method.
​
methodId
String
required
The ID of the authentication method to use (from the agent’s advertised auth methods)
​
_meta
Map<String, dynamic>
Optional metadata

​
Session Management

​
NewSessionRequest

Creates a new conversation session with the agent.
​
cwd
String
required
The current working directory for the session
​
mcpServers
List<McpServerBase>
required
List of MCP servers to connect to. Can be HttpMcpServer, SseMcpServer, or StdioMcpServer
​
_meta
Map<String, dynamic>
Optional metadata

​
LoadSessionRequest

Loads an existing session to resume a previous conversation.
​
sessionId
String
required
The ID of the session to load
​
cwd
String
required
The current working directory for the session
​
mcpServers
List<McpServerBase>
required
List of MCP servers to connect to
​
_meta
Map<String, dynamic>
Optional metadata

​
ListSessionsRequest

UNSTABLE: This capability is not part of the spec yet, and may be removed or changed at any point.
Lists existing sessions from the agent.
​
cursor
String
Pagination cursor for fetching the next page of results
​
cwd
String
Filter sessions by current working directory
​
_meta
Map<String, dynamic>
Optional metadata

​
ForkSessionRequest

UNSTABLE: This capability is not part of the spec yet, and may be removed or changed at any point.
Forks an existing session to create a new independent session.
​
sessionId
SessionId
required
The ID of the session to fork
​
cwd
String
required
The current working directory for the new session
​
mcpServers
List<McpServerBase>
Optional list of MCP servers for the forked session
​
_meta
Map<String, dynamic>
Optional metadata

​
ResumeSessionRequest

UNSTABLE: This capability is not part of the spec yet, and may be removed or changed at any point.
Resumes an existing session without replaying previous messages.
​
sessionId
SessionId
required
The ID of the session to resume
​
cwd
String
required
The current working directory for the session
​
mcpServers
List<McpServerBase>
Optional list of MCP servers
​
_meta
Map<String, dynamic>
Optional metadata

​
SetSessionModeRequest

Sets the operational mode for a session.
​
sessionId
String
required
The ID of the session
​
modeId
String
required
The ID of the mode to set (must be from availableModes)
​
_meta
Map<String, dynamic>
Optional metadata

​
SetSessionConfigOptionRequest

Sets the current value for a session configuration option.
​
sessionId
SessionId
required
The ID of the session
​
configId
SessionConfigId
required
The ID of the configuration option to set
​
value
SessionConfigValueId
required
The new value for the configuration option
​
_meta
Map<String, dynamic>
Optional metadata

​
SetSessionModelRequest

UNSTABLE: This capability is not part of the spec yet, and may be removed or changed at any point.
Selects the model for a given session.
​
sessionId
String
required
The ID of the session
​
modelId
String
required
The ID of the model to use
​
_meta
Map<String, dynamic>
Optional metadata

​
Prompt

​
PromptRequest

Processes a user prompt within a session. See User Message.
​
sessionId
String
required
The ID of the session this prompt belongs to
​
prompt
List<ContentBlock>
required
Structured content blocks representing the user’s message. Can include text, images, audio, resources, etc.
​
_meta
Map<String, dynamic>
Optional metadata

​
File System

​
WriteTextFileRequest

Writes content to a text file in the client’s file system.
​
sessionId
String
required
The ID of the session
​
path
String
required
The file path to write to
​
content
String
required
The text content to write
​
_meta
Map<String, dynamic>
Optional metadata

​
ReadTextFileRequest

Reads content from a text file in the client’s file system.
​
sessionId
String
required
The ID of the session
​
path
String
required
The file path to read from
​
line
int
Optional starting line number (0-based)
​
limit
int
Optional maximum number of lines to read
​
_meta
Map<String, dynamic>
Optional metadata

​
Permissions

​
RequestPermissionRequest

Requests permission from the user for a tool call operation.
​
sessionId
String
required
The ID of the session
​
options
List<PermissionOption>
required
Available permission options to present to the user
​
toolCall
ToolCallUpdate
required
Information about the tool call requesting permission
​
_meta
Map<String, dynamic>
Optional metadata

​
Terminal

​
CreateTerminalRequest

Creates a new terminal and executes a command.
​
sessionId
String
required
The ID of the session
​
command
String
required
The command to execute in the terminal
​
args
List<String>
Arguments to pass to the command
​
cwd
String
Working directory for the command (defaults to current directory)
​
env
List<EnvVariable>
Environment variables to set for the command
​
outputByteLimit
int
Optional limit for terminal output bytes returned in responses
​
_meta
Map<String, dynamic>
Optional metadata

​
TerminalOutputRequest

Gets the current output and exit status of a terminal.
​
sessionId
String
required
The ID of the session
​
terminalId
String
required
The ID of the terminal
​
_meta
Map<String, dynamic>
Optional metadata

​
ReleaseTerminalRequest

Releases a terminal and frees all associated resources.
​
sessionId
String
required
The ID of the session
​
terminalId
String
required
The ID of the terminal to release
​
_meta
Map<String, dynamic>
Optional metadata

​
WaitForTerminalExitRequest

Waits for a terminal command to exit and returns its exit status.
​
sessionId
String
required
The ID of the session
​
terminalId
String
required
The ID of the terminal
​
_meta
Map<String, dynamic>
Optional metadata

​
KillTerminalCommandRequest

Kills a terminal command without releasing the terminal.
​
sessionId
String
required
The ID of the session
​
terminalId
String
required
The ID of the terminal
​
_meta
Map<String, dynamic>
Optional metadata

​
MCP Server Types

​
HttpMcpServer

HTTP-based MCP server configuration.
​
type
String
default:"http"
Server type (always “http”)
​
name
String
required
Name of the MCP server
​
url
String
required
The HTTP URL for the server
​
headers
List<HttpHeader>
required
HTTP headers to include with requests

​
SseMcpServer

Server-Sent Events based MCP server configuration.
​
type
String
default:"sse"
Server type (always “sse”)
​
name
String
required
Name of the MCP server
​
url
String
required
The SSE URL for the server
​
headers
List<HttpHeader>
required
HTTP headers to include with the SSE connection

​
StdioMcpServer

Stdio-based MCP server configuration.
​
name
String
required
Name of the MCP server
​
command
String
required
The command to execute
​
args
List<String>
required
Arguments for the command
​
env
List<EnvVariable>
required
Environment variables for the command

Build docs developers (and LLMs) love

Get started for freeTalk to us