This page is a protocol reference for ACP (Agent Client Protocol) v1 — the protocol simse uses to communicate with AI backends. It covers message types, field naming, session lifecycle, permission flow, and tool call lifecycle.
| Property | Value |
|---|---|
| Protocol version | 1 |
| Field naming | camelCase (sessionId, stopReason, agentInfo) |
| Transport | Local subprocess (stdio) |
| Specification | agentclientprotocol.com |
Creates a new session on the backend.
Request fields:
| Field | Type | Description |
|---|---|---|
cwd | string | Working directory for the session |
mcpServers | array | Optional list of MCP servers to make available |
Response fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | Unique session identifier, used in all subsequent calls |
Sends a message to an existing session.
Request fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | Session identifier from session/new |
prompt | string | The prompt text |
Response: Streams session/update notifications until completion.
Streamed from the backend during response generation.
Fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | The session this update belongs to |
sessionUpdate | string | Discriminator for the update type: agent_message_chunk, tool_call, tool_call_update |
When the backend wants to execute an action requiring user approval, it sends a permission request embedded in a session/update notification.
Permission request fields:
| Field | Type | Description |
|---|---|---|
type | string | "request_permission" |
action | string | The action being requested |
description | string | Human-readable description of what will happen |
requestId | string | Identifier for this permission request |
Permission response values:
| Value | Behavior |
|---|---|
allow_once | Permit this specific action instance |
allow_always | Permit this action type for the remainder of the session |
reject_once | Deny this specific action instance |
reject_always | Deny this action type for the remainder of the session |
Tool calls are initiated by the backend and executed by simse.
The backend requests a tool invocation.
Fields:
| Field | Type | Description |
|---|---|---|
type | string | "tool_call" |
toolCallId | string | Unique identifier for this tool call |
toolName | string | Name of the tool to invoke |
input | object | Tool input parameters |
simse has started executing the tool.
Fields:
| Field | Type | Description |
|---|---|---|
type | string | "tool_call_update" |
toolCallId | string | Matches the originating tool_call |
status | string | "in_progress" |
Tool execution finished. Result is returned to the backend.
Fields:
| Field | Type | Description |
|---|---|---|
type | string | "tool_call_update" |
toolCallId | string | Matches the originating tool_call |
status | string | "completed" |
output | any | Tool execution result |
error | string | Error message if execution failed |
| Timeout | Default | Config key |
|---|---|---|
| Request timeout | 60,000 ms | timeoutMs |
Configurable per server in acp.json.