Agent SDK API 参考速查

这一页把官方 TypeScript/Python API 参考压缩成工程速查。完整 API 仍以官方参考为准,但日常选型通常只需要先判断:一次性 query()、长连接 client、custom tools、session 管理、settings 解析和迁移差异。

如果你要看 custom tools、streaming、structured output、tool search 和用户审批,看 Agent SDK 运行时模式。如果你要做多租户和生产部署,看 Agent SDK 生产部署。

#覆盖的官方页面

#安装

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

接 Passion8 时,关键仍是子进程环境:

export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key"

TypeScript env 选项会替换子进程环境。传自定义 env 时通常要展开 ...process.env。

#选择入口

#query() 最小例子

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "解释这个仓库的入口文件",
  options: {
    cwd: process.cwd(),
    maxTurns: 5,
    permissionMode: "dontAsk",
    allowedTools: ["Read", "Grep", "Glob"],
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://passion8.cc",
      ANTHROPIC_AUTH_TOKEN: process.env.PASSION8_API_KEY ?? ""
    }
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, query


async def main() -> None:
    options = ClaudeAgentOptions(
        cwd=".",
        max_turns=5,
        permission_mode="dontAsk",
        allowed_tools=["Read", "Grep", "Glob"],
        env={
            "ANTHROPIC_BASE_URL": "https://passion8.cc",
            "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 API Key",
        },
    )

    async for message in query(prompt="解释这个仓库的入口文件", options=options):
        if getattr(message, "type", None) == "result":
            print(message.result)


asyncio.run(main())

#Python query() 与 ClaudeSDKClient

如果你的产品是“用户打开一个 agent 面板连续对话”,Python 优先用 ClaudeSDKClient。如果是“队列里每条任务跑一次”,用 query() 更简单。

#常用函数

#Permission mode 速查

allowedTools 是预批准列表,不是工具全集限制。要移除工具定义,使用 disallowedTools 或缩小 tools。

#Session API

常见 UI:

const sessions = await listSessions({ dir: "/repo", limit: 50 });
const current = await getSessionInfo(sessions[0].sessionId, { dir: "/repo" });
const messages = await getSessionMessages(sessions[0].sessionId, { dir: "/repo", limit: 100 });

不要把本地 transcript 当唯一可靠存储。跨主机恢复看 Agent SDK 生产部署 的 SessionStore。

#Settings 解析

TypeScript resolveSettings() 适合宿主应用在启动前展示“最终哪些配置生效”。

多租户产品建议默认:

{
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: `/srv/claude-config/${tenantId}`,
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}

#从旧 SDK 迁移

如果你从 CLI 迁移,并希望行为像 Claude Code CLI,设置:

systemPrompt: {
  type: "preset",
  preset: "claude_code"
}

#缓存影响

观测字段见 Agent SDK 生产部署。

#官方参考

• Agent SDK overview
• Agent SDK quickstart
• TypeScript reference
• Python reference
• Migration guide
• TypeScript V2 session API removed