1. 从零搭 Agent为什么总在第五步就卡住如果你正在搜「Agent 开发难点」「Function Calling 怎么调」「Tool Use 编排」「Prompt Caching 省钱」这几个词大概率你已经踩过坑了Demo 跑得挺顺一上真实任务就开始循环、选错工具、上下文爆掉、报错崩盘、账单飙升。这篇就聚焦从零搭建 Agent 时最常卡住的五个环节——LLM 接入、Function Calling/Tool Use 编排、Prompt Caching 成本控制、多工具鉴权、调试可观测性用 TaoToken 统一 Key/API 通道做接入层给你一份能直接复制的config.toml与settings.json骨架再演示一次完整的工具调用链路验证动作帮你快速跑通最小可用 Agent。先说清楚 TaoToken 在这里扮演什么角色。它是一层统一的模型接入通道你只需要一个 Key、一个 Base URL就能在同一个接口下切换不同模型、复用同一套鉴权逻辑不用为每个模型单独维护 endpoint 和密钥。对 Agent 来说这点很关键——Agent 天然要频繁调用 LLM如果每次换模型都要改代码、换 Key、调参数调试成本会成倍上升。统一接入层把「模型选择」和「业务逻辑」解耦你改config.toml里一行模型名整条链路就跟着切。适合谁看写过一点 Python、想搭第一个能真正干活的 Agent 的人已经在用 LangChain / 自研编排、但被循环和成本折磨的人以及想把工具调用链路跑通、再逐步加复杂度的工程同学。下面按五个难点逐个拆每个都给可复制的配置和代码最后用一次真实的工具调用验证收尾。2. 难点一LLM 接入与统一 Key 的前置准备2.1 为什么接入层要单独抽出来很多人搭 Agent 的第一版代码是这样的模型调用、工具定义、循环控制全糊在一个文件里。跑通没问题但一旦要换模型、加工具、调缓存就变成牵一发动全身。正确做法是把「接入层」独立出来它只负责三件事拿 Key、拼请求、返回统一格式的响应。TaoToken 的 API 地址是https://taotoken.net/api所有模型请求都走这一个入口。统一 Key 的好处在于多工具鉴权时你不需要给每个工具、每个模型分别配密钥。Agent 的工具调用链路里LLM 请求走 TaoToken工具本身的鉴权比如搜索 API、数据库连接单独管理两者不混在一起排查问题时边界清晰。2.2 环境变量与 Key 管理先把 Key 放进环境变量别硬编码进代码。这是所有后续步骤的前提# Linux / macOS export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/apiKey 的创建入口在控制台的 API Keys 页面建议给 Agent 单独建一个 Key方便按项目统计用量、单独吊销。如果你还没建可以先到 API Keys 管理页 生成一个命名成agent-dev之类后面排查成本时能一眼看出是哪个项目在烧 token。注意Key 只放环境变量或密钥管理服务不要提交到 Git。Agent 项目尤其容易在调试时把 Key 打进日志记得在日志层做脱敏。2.3 最小接入验证在写 Agent 之前先用一段最小代码确认接入层通了。这一步能帮你排除掉 80% 的「到底是模型问题还是我的编排问题」import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)跑出「通了」两个字说明接入层没问题可以进入工具编排。如果这里就报 401先检查 Key 和环境变量报 404 就检查base_url有没有写错路径。3. 难点二Function Calling / Tool Use 编排3.1 工具描述写不好模型必然选错工具选择错误的根因九成出在描述上。模型看不到你的代码它只能靠description和参数 schema 判断「这个工具是干嘛的、什么时候该用」。一份合格的工具体应该包含一句话概括、2-3 个典型使用场景、明确的能力边界、每个参数的含义与示例、返回值格式。下面是一个可直接用的工具定义注意description里把「何时用/何时不用」都写清楚了tools [ { type: function, function: { name: search_code, description: ( 在本地代码库中按关键字搜索代码。 适用场景定位函数定义、查找变量引用、搜索错误信息。 不适用搜索网页内容请用 web_search、读取完整文件请用 read_file。 返回匹配的文件路径、行号和代码片段。 ), parameters: { type: object, properties: { query: { type: string, description: 搜索关键字例如 def login 或 NullPointerException, }, path: { type: string, description: 搜索根目录默认当前目录例如 src/, }, }, required: [query], }, }, } ]3.2 工具集要精简不要一次全暴露工具超过 20-30 个模型选择准确率会明显下降这是注意力被稀释的结果。做法是按场景动态注册代码审查场景只给read_file / grep / git_diff不给web_search / bash_execute。下面这个函数按任务上下文返回工具子集def get_tools_for_context(ctx: dict) - list: tools [] if ctx.get(needs_file_access): tools [read_file_tool, grep_tool, glob_tool] if ctx.get(needs_execution): tools [bash_tool] if ctx.get(needs_web): tools [web_search_tool, web_fetch_tool] return tools3.3 循环检测Agent 卡死的头号原因Agent 反复调同一个工具、永远不收敛是最经典的故障。两道防线硬性步数上限 循环检测。步数上限直接卡死最坏情况循环检测在重复出现时提前干预from collections import Counter MAX_STEPS 50 def detect_repeating_pattern(history: list, threshold: int 3) - bool: 检测同一个 action参数组合是否重复超过阈值 recent [str(a) for a in history[-20:]] counts Counter(recent) return any(c threshold for c in counts.values()) for step in range(MAX_STEPS): action agent.decide() if action.is_final: break if detect_repeating_pattern(agent.history): agent.add_context(你似乎在重复操作请换一种方法或直接给出当前结论) execute(action) else: raise RuntimeError(Agent 超过最大步数已强制终止)检测到循环时不要直接崩而是把提示注入上下文让模型自己调整策略——这是 Agent 相比传统程序最独特的地方。4. 难点三Prompt Caching 与上下文成本控制4.1 上下文是怎么爆掉的一次典型 Agent 执行系统提示约 2000 token工具定义约 3000 token每步的模型输出加工具返回 1500-12000 token。20 步之后轻松到 5 万-15 万 token50 步之后可能到 50 万。后果不只是贵还有模型在长上下文里「迷失」、关键指令被截断。4.2 分层上下文管理把上下文分四层不同层不同生命周期这是最有效的结构化管理方式层级内容生命周期L1 永久指令系统提示、核心规则、工具定义全生命周期L2 任务记忆任务目标、关键里程碑、重要发现当前任务L3 工作上下文最近 N 步的工具调用历史滑动窗口L4 即时上下文当前工具返回结果仅当前步4.3 用 Prompt Caching 压固定前缀成本系统提示和工具定义通常占总消耗的 30-50%而且每步都重复发送。Prompt Caching 的核心是把稳定不变的前缀缓存起来后续请求命中缓存这部分成本大幅下降。设计要点是——系统提示和工具定义格式保持稳定不要每步动态改把频繁读取的参考信息放进缓存边界内动态内容当前步结果放在缓存边界之后。# 稳定前缀放前面动态内容放后面命中缓存的概率更高 messages [ {role: system, content: SYSTEM_PROMPT}, # 稳定可缓存 {role: system, content: TOOLS_SPEC}, # 稳定可缓存 {role: user, content: current_task}, # 动态 *recent_steps, # 动态滑动窗口 ]4.4 预算上限与成本感知提示给每个任务设 token 预算超了就抛异常别让它无限烧class TokenBudget: def __init__(self, max_tokens: int 200_000): self.max_tokens max_tokens self.used 0 def consume(self, tokens: int): self.used tokens if self.used self.max_tokens: raise RuntimeError(f预算耗尽: {self.used}/{self.max_tokens}) def remaining(self) - int: return max(0, self.max_tokens - self.used)同时把剩余预算注入上下文让模型自己感知紧迫度「剩余预算 35000/200000请优先给出最重要的结果省略非关键细节。」实测下来这一句提示能明显减少无效步骤。5. 难点四多工具鉴权与可观测性5.1 鉴权分层别把 Key 混在一起Agent 会调用多种工具LLM 走 TaoToken搜索走第三方 API数据库走连接串。鉴权要分层管理各管各的。下面这份config.toml骨架把接入层和工具层分开模型切换只改[llm]段# config.toml [llm] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-5 max_tokens 4096 temperature 0.2 [llm.budget] max_tokens_per_task 200000 warn_threshold 0.8 [agent] max_steps 50 loop_window 5 loop_threshold 3 [tools.search] enabled true api_key_env SEARCH_API_KEY timeout_seconds 15 [tools.database] enabled false dsn_env DB_DSN readonly true [observability] log_level INFO log_tool_calls true redact_keys true对应的settings.json骨架用于运行时覆盖和工具开关{ agent: { name: minimal-agent, max_steps: 50, early_exit: true }, llm: { model: claude-sonnet-4-5, fallback_model: claude-haiku-4-5, prompt_cache: true }, tools: { search_code: { enabled: true, tier: 1 }, read_file: { enabled: true, tier: 1 }, bash_execute: { enabled: true, tier: 2, require_confirm: true }, delete_file: { enabled: false, tier: 3 } }, observability: { trace_tool_calls: true, log_dir: ./logs/agent } }工具分级的意义在于Level 1 默认可用读文件、搜索Level 2 需确认执行命令、写文件Level 3 高风险默认关闭删除、强推。这样即使模型选错工具也不会造成不可逆的破坏。5.2 可观测性看不见就没法改Agent 调试最难的是「它为什么这么决策」。至少记录三样东西每步的输入上下文摘要、模型输出的工具调用、工具返回结果。日志里对 Key 做脱敏别把密钥写进去。有了 trace你才能回答「它第 7 步为什么选了 web_search 而不是 search_code」这类问题。6. 难点五完整工具调用链路验证6.1 一次端到端的验证动作前面都是零件现在把它们装起来跑一次。目标让 Agent 完成「在代码库里找到 login 函数并读取实现」这个任务验证 LLM 接入、工具选择、循环控制、结果返回整条链路。import os, json from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) # 1. 定义工具精简版只给两个 tools [ { type: function, function: { name: search_code, description: 在代码库中按关键字搜索返回文件路径和行号。, parameters: { type: object, properties: {query: {type: string}}, required: [query], }, }, }, { type: function, function: { name: read_file, description: 读取指定文件的指定行范围。, parameters: { type: object, properties: { path: {type: string}, offset: {type: integer}, limit: {type: integer}, }, required: [path], }, }, }, ] # 2. 工具的真实实现示例用假数据替换成你的逻辑 def search_code(query, path.): return {status: success, matches: 1, results: [{file: src/auth/login.py, line: 45, snippet: def login(username, password):}]} def read_file(path, offset0, limit200): return {status: success, path: path, offset: offset, content: def login(username, password):\n ...} TOOL_MAP {search_code: search_code, read_file: read_file} # 3. 单步执行 循环控制 messages [ {role: system, content: 你是代码助手先搜索定位再精确读取。}, {role: user, content: 找到 login 函数并读取它的实现。}, ] for step in range(10): resp client.chat.completions.create( modelclaude-sonnet-4-5, messagesmessages, toolstools, ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: print(最终回答:, msg.content) break for call in msg.tool_calls: fn TOOL_MAP[call.function.name] args json.loads(call.function.arguments) result fn(**args) print(f[step {step}] 调用 {call.function.name}({args}) - {result}) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), })6.2 期望的成功结果跑通后你会看到类似输出第 0 步模型调用search_code({query: def login})拿到文件路径和行号第 1 步调用read_file({path: src/auth/login.py, offset: 45})拿到实现第 2 步模型不再调工具直接输出总结。整条链路走完说明接入层、工具编排、循环控制都正常。如果模型在第 0 步就选了read_file而不是search_code说明工具描述还不够清晰回去补「何时用/何时不用」。如果它反复调search_code检查循环检测有没有生效。7. 本篇常见错排查报 401 UnauthorizedKey 没读到或写错。先echo $TAOTOKEN_API_KEY确认环境变量存在再确认base_url是https://taotoken.net/api不要多加路径。模型不返回 tool_calls工具描述太模糊或tools参数没传对。检查description是否写清了使用场景parameters的required是否合理。Agent 无限循环先看步数上限有没有设再看循环检测的window和threshold。常见原因是工具返回信息不足模型觉得「还没找到」就反复搜把返回结果做得更结构化能缓解。上下文爆掉报超长检查有没有做历史压缩和滑动窗口。把完整文件内容内联进上下文是最大元凶改成引用路径加行号。成本异常高先看 Prompt Caching 有没有命中稳定前缀有没有被动态内容污染。再看模型分层有没有做简单任务别用最强模型。工具鉴权失败确认工具自己的 Key 和 LLM 的 Key 是分开管理的别把 TaoToken 的 Key 拿去调搜索 API。8. 下一步把最小 Agent 跑稳再扩复杂度最小可用 Agent 跑通之后别急着加工具。先把三件事做扎实循环检测的阈值调到你任务场景合适的值、Prompt Caching 的命中率打日志观察、成本监控按任务维度出日报。这三样稳了再加工具、加模型分层、加检查点恢复每一步都可控。如果你在接入或工具编排上卡住可以先看 接入文档 对照参数想先验证模型返回格式和工具调用结构用 模型对话 手动发几次请求最快如果是要长期跑编码类 Agent、需要稳定的额度和并发Coding Plan 更适合按周期用。Key 还没建的去 API Keys 建一个命名带上项目名后面查成本会省很多事。