Skip to main content
The schema module exports important constants for working with the Agent Client Protocol.

​
Protocol Version

​
PROTOCOL_VERSION

The current version of the Agent Client Protocol. 
export const PROTOCOL_VERSION = 1;
Use this constant when initializing a connection: 
import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk/schema';

const response = await conn.initialize({
  protocolVersion: PROTOCOL_VERSION,
  clientCapabilities: { /* ... */ },
  clientInfo: {
    name: 'my-client',
    version: '1.0.0'
  }
});

​
Method Name Constants

The SDK exports constants for all protocol method names. These ensure type safety and prevent typos when working with method names directly.

​
AGENT_METHODS

Method names for requests sent to agents (client-to-agent). 
export const AGENT_METHODS = {
  authenticate: "authenticate",
  initialize: "initialize",
  session_cancel: "session/cancel",
  session_fork: "session/fork",
  session_list: "session/list",
  session_load: "session/load",
  session_new: "session/new",
  session_prompt: "session/prompt",
  session_resume: "session/resume",
  session_set_config_option: "session/set_config_option",
  session_set_mode: "session/set_mode",
  session_set_model: "session/set_model",
  session_stop: "session/stop",
} as const;

​
Usage Example

import { AGENT_METHODS } from '@agentclientprotocol/sdk/schema';

// Using with custom request handling
const request = {
  id: '1',
  method: AGENT_METHODS.session_prompt,
  params: { /* ... */ }
};

​
Method Descriptions

  • authenticate: Authenticate with the agent
  • initialize: Initialize the connection
  • session_cancel: Cancel ongoing session operations
  • session_fork: Fork an existing session (UNSTABLE)
  • session_list: List available sessions (UNSTABLE)
  • session_load: Load an existing session
  • session_new: Create a new session
  • session_prompt: Send a prompt to the session
  • session_resume: Resume a stopped session (UNSTABLE)
  • session_set_config_option: Update a configuration option
  • session_set_mode: Change the session mode
  • session_set_model: Change the session model (UNSTABLE)
  • session_stop: Stop a running session (UNSTABLE)

​
CLIENT_METHODS

Method names for requests sent to clients (agent-to-client). 
export const CLIENT_METHODS = {
  fs_read_text_file: "fs/read_text_file",
  fs_write_text_file: "fs/write_text_file",
  session_request_permission: "session/request_permission",
  session_update: "session/update",
  terminal_create: "terminal/create",
  terminal_kill: "terminal/kill",
  terminal_output: "terminal/output",
  terminal_release: "terminal/release",
  terminal_wait_for_exit: "terminal/wait_for_exit",
} as const;

​
Usage Example

import { CLIENT_METHODS } from '@agentclientprotocol/sdk/schema';

// Register handler for file read requests
conn.onRequest(CLIENT_METHODS.fs_read_text_file, async (request) => {
  const { path } = request.params;
  const content = await fs.readFile(path, 'utf-8');
  return { content };
});

​
Method Descriptions

File System Methods:
  • fs_read_text_file: Read a text file from the file system
  • fs_write_text_file: Write a text file to the file system
Session Methods:
  • session_request_permission: Request user permission for an operation
  • session_update: Stream session updates (notification)
Terminal Methods:
  • terminal_create: Create a new terminal
  • terminal_kill: Kill a terminal process
  • terminal_output: Get terminal output
  • terminal_release: Release a terminal
  • terminal_wait_for_exit: Wait for terminal to exit

​
Type Safety

All method constant objects are defined with as const to ensure type safety: 
// Type is inferred as the literal string "session/prompt"
const method = AGENT_METHODS.session_prompt;

// TypeScript will catch typos
const invalid = AGENT_METHODS.sesion_prompt; // Error: Property does not exist

​
Working with Custom Methods

While the protocol defines standard methods, you can also use custom extension methods: 
import { AGENT_METHODS } from '@agentclientprotocol/sdk/schema';

// Standard method
await conn.request({
  method: AGENT_METHODS.session_prompt,
  params: { /* ... */ }
});

// Custom extension method
await conn.request({
  method: 'x-custom/my-method',
  params: { /* ... */ }
});
Custom methods should be prefixed with x- to avoid conflicts with future protocol additions.

​
Notification Methods

Some methods are notifications (one-way messages) rather than requests: 
import { CLIENT_METHODS } from '@agentclientprotocol/sdk/schema';

// session_update is a notification method
conn.onNotification(CLIENT_METHODS.session_update, (notification) => {
  console.log('Session update:', notification.params);
});
Notifications:
  • Don’t expect a response
  • Don’t have a request ID
  • Are used for streaming updates

​
Method Naming Convention

The protocol uses a consistent naming pattern:
  • Method names use lowercase with slashes: noun/verb
  • Constants use underscores: noun_verb
  • TypeScript types use PascalCase: VerbNounRequest/VerbNounResponse
Examples:
Protocol MethodConstantRequest TypeResponse Type
session/newsession_newNewSessionRequestNewSessionResponse
session/promptsession_promptPromptRequestPromptResponse
terminal/createterminal_createCreateTerminalRequestCreateTerminalResponse
fs/read_text_filefs_read_text_fileReadTextFileRequestReadTextFileResponse

Build docs developers (and LLMs) love

Get started for freeTalk to us