进阶 pydantic.dev 2026-11-20 05:57:40 · 5 阅读
第20章 Pydantic AI vs Claude Agent SDK:谁掌控 Agent?
我的职业生涯一直建立在一个信念上:软件应该是显式的。依赖要明确、权限要最小、行为要可观测——这些是基本的软件工程常识。我们不需要亲手写好部署的每一行代码,但至少应该清楚:应用程序的边界在哪里,别人的决策从哪里开始。
Agent 不应例外。
那么,用 Claude Agent SDK 构建应用时,你该为哪些事情负责?哪些决策属于你,哪些属于 Claude Code?当这些决策不再契合你的应用时,你还有多少控制权?
Claude Agent SDK(前身是 Claude Code SDK)本质上是包了一层 Claude Code。如果你要做的就是编程 agent,这很实用。但我不断看到有人拿它构建和编程毫无关系的应用。
Claude Code 是个不错的编程 agent。如果你的产品不是编程 agent,为什么要连着一个一起发布?
自嘲完这个蹩脚的梗,我们来看看这个 SDK 会给你的应用带来什么,以及一旦引入它,你需要承担什么。
契约比 API 更大
任何应用都会依赖维护者没写过的代码。可控不等于自己编写,但 SDK 依然要遵守一份契约:我们锁定依赖、审查升级、期待破坏性变更是可见的。 Agent 让这份契约比公开 API 复杂得多。 想象一下,我们改动 Pydantic AI 的重试提示词,改成一个荒诞的版本。import 照常工作,类型检查照常通过,公开 API 上没有任何东西被破坏——但部署上线的 agent 行为可能完全不同。 这算 API 破坏性变更吗?不算。但它是你应用出问题的原因吗?绝对是。 对待 agent,我们需要更审慎。它们的提示词、工具、权限、控制循环和失败处理不是无关紧要的实现细节,而是决定了模型能看到什么、能做什么、接下来会发生什么。 如果这些决策藏在另一个产品内部,那这个产品就掌握着你应用行为的很大一部分。披着 SDK 外衣的编程 agent 框架
pip install claude-agent-sdk 听起来像是安装一个 Claude 的 Python 客户端。 它确实安装了 Python 客户端,还附带了打包好的 Claude Code 可执行文件。每个会话都以子进程方式启动 Claude Code,它的 shell、文件工具、skills、插件、权限、设置、会话文件和 agent 循环一并带入。 这些设计对 Claude Code 来说很合理——它需要检查仓库、编辑文件、运行命令、从故障中恢复、遵循项目指令。 但这是为一个编程 agent 做的设计。 其中大多数都有开关:你可以禁用工具、添加 hooks、替换系统提示词、提供自己的 MCP 工具,还可以传 setting_sources=[] 和 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1,让会话不再加载项目的 .claude/ 设置和记忆。可即便如此,你依然是在配置 Claude Code,而不是构建你的应用真正需要的运行时。如果你的用户根本不想要编程 agent,为什么一开始就带上它,然后花时间把它一个个拆掉? 如果你不想要那个子进程,Anthropic 还提供 Managed Agents,帮你托管 agent 循环,工具则运行在 Anthropic 的云沙箱或你自建的沙箱里。但循环仍然是 Anthropic 的。对你应用的影响
Claude Agent SDK 锁定了 Claude Code 版本,所以锁定的部署不会一夜之间变化。但升级 SDK 时,可能替换掉捆绑的 Claude Code 二进制文件。 Anthropic 表示,Claude Code 的升级通常会改变系统提示词或工具定义。而系统提示词并不作为 SDK 契约的一部分公开发布。 你的提示词不变,模型不变,代码不变,但你部署的 agent 依然可能改变,而原因不会出现在你的代码审查里。 这是有实际代价的。团队必须理解 Claude Code 的假设、限制应用用不到的能力,还要排查由一个为另一种用途设计的运行时所控制的行为。 问题不在于 Claude Code 有强烈的自身主张——好的编程 agent 本该如此。问题在于,你本来并不打算发布一个编程 agent,却全盘接受了这些主张。Pydantic AI 随应用一起成长
Pydantic AI 从应用本身出发,而不是一个预置的框架。模型(从 Pydantic AI 支持的任意 provider 中选)、指令、工具、依赖、输出类型和能力,都由你自己决定。 from pydantic import BaseModel from pydantic_ai import Agent class SupportReply(BaseModel): answer: str needs_human: bool agent = Agent("anthropic:claude-sonnet-4-6", output_type=SupportReply) 从一次模型调用开始。需要时添加带类型的工具。随着应用成长,再逐步引入依赖注入、结构化输出、人工审批、持久化执行、多 agent 或显式图。 如果应用最终需要文件系统访问、shell、规划、记忆或子 agent,Pydantic AI Harness 把这些做成了可以逐个添加的能力。 它还提供了一些现成的完整 agent。Coder 是完整的编程 agent,包含文件工具、shell、仓库指令、任务委派和上下文管理。Researcher 从网络检索信息回答问题,并附上引用来源。两者都由相同的能力组合而成,所以也能像组装时一样拆开——从其中一个出发删掉不需要的部分,或者两个都不用、自己动手搭。 from pydantic_ai import Agent from pydantic_ai.capabilities import LocalWorkspace from pydantic_ai_harness import Coder agent = Agent("anthropic:claude-sonnet-4-6", capabilities=[LocalWorkspace("."), Coder()]) 同一个 agent 也能跑在 CI 里。把你自己的 Pydantic AI agent 接到 GitHub Agentic Workflow 上,由 issue、pull request 或定时任务触发——也就是厂商的 GitHub Action 为它们自己的 agent 做的事。不同的是,这里跑的是你的 agent,用你的指令、你的工具,模型任你选。 应用变得更有野心时,你不必推倒重来换掉那个小 agent,也不必从别人的一整套工作环境起步。我们宁愿你把时间花在构建自己的应用上,而不是去绕开我们为另一个应用做的决策。给它一个合适的工作环境
LocalWorkspace(".") 以你的身份在本机运行 agent 的命令。对你自己的仓库来说没问题,但不是运行用户提交的代码该待的地方。 要把工作挪到隔离环境,只需换掉 workspace,其余照旧: from pydantic_ai_harness.modal_sandbox import ModalSandbox agent = Agent("anthropic:claude-sonnet-4-6", capabilities=[ModalSandbox(), Coder()]) Coder 的文件和 shell 工具现在运行在 Modal 沙箱里。E2BSandbox() 和 SpritesSandbox() 也能放进同一个位置。你自己写的工具通过 ctx.workspace 访问环境,所以在笔记本上测试过的工具,可以原封不动地跑进沙箱。 agent 本身仍留在你的应用里,只有命令和文件操作被挪走。而 Claude Agent SDK 的官方建议是把 SDK 放进沙箱容器里运行,这样整个 agent 都得跟着搬进去。 沙箱在运行结束后仍在运行,用完记得删掉。看清你的 agent 到底做了什么
能掌控 agent,前提是能看见它运行。调用 logfire.configure() 和 logfire.instrument_pydantic_ai(),Pydantic Logfire 就会记录每次模型请求、工具调用和重试,包括模型收到的完整提示词。 这也顺便解决了前面的升级问题。在 Pydantic Evals 里维护一组测试用例,在升级依赖或修改提示词前后各跑一遍,行为上的变化就会出现在你审查时阅读的报告里。选你真正想发布的东西
如果你在构建编程 agent,想要 Claude Code 的行为,Claude Agent SDK 是直接的选择。它的 shell、文件系统、项目指令、skills、权限和编程循环,正是你要的产品。 Claude Agent SDK | Pydantic AI 安装内容 | Python 客户端 + 捆绑的 Claude Code 可执行文件 | Python 库 Agent 循环 | Claude Code 的,以子进程运行 | Pydantic AI 的,运行在你的进程里 系统提示词 | 你的或 Claude Code 的,外加 Claude Code 自动附加的提醒 | 你自己写的指令 默认工具 | shell、文件工具、skills 和插件 | 没有工具,除非你主动添加 工具运行位置 | SDK 进程所在之处 | 你的机器,或 Modal、E2B、Sprites 沙箱 模型 | Claude | 任意支持的 provider 编程 agent | Claude Code | Pydantic AI Harness 的 Coder 最适合 | 基于 Claude Code 行为构建的编程产品 | 自主定义 agent 的应用 如果你要做的不是编程 agent,就别因为它 packaged 成 SDK 的样子,就伸手去拿一个编程 agent 框架。 想让应用自己定义 agent、并在成长过程中不放弃对它的控制,就用 Pydantic AI。 我们于 2026 年 9 月 4 日审查了 claude-agent-sdk==0.2.152 及其捆绑的 Claude Code 2.1.259,并于 2026 年 10 月 1 日基于 commit 06ba88fd 验证了 Pydantic AI 的示例。