SDK References

Qoder Agent SDK 提供 TypeScript 和 Python 两个语言版本。两者覆盖相同的核心能力面——Agent 循环、工具、权限、Hooks、会话、MCP、Skills 和插件，但 API 签名、类型定义和命名风格各自遵循所在语言的习惯（TypeScript 为 camelCase，Python 公共 options 为 snake_case）。少数选项仅在一种语言中提供，参见下方语言差异。完整 API 参考按语言分开维护：

按语言查看

语言	参考页	包名
TypeScript	SDK References - TypeScript	`@qoder-ai/qoder-agent-sdk`
Python	SDK References - Python	`qoder-agent-sdk`

语言差异

绝大多数选项在两个 SDK 之间一一对应，以下除外。各语言的参考页仍是其自身能力面的权威来源。

仅 TypeScript

能力	选项或方法	说明
记忆	`memory`、`flushMemory()`、`refreshMemory()`	配置原生或由应用接管的记忆，参见记忆
内置工具行为	`toolConfig`	调整内置工具的行为，参见工具
会话持久化控制	`persistSession`、`resumeSessionAt`、`resumeDropsTurn`	细粒度控制恢复会话时加载和保留的内容
提示建议	`promptSuggestions`	接收建议的后续提示词
模型请求调整	`modelRequestPatches`	调整发出的模型请求
Hook 事件筛选	`includeHookEvents`	选择哪些 Hook 事件进入消息流
自定义传输与进程控制	`transport`、`spawnQoderCLIProcess`、`executable`、`executableArgs`	替换运行时的启动或连接方式

仅 Python

能力	选项	说明
从文件加载系统提示词	`system_prompt={"type": "file", "path": ...}`	参见从文件加载提示词
MCP 认证回调	`on_mcp_oauth_required`	服务需要 OAuth 时的入向回调；TypeScript 通过运行时方法完成同类能力
MCP 状态回调	`on_mcp_status_change`	服务状态变化的入向回调
读取缓冲上限	`max_buffer_size`	限制传输层读取缓冲区大小

命名对照

两个 SDK 的核心 API 对照如下，方便跨语言迁移：

能力	TypeScript	Python
一次性查询	`query()`	`query()`
流式输入	`query()` + 异步消息流	`QoderSDKClient`
会话 options	`Options`（`query({ options })`）	`QoderAgentOptions`
认证：环境变量 PAT	`accessTokenFromEnv()`	`access_token_from_env()`
认证：直接传 PAT	`accessToken()`	`access_token()`
认证：Service Account	`serviceAccount()`	`service_account()`
认证：本机登录态	`qodercliAuth()`	`qodercli_auth()`
自定义工具	`tool()`	`@tool()` 装饰器
进程内 MCP server	`createSdkMcpServer()`	`create_sdk_mcp_server()`
权限回调	`canUseTool`	`can_use_tool`
中断当前回复	`q.interrupt()`	`client.interrupt()`
文件回滚	`q.rewindFiles()`	`client.rewind_files()`
MCP 状态查询	`q.mcpServerStatus()`	`client.get_mcp_status()`
初始化结果	`q.initializationResult()`	`client.get_server_info()`
上下文用量	`q.getContextUsage()`	`client.get_context_usage()`
账号与会话用量	`q.getUsageInfo()`	`client.get_usage_info()`

注意：Python 的 AgentDefinition、hooks 输出、settings 等协议层结构沿用线路协议的 camelCase 字段名（如 maxTurns、hookSpecificOutput），与公共 options 的 snake_case 不同，详见各功能页说明。

功能文档

各功能页已合并双语言示例，可在代码块内切换 TypeScript / Python：

​按语言查看

​语言差异

​仅 TypeScript

​仅 Python