+Agent+MCP工具全解析｜TaoToken统一Key接入指南)
1. 从一次 RAG 问答翻车说起检索生成链路到底卡在哪如果你正在用 LangChain 搭 RAG 问答大概率遇到过这种场景向量库检索出来的片段明明是对的但大模型回答时开始自由发挥甚至编造出上下文里根本没有的条款。我试过把 temperature 调到 0.1、把提示词写死只根据上下文回答效果依然不稳定。排查一圈才发现问题往往不在检索也不在提示词而在模型调用这一层——Base URL 指向的通道不稳定、Key 额度被限流、不同模型适配器各写一套环境变量导致你以为在调 GPT-4o实际请求早就超时降级了。检索增强生成RAG解决的是大模型知识过时和幻觉问题Agent 智能体解决的是只会说不会做的问题MCP 工具协议解决的是工具跨平台复用的问题。这三件事单独看都不难难的是把它们串成一条能稳定跑起来的工程链路。而这条链路的底座是模型调用通道。本文聚焦 LangChain RAG Agent MCP 工具链的工程化落地用 TaoToken 统一 Key 和 API 通道打通模型调用环节交付可复制的环境变量与 Base URL 配置片段、MCP 工具注册示例以及一次端到端 RAG 问答的验证动作与预期输出。适合谁看已经跑通过 LangChain 基础 Demo、想把手上的 RAG 原型往生产环境推一步的开发者正在纠结 Agent 工具怎么封装、MCP 怎么接进 LangChain 的同学以及被多套 API Key 管理折磨过、想统一模型入口的人。全文代码可直接运行配置片段可直接复制验证步骤有明确的预期输出。先说清楚本文的技术栈边界向量检索用 Milvus 的 HNSW 近似搜索嵌入模型用 bge-base-zh-v1.5生成层用 LangChain 的 init_chat_model 统一接口Agent 用 create_agent 构建工具层同时演示本地 tool 封装和 MCP 协议工具集成记忆用 LangGraph 的 Checkpointer。模型调用全部走 TaoToken 的 OpenAI 兼容通道这样无论底层换哪个模型代码里的 base_url 和 api_key 都不用动。2. TaoToken 前置准备统一 Key 与 Base URL 配置在写任何 LangChain 代码之前先把模型调用通道固定下来。这一步做扎实后面 RAG、Agent、MCP 三条链路才能共用同一套凭证不用每换一个模型就改一遍代码。TaoToken 提供的是 OpenAI 兼容的 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。注意这个 /api 后缀很多同学第一次配的时候只填了域名结果 LangChain 报 404后面排障章节会专门讲这个坑。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面新建一个 Key复制出来先存到安全的地方。这个 Key 就是后面所有代码里 OPENAI_API_KEY 的值。如果你还没决定用哪个模型可以先在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几条 prompt确认通道通畅再进代码环节。第二步把凭证写进环境变量。LangChain 的 init_chat_model 和 OpenAI SDK 都认 OPENAI_API_KEY 和 OPENAI_BASE_URL 这两个标准变量所以最省事的做法是在项目根目录建一个 .env 文件# .env OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api这里有个细节OPENAI_BASE_URL 结尾不要带斜杠也不要带 /v1。LangChain 的 OpenAI 适配器会自动拼接 /chat/completions如果你写成 https://taotoken.net/api/v1最终请求路径会变成 /api/v1/chat/completions虽然部分兼容层能处理但为了统一建议就写 https://taotoken.net/api 。第三步安装依赖。RAG 链路需要向量库和嵌入模型Agent 链路需要 LangChain 的 agent 模块MCP 链路需要适配器pip install python-dotenv langchain langchain-openai langchain-huggingface pymilvus langchain-tavily langchain-mcp-adapters mcp如果你打算用 Coding Plan 做长期编码和 Agent 开发可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合需要持续调用、多项目并行的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数细节可以对照查。第四步验证通道。写一个最小脚本确认 Key 和 Base URL 能通from dotenv import load_dotenv import os from langchain.chat_models import init_chat_model load_dotenv() llm init_chat_model( modelgpt-4o-mini, model_provideropenai, base_urlos.getenv(OPENAI_BASE_URL), api_keyos.getenv(OPENAI_API_KEY), temperature0.1, ) res llm.invoke(用一句话说明什么是RAG) print(res.content)预期输出是一句关于检索增强生成的解释。如果这一步报 401说明 Key 没读到或者复制时带了空格如果报连接超时检查 Base URL 是否写成了 https://taotoken.net/api 。这一步通了后面的 RAG 和 Agent 才有意义。3. 可复制配置RAG 检索生成 Agent MCP 工具链这一节是全文的核心把三条链路的配置片段一次性给全。所有片段都基于上一节的环境变量路径和原文保持一致你可以直接复制到项目里改。3.1 RAG 检索生成配置先建向量集合。Milvus 本地部署默认端口 19530用 MilvusClient 连接from pymilvus import MilvusClient from langchain_huggingface.embeddings import HuggingFaceEmbeddings client MilvusClient(urihttp://127.0.0.1:19530, db_namedefault) embed_model HuggingFaceEmbeddings( model_namer.\assets\models\bge-base-zh-v1.5 ) query 不动产被占有了怎么办 query_vector embed_model.embed_query(query) res client.search( collection_namedemo_collection, data[query_vector], limit3, output_fields[text, metadata], ) context \n.join([data[entity][text] for data in res[0]])检索到上下文后构建消息列表并调用模型。这里的关键是系统提示词要约束模型严格基于上下文回答message_list [ { role: system, content: 你是一个专业的法律问答机器人请严格根据提供的上下文回答问题当上下文无法回答问题时直接回答“根据上下文无法回答该问题” }, { role: user, content: f根据以下上下文回答问题\n{context}\n\n问题{query} } ] llm init_chat_model( model_namegpt-4o-mini, base_urlos.getenv(OPENAI_BASE_URL), api_keyos.getenv(OPENAI_API_KEY), temperature0.1, ) res llm.invoke(message_list) print(res.content)3.2 Agent 本地工具配置Agent 的核心是大模型做决策工具做执行。用 tool 装饰器把普通函数转成标准工具from langchain.tools import tool from pydantic import BaseModel, Field class AddNumberParams(BaseModel): a: int Field(description需要相加的第一个整数) b: int Field(description需要相加的第二个整数) tool( name_or_callablecalc_two_int_sum, description用于计算两个整数的和输入为两个整数输出为求和结果, args_schemaAddNumberParams ) def add_number(a: int, b: int) - int: return a b然后创建 Agent把工具列表传进去from langchain.agents import create_agent from langchain_tavily import TavilySearch tavily_search TavilySearch( tavily_api_keyos.getenv(TAVILY_API_KEY), max_results5 ) tools [add_number, tavily_search] llm init_chat_model( modelgpt-4o-mini, model_provideropenai, base_urlos.getenv(OPENAI_BASE_URL), api_keyos.getenv(OPENAI_API_KEY), temperature0.1 ) agent create_agent( modelllm, toolstools, system_prompt你是一个全能助手会根据用户问题选择合适的工具计算问题调用add_number信息查询问题调用TavilySearch无需工具时直接回答 )3.3 MCP 工具注册配置MCP 工具通过 langchain_mcp_adapters 接入配置用 JSON 结构描述传输方式和地址from langchain_mcp_adapters.client import MultiServerMCPClient mcp_client MultiServerMCPClient( { 12306-mcp: { transport: streamable_http, url: https://mcp.api-inference.modelscope.net/c30f9b25034446/mcp } } ) mcp_tools await mcp_client.get_tools() agent create_agent(llm, mcp_tools)如果你要自己搭 MCP 服务器Stdio 模式的启动配置是from mcp.server.fastmcp import FastMCP mcp FastMCP(DemoMCP-Stdio) mcp.tool() def add(a: int, b: int) - int: 两个整数相加 return a b if __name__ __main__: mcp.run(transportstdio)Streamable HTTP 模式只需改传输参数if __name__ __main__: mcp.run(transportstreamable-http, host0.0.0.0, port8000)3.4 Agent 记忆配置记忆功能靠 Checkpointer 实现开发阶段用 InMemorySaver生产环境换 RedisSaverfrom langgraph.checkpoint.memory import InMemorySaver checkpointer InMemorySaver() agent create_agent( modelllm, toolstools, checkpointercheckpointer, system_prompt你是一个智能搜索助手按需调用搜索工具记住用户之前的问题 ) THREAD_ID session_001 resp agent.invoke( input{messages: [{role: user, content: 2026年杭州亚运会的举办时间是什么时候}]}, config{configurable: {thread_id: THREAD_ID}} )三件套对照表方便你检查配置是否齐全组件Base URLKeyModel IDRAG 生成https://taotoken.net/apiOPENAI_API_KEYgpt-4o-miniAgent 推理https://taotoken.net/apiOPENAI_API_KEYgpt-4o-miniMCP 工具由 MCP Server 地址决定由 MCP Server 决定不涉及4. 验证请求一次端到端 RAG 问答的预期输出配置写完必须跑一次完整链路确认。这一节给出验证动作和每一步的预期输出你对照着看就知道哪一环断了。验证一模型通道。运行第 2 节的最小脚本预期输出一句关于 RAG 的解释。如果返回空字符串检查 model 名称是否拼错如果报 401检查 .env 是否被 load_dotenv 正确加载。验证二向量检索。运行 3.1 的检索片段预期输出三条相似结果每条包含 distance、text、metadata【相似结果1】 相似度0.8231 文本内容不动产被他人占有的权利人可以请求返还原物... 元数据{source: law_doc_001}如果 distance 全是 0 或者结果明显不相关说明嵌入模型和入库时的模型不一致检查 bge-base-zh-v1.5 的路径是否指向同一个模型。验证三RAG 生成。把检索结果拼成 context 后调用模型预期输出一段严格基于上下文的回答。如果模型开始编造说明系统提示词没生效检查 message_list 里 system 角色是否放在第一位。验证四Agent 工具调用。运行 3.2 的 Agent输入计算100200的结果预期输出 300并且中间能看到工具调用记录。输入2026年北京冬奥会的比赛项目有哪些预期触发 TavilySearch 并返回搜索结果摘要。验证五MCP 工具。运行 3.3 的 MCP Agent输入帮我查一下明天北京到上海的高铁预期 Agent 调用 12306 MCP 工具并返回车次信息。如果报连接错误检查 MCP Server 地址是否可访问。验证六记忆功能。运行 3.4 的代码第一次问2026年杭州亚运会的举办时间第二次问这个赛事的主体育场是什么预期第二次回答能关联到第一次的问题。第三次问我刚才问了你什么问题预期返回历史问题。流式调用验证Agent 处理多步任务时用 stream 看中间进度for chunk in agent.stream( { messages: [ {role: system, content: 你是一个全能助手按需调用工具}, {role: user, content: 计算999888的结果再查一下这个结果的相关数学知识} ] } ): print(chunk, end\n\n)预期能看到工具调用、工具返回、最终回答分块输出。如果 stream 一直卡住不返回检查模型通道是否支持流式TaoToken 的 OpenAI 兼容通道默认支持。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个错误给出原因和修复动作。401 Unauthorized。最常见的原因是 Key 没读到。检查三处.env 文件是否在项目根目录、load_dotenv() 是否在读取环境变量之前调用、Key 复制时是否带了首尾空格。还有一种情况是 Key 被禁用或额度耗尽去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 确认 Key 状态。local proxy failed / Connection error。这个报错通常出现在 Base URL 配置错误时。如果你把 OPENAI_BASE_URL 写成了 https://taotoken.net 而漏了 /apiLangChain 会请求 https://taotoken.net/chat/completions返回 404 或连接失败。正确写法是 https://taotoken.net/api 。另外检查本地网络是否能访问该地址公司内网可能需要配置出口。Error reading choices / KeyError: choices。这个报错说明返回的 JSON 结构里没有 choices 字段通常是模型名称写错了。比如你写了 modelgpt-4o 但通道里没有这个模型返回的可能是错误信息而不是标准响应。检查 model 名称是否在 TaoToken 支持的模型列表里可以先用模型对话页面确认。OAuth / authentication_error。如果你用的是 Claude Code 或 Codex 这类工具报 OAuth 错误说明认证方式不对。这类工具需要配置 Base URL Key Model ID 三件套。以 Codex 的 auth.json 为例{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }Claude Code 的配置在 settings.json 里同样需要填全 Base URL、Key、Model ID。如果只填了 Key 没填 Base URL工具会默认走官方通道导致认证失败。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各工具的完整配置示例。MCP 工具加载为空。mcp_client.get_tools() 返回空列表检查 MCP Server 地址是否可访问、transport 类型是否匹配。Streamable HTTP 用 streamable_httpStdio 用 stdio。如果 MCP Server 需要认证还要在配置里加 headers。Agent 不调用工具。模型直接回答而不调工具通常是 system_prompt 没写清楚工具用途。把每个工具什么时候用写进提示词比如计算问题调用 add_number信息查询调用 TavilySearch。另外检查工具描述是否准确模型是根据 description 判断是否调用的。记忆不生效。多轮对话没有上下文检查 invoke 时是否传了 config{configurable: {thread_id: THREAD_ID}}以及 create_agent 时是否传了 checkpointer。两个条件缺一不可。6. 把链路跑稳之后统一 Key 的长期价值走到这里你应该已经跑通了一条完整的 LangChain RAG Agent MCP 链路。回头看最省事的决定是把模型调用统一到一套 Base URL 和 Key 上。RAG 的生成层、Agent 的推理层、MCP 工具背后的模型调用全部走同一个通道换模型时只改 model 参数不动 base_url 和 api_key。如果你打算把这条链路用到长期项目里Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 比按量调用更适合高频场景。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各语言 SDK 的配置示例遇到参数问题可以直接对照。API Keys 管理页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 可以创建多个 Key 做项目隔离避免一个 Key 被限流影响所有服务。最后留一个实用技巧把 RAG 的检索结果和 Agent 的工具调用记录都打到日志里出问题时先看检索片段是否相关、再看模型是否基于上下文回答、最后看工具调用参数是否正确。这三层日志能覆盖 90% 的 RAG Agent 故障。链路跑通只是开始把可观测性做起来才能在生产环境里睡得着觉。
