企业官网建设流程全解析

1. 先把“三角关系”摆正：Skills、MCP、LangGraph 到底谁管什么

如果你最近在折腾 Agent，大概率会被三个词反复轰炸：Agent Skills、MCP、LangGraph。我一开始也犯迷糊，觉得它们功能重叠——LangGraph 不是能直接 bind_tools 吗，为什么还要 MCP？Skills 不就是写个 Python 函数，凭什么单独拎出来讲？

后来把一条完整链路跑通才明白，这三者压根不在一个层面上打架，它们是纵向分层的。你可以把一次 Agent 任务想象成点外卖：Skills 是后厨真正会做的菜（具体能力），MCP 是统一的餐盒和菜单标准（接口协议），LangGraph 是那个决定“先做汤还是先炒菜、咸了要不要重做”的调度经理（编排大脑）。缺了谁，链路都跑不顺。

这篇不讲空概念，直接交付一条能本地跑通的最小 Agent 链路：用 MCP 把工具标准化，用 LangGraph 做图编排，用 TaoToken 统一 Key 通道解决模型调用入口分散的问题。跑完之后你能亲眼看到调用顺序和数据流向，而不是停留在“连上就能用”的想象里。

适合谁看：已经会写 Python 函数、想让 AI 真正调用自己脚本的开发者；被多个模型 Key 管理搞烦、想统一入口的人；以及想搞懂 MCP 和 LangGraph 到底怎么配合的 Agent 初学者。核心检索词就三个：Agent Skills、MCP、LangGraph，外加一个统一 Key 通道的落地方式。

先说结论，避免你走弯路：Skills 解决“能不能做”，MCP 解决“好不好接”，LangGraph 解决“怎么编排”，TaoToken 解决“模型入口统一”。四者各司其职，串起来才是一个能上生产的 Agent 骨架。下面按这个顺序，一层层把配置和验证动作铺开。

2. TaoToken 统一 Key 通道前置准备：一个入口管住所有模型调用

在讲 MCP 和 LangGraph 之前，得先把模型调用这条线理顺。因为无论你的图怎么编排、工具怎么封装，最后都要落到“调哪个模型、用哪个 Key、走哪个 Base URL”上。如果每个组件各自配一套 Key，调试时会非常痛苦——LangGraph 里报 401，你都不知道是哪个环节的凭证失效了。

TaoToken 在这里扮演的角色就是统一 Key 通道：一个 API Key，一个 Base URL，兼容主流模型调用格式。你不需要在 LangGraph、MCP Server、本地脚本里各维护一份凭证，全部指向同一个入口即可。

前置准备分三步，都是可复制的动作。

第一步，拿到 Key。访问控制台创建 API Key，地址是https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=agent_arch_guide&utm_campaign=rewrite。创建后立刻复制保存，页面刷新后不再完整显示。

第二步，确认 Base URL。统一入口是https://taotoken.net/api，注意这个地址不加任何 UTM 参数，直接作为 OpenAI 兼容的 base_url 使用。很多 SDK 会在 base_url 后面自动拼/v1/chat/completions，所以填的时候不要自己多加/v1，否则会变成双斜杠路径导致 404。

第三步，确认 Model ID。不同模型对应不同 ID，比如常见的对话模型、编码模型各有标识。你可以在模型对话页面试跑确认，地址是https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=agent_arch_guide&utm_campaign=rewrite。选一个你打算在 Agent 里用的模型，记下它的 ID。

把这三样东西整理成一个环境变量文件，后面所有组件都从这里读，避免硬编码散落各处：

# .env 文件，放在项目根目录 TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=你的模型ID

注意：.env一定要加进.gitignore。我见过有人把 Key 直接写进代码提交到仓库，结果被扫描到滥用，这个坑别踩。

装依赖的时候，Python 侧建议用虚拟环境隔离：

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install langgraph langchain-openai mcp python-dotenv

这里langchain-openai是用来对接 OpenAI 兼容接口的，TaoToken 的 Base URL 正好走这个协议，所以直接复用即可。mcp是官方 SDK，用来写 MCP Server。langgraph负责图编排。装完可以用pip list确认版本，避免新旧版本 API 差异导致后面报错。

前置准备到这就够了。核心就一句话：所有模型调用都走 TaoToken 这一个入口，Key、Base URL、Model ID 三件套配齐，后面 MCP 和 LangGraph 都复用这套配置。这样调试时只要模型调用出问题，排查范围就收敛到一个地方。

3. 可复制配置：MCP Server 封装 Skill + LangGraph 接入

这一节是全文的技术核心，我会把 Skills、MCP、LangGraph 三者的配置片段完整写出来，你直接复制改改就能跑。先明确数据流向：LangGraph 节点决定调用哪个工具 → 通过 MCP 客户端请求 MCP Server → MCP Server 执行对应的 Skill 函数 → 结果原路返回给图节点 → 图节点把结果交给模型生成回复。

3.1 用 MCP 把 Skill 封装成标准工具

先写一个最朴素的 Skill——查天气。它本身只是个普通函数，AI 看不懂。用 MCP 的装饰器包一层，它就变成了任何支持 MCP 的客户端都能识别的工具。

# mcp_server.py from mcp.server.fastmcp import FastMCP mcp = FastMCP("My Agent Tools") @mcp.tool() def get_weather(city: str) -> str: """查询指定城市的天气情况。 Args: city: 城市名称，例如"北京"、"上海" """ # 这里用假数据演示，实际可替换为真实 API 调用 fake_data = { "北京": "晴，18°C", "上海": "多云，22°C", "广州": "小雨，26°C", } return fake_data.get(city, f"{city}：暂无数据") @mcp.tool() def calculate(expression: str) -> str: """计算一个数学表达式，例如 '2 + 3 * 4'。 Args: expression: 合法的 Python 数学表达式字符串 """ try: result = eval(expression, {"__builtins__": {}}, {}) return f"计算结果：{result}" except Exception as e: return f"计算失败：{e}" if __name__ == "__main__": mcp.run(transport="stdio")

注意@mcp.tool()装饰器下面的 docstring 非常关键——它就是给模型看的工具说明书。模型靠这段文字判断“什么时候该调用这个工具”。所以描述要写清楚用途和参数含义，别偷懒写个“查询”两个字就完事。

启动这个 Server：

python mcp_server.py

它默认走 stdio 传输，也就是通过标准输入输出和客户端通信。这种方式适合本地进程间调用，不需要开端口，安全性也好。

3.2 LangGraph 接入 MCP 工具并编排

接下来是 LangGraph 的部分。它要做两件事：一是通过 MCP 客户端把上面的工具加载进来，二是用图结构决定“先思考、再调工具、再生成回复”的流程。

# agent_graph.py import os import asyncio from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_core.tools import StructuredTool from typing import TypedDict, Annotated import operator load_dotenv() # 1. 统一模型入口，全部走 TaoToken llm = ChatOpenAI( model=os.getenv("TAOTOKEN_MODEL_ID"), api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), temperature=0, ) # 2. 通过 MCP 客户端加载工具 async def load_mcp_tools(): server_params = StdioServerParameters( command="python", args=["mcp_server.py"], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools_response = await session.list_tools() langchain_tools = [] for tool in tools_response.tools: async def _run(_tool_name=tool.name, **kwargs): result = await session.call_tool(_tool_name, kwargs) return result.content[0].text langchain_tools.append( StructuredTool.from_function( coroutine=_run, name=tool.name, description=tool.description, ) ) return langchain_tools # 3. 定义图状态 class AgentState(TypedDict): messages: Annotated[list, operator.add] # 4. 构建图 async def build_graph(): tools = await load_mcp_tools() llm_with_tools = llm.bind_tools(tools) def agent_node(state: AgentState): response = llm_with_tools.invoke(state["messages"]) return {"messages": [response]} def should_continue(state: AgentState): last = state["messages"][-1] if hasattr(last, "tool_calls") and last.tool_calls: return "tools" return END graph = StateGraph(AgentState) graph.add_node("agent", agent_node) graph.add_node("tools", ToolNode(tools)) graph.set_entry_point("agent") graph.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END}) graph.add_edge("tools", "agent") return graph.compile() if __name__ == "__main__": from langchain_core.messages import HumanMessage graph = asyncio.run(build_graph()) result = graph.invoke({"messages": [HumanMessage(content="北京天气怎么样？顺便算一下 12*8")]}) for msg in result["messages"]: print(msg.content)

这段代码里有几个关键点值得单独说。

ChatOpenAI的base_url直接指向 TaoToken 的 API 地址，api_key和model都从环境变量读。这样 LangGraph 里所有模型调用都走统一通道，不需要为每个节点单独配凭证。

load_mcp_tools通过 stdio 启动 MCP Server 子进程，列出工具后包装成 LangChain 的StructuredTool。这一步就是“MCP 标准化”的价值——LangGraph 不需要知道工具内部怎么实现，只要按 MCP 协议拿到工具列表和描述就能用。

should_continue是图编排的灵魂。它检查模型最后一条消息里有没有tool_calls：有就去tools节点执行，没有就结束。这就是 LangGraph 相比线性链的优势——它能根据模型输出动态决定下一步走向，而不是写死流程。

3.3 配置片段汇总（JSON 形式）

如果你用的是支持 JSON 配置的客户端（比如某些 MCP 客户端或编辑器插件），可以把 MCP Server 的配置写成这样：

{ "mcpServers": { "my-agent-tools": { "command": "python", "args": ["mcp_server.py"], "env": { "TAOTOKEN_API_KEY": "sk-你的实际Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_MODEL_ID": "你的模型ID" } } } }

这份配置里，command和args决定怎么启动 MCP Server，env把统一 Key 通道的凭证注入进去。Base URL、Key、Model ID 三件套在这里必须齐全，缺任何一个，Server 内部如果也要调模型就会失败。

到这里，Skills（工具函数）、MCP（标准化封装）、LangGraph（图编排）、TaoToken（统一模型入口）四者的配置就串起来了。下一节验证它到底跑不跑得通。

4. 验证请求与成功结果：看调用顺序和数据流向

配置写完不验证，等于没写。这一节我们实际跑一遍，重点观察三件事：模型有没有正确识别工具、MCP 有没有被调用、LangGraph 的循环有没有按预期走。

先启动验证脚本：

python agent_graph.py

如果一切正常，你会看到类似这样的输出（内容因模型而异，但结构一致）：

我需要先查询北京天气，然后计算 12*8。 [工具调用] get_weather(city="北京") [工具返回] 北京：晴，18°C [工具调用] calculate(expression="12*8") [工具返回] 计算结果：96 北京今天晴，气温 18°C。另外 12*8 的结果是 96。

这个输出揭示了完整的数据流向，我拆开讲。

第一轮，agent节点收到用户消息“北京天气怎么样？顺便算一下 12*8”，模型判断需要调用工具，于是返回带tool_calls的消息。should_continue检测到工具调用，把流程导向tools节点。

tools节点（ToolNode）执行 MCP 工具。注意这里实际是 LangGraph 通过我们包装的StructuredTool去调用 MCP Server 的call_tool，MCP Server 再执行对应的 Skill 函数。这就是 MCP 的价值：LangGraph 不直接碰 Skill 代码，中间隔了一层标准协议。

工具结果返回后，add_edge("tools", "agent")把流程送回agent节点。模型拿到工具结果，生成最终自然语言回复。此时should_continue发现没有新的tool_calls，返回END，图结束。

如果你想更直观地确认 MCP 这一层真的被调用了，可以在mcp_server.py的每个工具函数里加一行日志：

@mcp.tool() def get_weather(city: str) -> str: """查询指定城市的天气情况。""" print(f"[MCP Server] get_weather 被调用，参数 city={city}", flush=True) ...

重新跑一遍，你会在终端看到[MCP Server]开头的日志。这行日志出现在输出里，就证明调用链路是 LangGraph → MCP Client → MCP Server → Skill 函数，而不是 LangGraph 直接执行了本地函数。这个区分很重要，很多人以为自己接了 MCP，其实只是本地 bind_tools，根本没走协议层。

再验证一个边界情况：问一个不需要工具的问题，比如“你好，介绍一下你自己”。预期结果是模型直接回复，不触发任何工具调用，图走agent → END这条最短路径。如果它还是去调工具了，说明工具描述写得太宽泛，模型误判了。

还有一个值得观察的点：多轮工具调用的循环。你可以问“北京和上海天气分别怎么样”，模型可能会连续调用两次get_weather，或者一次调用带两个参数（取决于工具定义）。无论哪种，你都能在日志里看到agent → tools → agent → tools → agent → END的完整循环。这正是 LangGraph 相比线性链的核心能力——它支持任意轮次的“思考-行动-观察”循环，直到模型认为任务完成。

验证通过的标准很简单：工具被正确调用、结果被正确回填、最终回复符合预期、日志证明走了 MCP 协议层。四条都满足，说明你的最小 Agent 链路是通的。

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

跑不通是常态，我把几个高频报错和对应排查动作列出来，你对照着看。

报错一：401 Unauthorized

这是最常见的。原因通常是 Key 没读到或读错了。排查顺序：先确认.env文件在项目根目录且load_dotenv()在读取环境变量之前调用；再确认TAOTOKEN_API_KEY的值没有多余空格或引号；最后确认你用的 Key 是在控制台新建的、没有过期。如果 Key 是对的还报 401，检查base_url是不是写成了https://taotoken.net/api/（末尾多了斜杠），有些 SDK 拼接路径时会因此出错。

报错二：local proxy failed / connection refused

这个报错通常出现在 MCP Server 启动环节。如果你用的是 stdio 传输，检查StdioServerParameters里的command和args是否正确——command="python"要求当前虚拟环境里有 python，args=["mcp_server.py"]要求文件路径相对于运行目录正确。如果 MCP Server 启动就崩了，客户端会报连接失败。单独跑一次python mcp_server.py，看它能不能正常启动不报错，这是最快的定位方式。

报错三：reading choices / 'choices' key error

这个报错说明模型返回的响应结构不符合预期。常见原因是base_url配错了，请求打到了非 OpenAI 兼容的端点，返回了完全不同的 JSON 结构。确认base_url是https://taotoken.net/api，且你用的 SDK 是 OpenAI 兼容的。另外检查model参数填的是不是有效的 Model ID，填错模型名有时也会返回异常结构。

报错四：OAuth / authentication failed

如果你在某个客户端里配置 MCP 时遇到 OAuth 相关报错，通常是因为该客户端默认走 OAuth 流程，而你的 MCP Server 是本地 stdio 模式，不需要 OAuth。检查客户端的 MCP 配置，确认command和args写对了，不要勾选需要 OAuth 的选项。本地 stdio 模式的 MCP Server 靠进程间通信，不涉及网络认证。

报错五：工具被调用但返回空 / 参数错误

如果日志显示工具被调用了，但返回结果为空或参数不对，问题多半在工具函数的 docstring 上。模型靠 docstring 理解参数含义，如果参数描述模糊，模型可能传错类型或漏传参数。把 docstring 写清楚，参数名和类型标注对齐，能解决大部分参数问题。

排查的通用思路是分层定位：先确认模型调用通不通（单独跑一个最简单的 chat 请求），再确认 MCP Server 能不能独立启动，最后确认 LangGraph 的图逻辑对不对。一层层排除，比一上来就盯着完整链路猜要快得多。

如果你在接入文档里找不到对应说明，可以查接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=agent_arch_guide&utm_campaign=rewrite，里面有 Base URL、鉴权方式、常见错误码的说明。

6. 把这条链路用起来：从最小示例到长期编码 Agent

跑通最小示例只是起点。真正有价值的是把这条链路用到日常开发里——比如让 Agent 帮你查数据库、跑运维脚本、调内部 API。这时候 Skills 的沉淀就很重要：把你手头好用的脚本整理成一个个 MCP 工具，一次封装，LangGraph、编辑器、其他 MCP 客户端都能复用。

如果你打算长期跑编码类 Agent，或者需要多步推理、容错、人机交互的复杂流程，可以考虑 Coding Plan 这类长期方案，地址是https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=agent_arch_guide&utm_campaign=rewrite。它适合需要稳定模型通道、频繁调用、不想每次手动管 Key 的场景。

想先验证模型效果再决定用哪个，可以去模型对话页面直接试：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=agent_arch_guide&utm_campaign=rewrite。选好模型后把 Model ID 填回你的.env，整条链路就切换过去了，不需要改任何代码逻辑——这就是统一 Key 通道的好处。

最后给一个实用建议：先把一个 Skill 跑通，再扩展。很多人一上来就想封装十几个工具，结果调试时根本分不清是哪个环节出错。先用一个get_weather把 LangGraph → MCP → Skill → 模型 这条链路验证透，确认调用顺序和数据流向都符合预期，再往上加工具。这样每加一个工具，你都能快速定位问题出在哪一层。

链路跑通之后，你会发现 Agent 架构没那么神秘：Skills 是弹药，MCP 是弹匣，LangGraph 是火控系统，TaoToken 是统一的供弹通道。四者各就各位，剩下的就是往弹匣里装什么子弹的问题了。