企业官网建设流程全解析

1. 从空目录到能跑的 Agent，卡点往往不在 LangChain

AI Engineering 系列第二篇，我想把视角从“概念”拉到“工程落地”。LangChain Agent 最小工程骨架，指的是用 Python + LangChain 搭一个能真实跑起来、能调用工具、能返回结果的智能体项目结构，而不是停留在 notebook 里跑一段 demo。它适合已经看过 LangChain 文档、但一落到多文件项目就不知道从哪下手的人，也适合想把模型调用统一收敛到一个 Key 通道、避免到处散落 API Key 的开发者。

我见过太多人卡在同一个地方：LangChain 的AgentExecutor能跑通，但一旦拆成tools/、config/、.env、main.py就乱了。更麻烦的是模型通道——今天用这家、明天换那家，Key 散落在各个文件里，改一次要翻半天。这篇就解决两件事：一是给出一个可复制的最小工程骨架，二是把模型调用统一收敛到 TaoToken 的 Key/API 通道，让base_url和api_key只在一个地方配置。

整篇按“能跟做”来写：先讲清楚 Agent 最小骨架该有哪些文件，再给依赖清单和目录结构，然后是环境变量与 TaoToken 接入配置，接着是一次从空目录到 Agent 成功返回结果的验证动作，最后是排错清单。全程用 Python + LangChain，代码可直接复制。

2. TaoToken 前置：把模型通道收敛成一个 Key

在动手写代码前，先把模型通道这件事定下来。LangChain 支持很多模型提供方，但如果你每个项目都单独配一套 Key，维护成本会很高。TaoToken 的思路是提供一个统一的 API 通道，你只需要一个 Key、一个 Base URL，就能在 LangChain 里通过 OpenAI 兼容接口调用模型。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

这里要强调一个工程习惯：模型配置只出现在一个地方。在最小骨架里，我把它放在.env加一个config/llm.py，其他地方一律从这两个地方读。这样以后换模型、换通道，只改一处。

具体来说，LangChain 里用ChatOpenAI就能对接 OpenAI 兼容的接口。你需要三个东西：Base URL、API Key、Model ID。Base URL 填 TaoToken 的 API 地址，API Key 从控制台生成，Model ID 填你要用的模型名。这三件套是后面所有配置的基础，缺一不可。

如果你还没生成 Key，可以去控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。生成后先别急着写进代码，放到.env里，.gitignore里加上.env，这是基本的安全习惯。

为什么要在 Agent 项目里先做这一步？因为 Agent 和普通 LLM 调用不同，它会多次调用模型（推理、决定调哪个工具、整合结果），如果通道不稳定或配置散乱，排错会非常痛苦。把通道收敛好，后面调试 Agent 逻辑时就能排除掉“是不是 Key 又配错了”这类干扰。

另外，LangChain 的版本迭代比较快，建议锁定版本。下面依赖清单里我会给出经过验证的版本组合，避免你装到最新版后 API 对不上。

3. 可复制配置：依赖清单、目录结构与 settings 片段

这一节是整篇的核心，给出可以直接复制的配置。先看目录结构，这是最小骨架，不追求大而全，但每个文件都有明确职责。

my-agent/ ├── .env # 环境变量，不提交 ├── .gitignore ├── requirements.txt ├── main.py # 入口 ├── config/ │ ├── __init__.py │ └── llm.py # 模型配置，唯一读 Key 的地方 ├── tools/ │ ├── __init__.py │ └── order_api.py # 示例工具 └── agent/ ├── __init__.py └── builder.py # 组装 Agent

依赖清单requirements.txt：

langchain==0.3.7 langchain-core==0.3.15 langchain-openai==0.2.8 python-dotenv==1.0.1 pydantic==2.9.2

这里用langchain-openai是因为 TaoToken 提供 OpenAI 兼容接口，用这个包最省事。版本锁定是为了避免langchain-core升级导致的接口变动。

.env文件内容：

TAOTOKEN_API_KEY=你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=你的模型ID

注意 Base URL 这里不加 UTM，保持干净。.gitignore至少包含：

.env __pycache__/ *.pyc .venv/

config/llm.py是唯一读取 Key 的地方：

import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() def get_llm(temperature: float = 0.0) -> ChatOpenAI: api_key = os.getenv("TAOTOKEN_API_KEY") base_url = os.getenv("TAOTOKEN_BASE_URL") model_id = os.getenv("TAOTOKEN_MODEL_ID") if not api_key or not base_url or not model_id: raise ValueError("缺少 TAOTOKEN_API_KEY / TAOTOKEN_BASE_URL / TAOTOKEN_MODEL_ID") return ChatOpenAI( api_key=api_key, base_url=base_url, model=model_id, temperature=temperature, )

这段代码就是“三件套”的落地：Base URL、Key、Model ID 全部从环境变量读，其他地方调用get_llm()即可。如果你用 Cline MCP 或 Claude Code 这类工具，配置逻辑是一样的，都是填 Base URL + Key + Model ID，只是配置文件位置不同。

tools/order_api.py给一个示例工具，用@tool装饰器：

from langchain_core.tools import tool @tool def query_order(order_id: str) -> dict: """根据订单号查询订单状态。参数 order_id 为订单编号字符串。""" mock_db = { "ORD-1001": {"order_id": "ORD-1001", "status": "delivered", "amount": 299.99}, "ORD-1002": {"order_id": "ORD-1002", "status": "refunded", "amount": 159.50}, } if order_id in mock_db: return mock_db[order_id] return {"error": f"订单 {order_id} 不存在"}

agent/builder.py组装 Agent：

from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from config.llm import get_llm from tools.order_api import query_order def build_agent() -> AgentExecutor: llm = get_llm() tools = [query_order] prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个订单助手，根据用户问题调用工具查询订单。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) return AgentExecutor(agent=agent, tools=tools, verbose=True)

main.py入口：

from agent.builder import build_agent def main(): executor = build_agent() result = executor.invoke({"input": "帮我查一下订单 ORD-1001 的状态"}) print(result["output"]) if __name__ == "__main__": main()

到这里，配置部分就齐了。你可以直接复制这些文件，把.env里的三个值换成自己的，就能进入下一步验证。

4. 验证请求：从空目录到 Agent 成功返回结果

配置写完后，最关键的是验证。很多人配置写完不敢跑，或者跑出报错不知道从哪查。这一节给出完整的验证动作，从建目录到看到结果。

第一步，建目录并进入：

mkdir my-agent && cd my-agent python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate

第二步，把上面的requirements.txt、.env、.gitignore和各个.py文件按目录结构创建好。注意config/、tools/、agent/下都要有__init__.py，空文件即可。

第三步，安装依赖：

pip install -r requirements.txt

第四步，先单独验证模型通道是否通。写一个临时脚本check_llm.py：

from config.llm import get_llm llm = get_llm() resp = llm.invoke("回复两个字：收到") print(resp.content)

运行：

python check_llm.py

如果输出类似“收到”，说明 Base URL、Key、Model ID 三件套配置正确，模型通道通了。这一步很重要，它把“模型通道问题”和“Agent 逻辑问题”隔离开。如果这一步就报错，直接看第 5 节的排错清单。

第五步，运行 Agent：

python main.py

预期输出会先打印 Agent 的思考过程（因为verbose=True），包括它决定调用query_order工具、传入ORD-1001、拿到结果、再整合成自然语言。最后一行是类似：

订单 ORD-1001 的状态是已送达（delivered），金额 299.99 元。

看到这个结果，说明从空目录到 Agent 成功返回结果的链路全部打通：环境变量读取正常、模型通道正常、工具调用正常、Agent 编排正常。

如果你想验证工具的错误分支，把main.py里的订单号改成ORD-9999，再跑一次。预期 Agent 会调用工具、拿到error字段、然后回复“订单不存在，请核实订单号”。这一步能验证 Agent 对工具返回错误的处理能力，也是最小骨架里很关键的一环。

验证通过后，你可以把check_llm.py删掉，或者保留作为日常自检脚本。我建议保留，因为以后换 Key、换模型时，先跑它比直接跑 Agent 更快定位问题。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来写，都是我在搭这类骨架时踩过的坑。每条给出报错特征、原因、解决动作。

401 Unauthorized。报错通常长这样：openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key'}}。原因基本是 Key 不对：要么.env里 Key 写错，要么load_dotenv()没生效，要么 Key 前后有空格。解决动作：先确认.env和config/llm.py在同一工作目录下能被找到；然后在get_llm()里临时打印api_key[:6]看前几位对不对；最后去控制台重新生成一个 Key 替换。注意不要把 Key 硬编码进代码。

local proxy failed。报错类似APIConnectionError: Connection error或local proxy failed。这类通常是网络层问题，不是 Key 问题。先确认TAOTOKEN_BASE_URL填的是https://taotoken.net/api，没有多余斜杠或路径。然后用curl直接测：

curl -X POST https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer 你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"你的模型ID","messages":[{"role":"user","content":"hi"}]}'

如果 curl 通而 Python 不通，多半是环境变量没读到或虚拟环境问题。如果 curl 也不通，检查本机网络和 DNS。

reading choices 相关报错。典型是KeyError: 'choices'或TypeError: 'NoneType' object is not subscriptable，出现在解析响应时。原因是返回结构不是预期的 OpenAI 格式，常见于 Base URL 填错、把非兼容接口当兼容接口用，或者 Model ID 填了一个不存在的模型导致返回错误体。解决动作：先用上面的 curl 看原始返回，确认有choices字段；再检查 Model ID 是否拼写正确；确认 Base URL 指向的是兼容接口。

OAuth 相关报错。如果你用 Claude Code 或某些 CLI 工具，可能遇到OAuth token expired或要求登录。这类工具如果支持自定义 Base URL + Key，就切到 Key 模式，不要走 OAuth。配置时确保三件套齐全：Base URL、Key、Model ID。如果工具只认 OAuth，那它不适合这种统一 Key 的用法，换用 LangChain 直接调更省心。

Agent 不调用工具。报错不明显，但结果是 Agent 直接编答案。原因通常是工具的 docstring 写得太模糊，模型不知道什么时候调。解决动作：把@tool函数的 docstring 写清楚，说明参数含义和返回内容；create_tool_calling_agent要求模型支持 tool calling，确认你选的 Model ID 支持。

verbose 输出里 agent_scratchpad 报错。常见于 prompt 里{agent_scratchpad}占位符没加，或者加了但类型不对。解决动作：确认ChatPromptTemplate里有("placeholder", "{agent_scratchpad}")，且用的是create_tool_calling_agent而不是旧版create_react_agent。

排错的核心思路是分层：先验模型通道（check_llm.py），再验工具（单独调query_order），最后验 Agent 编排。哪层报错就查哪层，不要一上来就怀疑 Agent 逻辑。

6. 语义一致 CTA：把骨架跑通后往哪走

骨架跑通后，下一步通常是两件事：一是把模型通道用得更顺，二是把 Agent 用到真实编码或业务流程里。

如果你在排错或接入阶段，需要先确认 Key 和文档，可以去 API Keys 页面生成和管理 Key：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，接入文档在：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。这两个是排错时最常回看的地方。

如果你想先验证模型本身的表现，比如换个 Model ID 看效果，可以直接在模型对话里试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。这样不用改代码就能对比不同模型。

如果你打算把 Agent 长期用在编码或自动化任务上，比如接 Claude Code 或做持续性的 Agent 工作流，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。它更适合长期编码场景，和这篇的最小骨架是互补的。

最后给一个实用建议：把这篇的骨架当成模板，每做一个新 Agent 就复制一份，只改tools/和agent/builder.py里的 prompt。模型通道那部分永远不动，这样你的项目会越搭越快，排错范围也越来越小。