Skip to main content
Notification types define the structure of one-way messages that don’t require a response. Notifications are used to stream updates and inform the other party of state changes.

​
Session Notifications

​
SessionNotification

Container for session update notifications sent from agent to client. 
export type SessionNotification = {
  method: string;
  params?: SessionUpdate | ExtNotification | null;
};
The params field contains a SessionUpdate, which is a union type representing different kinds of session updates.

​
SessionUpdate

Union type for all possible session update notifications. The agent sends these during prompt processing to stream content, tool calls, usage information, and more. 
export type SessionUpdate =
  | (ContentChunk & {
      type: "content";
    })
  | (ToolCallUpdate & {
      type: "tool_call";
    })
  | (UsageUpdate & {
      type: "usage";
    })
  | (SessionInfoUpdate & {
      type: "session_info";
    })
  | (CurrentModeUpdate & {
      type: "current_mode";
    })
  | (ConfigOptionUpdate & {
      type: "config_option";
    })
  | (AvailableCommandsUpdate & {
      type: "available_commands";
    });

​
Update Types

​
ContentChunk

A streamed item of content from the language model. 
export type ContentChunk = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * A single item of content
   */
  content: ContentBlock;
  /**
   * A unique identifier for the message this chunk belongs to (UNSTABLE).
   * All chunks belonging to the same message share the same messageId.
   */
  messageId?: string | null;
};
The content field is a ContentBlock: 
export type ContentBlock =
  | (TextContent & { type: "text" })
  | (ImageContent & { type: "image" })
  | (AudioContent & { type: "audio" })
  | (ResourceLink & { type: "resource_link" })
  | (EmbeddedResource & { type: "resource" });

​
ToolCallUpdate

Notifies about tool call execution status and results. 
export type ToolCallUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The tool call being updated.
   */
  toolCall: ToolCall;
};

export type ToolCall = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Human-readable description of what the tool is doing.
   */
  content: string;
  /**
   * Unique identifier for this tool call.
   */
  id: ToolCallId;
  /**
   * The kind of tool being called.
   */
  kind: ToolKind;
  /**
   * Optional location information (e.g., file path and line range).
   */
  location?: ToolCallLocation | null;
  /**
   * Current execution status of the tool call.
   */
  status: ToolCallStatus;
  /**
   * Optional result content if the tool call has completed.
   */
  toolCallContent?: ToolCallContent | null;
};
Tool call status: 
export type ToolCallStatus =
  | "pending"
  | "in_progress"
  | "completed"
  | "failed";
Tool kinds: 
export type ToolKind =
  | "read_file"
  | "write_file"
  | "edit_file"
  | "mcp_tool"
  | "command";

​
UsageUpdate

Notifies about token usage for the session. 
export type UsageUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The usage information.
   */
  usage: Usage;
};

export type Usage = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Optional cost information for the session (UNSTABLE).
   */
  cost?: Cost | null;
  /**
   * Number of input tokens used.
   */
  inputTokens: number;
  /**
   * Number of output tokens used.
   */
  outputTokens: number;
};

​
SessionInfoUpdate

Notifies about session information changes. 
export type SessionInfoUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The updated session information.
   */
  sessionInfo: SessionInfo;
};

export type SessionInfo = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Working directory path.
   */
  cwd: string;
  /**
   * Optional session name.
   */
  name?: string | null;
  /**
   * Optional agent plan for the session.
   */
  plan?: Plan | null;
  /**
   * The session ID.
   */
  sessionId: SessionId;
};

​
CurrentModeUpdate

Notifies that the session mode has changed. 
export type CurrentModeUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the current mode
   */
  currentModeId: SessionModeId;
};

​
ConfigOptionUpdate

Notifies that session configuration options have been updated. 
export type ConfigOptionUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The full set of configuration options and their current values.
   */
  configOptions: Array<SessionConfigOption>;
};

​
AvailableCommandsUpdate

Notifies that available commands are ready or have changed. 
export type AvailableCommandsUpdate = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Commands the agent can execute
   */
  availableCommands: Array<AvailableCommand>;
};

export type AvailableCommand = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * Human-readable description of what the command does.
   */
  description: string;
  /**
   * Input for the command if required
   */
  input?: AvailableCommandInput | null;
  /**
   * Command name (e.g., 'create_plan', 'research_codebase').
   */
  name: string;
};

​
Cancellation Notifications

​
CancelNotification

Notification to cancel ongoing operations for a session. 
export type CancelNotification = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the session to cancel operations for.
   */
  sessionId: SessionId;
};

​
CancelRequestNotification

UNSTABLE - Notification to cancel an ongoing request. 
export type CancelRequestNotification = {
  _meta?: {
    [key: string]: unknown;
  } | null;
  /**
   * The ID of the request to cancel.
   */
  requestId: RequestId;
};

​
Extensibility

​
ExtNotification

Allows for sending arbitrary notifications that are not part of the ACP spec. 
export type ExtNotification = unknown;
Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility.

​
Usage Example

Here’s how notifications are typically used: 
import { AgentConnection } from '@agentclientprotocol/sdk';

const conn = new AgentConnection(/* ... */);

// Listen for session updates
conn.onNotification('session/update', (notification) => {
  const update = notification.params;
  
  if (update.type === 'content') {
    // Handle content chunk
    console.log('Content:', update.content);
  } else if (update.type === 'tool_call') {
    // Handle tool call update
    console.log('Tool call:', update.toolCall);
  } else if (update.type === 'usage') {
    // Handle usage update
    console.log('Usage:', update.usage);
  }
});

// Send a prompt
await conn.prompt({
  sessionId: 'session-123',
  prompt: [{ content: { type: 'text', text: 'Hello!' } }]
});
The agent will send multiple SessionUpdate notifications during processing, allowing the client to stream content and display progress in real-time.

Build docs developers (and LLMs) love

Get started for freeTalk to us