Notification Types

Notification types for one-way messages

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.