1. 为什么你搭的 Agent 总是“跑两轮就崩”很多人第一次搭 Agent代码能跑起来但一放到真实任务里就露馅要么循环停不下来要么聊到第五轮就忘了前面说过什么要么工具调用参数永远对不上。问题不在框架而在你没把 Agent 当成一个“系统”来看只把它当成一次 API 调用。Agent 内部其实有四个必须协同的模块Agent Loop 负责“心跳”决定什么时候继续、什么时候停记忆系统负责“长期大脑”让跨会话的偏好和历史能沉淀下来工具系统负责“手脚”把模型意图翻译成真实世界的文件、命令、网络请求Context Engine 负责“调度中枢”把身份、记忆、工具声明、历史消息组装成一次合法请求。这四个模块任何一个缺位Agent 都会退化成“会聊天的脚本”。这篇面向想从零搭建可运行 Agent 的开发者。我会先讲清楚每个模块的最小可用形态然后交付两份可直接复制的配置骨架一份settings.json用于工具与权限声明一份config.toml用于模型通道与上下文预算。同时演示如何通过 TaoToken 统一 Key/API 通道接入 AI 工具让模型调用、编码 Agent、上下文压缩这些环节走同一条链路最后给出逐项验证四大模块是否真正生效的具体动作。你不需要先精通 LangChain 或 LangGraph只要会写 Python 和改配置文件就能跟着做。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写 Agent Loop 之前先把“模型从哪来”这件事固定下来。Agent 开发最烦的是一边调逻辑一边换模型通道今天用这个 Key明天换那个 Base URL配置散落在环境变量、代码常量、IDE 插件里排障时根本不知道是哪一层出的问题。我的做法是所有模型调用统一走 TaoToken 的 API 通道Key 只维护一份。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key。API 基地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为base_url使用。你需要准备三样东西一个可用的 API Key、一个你打算作为主推理的模型名、一个用于辅助任务摘要、压缩、审批的轻量模型名。主模型负责 Agent Loop 里的推理和工具选择辅助模型负责上下文压缩和历史摘要这样成本结构更合理。注意Key 不要写进会提交到 Git 的配置文件。用环境变量注入或者放在本地.env里并加入.gitignore。下面所有配置骨架里出现的TAOTOKEN_API_KEY都指代这个环境变量。如果你还没生成 Key先去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后建议先单独用 curl 验证一次确认通道可用再进入 Agent 代码避免把“Key 无效”和“Loop 写错”两个问题混在一起排查。3. 可复制配置settings.json 与 config.toml 骨架3.1 settings.json工具系统与权限声明工具系统的核心不是“有多少工具”而是“每个工具的风险等级和参数约束是否清晰”。下面这份settings.json声明了两个工具一个高危的 shell 执行一个低危的网页搜索。requires_approval字段是 Agent Loop 里人机交互的触发点。{ agent: { name: my-first-agent, max_iterations: 30, early_stop_on_complete: true }, tools: [ { name: execute_command, description: 在终端执行 shell 命令。适合文件操作、系统管理、脚本执行。, parameters: { command: { type: string, description: 要执行的命令 }, timeout: { type: integer, default: 30000 } }, risk_level: high, requires_approval: true }, { name: web_search, description: 搜索互联网获取信息。适合查询实时数据、新闻、文档。, parameters: { query: { type: string, description: 搜索关键词 } }, risk_level: low, requires_approval: false } ], memory: { long_term_file: ./MEMORY.md, user_profile_file: ./USER.md, max_memory_chars: 2200, max_user_chars: 1375, session_search: { enabled: true, backend: sqlite_fts5, db_path: ./sessions.db } }, context: { frozen_snapshot: true, budget: { system_prompt: 10000, tool_declarations: 15000, session_history: 80000, working_memory: 10000, response_output: 10000 } } }这份配置里frozen_snapshot: true对应记忆系统的关键设计Session 启动时把MEMORY.md和USER.md注入 system prompt运行期间记忆修改即时落盘但当前 session 继续用启动时的快照下一个 session 才读新版本。这样做的好处是 prompt 前缀稳定缓存命中率高长对话成本明显下降。3.2 config.toml模型通道与辅助模型config.toml负责模型侧配置。主模型走 TaoToken 的 API 通道辅助模型单独指定用于压缩和摘要。[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models.main] model claude-sonnet-4-20250514 max_tokens 8192 temperature 0.3 [models.auxiliary] compression claude-haiku-3-5-20241022 session_search claude-haiku-3-5-20241022 approval claude-haiku-3-5-20241022 [compression] trigger_ratio 0.8 keep_recent_messages 10 summarize_with compression [loop] max_iterations 30 tool_timeout_ms 30000trigger_ratio 0.8表示当 session history 用量达到预算的 80% 时触发压缩。keep_recent_messages 10是压缩后保留的最近消息条数避免摘要把刚发生的关键上下文也压掉。3.3 Agent Loop 最小实现有了配置Loop 本身其实很短。下面这段代码把推理、行动、观察、迭代四步串起来并接入上面两份配置。import json, os, subprocess from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) def load_config(): with open(settings.json) as f: settings json.load(f) return settings def execute_tool(name, args, settings): tool next(t for t in settings[tools] if t[name] name) if tool[requires_approval]: print(f[审批] 即将执行: {args}) if input(确认? (y/n): ).lower() ! y: return 用户拒绝执行 if name execute_command: r subprocess.run(args[command], shellTrue, capture_outputTrue, textTrue, timeoutargs.get(timeout, 30000) / 1000) return r.stdout r.stderr if name web_search: return f[模拟搜索] {args[query]} 的结果 return 未知工具 def agent_loop(task, settings): history [{role: user, content: task}] for i in range(settings[agent][max_iterations]): resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messageshistory, tools[{type: function, function: { name: t[name], description: t[description], parameters: t[parameters], }} for t in settings[tools]], ) msg resp.choices[0].message history.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: args json.loads(call.function.arguments) result execute_tool(call.function.name, args, settings) history.append({ role: tool, tool_call_id: call.id, content: str(result)[:4000], }) return 达到迭代上限任务未完成 if __name__ __main__: cfg load_config() print(agent_loop(列出当前目录下的 Python 文件, cfg))这段代码里max_iterations来自settings.json工具声明直接由配置生成审批逻辑由requires_approval驱动。你改配置就能改行为不用动 Loop 代码。4. 验证请求逐项确认四大模块是否生效配置写完不代表生效。下面四个验证动作分别对应 Agent Loop、记忆系统、工具系统、Context Engine。每做完一个你都能看到明确的输出信号。4.1 验证 Agent Loop观察迭代次数把任务设成“先列出目录再统计文件数量”运行后打印每轮迭代的i和工具调用名。如果只跑了一轮就返回说明 Loop 没进入工具分支如果跑满 30 轮还没停说明早停条件没写对。正常表现是 2 到 4 轮内完成每轮都有明确的 thought 和 result。4.2 验证记忆系统跨会话读取第一次运行让 Agent 记住“我偏好用 Python 而不是 Node”。退出进程。第二次运行直接问“我偏好什么语言”。如果 Agent 答不出来检查MEMORY.md是否真的写入了内容以及frozen_snapshot是否导致新 session 才读取。你可以手动打开MEMORY.md确认落盘。4.3 验证工具系统审批与参数故意让 Agent 执行一条rm -rf开头的命令。如果requires_approval生效你应该看到审批提示输入n后 Agent 收到“用户拒绝执行”并调整策略。如果直接执行了说明审批逻辑没接进execute_tool。4.4 验证 Context Engine预算与压缩连续对话 20 轮每轮打印当前 history 的 token 估算值。当用量超过session_history预算的 80% 时应该看到压缩日志且压缩后 history 条数降到keep_recent_messages附近。如果一直不压缩检查trigger_ratio是否被正确读取。提示验证阶段建议把max_iterations调小到 5避免调试时跑太久。确认逻辑正确后再调回 30。5. 本篇常见错排查报错一openai.AuthenticationError: Invalid API key先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在用echo $TAOTOKEN_API_KEY检查。如果存在但仍报错去控制台重新生成一次 Key注意复制时不要带空格。API 基地址必须是https://taotoken.net/api不要手动加/v1或其他路径。报错二工具调用参数解析失败json.decoder.JSONDecodeError模型返回的arguments偶尔会带 markdown 代码块标记。在json.loads之前先做一次清洗去掉首尾的json 和。另外确认parameters的 schema 里type字段拼写正确integer不要写成int。报错三Agent 无限循环不停止三个检查点max_iterations是否被正确传入is_task_complete的判断条件是否过于宽松工具返回结果是否为空导致模型一直重试。建议在每轮迭代打印i和工具名观察是否在重复同一个调用。报错四记忆文件写入但读不到frozen_snapshot模式下当前 session 用的是启动时的快照。如果你在同一个 session 里写入记忆又立刻读取读到的还是旧版本。这是设计行为不是 bug。验证记忆系统时务必重启进程。报错五压缩后 Agent 丢失关键信息调大keep_recent_messages或者在压缩时显式保留工具调用结果。纯摘要容易把“上一步执行了什么命令、返回了什么”压掉导致 Agent 重复执行。可以在压缩 prompt 里要求“保留所有工具调用及其结果摘要”。6. 把通道固定下来再谈 Agent 设计搭 Agent 最容易走偏的地方是一边调 Loop 逻辑一边换模型通道最后分不清是架构问题还是接入问题。我的建议是先把 TaoToken 的 Key 和 API 通道固定成一份配置让模型调用、辅助压缩、审批判断都走同一条链路然后再专心打磨 Agent Loop 和 Context Engine。如果你主要做长期编码类 Agent比如让它持续读写仓库、跑测试、提交 PR可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想先验证模型对话和工具调用是否通直接去模型对话页试一轮https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 管理在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。回到 Agent 本身四个模块里最容易被低估的是 Context Engine。很多人把 prompt 组装写成字符串拼接结果工具声明、记忆、历史混在一起缓存命中率极低成本翻倍。把 Frozen 部分和 Dynamic 部分分开是让 Agent 从“能跑”到“跑得起”的关键一步。