npm install @tencent-ai/agent-sdk

yarn add @tencent-ai/agent-sdk
pnpm add @tencent-ai/agent-sdk

function query(params: {
  prompt: string | AsyncIterable<UserMessage>;
  options?: Options;
}): Query;

interface Query extends AsyncGenerator<Message, void> {
  // Interrupt the current execution
  interrupt(): Promise<void>;

  // Dynamically modify the permission mode
  setPermissionMode(mode: PermissionMode): Promise<void>;

  // Dynamically modify the model
  setModel(model?: string): Promise<void>;

  // Set the maximum number of thinking tokens
  setMaxThinkingTokens(tokens: number | null): Promise<void>;

  // Get the list of available permission modes
  getAvailableModes(): Promise<ModeInfo[]>;

  // Get the list of available models
  getAvailableModels(): Promise<ModelInfo[]>;

  // Get the supported slash commands
  supportedCommands(): Promise<SlashCommand[]>;

  // Get the list of supported models
  supportedModels(): Promise<ModelInfo[]>;

  // Get the MCP server status
  mcpServerStatus(): Promise<McpServerStatus[]>;

  // Get account information
  accountInfo(): Promise<AccountInfo>;

  // Stream user messages as input
  streamInput(stream: AsyncIterable<UserMessage>): Promise<void>;
}

// All supported Hook events
const HOOK_EVENTS: readonly [
  'PreToolUse',
  'PostToolUse',
  'PostToolUseFailure',
  'Notification',
  'UserPromptSubmit',
  'SessionStart',
  'SessionEnd',
  'Stop',
  'SubagentStart',
  'SubagentStop',
  'PreCompact',
  'PermissionRequest',
  'WorktreeCreate',
  'WorktreeRemove'
];

// All exit reasons
const EXIT_REASONS: readonly [
  'user_cancelled',
  'tool_error',
  'max_turns',
  'max_budget_usd',
  'completed',
  'interrupted',
  'hook_blocked'
];

class AbortError extends Error {
  // Thrown when the operation is aborted
}

function unstable_v2_createSession(options: SessionOptions): Session;

function unstable_v2_resumeSession(
  sessionId: string,
  options: SessionOptions
): Session;

function unstable_v2_prompt(
  message: string,
  options: SessionOptions
): Promise<Message[]>;

function unstable_v2_authenticate(options: AuthenticateOptions): Promise<AuthenticateResponse>;

import { unstable_v2_authenticate } from '@tencent-ai/agent-sdk';
import open from 'open';

// Log in to the overseas edition.
const result = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: async (authState) => {
    console.log('Please log in:', authState.authUrl);
    await open(authState.authUrl);
  }
});

console.log('Login successful:', result.userinfo.userName);

// Log in to a self-hosted deployment.
const result2 = await unstable_v2_authenticate({
  endpoint: 'https://your-company.com',
  onAuthUrl: async (authState) => {
    console.log('Please log in:', authState.authUrl);
    await open(authState.authUrl);
  }
});

function unstable_v2_logout(options?: LogoutOptions): Promise<void>;

import { unstable_v2_authenticate, unstable_v2_logout } from '@tencent-ai/agent-sdk';

// Log in.
const result = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: (authState) => console.log('Login:', authState.authUrl),
});

// Log out
await unstable_v2_logout({ environment: 'external' });

// Log in again as a different user.
const newUser = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: (authState) => console.log('Login:', authState.authUrl),
});

interface Session {
  // Session ID (available after initialization).
  readonly sessionId: string;

  // Send a message.
  send(message: string | UserMessage): Promise<void>;

  // Get the response stream.
  stream(): AsyncGenerator<Message, void>;

  // Close the session.
  close(): void;

  // Release asynchronously.
  [Symbol.asyncDispose](): Promise<void>;
}

type SessionOptions = {
  model: string;
  pathToCodebuddyCode?: string;
  executable?: 'node' | 'bun';
  executableArgs?: string[];
  env?: Record<string, string | undefined>;
  canUseTool?: CanUseTool;
};

type SettingSource = 'user' | 'project' | 'local';

// Default: Do not load any configuration (clean environment).
const q = query({ prompt: '...' });

// Load project configuration.
const q = query({
  prompt: '...',
  options: { settingSources: ['project'] }
});

// Load all configuration (similar to CLI behavior).
const q = query({
  prompt: '...',
  options: { settingSources: ['user', 'project', 'local'] }
});

type PermissionMode =
  | 'default'           // Default mode. All operations require confirmation.
  | 'acceptEdits'       // Automatically approve file edits.
  | 'bypassPermissions' // Skip all permission checks.
  | 'plan'              // Plan mode. Read-only access.

type PermissionResult =
  | {
      behavior: 'allow';
      updatedInput: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: CanUseToolOptions
) => Promise<PermissionResult>;

type CanUseToolOptions = {
  signal: AbortSignal;
  suggestions?: PermissionUpdate[];
  blockedPath?: string;
  decisionReason?: string;
  toolUseID: string;
  agentID?: string;
};

type AgentDefinition = {
  description: string;          // Agent description
  prompt: string;               // System prompt
  tools?: string[];             // Allowed tools
  disallowedTools?: string[];   // Disallowed tools
  model?: string;               // Model used
};

interface ModeInfo {
  id: string;           // Mode ID
  name: string;         // Display name
  description: string;  // Mode description
}

interface ModelInfo {
  modelId: string;       // Model ID
  name: string;          // Display name
  description?: string;  // Model description
}

// Stdio type
type McpStdioServerConfig = {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

// SSE type
type McpSSEServerConfig = {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
};

// HTTP type
type McpHttpServerConfig = {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
};

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig;

type HookEvent =
  | 'PreToolUse'
  | 'PostToolUse'
  | 'PostToolUseFailure'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStart'
  | 'SubagentStop'
  | 'PreCompact'
  | 'PermissionRequest'
  | 'WorktreeCreate'
  | 'WorktreeRemove';

type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;        // Matching pattern (regex supported)
  hooks: HookCallback[];   // List of callback functions
  timeout?: number;        // Timeout in milliseconds
}

// Output synchronously.
type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?: Record<string, unknown>;
};

// Output asynchronously.
type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
};

type HookJSONOutput = SyncHookJSONOutput | AsyncHookJSONOutput;

type Message =
  | SystemMessage
  | UserMessage
  | AssistantMessage
  | PartialAssistantMessage
  | ResultMessage
  | CompactBoundaryMessage
  | StatusMessage
  | TaskStartedMessage
  | TaskNotificationMessage
  | ToolProgressMessage;

type SystemMessage = {
  type: 'system';
  subtype: 'init';
  uuid: string;
  session_id: string;
  apiKeySource?: string;
  cwd?: string;
  tools: string[];
  mcp_servers?: Array<{ name: string; status: string }>;
  model: string;
  permissionMode: PermissionMode;
  slash_commands?: string[];
  codebuddy_code_version?: string;
  skills?: string[];
  plugins?: Array<{ name: string; path: string }>;
};

interface TaskStartedMessage {
  type: 'system';
  subtype: 'task_started';
  task_id: string;
  tool_use_id?: string;
  description: string;
  task_type?: string; // "Bash" / "PowerShell" / "Workflow" / "Agent"
  uuid: string;
  session_id: string;
}

interface TaskUsage {
  total_tokens: number;
  tool_uses: number;
  duration_ms: number;
}

interface TaskProgressMessage {
  type: 'system';
  subtype: 'task_progress';
  task_id: string;
  tool_use_id?: string;
  description: string;
  usage: TaskUsage;
  last_tool_name?: string;
  uuid: string;
  session_id: string;
}

interface TaskUpdatedMessage {
  type: 'system';
  subtype: 'task_updated';
  task_id: string;
  patch: Record<string, unknown>; // e.g. { status, end_time }
  status?: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'killed';
  uuid?: string;
  session_id?: string;
}