Schema Constants

Protocol constants and method names

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 Method	Constant	Request Type	Response Type
session/new	session_new	NewSessionRequest	NewSessionResponse
session/prompt	session_prompt	PromptRequest	PromptResponse
terminal/create	terminal_create	CreateTerminalRequest	CreateTerminalResponse
fs/read_text_file	fs_read_text_file	ReadTextFileRequest	ReadTextFileResponse