Documentation Index
Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
Use this file to discover all available pages before exploring further.
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;
};
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;
};
content field is a ContentBlock:
export type ContentBlock =
| (TextContent & { type: "text" })
| (ImageContent & { type: "image" })
| (AudioContent & { type: "audio" })
| (ResourceLink & { type: "resource_link" })
| (EmbeddedResource & { type: "resource" });
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;
};
export type ToolCallStatus =
| "pending"
| "in_progress"
| "completed"
| "failed";
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;
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!' } }]
});
SessionUpdate notifications during processing, allowing the client to stream content and display progress in real-time.