Claude Code 智能体设计拆解：从 ReAct 到工具调用的工程实现

1. 从一次真实任务说起为什么需要理解 Claude Code 的智能体设计很多人第一次用 Claude Code会觉得它“就是能改代码的聊天框”。但真正让它区别于普通代码补全的是背后那套ReAct 推理循环 工具调用的智能体设计。你给它一句“帮我把这个模块改成异步的”它不会直接吐一段代码而是先读文件、再分析结构、然后逐个改、最后跑测试——这一整套动作才是 Claude Code 智能体的核心。这篇内容聚焦 Claude Code 智能体的设计链路拆解 ReAct 推理循环与工具调用机制如何协同完成复杂任务。面向想自建 Agent 的开发者我会给出可复制的 Agent 配置骨架与工具注册示例并附一轮真实任务下的调用链验证步骤帮你理解从规划到执行的完整闭环。如果你正在做自己的 Agent 项目或者想把 Claude Code 这类工具接入到自己的开发流里理解这套设计比单纯会用快捷键重要得多。下面我会从问题场景出发先讲清楚为什么传统补全工具不够用再一步步拆到可运行的配置和验证。2. 原问题与场景补全工具为什么撑不起复杂任务传统代码补全工具的工作模式是“你写一半它猜后半”。它不关心你的项目结构不知道你刚改了哪个文件也不会主动去跑测试。遇到“重构一个模块”这种多步骤任务它只能给你零散的建议剩下的规划、执行、验证全得你自己来。Claude Code 智能体要解决的就是这个断层。它把大模型当作“大脑”把文件读写、命令执行、代码搜索这些能力封装成“工具”让模型在推理循环里自己决定下一步做什么。你可以把它理解成一个会自己看代码、自己动手改、自己验证结果的开发助手。这个场景里最关键的三个角色是模型负责意图理解、推理规划、决定调用哪个工具。工具层一组预定义函数比如read_file、write_to_file、run_command、search_code。执行引擎解析模型的工具调用请求校验参数在安全边界内执行再把结果喂回模型。三者协同才能让“观察-思考-行动-观察”的循环跑起来。下面我先讲清楚在自建 Agent 时前置需要准备什么。3. TaoToken 前置给 Agent 准备一个稳定的模型入口自建 Agent 的第一步不是写循环而是让模型能稳定调用。Claude Code 这类智能体对模型的推理连贯性要求很高如果接口不稳定ReAct 循环很容易在中间断掉导致任务半途而废。我自己的做法是先把模型入口统一到一个兼容 Anthropic 协议的服务上。TaoToken 提供的就是这样一个入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 它兼容 Anthropic 的接口格式Claude Code 和自建 Agent 都能直接对接。前置准备分三步第一步拿到 API Key。进入控制台创建密钥地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后先复制保存后面配置环境变量要用。第二步确认模型可用。在模型对话页面先跑一轮简单对话确认密钥和模型都正常地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这一步别跳过很多接入问题其实是密钥或模型名写错了。第三步配置环境变量。把 API Key 和 Base URL 写进环境变量避免硬编码在代码里export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_API_Key如果你用的是 Claude Code 命令行工具它默认会读这两个变量。自建 Agent 时你在 HTTP 客户端里把 base_url 指向https://taotoken.net/api请求头带上x-api-key即可。注意API 地址不要加 UTM 参数保持https://taotoken.net/api干净避免某些客户端把查询参数拼进请求路径导致 404。前置准备好之后就可以进入真正的 Agent 配置环节了。4. 可复制配置Agent 骨架与工具注册示例这一节是全文的技术核心。我会给出一个最小可运行的 Agent 骨架包含 ReAct 循环、工具注册、工具调用解析三部分。你可以直接复制到自己的项目里改。4.1 Agent 配置骨架先定义 Agent 的基本配置。这里用 Python 写结构清晰换成其他语言思路一样。import os import json import anthropic class AgentConfig: def __init__(self): self.client anthropic.Anthropic( base_urlos.environ.get(ANTHROPIC_BASE_URL, https://taotoken.net/api), api_keyos.environ.get(ANTHROPIC_API_KEY), ) self.model claude-sonnet-4-20250514 self.max_iterations 15 self.tools [] self.system_prompt ( 你是一个编程智能体。你可以调用工具来读写文件、执行命令、搜索代码。 每一步先思考当前状态再决定调用哪个工具。任务完成后给出最终回复。 ) def register_tool(self, name, description, parameters, func): self.tools.append({ name: name, description: description, input_schema: parameters, }) setattr(self, f_tool_{name}, func)这个骨架里max_iterations是 ReAct 循环的安全阀防止模型陷入死循环。system_prompt里明确告诉模型“先思考再行动”这是 ReAct 模式的关键提示。4.2 工具注册示例工具注册要遵循 JSON Schema 格式模型才能正确理解参数。下面注册三个最常用的工具def read_file(file_path: str) - str: with open(file_path, r, encodingutf-8) as f: return f.read() def write_to_file(file_path: str, content: str) - str: with open(file_path, w, encodingutf-8) as f: f.write(content) return f已写入 {file_path}共 {len(content)} 字符 def run_command(command: str) - str: import subprocess result subprocess.run(command, shellTrue, capture_outputTrue, textTrue, timeout30) return fexit{result.returncode}\nstdout{result.stdout}\nstderr{result.stderr} config AgentConfig() config.register_tool( nameread_file, description读取指定文件的全部内容, parameters{ type: object, properties: { file_path: {type: string, description: 文件路径} }, required: [file_path], }, funcread_file, ) config.register_tool( namewrite_to_file, description将内容写入指定文件文件不存在则创建, parameters{ type: object, properties: { file_path: {type: string, description: 文件路径}, content: {type: string, description: 文件内容}, }, required: [file_path, content], }, funcwrite_to_file, ) config.register_tool( namerun_command, description执行 Shell 命令并返回输出, parameters{ type: object, properties: { command: {type: string, description: 要执行的命令} }, required: [command], }, funcrun_command, )工具描述写得越清楚模型选错工具的概率越低。比如read_file的描述里强调“全部内容”避免模型以为它只读一部分。4.3 ReAct 循环实现这是整个 Agent 的心脏。循环的逻辑是把消息发给模型如果模型返回工具调用就执行工具并把结果追加到消息历史然后继续下一轮如果模型返回纯文本说明任务完成退出循环。def run_agent(config: AgentConfig, user_input: str): messages [{role: user, content: user_input}] for i in range(config.max_iterations): response config.client.messages.create( modelconfig.model, max_tokens4096, systemconfig.system_prompt, toolsconfig.tools, messagesmessages, ) messages.append({role: assistant, content: response.content}) tool_calls [b for b in response.content if b.type tool_use] if not tool_calls: final_text .join(b.text for b in response.content if b.type text) print(f[第 {i1} 轮] 任务完成{final_text}) return final_text tool_results [] for call in tool_calls: print(f[第 {i1} 轮] 调用工具{call.name}参数{json.dumps(call.input, ensure_asciiFalse)}) func getattr(config, f_tool_{call.name}, None) if func is None: result f错误未注册的工具 {call.name} else: try: result func(**call.input) except Exception as e: result f工具执行异常{e} tool_results.append({ type: tool_result, tool_use_id: call.id, content: str(result), }) messages.append({role: user, content: tool_results}) return 达到最大迭代次数任务未完成这段代码里有几个设计点值得注意。第一messages里 assistant 的回复要原样追加包括工具调用块否则模型下一轮会丢失上下文。第二工具结果要用tool_result类型包装并带上tool_use_id这是 Anthropic 协议的要求。第三异常要捕获并作为结果返回让模型自己决定怎么处理而不是直接崩掉。4.4 参数对照表为了让你更清楚每个配置项的作用我整理了一张对照表配置项作用建议值model指定推理模型按任务复杂度选复杂任务用强模型max_iterations循环上限防死循环10–20system_prompt定义 Agent 行为边界明确“先思考再行动”tools工具定义列表按需注册别一次给太多max_tokens单次回复长度上限4096 起步工具不是越多越好。我试过一次性注册十几个工具结果模型经常选错。后来精简到核心几个准确率明显提升。5. 验证请求跑一轮真实任务看调用链配置写完了得验证它真的能跑通。我准备了一个真实任务让 Agent 读取一个 Python 文件找出其中的 bug修复它然后运行测试确认。5.1 准备测试文件先创建一个有 bug 的文件login.pydef check_password(password): if password.length 0: return False return True这个 bug 很明显Python 字符串没有.length属性应该用len()。5.2 发起任务调用 Agentrun_agent(config, 请读取 login.py找出其中的 bug 并修复然后运行 python -c from login import check_password; print(check_password(\\)) 验证)5.3 预期调用链正常情况下你会看到类似这样的输出[第 1 轮] 调用工具read_file参数{file_path: login.py} [第 2 轮] 调用工具write_to_file参数{file_path: login.py, content: def check_password(password):\n if len(password) 0:\n return False\n return True\n} [第 3 轮] 调用工具run_command参数{command: python -c from login import check_password; print(check_password(\\))} [第 4 轮] 任务完成已修复 login.py 中的 bug将 password.length 改为 len(password)验证输出为 False符合预期。这条调用链完整展示了 ReAct 循环观察读文件→ 思考发现 bug→ 行动写文件→ 观察跑命令→ 思考确认结果→ 最终回复。5.4 验证要点验证时重点看三件事第一工具调用顺序是否合理。正常应该是先读后写而不是直接写。第二工具参数是否正确。比如write_to_file的content应该是修复后的完整代码而不是片段。第三最终回复是否基于工具结果。如果模型没跑命令就说“已修复”说明它跳过了验证步骤这时候要检查 system prompt 是否强调了“验证”。如果你在验证模型本身的行为可以到模型对话页面单独测一轮地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 这样能把 Agent 逻辑和模型能力分开排查。6. 本篇常见错排查自建 Agent 的过程中有几个错误几乎每个人都会遇到。我把它们整理出来方便你对照排查。6.1 工具调用解析失败现象模型返回了工具调用但执行引擎报“未注册的工具”或参数解析错误。原因工具名拼写不一致或者input_schema格式不对。Anthropic 协议要求工具定义用input_schema不是parameters。如果你从其他协议迁移过来很容易踩这个坑。解决检查register_tool里的字段名确保是name、description、input_schema三个字段。参数 schema 里required要和properties对应。6.2 循环不退出现象Agent 一直在调用工具跑到max_iterations才停。原因模型没有收到“任务完成”的信号或者工具结果里没有足够信息让它判断完成。解决在 system prompt 里明确“任务完成后直接给出最终回复不要再调用工具”。另外检查工具结果是否包含关键信息比如run_command要返回 exit code模型才能判断命令是否成功。6.3 上下文超限现象任务跑到一半报 context length 超限。原因工具结果太长比如read_file读了一个几千行的文件直接把上下文撑爆。解决给工具加截断逻辑。比如read_file只返回前 200 行或者按需分页读取。这也是 Claude Code 上下文管理策略里“分页加载”的思路。def read_file(file_path: str, max_lines: int 200) - str: with open(file_path, r, encodingutf-8) as f: lines f.readlines() if len(lines) max_lines: return .join(lines[:max_lines]) f\n...已截断共 {len(lines)} 行 return .join(lines)6.4 接口 401 或 404现象请求直接失败返回鉴权错误或路径不存在。原因API Key 没配好或者 base_url 写错。常见的是把 UTM 参数拼进了 API 地址。解决确认ANTHROPIC_BASE_URL是https://taotoken.net/api不带任何查询参数。API Key 到控制台重新复制一次地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。如果还是不通到接入文档对照一下请求格式地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6.5 工具执行超时现象run_command卡住整个 Agent 无响应。原因执行的命令是交互式的或者耗时太长。解决给subprocess.run加timeout参数超时后返回错误信息让模型处理。同时避免执行需要交互输入的命令比如vim、top。7. 从规划到执行的闭环把 Agent 用起来理解 Claude Code 智能体的设计最终要落到“能自己搭一个”上。上面这套骨架虽然简单但已经包含了 ReAct 循环、工具注册、调用解析、结果回传的完整链路。你可以在这个基础上扩展工具比如加search_code、web_fetch也可以加权限校验让高风险操作先确认。如果你打算长期跑编码类 Agent 任务比如让它持续帮你改代码、跑测试可以考虑用 Coding Plan 来管理调用额度地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。对于 Claude Code 命令行工具的重度用户Anthropic 兼容接入的配置可以参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 里面有针对性的接入说明。最后留一个实用技巧调试 Agent 时把每一轮的messages打印出来。你会清楚看到模型在每一步“看到”了什么、“想”了什么、“做”了什么。很多问题不是模型不行而是你给它的上下文里缺了关键信息。把调用链看清楚比反复调 prompt 有效得多。