TypeScript SDK 参考

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(): Promise<void>;

  // 动态修改权限模式
  setPermissionMode(mode: PermissionMode): Promise<void>;

  // 动态修改模型
  setModel(model?: string): Promise<void>;

  // 设置最大思考 token 数
  setMaxThinkingTokens(tokens: number | null): Promise<void>;

  // 获取可用权限模式列表
  getAvailableModes(): Promise<ModeInfo[]>;

  // 获取可用模型列表
  getAvailableModels(): Promise<ModelInfo[]>;

  // 获取支持的斜杠命令
  supportedCommands(): Promise<SlashCommand[]>;

  // 获取支持的模型列表
  supportedModels(): Promise<ModelInfo[]>;

  // 获取 MCP 服务器状态
  mcpServerStatus(): Promise<McpServerStatus[]>;

  // 获取账户信息
  accountInfo(): Promise<AccountInfo>;

  // 流式输入用户消息
  streamInput(stream: AsyncIterable<UserMessage>): Promise<void>;
}

// 所有支持的 Hook 事件
const HOOK_EVENTS: readonly [
  'PreToolUse',
  'PostToolUse',
  'PostToolUseFailure',
  'Notification',
  'UserPromptSubmit',
  'SessionStart',
  'SessionEnd',
  'Stop',
  'SubagentStart',
  'SubagentStop',
  'PreCompact',
  'PermissionRequest',
  'WorktreeCreate',
  'WorktreeRemove'
];

// 所有退出原因
const EXIT_REASONS: readonly [
  'user_cancelled',
  'tool_error',
  'max_turns',
  'max_budget_usd',
  'completed',
  'interrupted',
  'hook_blocked'
];

class AbortError extends Error {
  // 当操作被中止时抛出
}

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';

// 海外版登录
const result = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: async (authState) => {
    console.log('请登录:', authState.authUrl);
    await open(authState.authUrl);
  }
});

console.log('登录成功:', result.userinfo.userName);

// 私有化部署登录
const result2 = await unstable_v2_authenticate({
  endpoint: 'https://your-company.com',
  onAuthUrl: async (authState) => {
    console.log('请登录:', 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';

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

// 登出
await unstable_v2_logout({ environment: 'external' });

// 以不同用户重新登录
const newUser = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: (authState) => console.log('Login:', authState.authUrl),
});

interface Session {
  // 会话 ID（初始化后可用）
  readonly sessionId: string;

  // 发送消息
  send(message: string | UserMessage): Promise<void>;

  // 获取响应流
  stream(): AsyncGenerator<Message, void>;

  // 关闭会话
  close(): void;

  // 异步释放
  [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';

// 默认：不加载任何配置（干净环境）
const q = query({ prompt: '...' });

// 加载项目配置
const q = query({
  prompt: '...',
  options: { settingSources: ['project'] }
});

// 加载所有配置（类似 CLI 行为）
const q = query({
  prompt: '...',
  options: { settingSources: ['user', 'project', 'local'] }
});

type PermissionMode =
  | 'default'           // 默认模式，所有操作需确认
  | 'acceptEdits'       // 自动批准文件编辑
  | 'bypassPermissions' // 跳过所有权限检查
  | 'plan'              // 规划模式，仅允许读取

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 描述
  prompt: string;               // 系统提示词
  tools?: string[];             // 允许的工具
  disallowedTools?: string[];   // 禁止的工具
  model?: string;               // 使用的模型
};

interface ModeInfo {
  id: string;           // 模式 ID
  name: string;         // 显示名称
  description: string;  // 模式说明
}

interface ModelInfo {
  modelId: string;       // 模型 ID
  name: string;          // 显示名称
  description?: string;  // 模型说明
}

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

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

// HTTP 类型
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;        // 匹配模式（支持正则）
  hooks: HookCallback[];   // 回调函数列表
  timeout?: number;        // 超时时间（毫秒）
}

// 同步输出
type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?: Record<string, unknown>;
};

// 异步输出
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;
}