1. 为什么你的第一个 LangChain Agent 总是跑不起来
很多人第一次接触 LangChain 构建 AI Agent，卡住的地方往往不是 Agent 的逻辑本身，而是环境配置和模型接入。你兴冲冲地pip install langchain，照着文档写了几十行代码，结果一运行就报AuthenticationError或者Connection error。更让人头疼的是，你手头可能有好几个模型供应商的 Key，OpenAI 的、Anthropic 的、国内各种平台的，每个都要单独配置环境变量，项目一多就乱成一锅粥。
我试过在一个项目里同时用三个不同平台的模型做对比测试，光是管理这些 Key 和环境变量就花了大半天，还经常出现 A 项目的 Key 被 B 项目误用的情况。后来我把所有模型调用统一收敛到一个入口，用同一套 Key 和 Base URL 来管理，整个开发流程才顺畅起来。这篇文章要讲的，就是怎么用 TaoToken 统一 Key 接入的方式，配合 LangChain 快速搭建你的第一个 AI Agent，并且把 Harness Engineering 的工程化思路落地进去——所谓 Harness，就是给 Agent 套上一层可控、可观测、可排查的执行框架，让它不只是个玩具，而是能稳定跑起来的工程系统。
这篇文章适合谁？如果你已经会写 Python，了解 LangChain 的基本概念（比如 Chain、Tool、Agent Executor），但每次配环境、接模型、调工具调用都踩坑，那这篇就是写给你的。我会从环境变量配置开始，一步步带你完成模型调用、工具注册、执行循环，最后用日志和返回结构验证整个 Harness 是否生效。全程可复制，你跟着做就能跑通。
核心检索词先明确：LangChain AI Agent 搭建、TaoToken 统一 Key 接入、Harness Engineering 工程化落地。这三个词贯穿全文，你可以在每个章节里看到它们的具体落地方式。
2. TaoToken 统一 Key 接入：环境变量与依赖配置
在开始写 Agent 代码之前，先把模型接入层搞定。TaoToken 的核心价值在于：你只需要一个 API Key 和一个 Base URL，就能调用多个主流模型，不用为每个供应商单独维护一套配置。对于 LangChain 项目来说，这意味着你可以用ChatOpenAI这个标准接口，通过改base_url和model参数来切换模型，代码几乎不用动。
2.1 安装依赖
先创建一个干净的虚拟环境，然后安装必要的包。我习惯用venv，你也可以用 conda，看个人偏好。
python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install langchain langchain-openai python-dotenv这里说明一下每个包的作用：langchain是核心框架，langchain-openai提供了ChatOpenAI这个模型接口类，python-dotenv用来从.env文件加载环境变量。如果你后续要接工具调用和 Agent Executor，还需要langchain-community，不过第一个 Agent 先用最简依赖跑通。
2.2 配置 .env 文件
在项目根目录创建一个.env文件，内容如下：
# TaoToken 统一接入配置 TAOTOKEN_API_KEY=sk-your-token-here TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=gpt-4o-mini # LangChain 相关 LANGCHAIN_TRACING_V2=false LANGCHAIN_PROJECT=my-first-agent这里的关键是TAOTOKEN_BASE_URL指向https://taotoken.net/api，注意不要加多余的路径后缀。TAOTOKEN_MODEL你可以根据实际需要换成gpt-4o、claude-3-5-sonnet等模型 ID，具体支持列表可以在 TaoToken 的模型对话页面查看。
注意：
.env文件不要提交到 Git，记得加到.gitignore里。API Key 泄露是常见的安全事故，尤其是团队协作时。
2.3 验证环境变量加载
写一个简单的脚本确认环境变量能正确读取：
import os from dotenv import load_dotenv load_dotenv() api_key = os.getenv("TAOTOKEN_API_KEY") base_url = os.getenv("TAOTOKEN_BASE_URL") model = os.getenv("TAOTOKEN_MODEL") print(f"API Key 前缀: {api_key[:8]}..." if api_key else "API Key 未设置") print(f"Base URL: {base_url}") print(f"Model: {model}")运行后如果能看到正确的输出，说明环境变量配置没问题。如果api_key是None，检查.env文件是否在项目根目录，以及load_dotenv()是否在读取环境变量之前调用。
2.4 为什么用统一 Key 而不是每个平台单独配
这里展开说一下 Harness Engineering 的思路。在传统做法里，你可能会在代码里写死openai_api_key、anthropic_api_key等多个变量，每个模型供应商一套配置。项目小的时候没问题，但一旦你要做模型对比、故障切换、成本优化，这种分散配置就会变成噩梦。
统一 Key 接入的好处是：第一，配置收敛，所有模型调用走同一个入口，环境变量只需要维护一套；第二，切换成本低，改一个model参数就能换模型，不用改代码逻辑；第三，便于观测，所有请求都经过同一个 Base URL，日志和监控可以统一收集。这就是 Harness 工程化的第一步——把模型接入层标准化。
3. 可复制的 Agent 初始化配置与工具注册
环境搞定后，开始写 Agent 的核心代码。这一节我会给出完整的可复制配置，包括模型初始化、工具注册、Agent Executor 的组装。你直接复制到项目里就能跑。
3.1 模型初始化
创建一个agent.py文件，先写模型初始化部分：
import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def create_llm(): """创建统一的 LLM 实例，所有模型调用走 TaoToken 接入""" return ChatOpenAI( model=os.getenv("TAOTOKEN_MODEL", "gpt-4o-mini"), api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), temperature=0, timeout=30, max_retries=2, ) llm = create_llm()这里几个参数值得说明：temperature=0让输出更稳定，适合 Agent 场景；timeout=30设置 30 秒超时，避免请求卡死；max_retries=2在网络抖动时自动重试。这些参数在 Harness 工程里属于基础防护，后面排查问题时你会感谢自己提前设了超时。
3.2 注册工具
Agent 的核心能力是调用工具。LangChain 用@tool装饰器来定义工具，工具的 docstring 会被用作给模型的描述，所以写清楚很重要。
from langchain_core.tools import tool import datetime @tool def get_current_time() -> str: """获取当前日期和时间，返回格式为 YYYY-MM-DD HH:MM:SS""" return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") @tool def calculate(expression: str) -> str: """计算数学表达式，输入为合法的 Python 数学表达式，如 '2 + 3 * 4'""" try: result = eval(expression, {"__builtins__": {}}, {}) return f"计算结果: {result}" except Exception as e: return f"计算失败: {str(e)}" @tool def search_knowledge(query: str) -> str: """搜索内部知识库，输入为查询关键词，返回相关文档片段""" # 这里用模拟数据，实际项目替换为真实检索逻辑 knowledge_base = { "退款": "退款政策：未发货订单可直接退款，已发货订单需先退货。", "发货": "发货时间：工作日 48 小时内发货，节假日顺延。", "发票": "发票申请：订单完成后 7 天内可申请电子发票。", } for key, value in knowledge_base.items(): if key in query: return value return "未找到相关文档。" tools = [get_current_time, calculate, search_knowledge]三个工具分别覆盖了时间查询、数学计算、知识检索，足够演示 Agent 的工具调用循环。注意calculate里用了eval，实际生产环境要换成安全的表达式解析库，这里为了演示简洁先用eval并限制了__builtins__。
3.3 组装 Agent Executor
LangChain 提供了create_tool_calling_agent和AgentExecutor来组装工具调用型 Agent：
from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate def create_agent_executor(llm, tools): """创建带工具调用能力的 Agent Executor""" prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个有用的 AI 助手，可以调用工具来回答问题。" "如果需要实时信息或计算，请优先使用工具。" "回答时请简洁明了，并在使用工具后说明结果来源。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) return AgentExecutor( agent=agent, tools=tools, verbose=True, max_iterations=5, handle_parsing_errors=True, return_intermediate_steps=True, ) agent_executor = create_agent_executor(llm, tools)这里的verbose=True会打印详细的执行日志，包括模型思考、工具调用、工具返回，这是 Harness 可观测性的最基础手段。max_iterations=5限制最大循环次数，防止 Agent 陷入死循环。handle_parsing_errors=True让解析错误不会直接崩溃，而是返回给模型重新生成。
3.4 完整配置文件汇总
把上面的代码整合到一个文件里，方便你直接复制：
# agent.py import os import datetime from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate load_dotenv() def create_llm(): return ChatOpenAI( model=os.getenv("TAOTOKEN_MODEL", "gpt-4o-mini"), api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), temperature=0, timeout=30, max_retries=2, ) @tool def get_current_time() -> str: """获取当前日期和时间，返回格式为 YYYY-MM-DD HH:MM:SS""" return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") @tool def calculate(expression: str) -> str: """计算数学表达式，输入为合法的 Python 数学表达式""" try: result = eval(expression, {"__builtins__": {}}, {}) return f"计算结果: {result}" except Exception as e: return f"计算失败: {str(e)}" @tool def search_knowledge(query: str) -> str: """搜索内部知识库，输入为查询关键词""" knowledge_base = { "退款": "退款政策：未发货订单可直接退款，已发货订单需先退货。", "发货": "发货时间：工作日 48 小时内发货，节假日顺延。", "发票": "发票申请：订单完成后 7 天内可申请电子发票。", } for key, value in knowledge_base.items(): if key in query: return value return "未找到相关文档。" tools = [get_current_time, calculate, search_knowledge] def create_agent_executor(llm, tools): prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个有用的 AI 助手，可以调用工具来回答问题。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) return AgentExecutor( agent=agent, tools=tools, verbose=True, max_iterations=5, handle_parsing_errors=True, return_intermediate_steps=True, ) if __name__ == "__main__": llm = create_llm() executor = create_agent_executor(llm, tools) result = executor.invoke({"input": "现在几点了？"}) print(result["output"])这段代码可以直接运行，前提是.env配置正确。下一节我们会详细看运行结果和验证方法。
4. 端到端运行与 Harness 生效验证
代码写完了，现在跑一次完整的端到端请求，看看 Agent 是否真的能调用工具、返回结果，以及 Harness 层的日志和返回结构是否如预期。
4.1 运行命令
在终端执行：
python agent.py如果一切正常，你会看到类似下面的输出（verbose=True会打印详细过程）：
> Entering new AgentExecutor chain... Invoking: `get_current_time` with `{}` 2025-01-15 14:32:08 现在时间是 2025-01-15 14:32:08。 > Finished chain.这个输出说明 Agent 正确识别了用户意图，调用了get_current_time工具，并把工具返回结果整合成了自然语言回复。
4.2 验证工具调用循环
再测试一个需要多步推理的请求：
result = executor.invoke({"input": "帮我算一下 128 乘以 37 等于多少，然后告诉我现在的时间"}) print(result["output"]) print("--- 中间步骤 ---") for step in result["intermediate_steps"]: print(f"工具: {step[0].tool}") print(f"输入: {step[0].tool_input}") print(f"输出: {step[1]}")预期输出会显示 Agent 先调用calculate，再调用get_current_time，最后整合两个结果。intermediate_steps是 Harness 可观测性的关键数据结构，它记录了每一步的工具调用详情，方便你排查问题。
4.3 用返回结构验证 Harness 是否生效
Harness Engineering 的核心要求之一是执行过程可观测。AgentExecutor返回的字典包含以下字段：
| 字段 | 含义 | 用途 |
|---|---|---|
input | 用户原始输入 | 审计追踪 |
output | 最终回复 | 结果展示 |
intermediate_steps | 工具调用步骤列表 | 排查工具调用问题 |
chat_history | 对话历史（如果传入） | 多轮对话管理 |
你可以写一个简单的日志函数，把每次请求的输入、输出、工具调用步骤记录到文件：
import json import logging logging.basicConfig( filename="agent_harness.log", level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s" ) def run_with_logging(executor, user_input): result = executor.invoke({"input": user_input}) log_entry = { "input": user_input, "output": result["output"], "steps": [ {"tool": s[0].tool, "input": s[0].tool_input, "output": s[1]} for s in result.get("intermediate_steps", []) ] } logging.info(json.dumps(log_entry, ensure_ascii=False)) return result运行几次后，agent_harness.log里就会有完整的执行记录。这就是最基础的 Harness 落地——每次执行都有日志可查，出问题能定位到具体是哪一步、哪个工具、什么输入导致的。
4.4 检查模型调用是否走 TaoToken
如果你想确认请求确实走了 TaoToken 的 Base URL，可以在ChatOpenAI初始化后打印配置：
llm = create_llm() print(f"Base URL: {llm.openai_api_base}") print(f"Model: {llm.model_name}")输出应该显示https://taotoken.net/api和你配置的模型 ID。如果 Base URL 不对，检查.env里的TAOTOKEN_BASE_URL是否被正确加载。
5. 常见报错排查：401、连接失败与解析错误
即使配置看起来没问题，实际运行时还是会遇到各种报错。这一节整理几个高频错误和排查方法，都是我在实际项目中踩过的坑。
5.1 401 AuthenticationError
报错信息通常长这样：
openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key', 'type': 'invalid_request_error'}}排查步骤：第一，确认.env里的TAOTOKEN_API_KEY没有多余空格或换行；第二，确认load_dotenv()在读取环境变量之前调用；第三，检查 Key 是否过期或被禁用。你可以在 TaoToken 的 API Keys 页面重新生成一个 Key 测试。
如果 Key 没问题但还是 401，检查base_url是否写成了https://taotoken.net/api/（末尾多了斜杠），有些客户端对 URL 格式敏感，去掉末尾斜杠试试。
5.2 连接超时或 Connection error
报错信息：
openai.APIConnectionError: Connection error.这种通常是网络问题或 Base URL 配置错误。先确认TAOTOKEN_BASE_URL=https://taotoken.net/api没有拼写错误。然后检查本地网络是否能正常访问该地址，可以用curl测试：
curl -I https://taotoken.net/api如果返回 200 或 401（说明服务可达，只是没带 Key），说明网络没问题。如果超时，检查是否有防火墙或代理设置干扰。注意：这里不要配置任何非官方的网络代理工具，直接用系统默认网络即可。
5.3 工具调用解析错误
报错信息：
Could not parse LLM output: ...这种通常发生在模型返回的工具调用格式不符合 LangChain 预期时。解决方法：第一，确保handle_parsing_errors=True已设置；第二，检查模型的temperature是否过高（建议设为 0）；第三，确认使用的模型支持 Function Calling / Tool Calling，部分老模型不支持工具调用。
如果频繁出现解析错误，可以在 prompt 里加一句：“请严格按照工具调用的格式返回，不要添加额外解释。”
5.4 模型返回空结果或 reading choices 错误
报错信息：
KeyError: 'choices' 或 IndexError: list index out of range这通常说明 API 返回结构不符合预期。排查：第一，确认TAOTOKEN_MODEL是有效的模型 ID；第二，检查请求是否被限流（返回 429）；第三，打印原始响应看看返回了什么。你可以在ChatOpenAI初始化时加max_retries=0先禁用重试，方便看到原始错误。
5.5 工具调用死循环
如果 Agent 反复调用同一个工具，最后触发max_iterations限制，说明模型没有正确理解工具返回结果。解决方法：第一，检查工具的 docstring 是否清晰描述了输入输出；第二，在 prompt 里明确要求“如果工具返回结果已经足够回答问题，请直接给出最终答案”；第三，降低max_iterations到 3-5，避免无限循环消耗 token。
6. 从第一个 Agent 到可扩展的 Harness 工程
跑通第一个 Agent 只是起点。Harness Engineering 的思路是让这套系统可扩展、可观测、可治理。这一节给出几个实用的扩展方向，你可以根据自己的项目需求逐步加上。
6.1 统一 Key 接入的扩展价值
当你需要切换模型做对比测试时，只需要改.env里的TAOTOKEN_MODEL，代码完全不用动。比如从gpt-4o-mini换成claude-3-5-sonnet，重启服务即可。这种灵活性在快速迭代阶段非常有用。
如果你要做多模型路由（比如简单问题用小模型，复杂问题用大模型），可以在create_llm()里根据输入长度或关键词动态选择模型 ID，Base URL 和 API Key 保持不变。
6.2 增加执行日志与追踪
前面已经演示了用logging记录执行步骤。更进一步，你可以接入 LangSmith 或自建追踪系统，把每次请求的完整链路（模型调用、工具调用、耗时、token 消耗）记录下来。LangChain 支持通过环境变量开启追踪：
LANGCHAIN_TRACING_V2=true LANGCHAIN_API_KEY=your_langsmith_key LANGCHAIN_PROJECT=my-first-agent这样每次executor.invoke()都会自动上报追踪数据，方便你在面板上查看执行详情。
6.3 工具权限与限流
生产环境的 Agent 必须考虑权限控制。你可以在工具函数内部加权限校验：
@tool def refund_order(order_id: str, user_id: str) -> str: """申请订单退款，仅管理员有权限调用""" if not is_admin(user_id): return "权限不足：只有管理员可以执行退款操作。" # 执行退款逻辑 return f"订单 {order_id} 退款成功。"限流可以在 AgentExecutor 外层加一个简单的计数器，或者用ratelimit库装饰工具函数。这些都属于 Harness 层的管控措施。
6.4 下一步学习路径
如果你已经跑通了本文的示例，建议接下来做这几件事：第一，把工具替换成你实际业务需要的 API 调用；第二，加上多轮对话记忆（用ConversationBufferMemory）；第三，尝试用 LangGraph 替代 AgentExecutor，获得更精细的执行流程控制；第四，把日志接入到你的监控系统，实现告警和异常检测。
TaoToken 的模型对话页面可以帮你快速测试不同模型的效果，接入文档里有更详细的参数说明。如果你打算长期做 Agent 开发，Coding Plan 提供了更稳定的调用额度和优先级支持，适合持续迭代的项目。
6.5 一个实用技巧
最后分享一个我在实际项目中总结的小技巧：在 Agent 的 system prompt 里加一句“如果不确定，请先调用工具确认，不要凭记忆回答”。这句话能显著降低幻觉率，尤其是涉及实时数据或内部知识的场景。配合temperature=0和工具调用的强制校验，你的第一个 Agent 就能达到可用的稳定度。
现在你可以打开终端，把.env配好，运行python agent.py，看着 Agent 第一次成功调用工具并返回结果。那一刻的成就感，就是继续深入 Harness Engineering 的最好动力。
