尧图网页设计 
1. 为什么你的第一个 LangChain Agent 总是跑不起来很多人第一次接触 LangChain 构建 AI Agent卡住的地方往往不是 Agent 的逻辑本身而是环境配置和模型接入。你兴冲冲地pip install langchain照着文档写了几十行代码结果一运行就报AuthenticationError或者Connection error。更让人头疼的是你手头可能有好几个模型供应商的 KeyOpenAI 的、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_KEYsk-your-token-here TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini # LangChain 相关 LANGCHAIN_TRACING_V2false LANGCHAIN_PROJECTmy-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(fAPI Key 前缀: {api_key[:8]}... if api_key else API Key 未设置) print(fBase URL: {base_url}) print(fModel: {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( modelos.getenv(TAOTOKEN_MODEL, gpt-4o-mini), api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, timeout30, max_retries2, ) llm create_llm()这里几个参数值得说明temperature0让输出更稳定适合 Agent 场景timeout30设置 30 秒超时避免请求卡死max_retries2在网络抖动时自动重试。这些参数在 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 ExecutorLangChain 提供了create_tool_calling_agent和AgentExecutor来组装工具调用型 Agentfrom 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( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, ) agent_executor create_agent_executor(llm, tools)这里的verboseTrue会打印详细的执行日志包括模型思考、工具调用、工具返回这是 Harness 可观测性的最基础手段。max_iterations5限制最大循环次数防止 Agent 陷入死循环。handle_parsing_errorsTrue让解析错误不会直接崩溃而是返回给模型重新生成。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( modelos.getenv(TAOTOKEN_MODEL, gpt-4o-mini), api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, timeout30, max_retries2, ) 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( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, ) 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如果一切正常你会看到类似下面的输出verboseTrue会打印详细过程 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( filenameagent_harness.log, levellogging.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_asciiFalse)) return result运行几次后agent_harness.log里就会有完整的执行记录。这就是最基础的 Harness 落地——每次执行都有日志可查出问题能定位到具体是哪一步、哪个工具、什么输入导致的。4.4 检查模型调用是否走 TaoToken如果你想确认请求确实走了 TaoToken 的 Base URL可以在ChatOpenAI初始化后打印配置llm create_llm() print(fBase URL: {llm.openai_api_base}) print(fModel: {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_URLhttps://taotoken.net/api没有拼写错误。然后检查本地网络是否能正常访问该地址可以用curl测试curl -I https://taotoken.net/api如果返回 200 或 401说明服务可达只是没带 Key说明网络没问题。如果超时检查是否有防火墙或代理设置干扰。注意这里不要配置任何非官方的网络代理工具直接用系统默认网络即可。5.3 工具调用解析错误报错信息Could not parse LLM output: ...这种通常发生在模型返回的工具调用格式不符合 LangChain 预期时。解决方法第一确保handle_parsing_errorsTrue已设置第二检查模型的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_retries0先禁用重试方便看到原始错误。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()里根据输入长度或关键词动态选择模型 IDBase URL 和 API Key 保持不变。6.2 增加执行日志与追踪前面已经演示了用logging记录执行步骤。更进一步你可以接入 LangSmith 或自建追踪系统把每次请求的完整链路模型调用、工具调用、耗时、token 消耗记录下来。LangChain 支持通过环境变量开启追踪LANGCHAIN_TRACING_V2true LANGCHAIN_API_KEYyour_langsmith_key LANGCHAIN_PROJECTmy-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 里加一句“如果不确定请先调用工具确认不要凭记忆回答”。这句话能显著降低幻觉率尤其是涉及实时数据或内部知识的场景。配合temperature0和工具调用的强制校验你的第一个 Agent 就能达到可用的稳定度。现在你可以打开终端把.env配好运行python agent.py看着 Agent 第一次成功调用工具并返回结果。那一刻的成就感就是继续深入 Harness Engineering 的最好动力。 LangChain 实战：用 TaoToken 统一 Key 快速搭建你的第一个 AI Agent Harness Engineering
1. 为什么你的第一个 LangChain Agent 总是跑不起来很多人第一次接触 LangChain 构建 AI Agent卡住的地方往往不是 Agent 的逻辑本身而是环境配置和模型接入。你兴冲冲地pip install langchain照着文档写了几十行代码结果一运行就报AuthenticationError或者Connection error。更让人头疼的是你手头可能有好几个模型供应商的 KeyOpenAI 的、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_KEYsk-your-token-here TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini # LangChain 相关 LANGCHAIN_TRACING_V2false LANGCHAIN_PROJECTmy-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(fAPI Key 前缀: {api_key[:8]}... if api_key else API Key 未设置) print(fBase URL: {base_url}) print(fModel: {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( modelos.getenv(TAOTOKEN_MODEL, gpt-4o-mini), api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, timeout30, max_retries2, ) llm create_llm()这里几个参数值得说明temperature0让输出更稳定适合 Agent 场景timeout30设置 30 秒超时避免请求卡死max_retries2在网络抖动时自动重试。这些参数在 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 ExecutorLangChain 提供了create_tool_calling_agent和AgentExecutor来组装工具调用型 Agentfrom 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( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, ) agent_executor create_agent_executor(llm, tools)这里的verboseTrue会打印详细的执行日志包括模型思考、工具调用、工具返回这是 Harness 可观测性的最基础手段。max_iterations5限制最大循环次数防止 Agent 陷入死循环。handle_parsing_errorsTrue让解析错误不会直接崩溃而是返回给模型重新生成。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( modelos.getenv(TAOTOKEN_MODEL, gpt-4o-mini), api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, timeout30, max_retries2, ) 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( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, ) 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如果一切正常你会看到类似下面的输出verboseTrue会打印详细过程 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( filenameagent_harness.log, levellogging.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_asciiFalse)) return result运行几次后agent_harness.log里就会有完整的执行记录。这就是最基础的 Harness 落地——每次执行都有日志可查出问题能定位到具体是哪一步、哪个工具、什么输入导致的。4.4 检查模型调用是否走 TaoToken如果你想确认请求确实走了 TaoToken 的 Base URL可以在ChatOpenAI初始化后打印配置llm create_llm() print(fBase URL: {llm.openai_api_base}) print(fModel: {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_URLhttps://taotoken.net/api没有拼写错误。然后检查本地网络是否能正常访问该地址可以用curl测试curl -I https://taotoken.net/api如果返回 200 或 401说明服务可达只是没带 Key说明网络没问题。如果超时检查是否有防火墙或代理设置干扰。注意这里不要配置任何非官方的网络代理工具直接用系统默认网络即可。5.3 工具调用解析错误报错信息Could not parse LLM output: ...这种通常发生在模型返回的工具调用格式不符合 LangChain 预期时。解决方法第一确保handle_parsing_errorsTrue已设置第二检查模型的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_retries0先禁用重试方便看到原始错误。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()里根据输入长度或关键词动态选择模型 IDBase URL 和 API Key 保持不变。6.2 增加执行日志与追踪前面已经演示了用logging记录执行步骤。更进一步你可以接入 LangSmith 或自建追踪系统把每次请求的完整链路模型调用、工具调用、耗时、token 消耗记录下来。LangChain 支持通过环境变量开启追踪LANGCHAIN_TRACING_V2true LANGCHAIN_API_KEYyour_langsmith_key LANGCHAIN_PROJECTmy-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 里加一句“如果不确定请先调用工具确认不要凭记忆回答”。这句话能显著降低幻觉率尤其是涉及实时数据或内部知识的场景。配合temperature0和工具调用的强制校验你的第一个 Agent 就能达到可用的稳定度。现在你可以打开终端把.env配好运行python agent.py看着 Agent 第一次成功调用工具并返回结果。那一刻的成就感就是继续深入 Harness Engineering 的最好动力。