1. 从聊天到干活LLM 变身 Agent 到底缺了什么很多人第一次用大模型 API 的时候都会有一种“它好像很聪明但真让它干点活就掉链子”的感觉。你问它今天天气它给你编一个你让它查数据库里某个客户的信息它一本正经地报出一串数字结果一核对全是错的。这不是模型不行而是我们只把它当成了一个“问答机器”没有给它配上真正干活需要的三样东西明确的规则、可用的工具、以及反复尝试的机会。LLM 本身是一个基于海量文本训练出来的概率模型它的强项是理解语言、生成连贯的文本、做一定程度的推理。但它的短板也很明显它不知道你本地数据库里有什么不知道你公司内部 API 返回什么格式更不知道你昨天刚改过的表结构。它只能靠训练时“记住”的东西来回答而这些记忆往往是过时的、模糊的、甚至是错误的。所以当你问它一个需要实时数据的问题时它只能“猜”而猜出来的结果看起来越像真的危害就越大。Agent 的核心思路就是承认 LLM 有推理能力但不让它单打独斗。我们给它一套系统提示词告诉它“你是谁、你能做什么、遇到什么情况必须调用工具”再给它一组工具函数让它能真正去查数据库、调接口、读文件然后给它一个推理循环允许它多轮思考、多次调用工具、根据返回结果决定下一步最后把温度调低让它谨慎验证而不是大胆猜测。这四件事做完LLM 就从“只会聊天”变成了“能自主解决问题”的 Agent。这篇文章我会用一个最小可跑的本地示例带你走完从提示词设计到工具调用再到结果验证的完整链路。接入层我用 TaoToken 的统一 Key 和 API 通道来演示因为它把不同模型的 Base URL 和鉴权方式统一了你不需要为每个模型单独配一套环境变量。下面所有配置和代码都可以直接复制到本地运行跑通之后你就能理解 Agent 的骨架到底长什么样。2. TaoToken 统一通道配置Base URL 与 API Key 环境变量在写 Agent 代码之前先把接入层配好。TaoToken 的作用是提供一个统一的 API 入口你拿一个 Key 就能调用多种模型Base URL 固定为https://taotoken.net/api。这样你在 Agent 代码里切换模型时只需要改一个模型 ID不用动鉴权逻辑和请求地址。我试过在本地用环境变量管理 Key这样代码里不出现明文也方便在不同项目之间复用。Linux 或 macOS 下你可以在~/.zshrc或~/.bashrc里加两行export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 的话用$env:语法$env:TAOTOKEN_API_KEYsk-你的实际Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Python可以在项目根目录建一个.env文件然后用python-dotenv加载TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api对应的 Python 加载代码import os from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(TAOTOKEN_API_KEY) BASE_URL os.getenv(TAOTOKEN_BASE_URL) assert API_KEY, 请先设置 TAOTOKEN_API_KEY assert BASE_URL, 请先设置 TAOTOKEN_BASE_URL这里有一个容易踩的坑Base URL 末尾不要多加/v1或/chat/completionsTaoToken 的 SDK 会自动拼接路径。如果你手动拼了请求会打到错误的地址上返回 404。另外 Key 不要提交到 Git.env记得写进.gitignore。配好之后你可以先用一个最简单的请求验证通道是否通from openai import OpenAI client OpenAI(api_keyAPI_KEY, base_urlBASE_URL) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 只回复两个字通了}] ) print(resp.choices[0].message.content)如果输出“通了”说明 Key 和 Base URL 都没问题。如果报 401检查 Key 是否复制完整、有没有多余空格如果报连接错误检查 Base URL 是否写成了https://taotoken.net/api而不是其他路径。这一步过了再往下写 Agent 逻辑就不会被接入问题干扰。3. 可复制配置提示词、工具定义与推理循环的完整代码Agent 的代码结构可以拆成四块系统提示词、工具定义、工具绑定、推理循环。我下面给的是一个最小可跑版本你可以直接复制到一个agent_demo.py里运行。先看系统提示词。它的作用是给模型立规矩告诉它什么时候必须调用工具、什么时候可以自己回答。普通聊天提示词可能只写“你是一个助手”但 Agent 提示词要具体到行为边界SYSTEM_PROMPT 你是一名数据库排查助手。你的核心职责是帮助用户定位 SQL 问题和数据异常。 工作规则 1. 当用户提出任何与数据库相关的问题时你必须先调用 query_database 工具获取真实数据禁止凭记忆回答。 2. 如果工具返回的结果为空或不符合预期你需要再次调用工具换一个查询条件继续排查。 3. 每次调用工具后先分析返回结果再决定下一步是继续查询还是给出结论。 4. 最多允许调用工具 10 次超过后必须基于已有信息给出当前最优判断。 5. 回答时先说明你调用了哪些工具、得到了什么结果再给出结论。 你可以使用的工具 - query_database(sql: str) - str执行 SQL 查询并返回结果。 这段提示词的关键在于“必须调用工具”和“禁止凭记忆回答”这两句。没有这两句模型很可能直接给你编一个答案。加上之后它会在遇到数据库问题时优先走工具调用路径。接下来定义工具。这里我用一个模拟的数据库查询函数真实场景中你可以替换成实际的数据库连接逻辑from langchain_core.tools import tool tool def query_database(sql: str) - str: 执行 SQL 查询并返回结果。输入必须是合法的 SQL 语句。 # 模拟数据库返回真实场景替换为实际查询 fake_db { SELECT * FROM customers WHERE id17247: id17247, name张三, statusactive, SELECT COUNT(*) FROM orders WHERE customer_id17247: count0, SELECT * FROM orders WHERE customer_id17247: 无记录, } return fake_db.get(sql.strip(), 查询无结果请检查 SQL 条件)工具函数的 docstring 很重要模型会根据它来判断这个工具是干什么的、什么时候该调用。所以 docstring 要写清楚输入输出不要写“这是一个工具”这种废话。然后绑定工具到模型。用 LangChain 的话可以这样写from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI( modelgpt-4o-mini, api_keyAPI_KEY, base_urlBASE_URL, temperature0.1, ) tools [query_database] prompt ChatPromptTemplate.from_messages([ (system, SYSTEM_PROMPT), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, max_iterations10, verboseTrue)注意temperature0.1这是 Agent 模式和普通聊天模式的一个重要区别。普通聊天可以用 0.7 让回答更有创造性但 Agent 需要的是准确和谨慎温度低一点能减少它“自由发挥”的概率。max_iterations10对应提示词里的“最多调用 10 次”两者要一致否则模型可能以为还能继续调但执行器已经停了。最后跑一次完整任务result executor.invoke({ input: 客户 ID 17247 的订单情况怎么样帮我排查一下为什么查不到订单。 }) print(result[output])运行后你会看到verboseTrue打印出的推理过程模型先决定调用query_database查客户信息拿到结果后再查订单数量发现为 0 后继续查订单明细确认无记录最后给出结论。整个过程不需要你手动指定调用哪个工具模型自己根据提示词和工具描述做决策。4. 验证请求一次完整的 Agent 任务执行与结果分析上面代码跑起来之后终端会输出类似下面的过程。我把它拆开解释方便你对照自己的运行结果。第一步模型收到用户输入后先输出一个工具调用请求Invoking: query_database with {sql: SELECT * FROM customers WHERE id17247}这说明模型理解了“客户 ID 17247”这个信息并且决定先查客户表确认这个客户存在。工具返回id17247, name张三, statusactive模型拿到结果后继续思考。第二步模型决定查订单数量Invoking: query_database with {sql: SELECT COUNT(*) FROM orders WHERE customer_id17247}返回count0。这时候模型知道这个客户没有订单但它没有直接下结论而是继续查明细确认Invoking: query_database with {sql: SELECT * FROM orders WHERE customer_id17247}返回“无记录”。到这里模型已经通过三次工具调用确认了事实客户存在但没有任何订单。最后它输出结论根据查询结果客户 ID 17247张三当前状态为 active但订单表中没有该客户的任何记录。订单数量为 0订单明细查询也无结果。因此查不到订单的原因是该客户尚未产生任何订单。这个结果和普通 LLM 直接回答的区别在于普通 LLM 可能会说“可能是订单被删除了”或者“检查一下外键关联”这些都是猜测而 Agent 的结论是基于三次真实查询得出的每一步都有工具返回作为依据。如果你把verboseTrue关掉只看最终输出可能会觉得“这不就是一段普通回答吗”。但打开 verbose 看到中间的调用链你就能理解 Agent 的本质它不是一次性生成答案而是通过“思考—调用—观察—再思考”的循环逐步逼近事实。这个循环就是推理引擎max_iterations控制它最多转多少圈。验证的时候还有一个细节你可以故意把 SQL 写错比如查一个不存在的表看模型会不会重试。如果它第一次调用失败后能换一个查询继续排查说明提示词里的“如果工具返回结果不明确需要再次调用工具”生效了。如果它直接放弃或者开始编答案那就要回去检查提示词和工具描述是否足够清晰。5. 常见报错排查401、local proxy failed 与 reading choices 问题接入和运行 Agent 的过程中有几个报错出现频率特别高。我按实际遇到的顺序列一下你对照自己的终端输出排查。401 Unauthorized这个最常见基本就是 Key 的问题。先检查TAOTOKEN_API_KEY是否设置成功可以在 Python 里打印os.getenv(TAOTOKEN_API_KEY)看是不是 None。如果是 None说明环境变量没加载上检查.env文件路径和load_dotenv()的调用位置。如果 Key 有值但还是 401检查 Key 是否复制完整有没有把前后空格带进去。还有一种情况是 Key 过期或被禁用去控制台重新生成一个。local proxy failed / connection error这个报错通常和 Base URL 有关。先确认你写的是https://taotoken.net/api没有多写/v1或/chat/completions。然后检查本地网络是否能正常访问这个地址可以用curl https://taotoken.net/api看返回。如果公司网络有特殊限制可能需要换一个网络环境再试。注意不要在任何配置里写代理地址TaoToken 的通道本身是直连的额外加代理反而会导致连接失败。reading choices 报错 / KeyError: choices这个错误说明请求返回的 JSON 里没有choices字段通常是响应体被截断或者返回了错误信息。先打印完整的resp看内容如果是{error: ...}按错误信息处理。常见原因是模型 ID 写错了比如把gpt-4o-mini写成了gpt-4o-mini-2024这种不存在的版本。另外检查max_tokens是否设得太小导致响应被截断。还有一种情况是流式请求和非流式请求混用Agent 场景建议先用非流式跑通再考虑流式输出。OAuth / authentication 相关报错如果你用的是 Claude Code 或 Codex 这类工具可能会遇到 OAuth 认证问题。这类工具通常需要配置三件套Base URL、API Key、Model ID。以 Claude Code 为例你需要在配置文件里指定ANTHROPIC_BASE_URL为 TaoToken 的地址ANTHROPIC_API_KEY为你的 Key然后选择对应的模型 ID。三个都写对才能正常调用缺一个都会报认证失败。Codex 的话检查auth.json里的api_key和base_url是否和 TaoToken 的一致。工具调用不触发代码跑起来但模型一直不调用工具直接给文字回答。先检查工具是否真的绑定到了模型上create_tool_calling_agent的tools参数有没有传对。然后检查系统提示词里有没有明确写“必须调用工具”如果只写“可以使用工具”模型可能选择不用。最后检查工具函数的 docstring 是否清晰模型是根据 docstring 来判断工具用途的写得太模糊它就不敢调。6. 从最小 Agent 到可用工作流接入文档与模型验证入口跑通上面这个最小示例之后你已经有了一个能自主调用工具、多轮推理、验证结果的 Agent 骨架。接下来要做的是根据你的实际场景替换工具函数、调整提示词、增加工具数量。比如把模拟的query_database换成真实的数据库连接再加一个search_knowledge_base工具让模型能查文档加一个call_external_api工具让它能调外部服务。每加一个工具都要在系统提示词里写清楚“什么情况下用这个工具”否则模型可能该调的时候不调不该调的时候乱调。参数方面temperature建议保持在 0.1 到 0.3 之间太高会让模型在工具调用决策上变得不稳定。max_iterations根据任务复杂度调整简单查询 5 次够用复杂排查可以放到 15 到 20 次。但不要设得太大否则模型可能陷入无效循环反复调用同一个工具却得不到新信息。可以在提示词里加一句“如果连续两次调用返回相同结果停止调用并给出结论”这样能减少无效迭代。如果你需要查看完整的 API 参数和接入方式可以到接入文档里对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。里面列出了不同模型的 Model ID、请求格式和返回结构配 Agent 的时候直接查表就行。想先验证模型对话效果的话可以用模型对话页面快速试一条请求https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。长期跑编码类 Agent 任务的话Coding Plan 的额度更适合持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Key 的管理和生成在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后说一个实际经验Agent 的调试成本主要花在提示词和工具描述上而不是代码本身。代码框架搭好之后大部分时间是在改提示词里的规则、调整工具 docstring、观察模型在什么情况下会“跑偏”。建议你每改一次提示词就跑一次完整任务把 verbose 输出保存下来对比这样能快速定位是哪句话导致了行为变化。跑通一个场景之后再复制这套结构去跑第二个场景慢慢就能积累出一套适合自己业务的 Agent 模板。