claude-quickstarts agents用不足 300 行参考实现理解 Claude API 的 Agent 循环、工具体系与 MCP 集成【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts本篇技术指南基于 agents/README.md 展开带你拆解 claude-quickstarts 仓库中最小教育型 Agent 实现agents子项目的完整脉络如何用一个不到 300 行的核心骨架搭出「LLM 工具循环」的 Agent 范式如何同时接入本地工具与 MCPModel Context Protocol远程工具以及上下文截断、Prompt 缓存、并行工具执行等生产级细节在这份参考实现中是如何被刻意精简与保留的。读完后你可以直接复制其中的 Agent 初始化与 MCP 服务器配置模式并将其迁移到你自己的语言与生产技术栈。定位这是参考实现而不是 SDKREADME 开篇就明确声明了agents的性质它不是 SDK而是一份关键概念的最小参考实现a minimal educational implementation of LLM agents using the Claude API。它想验证的核心命题是——复杂的 AI 行为可以从一个简单基础中涌现LLM 在循环中调用工具LLMs using tools in a loop。这一设计立场直接体现在代码体量上核心逻辑agents/agent.py不足 300 行并刻意省略了生产级特性重试、鉴权、可观测性、流式等均未内置实现被刻意保持「不主张性」unopinionatedREADME 明确鼓励读者将这些模式翻译translate到自己的语言和生产栈而不是绑定这套代码本身因此它适合作为学习 Agent 架构的第一手材料或作为生产系统的设计蓝本但不适合作为生产依赖直接引入。从源码结构看agents恰好由 README 列出的三个组件构成职责划分清晰组件路径职责Agent 主体agents/agent.py管理 Claude API 交互与工具执行Agent 循环工具层agents/tools/工具实现覆盖本地工具与 MCP 工具工具层agents/utils/消息历史管理与 MCP 服务器连接Agent 类构造参数与模型配置入口类是 agents/agent.py 中的Agent其构造函数签名如下源码节选def __init__( self, name: str, # Agent 标识符用于日志 system: str, # 系统提示词 tools: list[Tool] | None None, # 本地工具列表 mcp_servers: list[dict[str, Any]] | None None, # MCP 服务器配置 config: ModelConfig | None None, # 模型配置 verbose: bool False, # 详细日志开关 client: Anthropic | None None, # 可注入 Anthropic 客户端 message_params: dict[str, Any] | None None, # 透传给 API 的额外参数 ):几个值得注意的实现细节API Key 读取若未注入client内部会构造Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY, ))即 API Key 必须通过环境变量ANTHROPIC_API_KEY提供对应 README 的 Requirements 一节。客户端可注入client参数允许传入自定义Anthropic实例便于切换 base_url如 Bedrock/Vertex 网关或复用连接。历史管理在构造期初始化MessageHistory在__init__中即被创建见下文「上下文管理」一节并会立即用client.messages.count_tokens预估系统提示词的 token 占用若该调用失败则回退为len(system) / 4的粗略估算见 agents/utils/history_util.py 第 29-42 行。ModelConfig模型参数的默认值模型行为由同文件中的ModelConfig数据类控制默认值与可选模型列表如下参数默认值说明modelclaude-sonnet-4-20250514模型 ID源码注释中列出的可选值还包括claude-opus-4-20250514、claude-haiku-4-5-20251001、claude-3-5-sonnet-20240620、claude-3-haiku-20240307max_tokens4096单次响应的最大输出 token 数temperature1.0采样温度context_window_tokens180000上下文窗口预算驱动历史截断逻辑注意context_window_tokens并非直接发给 API而是本地上下文管理器使用的预算值实际取值应以所选模型的真实窗口能力为准。快速上手README 的完整用法示例以下是 README「Usage」章节的完整示例可直接复制运行需已设置ANTHROPIC_API_KEYfrom agents.agent import Agent from agents.tools.think import ThinkTool # 同时使用本地工具与 MCP 服务器工具创建 Agent agent Agent( nameMyAgent, systemYou are a helpful assistant., tools[ThinkTool()], # 本地工具 mcp_servers[ { type: stdio, command: python, args: [-m, mcp_server], }, ] ) # 运行 Agent response agent.run(What should I consider when buying a new laptop?)要点说明agent.run(...)是同步入口内部通过asyncio.run调用异步版本run_async见 agents/agent.py因此即使 Agent 循环是异步的调用方也可以写同步代码mcp_servers的每一项是一个 dict支持stdio本地子进程与sse远程事件流两种传输详见下文「MCP 集成」返回值response是 API 返回的 message content blocks 列表文本块与tool_use块README 也提示你可以在此基础上自行实现自定义响应处理。仓库还附带了一个完整的交互式演示 agents/agent_demo.ipynb其中展示了连接brave_search_server与calculator_server两个 MCP 服务器mcp_servers[brave_search_server, calculator_server]、使用 Anthropic 服务器端工具WebSearchServerTool与CodeExecutionServerTool等进阶用法。核心Agent 循环的逐行拆解「LLM 在循环中调用工具」这一范式落在Agent._agent_loopagents/agent.py中。其每轮迭代可概括为五步截断历史self.history.truncate()检查 token 预算超限则从最旧的消息对开始丢弃细节见下文组装请求参数_prepare_message_params()将ModelConfig与message_params合并——message_params中任何与配置冲突的键都会覆盖配置默认值源码中通过**self.message_params后置展开实现合并 Beta 头默认注入anthropic-beta: code-execution-2025-05-22若message_params携带extra_headers会与默认头做字典合并默认头可被覆盖并从参数中弹出避免重复传给 API发起 API 调用并解析工具调用self.client.messages.create(**params, extra_headersmerged_headers)然后从response.content中筛出所有block.type tool_use的块执行或退出若存在工具调用先把 assistant 消息连同usage写入历史再调用execute_tools并行执行见下文把结果以user角色的tool_result块追加回历史进入下一轮循环若没有任何tool_use块说明模型已给出最终答案直接return response结束循环。这个「生成 → 若请求工具则执行并回灌 → 否则终止」的闭环正是整套参考实现最核心的资产。开启verboseTrue时每一轮的输出文本、工具调用含参数与工具结果都会打印到控制台非常适合调试。另外注意run_async的生命周期管理agents/agent.py它用AsyncExitStack承载 MCP 连接在进入循环前调用setup_mcp_connections把远端工具扩展进self.tools并在finally中恢复original_tools——即MCP 工具只在单次run期间挂载不会泄漏到后续调用。工具体系从 Tool 基类到本地工具与服务器端工具Tool 基类统一的最小协议所有本地工具继承 agents/tools/base.py 中的Tool数据类它只定义了三要素 一个抽象方法dataclass class Tool: name: str # 工具名与模型侧 tool_use 块中的 name 对应 description: str # 工具描述直接呈现给模型 input_schema: dict[str, Any] # JSON Schema描述入参 def to_dict(self) - dict[str, Any]: # 转换为 Claude API 的 tools 数组元素格式 return {name: self.name, description: self.description, input_schema: self.input_schema} async def execute(self, **kwargs) - str: # 子类必须实现执行工具并返回字符串结果 raise NotImplementedErrorto_dict()的输出会原样进入每次 API 请求的tools字段见_prepare_message_paramsexecute的返回值会被str()强转后作为tool_result内容回灌给模型。整个工具体系的扩展成本就是继承Tool、写好三个字段、实现execute。内置本地工具一览工具文件说明ThinkTool名为thinkagents/tools/think.py「思考」工具接收一个thought字符串返回固定文本Thinking complete!。不获取新信息、不产生副作用用于引导模型在复杂推理时显式落盘中间结论FileReadTool名为file_readagents/tools/file_tools.py两种操作read支持max_lines限行读取0表示不限制与list按pattern通配符列目录目录以 前缀、文件以 前缀输出。阻塞的 IO 通过asyncio.to_thread移到线程执行FileWriteTool名为file_writeagents/tools/file_tools.py两种操作write整体覆盖写自动makedirs建目录与editold_text→new_text定点替换命中多处时全部替换并返回 Warning未命中返回 Error二进制文件返回明确错误MCPToolagents/tools/mcp_tool.py由setup_mcp_connections动态生成的 MCP 代理工具见下文两个文件工具的错误处理风格值得注意它们从不抛异常而是把Error: ...字符串返回给模型让模型自行决定下一步——这是参考实现刻意演示的「让错误进入上下文」的设计。服务器端工具Web 搜索与代码执行除了自研工具仓库还演示了把Anthropic 服务器端托管工具当作Tool来用的技巧。WebSearchServerToolagents/tools/web_search.py的to_dict()输出的是服务器工具格式{ type: web_search_20250305, name: web_search, max_uses: ..., # 可选限制调用次数 allowed_domains: [...], # 可选域名白名单 blocked_domains: [...], # 可选域名黑名单 user_location: {...}, # 可选用户位置 }CodeExecutionServerToolagents/tools/code_execution.py同理输出{type: code_execution_20250522, name: code_execution}。二者都不需要实现execute——执行发生在 API 服务端。注意Agent中默认注入的code-execution-2025-05-22beta 头正与这个服务器端代码执行能力配套。MCP 集成mcp_servers 配置与连接生命周期mcp_servers参数是这份实现把「本地工具」与「协议化工具」统一起来的桥梁。它是一个 dict 列表由 agents/utils/connections.py 中的工厂函数create_mcp_connection解析type必填键可选键说明stdio默认commandargs、env以子进程方式启动 MCP 服务器通过标准输入/输出通信底层为mcp库的stdio_clientStdioServerParameterssseurlheaders连接远程 SSE 端点底层为sse_client缺失必填键如 stdio 没有command会抛出带明确信息的ValueError。连接生命周期与工具发现setup_mcp_connectionsagents/utils/connections.py的完整流程是遍历mcp_servers配置经工厂创建MCPConnection实例并用传入的AsyncExitStack进入其异步上下文MCPConnection.__aenter__内部完成三步创建读写上下文 → 包装为ClientSession→await session.initialize()完成 MCP 握手调用session.list_tools()向服务器动态发现工具为每个远端工具生成一个MCPTool名称、描述、inputSchema全部透传其execute方法通过session.call_tool(name, arguments...)远程执行并仅提取文本型结果非文本结果返回No text content in tool response单个服务器连接失败只打印错误并继续处理下一个最终打印Loaded N MCP tools from M servers.。资源清理由__aexit__保证会话与读写上下文按序退出异常被捕获打印连接句柄置空——这与run_async中的AsyncExitStack配合构成完整的生命周期闭环。写一个 MCP 服务器calculator 示例仓库自带一个最小 MCP 服务器 agents/tools/calculator_mcp.py展示了工具提供方视角from mcp.server import FastMCP mcp FastMCP(Calculator) mcp.tool(namecalculator) def calculator(number1: float, number2: float, operator: str) - str: Performs basic calculations with two numbers. ...docstring 即模型看到的工具描述 # 支持 - * / ^ sqrt含除零与负数开方等错误分支 return fResult: {result} if __name__ __main__: mcp.run()两点实现事实一是mcp.tool的函数签名与 docstring 会被 FastMCP 自动转成 JSON Schema因此「参数说明即工具描述」二是错误不抛异常而是返回Error: ...字符串与本地工具的风格一致。Agent 侧通过{type: stdio, command: python, args: [agents/tools/calculator_mcp.py]}之类的配置即可挂载它agent_demo.ipynb中的calculator_server即以此方式指向该文件。上下文管理token 追踪与历史截断长循环必然撞上下文窗口agents/utils/history_util.py 中的MessageHistory用三个机制应对1. 持续 token 记账。每次 assistant 响应返回usage后add_message会把本回合实际新增的 token 记入message_tokensinput/output 元组列表并累加到total_tokens。input 侧的统计显式包含cache_read_input_tokens与cache_creation_input_tokens保证缓存命中时记账依然准确。2. 成对截断truncate。每当total_tokens超过context_window_tokenstruncate()就从最旧处开始成对user/assistant 一对移除消息把被移除回合的 token 从总量中扣减当历史开头仍有残余消息时用一条固定文本[Earlier history has been truncated.]替换第一条消息并按常量 25 token 重新记账TRUNCATION_NOTICE_TOKENS 25。成对移除是为了维护 API 所要求的多轮对话角色交替结构。3. Prompt 缓存。format_for_api()在导出请求历史前会为最后一条消息的所有 content 块追加cache_control: {type: ephemeral}enable_caching默认开启。结合 Agent 循环中「同一系统提示词 稳定前缀历史」的调用模式这为多轮工具循环提供了前缀缓存的落地点add_message中对cache_read/creationtoken 的读取也印证了这一点。并行工具执行与错误边界一轮响应可能包含多个tool_use块。execute_toolsagents/utils/tool_util.py默认parallelTrue用asyncio.gather并发执行所有工具传parallelFalse则顺序执行对依赖先后顺序的工具链有意义。每个工具的执行被_execute_single_tool包了一层错误边界工具名找不到 →Tool name not foundis_errorTrue执行抛任意异常 →Error executing tool: 异常信息is_errorTrue结果统一包装为{type: tool_result, tool_use_id: call.id, content: str(result)}回灌历史。即单个工具的失败不会中断整个循环而是以带is_error标记的结果让模型「看到」失败并自行调整——这与文件工具的「错误返回字符串」策略共同构成了参考实现的容错哲学。进阶message_params 透传层与测试验证Agent的最后一个参数message_params是一个「逃生舱」任意键值对会被展开进client.messages.create()的调用参数且优先级高于ModelConfig冲突键被覆盖。agents/test_message_params.py 用八个用例系统验证了它的语义边界自定义 HTTP 头{extra_headers: {X-Custom-Header: ...}}可透传任意请求头Beta 头如{anthropic-beta: files-api-2025-04-14}可与默认头合并生效metadata{metadata: {user_id: ...}}透传给 API传入非法字段时 API 会返回invalid_request_error测试断言了这一拒绝行为采样参数top_k、top_p、temperature均可透传且能覆盖ModelConfig中的同名默认值test_parameter_override断言temperature0.5、max_tokens200胜出。需要说明的前提该测试套件是集成测试main()会检查ANTHROPIC_API_KEY未设置时直接退出运行即会真实调用 API。环境要求与运行方式README「Requirements」一节给出的前提条件与源码核对一致PythonREADME 标注 Python 3.8。但从源码结构看代码大量使用dict[str, Any]、list[Tool] | None等内建泛型与联合类型标注实际运行在Python 3.9更稳妥API Key环境变量ANTHROPIC_API_KEYagents/agent.py 在构造默认客户端时读取依赖库anthropic与mcp两个 Python 包前者驱动 API 客户端后者提供stdio_client/sse_client/FastMCP等 MCP 能力。仓库根目录的 pyproject.toml 定义了整体包配置演示入口为 agents/agent_demo.ipynb覆盖本地工具 双 MCP 服务器 服务器端 Web 搜索/代码执行的完整场景。小结从这份参考实现带走什么回到 README 的核心主张——「复杂行为来自简单基础」——这份实现恰好给出了可迁移的四件套循环即架构_agent_loop的五步闭环截断 → 组参 → 调 API → 执行工具 → 回灌是整个 Agent 的全部控制流无需状态机工具即数据本地工具Tool 三要素、动态 MCP 工具协议发现与服务器端工具托管执行共享同一个to_dict()/execute抽象新增能力不改循环上下文即预算token 记账 成对截断 ephemeral 缓存把「窗口管理」变成可单测的纯本地逻辑失败即上下文工具错误不中断、不吞掉而是作为tool_result让模型参与决策。这套不足 300 行的骨架正是把 Agent 概念翻译到你自己的技术栈时可以逐行对照的模板。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
claude-quickstarts agents用不足 300 行参考实现理解 Claude API 的 Agent 循环、工具体系与 MCP 集成【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts本篇技术指南基于 agents/README.md 展开带你拆解 claude-quickstarts 仓库中最小教育型 Agent 实现agents子项目的完整脉络如何用一个不到 300 行的核心骨架搭出「LLM 工具循环」的 Agent 范式如何同时接入本地工具与 MCPModel Context Protocol远程工具以及上下文截断、Prompt 缓存、并行工具执行等生产级细节在这份参考实现中是如何被刻意精简与保留的。读完后你可以直接复制其中的 Agent 初始化与 MCP 服务器配置模式并将其迁移到你自己的语言与生产技术栈。定位这是参考实现而不是 SDKREADME 开篇就明确声明了agents的性质它不是 SDK而是一份关键概念的最小参考实现a minimal educational implementation of LLM agents using the Claude API。它想验证的核心命题是——复杂的 AI 行为可以从一个简单基础中涌现LLM 在循环中调用工具LLMs using tools in a loop。这一设计立场直接体现在代码体量上核心逻辑agents/agent.py不足 300 行并刻意省略了生产级特性重试、鉴权、可观测性、流式等均未内置实现被刻意保持「不主张性」unopinionatedREADME 明确鼓励读者将这些模式翻译translate到自己的语言和生产栈而不是绑定这套代码本身因此它适合作为学习 Agent 架构的第一手材料或作为生产系统的设计蓝本但不适合作为生产依赖直接引入。从源码结构看agents恰好由 README 列出的三个组件构成职责划分清晰组件路径职责Agent 主体agents/agent.py管理 Claude API 交互与工具执行Agent 循环工具层agents/tools/工具实现覆盖本地工具与 MCP 工具工具层agents/utils/消息历史管理与 MCP 服务器连接Agent 类构造参数与模型配置入口类是 agents/agent.py 中的Agent其构造函数签名如下源码节选def __init__( self, name: str, # Agent 标识符用于日志 system: str, # 系统提示词 tools: list[Tool] | None None, # 本地工具列表 mcp_servers: list[dict[str, Any]] | None None, # MCP 服务器配置 config: ModelConfig | None None, # 模型配置 verbose: bool False, # 详细日志开关 client: Anthropic | None None, # 可注入 Anthropic 客户端 message_params: dict[str, Any] | None None, # 透传给 API 的额外参数 ):几个值得注意的实现细节API Key 读取若未注入client内部会构造Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY, ))即 API Key 必须通过环境变量ANTHROPIC_API_KEY提供对应 README 的 Requirements 一节。客户端可注入client参数允许传入自定义Anthropic实例便于切换 base_url如 Bedrock/Vertex 网关或复用连接。历史管理在构造期初始化MessageHistory在__init__中即被创建见下文「上下文管理」一节并会立即用client.messages.count_tokens预估系统提示词的 token 占用若该调用失败则回退为len(system) / 4的粗略估算见 agents/utils/history_util.py 第 29-42 行。ModelConfig模型参数的默认值模型行为由同文件中的ModelConfig数据类控制默认值与可选模型列表如下参数默认值说明modelclaude-sonnet-4-20250514模型 ID源码注释中列出的可选值还包括claude-opus-4-20250514、claude-haiku-4-5-20251001、claude-3-5-sonnet-20240620、claude-3-haiku-20240307max_tokens4096单次响应的最大输出 token 数temperature1.0采样温度context_window_tokens180000上下文窗口预算驱动历史截断逻辑注意context_window_tokens并非直接发给 API而是本地上下文管理器使用的预算值实际取值应以所选模型的真实窗口能力为准。快速上手README 的完整用法示例以下是 README「Usage」章节的完整示例可直接复制运行需已设置ANTHROPIC_API_KEYfrom agents.agent import Agent from agents.tools.think import ThinkTool # 同时使用本地工具与 MCP 服务器工具创建 Agent agent Agent( nameMyAgent, systemYou are a helpful assistant., tools[ThinkTool()], # 本地工具 mcp_servers[ { type: stdio, command: python, args: [-m, mcp_server], }, ] ) # 运行 Agent response agent.run(What should I consider when buying a new laptop?)要点说明agent.run(...)是同步入口内部通过asyncio.run调用异步版本run_async见 agents/agent.py因此即使 Agent 循环是异步的调用方也可以写同步代码mcp_servers的每一项是一个 dict支持stdio本地子进程与sse远程事件流两种传输详见下文「MCP 集成」返回值response是 API 返回的 message content blocks 列表文本块与tool_use块README 也提示你可以在此基础上自行实现自定义响应处理。仓库还附带了一个完整的交互式演示 agents/agent_demo.ipynb其中展示了连接brave_search_server与calculator_server两个 MCP 服务器mcp_servers[brave_search_server, calculator_server]、使用 Anthropic 服务器端工具WebSearchServerTool与CodeExecutionServerTool等进阶用法。核心Agent 循环的逐行拆解「LLM 在循环中调用工具」这一范式落在Agent._agent_loopagents/agent.py中。其每轮迭代可概括为五步截断历史self.history.truncate()检查 token 预算超限则从最旧的消息对开始丢弃细节见下文组装请求参数_prepare_message_params()将ModelConfig与message_params合并——message_params中任何与配置冲突的键都会覆盖配置默认值源码中通过**self.message_params后置展开实现合并 Beta 头默认注入anthropic-beta: code-execution-2025-05-22若message_params携带extra_headers会与默认头做字典合并默认头可被覆盖并从参数中弹出避免重复传给 API发起 API 调用并解析工具调用self.client.messages.create(**params, extra_headersmerged_headers)然后从response.content中筛出所有block.type tool_use的块执行或退出若存在工具调用先把 assistant 消息连同usage写入历史再调用execute_tools并行执行见下文把结果以user角色的tool_result块追加回历史进入下一轮循环若没有任何tool_use块说明模型已给出最终答案直接return response结束循环。这个「生成 → 若请求工具则执行并回灌 → 否则终止」的闭环正是整套参考实现最核心的资产。开启verboseTrue时每一轮的输出文本、工具调用含参数与工具结果都会打印到控制台非常适合调试。另外注意run_async的生命周期管理agents/agent.py它用AsyncExitStack承载 MCP 连接在进入循环前调用setup_mcp_connections把远端工具扩展进self.tools并在finally中恢复original_tools——即MCP 工具只在单次run期间挂载不会泄漏到后续调用。工具体系从 Tool 基类到本地工具与服务器端工具Tool 基类统一的最小协议所有本地工具继承 agents/tools/base.py 中的Tool数据类它只定义了三要素 一个抽象方法dataclass class Tool: name: str # 工具名与模型侧 tool_use 块中的 name 对应 description: str # 工具描述直接呈现给模型 input_schema: dict[str, Any] # JSON Schema描述入参 def to_dict(self) - dict[str, Any]: # 转换为 Claude API 的 tools 数组元素格式 return {name: self.name, description: self.description, input_schema: self.input_schema} async def execute(self, **kwargs) - str: # 子类必须实现执行工具并返回字符串结果 raise NotImplementedErrorto_dict()的输出会原样进入每次 API 请求的tools字段见_prepare_message_paramsexecute的返回值会被str()强转后作为tool_result内容回灌给模型。整个工具体系的扩展成本就是继承Tool、写好三个字段、实现execute。内置本地工具一览工具文件说明ThinkTool名为thinkagents/tools/think.py「思考」工具接收一个thought字符串返回固定文本Thinking complete!。不获取新信息、不产生副作用用于引导模型在复杂推理时显式落盘中间结论FileReadTool名为file_readagents/tools/file_tools.py两种操作read支持max_lines限行读取0表示不限制与list按pattern通配符列目录目录以 前缀、文件以 前缀输出。阻塞的 IO 通过asyncio.to_thread移到线程执行FileWriteTool名为file_writeagents/tools/file_tools.py两种操作write整体覆盖写自动makedirs建目录与editold_text→new_text定点替换命中多处时全部替换并返回 Warning未命中返回 Error二进制文件返回明确错误MCPToolagents/tools/mcp_tool.py由setup_mcp_connections动态生成的 MCP 代理工具见下文两个文件工具的错误处理风格值得注意它们从不抛异常而是把Error: ...字符串返回给模型让模型自行决定下一步——这是参考实现刻意演示的「让错误进入上下文」的设计。服务器端工具Web 搜索与代码执行除了自研工具仓库还演示了把Anthropic 服务器端托管工具当作Tool来用的技巧。WebSearchServerToolagents/tools/web_search.py的to_dict()输出的是服务器工具格式{ type: web_search_20250305, name: web_search, max_uses: ..., # 可选限制调用次数 allowed_domains: [...], # 可选域名白名单 blocked_domains: [...], # 可选域名黑名单 user_location: {...}, # 可选用户位置 }CodeExecutionServerToolagents/tools/code_execution.py同理输出{type: code_execution_20250522, name: code_execution}。二者都不需要实现execute——执行发生在 API 服务端。注意Agent中默认注入的code-execution-2025-05-22beta 头正与这个服务器端代码执行能力配套。MCP 集成mcp_servers 配置与连接生命周期mcp_servers参数是这份实现把「本地工具」与「协议化工具」统一起来的桥梁。它是一个 dict 列表由 agents/utils/connections.py 中的工厂函数create_mcp_connection解析type必填键可选键说明stdio默认commandargs、env以子进程方式启动 MCP 服务器通过标准输入/输出通信底层为mcp库的stdio_clientStdioServerParameterssseurlheaders连接远程 SSE 端点底层为sse_client缺失必填键如 stdio 没有command会抛出带明确信息的ValueError。连接生命周期与工具发现setup_mcp_connectionsagents/utils/connections.py的完整流程是遍历mcp_servers配置经工厂创建MCPConnection实例并用传入的AsyncExitStack进入其异步上下文MCPConnection.__aenter__内部完成三步创建读写上下文 → 包装为ClientSession→await session.initialize()完成 MCP 握手调用session.list_tools()向服务器动态发现工具为每个远端工具生成一个MCPTool名称、描述、inputSchema全部透传其execute方法通过session.call_tool(name, arguments...)远程执行并仅提取文本型结果非文本结果返回No text content in tool response单个服务器连接失败只打印错误并继续处理下一个最终打印Loaded N MCP tools from M servers.。资源清理由__aexit__保证会话与读写上下文按序退出异常被捕获打印连接句柄置空——这与run_async中的AsyncExitStack配合构成完整的生命周期闭环。写一个 MCP 服务器calculator 示例仓库自带一个最小 MCP 服务器 agents/tools/calculator_mcp.py展示了工具提供方视角from mcp.server import FastMCP mcp FastMCP(Calculator) mcp.tool(namecalculator) def calculator(number1: float, number2: float, operator: str) - str: Performs basic calculations with two numbers. ...docstring 即模型看到的工具描述 # 支持 - * / ^ sqrt含除零与负数开方等错误分支 return fResult: {result} if __name__ __main__: mcp.run()两点实现事实一是mcp.tool的函数签名与 docstring 会被 FastMCP 自动转成 JSON Schema因此「参数说明即工具描述」二是错误不抛异常而是返回Error: ...字符串与本地工具的风格一致。Agent 侧通过{type: stdio, command: python, args: [agents/tools/calculator_mcp.py]}之类的配置即可挂载它agent_demo.ipynb中的calculator_server即以此方式指向该文件。上下文管理token 追踪与历史截断长循环必然撞上下文窗口agents/utils/history_util.py 中的MessageHistory用三个机制应对1. 持续 token 记账。每次 assistant 响应返回usage后add_message会把本回合实际新增的 token 记入message_tokensinput/output 元组列表并累加到total_tokens。input 侧的统计显式包含cache_read_input_tokens与cache_creation_input_tokens保证缓存命中时记账依然准确。2. 成对截断truncate。每当total_tokens超过context_window_tokenstruncate()就从最旧处开始成对user/assistant 一对移除消息把被移除回合的 token 从总量中扣减当历史开头仍有残余消息时用一条固定文本[Earlier history has been truncated.]替换第一条消息并按常量 25 token 重新记账TRUNCATION_NOTICE_TOKENS 25。成对移除是为了维护 API 所要求的多轮对话角色交替结构。3. Prompt 缓存。format_for_api()在导出请求历史前会为最后一条消息的所有 content 块追加cache_control: {type: ephemeral}enable_caching默认开启。结合 Agent 循环中「同一系统提示词 稳定前缀历史」的调用模式这为多轮工具循环提供了前缀缓存的落地点add_message中对cache_read/creationtoken 的读取也印证了这一点。并行工具执行与错误边界一轮响应可能包含多个tool_use块。execute_toolsagents/utils/tool_util.py默认parallelTrue用asyncio.gather并发执行所有工具传parallelFalse则顺序执行对依赖先后顺序的工具链有意义。每个工具的执行被_execute_single_tool包了一层错误边界工具名找不到 →Tool name not foundis_errorTrue执行抛任意异常 →Error executing tool: 异常信息is_errorTrue结果统一包装为{type: tool_result, tool_use_id: call.id, content: str(result)}回灌历史。即单个工具的失败不会中断整个循环而是以带is_error标记的结果让模型「看到」失败并自行调整——这与文件工具的「错误返回字符串」策略共同构成了参考实现的容错哲学。进阶message_params 透传层与测试验证Agent的最后一个参数message_params是一个「逃生舱」任意键值对会被展开进client.messages.create()的调用参数且优先级高于ModelConfig冲突键被覆盖。agents/test_message_params.py 用八个用例系统验证了它的语义边界自定义 HTTP 头{extra_headers: {X-Custom-Header: ...}}可透传任意请求头Beta 头如{anthropic-beta: files-api-2025-04-14}可与默认头合并生效metadata{metadata: {user_id: ...}}透传给 API传入非法字段时 API 会返回invalid_request_error测试断言了这一拒绝行为采样参数top_k、top_p、temperature均可透传且能覆盖ModelConfig中的同名默认值test_parameter_override断言temperature0.5、max_tokens200胜出。需要说明的前提该测试套件是集成测试main()会检查ANTHROPIC_API_KEY未设置时直接退出运行即会真实调用 API。环境要求与运行方式README「Requirements」一节给出的前提条件与源码核对一致PythonREADME 标注 Python 3.8。但从源码结构看代码大量使用dict[str, Any]、list[Tool] | None等内建泛型与联合类型标注实际运行在Python 3.9更稳妥API Key环境变量ANTHROPIC_API_KEYagents/agent.py 在构造默认客户端时读取依赖库anthropic与mcp两个 Python 包前者驱动 API 客户端后者提供stdio_client/sse_client/FastMCP等 MCP 能力。仓库根目录的 pyproject.toml 定义了整体包配置演示入口为 agents/agent_demo.ipynb覆盖本地工具 双 MCP 服务器 服务器端 Web 搜索/代码执行的完整场景。小结从这份参考实现带走什么回到 README 的核心主张——「复杂行为来自简单基础」——这份实现恰好给出了可迁移的四件套循环即架构_agent_loop的五步闭环截断 → 组参 → 调 API → 执行工具 → 回灌是整个 Agent 的全部控制流无需状态机工具即数据本地工具Tool 三要素、动态 MCP 工具协议发现与服务器端工具托管执行共享同一个to_dict()/execute抽象新增能力不改循环上下文即预算token 记账 成对截断 ephemeral 缓存把「窗口管理」变成可单测的纯本地逻辑失败即上下文工具错误不中断、不吞掉而是作为tool_result让模型参与决策。这套不足 300 行的骨架正是把 Agent 概念翻译到你自己的技术栈时可以逐行对照的模板。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
