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_KEY="sk-你的实际Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

Windows PowerShell 的话，用$env:语法：

$env:TAOTOKEN_API_KEY="sk-你的实际Key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你用的是 Python，可以在项目根目录建一个.env文件，然后用python-dotenv加载：

TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://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/completions，TaoToken 的 SDK 会自动拼接路径。如果你手动拼了，请求会打到错误的地址上，返回 404。另外 Key 不要提交到 Git，.env记得写进.gitignore。

配好之后，你可以先用一个最简单的请求验证通道是否通：

from openai import OpenAI client = OpenAI(api_key=API_KEY, base_url=BASE_URL) resp = client.chat.completions.create( model="gpt-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 id=17247": "id=17247, name=张三, status=active", "SELECT COUNT(*) FROM orders WHERE customer_id=17247": "count=0", "SELECT * FROM orders WHERE customer_id=17247": "无记录", } 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( model="gpt-4o-mini", api_key=API_KEY, base_url=BASE_URL, temperature=0.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(agent=agent, tools=tools, max_iterations=10, verbose=True)

注意temperature=0.1，这是 Agent 模式和普通聊天模式的一个重要区别。普通聊天可以用 0.7 让回答更有创造性，但 Agent 需要的是准确和谨慎，温度低一点能减少它“自由发挥”的概率。max_iterations=10对应提示词里的“最多调用 10 次”，两者要一致，否则模型可能以为还能继续调但执行器已经停了。

最后跑一次完整任务：

result = executor.invoke({ "input": "客户 ID 17247 的订单情况怎么样？帮我排查一下为什么查不到订单。" }) print(result["output"])

运行后你会看到verbose=True打印出的推理过程：模型先决定调用query_database查客户信息，拿到结果后再查订单数量，发现为 0 后继续查订单明细，确认无记录，最后给出结论。整个过程不需要你手动指定调用哪个工具，模型自己根据提示词和工具描述做决策。

4. 验证请求：一次完整的 Agent 任务执行与结果分析

上面代码跑起来之后，终端会输出类似下面的过程。我把它拆开解释，方便你对照自己的运行结果。

第一步，模型收到用户输入后，先输出一个工具调用请求：

Invoking: `query_database` with `{'sql': 'SELECT * FROM customers WHERE id=17247'}`

这说明模型理解了“客户 ID 17247”这个信息，并且决定先查客户表确认这个客户存在。工具返回id=17247, name=张三, status=active，模型拿到结果后继续思考。

第二步，模型决定查订单数量：

Invoking: `query_database` with `{'sql': 'SELECT COUNT(*) FROM orders WHERE customer_id=17247'}`

返回count=0。这时候模型知道这个客户没有订单，但它没有直接下结论，而是继续查明细确认：

Invoking: `query_database` with `{'sql': 'SELECT * FROM orders WHERE customer_id=17247'}`

返回“无记录”。到这里，模型已经通过三次工具调用确认了事实：客户存在，但没有任何订单。最后它输出结论：

根据查询结果，客户 ID 17247（张三）当前状态为 active，但订单表中没有该客户的任何记录。订单数量为 0，订单明细查询也无结果。因此查不到订单的原因是：该客户尚未产生任何订单。

这个结果和普通 LLM 直接回答的区别在于：普通 LLM 可能会说“可能是订单被删除了”或者“检查一下外键关联”，这些都是猜测；而 Agent 的结论是基于三次真实查询得出的，每一步都有工具返回作为依据。

如果你把verbose=True关掉，只看最终输出，可能会觉得“这不就是一段普通回答吗”。但打开 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。里面列出了不同模型的 Model ID、请求格式和返回结构，配 Agent 的时候直接查表就行。想先验证模型对话效果的话，可以用模型对话页面快速试一条请求：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。长期跑编码类 Agent 任务的话，Coding Plan 的额度更适合持续调用：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。Key 的管理和生成在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

最后说一个实际经验：Agent 的调试成本主要花在提示词和工具描述上，而不是代码本身。代码框架搭好之后，大部分时间是在改提示词里的规则、调整工具 docstring、观察模型在什么情况下会“跑偏”。建议你每改一次提示词就跑一次完整任务，把 verbose 输出保存下来对比，这样能快速定位是哪句话导致了行为变化。跑通一个场景之后，再复制这套结构去跑第二个场景，慢慢就能积累出一套适合自己业务的 Agent 模板。