Agent SDK 运行时模式

Agent SDK 不只是把一句 prompt 发给模型。它会启动 Claude Code agent loop,加载工具、权限、settings、CLAUDE.md、hooks 和 MCP。生产应用要把这些运行时模式设计清楚,否则很容易出现工具暴露过多、缓存命中差、审批卡死或结构化输出不可控。

先看 Agent SDK 理解基本接入。TypeScript/Python API、session API、settings 解析和迁移差异见 Agent SDK API 参考速查。Agent loop、settingSources、skills、subagents、todo tracking 和 checkpointing 见 Agent SDK Agent 能力。多租户和观测继续看 Agent SDK 生产部署。

#运行时决策表

#Custom tools

Custom tools 用 SDK 的 in-process MCP server 暴露应用内能力。它适合内部 API、数据库、检索、工单系统和业务动作。

错误建议返回 isError: true,让 Claude 看到可恢复的工具失败。不要把普通业务错误都 throw 出去,否则 agent loop 可能直接中断。

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const lookupInvoice = tool(
  "lookup_invoice",
  "Look up an invoice by ID and return billing status, amount, and due date",
  {
    invoiceId: z.string().describe("Invoice ID, for example inv_123")
  },
  async ({ invoiceId }) => {
    const invoice = await getInvoice(invoiceId);
    if (!invoice) {
      return {
        isError: true,
        content: [{ type: "text", text: "Invoice not found" }]
      };
    }
    return {
      content: [{ type: "text", text: `Status: ${invoice.status}` }],
      structuredContent: invoice
    };
  }
);

const billingServer = createSdkMcpServer({
  name: "billing",
  version: "1.0.0",
  tools: [lookupInvoice]
});

for await (const message of query({
  prompt: "Check invoice inv_123 and summarize the next action",
  options: {
    mcpServers: { billing: billingServer },
    allowedTools: ["mcp__billing__lookup_invoice"]
  }
})) {
  console.log(message);
}

#System prompt 选择

如果产品仍然是 coding agent,优先用 preset 加 append:

{
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "When changing billing code, always mention migration and rollback risks."
  },
  settingSources: ["project"]
}

CLAUDE.md 不是 system prompt,而是作为项目上下文注入。它可以和任何 system prompt 配合。多租户产品如果不想加载宿主机规则,设置 settingSources: []。

#Streaming output

流式输出适合做终端、WebSocket、任务面板或日志 UI。不要只等最终 result。

单次输入模式适合简单任务。连续输入模式适合聊天 UI,但要显式处理取消、超时和用户离开页面。

#Structured output

结构化输出让最终结果通过 JSON Schema、Zod 或 Pydantic 校验,适合写入数据库或驱动 UI。

outputFormat: {
  type: "json_schema",
  schema: {
    type: "object",
    properties: {
      risk: { enum: ["low", "medium", "high"] },
      summary: { type: "string" },
      actions: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["risk", "summary", "actions"]
  }
}

#Tool search

工具定义会占上下文。工具多时,让 Claude 先搜索工具,再加载最相关的几个。

命名和描述会直接影响搜索质量:

在 Vertex、Bedrock、Foundry 或自定义 ANTHROPIC_BASE_URL 下,要确认网关是否支持 tool reference。如果不支持,SDK 可能回退为 upfront 工具定义,缓存和上下文占用都会变化。

#用户审批与提问

SDK 用 canUseTool 处理两类暂停:

注意:如果某个工具已经被 allow rule、permission mode 或 allowedTools 自动批准,canUseTool 不会再被调用。必须每次都检查的逻辑放到 PreToolUse hook。

#Slash commands in SDK

SDK 中可以把 slash command 当 prompt 发送,但只限可非交互调度的命令。可用列表来自 system/init 的 slash_commands。

发送 /compact 前需要已有对话历史。单轮任务刚启动就发 /compact 没有意义。

#Prompt cache 5m/1h 策略

Agent SDK 会自动使用 prompt caching。缓存命中取决于模型、effort、system prompt、tools、MCP、settings、CLAUDE.md 和历史前缀是否稳定。

默认不写时走 5 分钟 TTL。需要长间隔复用同一前缀时,再请求 1 小时 TTL:

export ENABLE_PROMPT_CACHING_1H=1

观测时分开看:

#官方参考

• Custom tools
• Modifying system prompts
• Streaming output
• Streaming Input
• Plugins in the SDK
• Structured outputs
• Tool search
• User input
• Slash commands in the SDK

#相关页面