企业官网建设流程全解析

1. ADK 智能体接入本地与云端模型的真实痛点

如果你已经在用 Google 的 Agent Development Kit（ADK）搭多智能体，大概率会遇到一个很具体的麻烦：ADK 默认走 Gemini 或 Vertex AI，但你的工具链里还挂着 ollama 本地模型和一堆 MCP 服务，结果就是模型通道、工具通道、密钥管理三套东西各管各的。我试过在一个项目里同时接 ollama 的 qwen 和云端模型，光是环境变量就写了四组，切换一次要改三处配置，调试时根本分不清是模型没响应还是 MCP 工具没注册上。

ADK 本身是一套 code-first 的 Python 框架，核心能力是把智能体搭建、编排、部署、评估封装成可组合的模块。它支持多代理分层设计、LiteLLM 集成、MCP 工具接入，也能把其他代理当工具用。问题在于，官方示例大多围绕 Gemini 展开，当你想把模型请求统一到一个兼容 OpenAI 协议的通道上，同时保留 ollama 的本地推理能力，就需要一个中间层来收敛 Key 和 API 地址。

这篇面向已经跑通 MCP 与 ollama 的开发者，给出settings.json与config.toml的可复制配置骨架，演示通过 TaoToken 统一 Key/API 通道完成一次工具调用，最后用启动 ADK 后检查 MCP 工具列表与 ollama 模型是否同时可用来做验证。适合谁：手里有 ADK 项目、本地起了 ollama、MCP server 能单独跑通，但还没把三者串成一条稳定链路的同学。

2. TaoToken 前置：统一 Key 与 API 通道

TaoToken 在这里扮演的角色是模型请求的统一入口。你不需要在 ADK 里为每个模型供应商写一套适配代码，而是把 base_url 指向同一个 API 地址，用同一个 Key 去请求不同模型。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。

实际操作上，你需要先拿到 API Key。进入控制台创建密钥，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成并复制，页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。这个 Key 后面会同时写进 ADK 的模型配置和 MCP 的工具调用配置里，做到一处 Key 多处复用。

注意：不要把 Key 硬编码进agent.py提交到 GitHub，统一放.env或settings.json里，用环境变量读取。

如果你还没决定用哪个模型做主力，可以先去模型对话页面试一下响应速度和工具调用表现，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。对于长期跑编码类 Agent 的场景，Coding Plan 会更合适，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置字段有疑问时对着查。

3. 可复制配置：settings.json 与 config.toml 骨架

ADK 项目里，模型通道和工具通道的配置通常分散在几个文件。下面给出两个骨架，一个管模型与 MCP 的运行时参数，一个管 ollama 与工具服务的本地声明。你可以直接复制后改 Key 和路径。

3.1 settings.json：模型与 MCP 统一入口

{ "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "default_model": "claude-3-5-sonnet", "fallback_model": "qwen2.5:7b" }, "mcp": { "servers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"], "env": { "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}" } }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"], "env": {} } } }, "ollama": { "base_url": "http://127.0.0.1:11434", "models": ["qwen2.5:7b", "llama3.1:8b"] } }

这里base_url指向 TaoToken 的 API 入口，api_key用环境变量占位。MCP 的filesystem和fetch两个 server 是常见组合，前者管本地文件读写，后者管网页抓取。ollama 部分单独声明本地地址和模型列表，方便 ADK 启动时探测。

3.2 config.toml：ADK 运行时与工具注册

[adk] app_name = "adk_mcp_ollama_demo" default_agent = "coordinator" [adk.model] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model_name = "claude-3-5-sonnet" [adk.tools.mcp] enabled = true config_path = "./settings.json" [adk.tools.ollama] enabled = true base_url = "http://127.0.0.1:11434" health_check = "/api/tags" [adk.logging] level = "INFO"

config.toml里把 MCP 的配置路径指向settings.json，避免重复写 server 列表。ollama 的健康检查走/api/tags，ADK 启动时会请求这个端点确认本地模型可用。

3.3 agent.py 里读取配置并注册工具

import os import json from google.adk.agents import LlmAgent from google.adk.tools.mcp_tool import MCPToolset with open("settings.json", "r", encoding="utf-8") as f: settings = json.load(f) os.environ["TAOTOKEN_API_KEY"] = os.getenv("TAOTOKEN_API_KEY", "") mcp_toolset = MCPToolset( server_params=settings["mcp"]["servers"] ) root_agent = LlmAgent( name="coordinator", model=settings["model"]["default_model"], instruction="你是一个协调代理，优先使用 MCP 工具完成文件与网络操作，本地推理走 ollama。", tools=[mcp_toolset] )

这段代码把settings.json里的 MCP server 列表直接喂给MCPToolset，模型名从配置读取。TAOTOKEN_API_KEY从环境变量注入，ADK 请求模型时会带上这个 Key 走 TaoToken 通道。

4. 验证请求：启动 ADK 并检查双通道可用

配置写完后，验证分两步：先确认 MCP 工具列表能拉出来，再确认 ollama 模型能被 ADK 识别。启动命令用 ADK 自带的 web 模式，方便直观看到工具和模型状态。

export TAOTOKEN_API_KEY="你的Key" adk web --config config.toml

启动后浏览器打开 ADK 的 Web UI，默认在http://127.0.0.1:8000。在界面里找到工具面板，应该能看到filesystem和fetch两个 MCP 工具已经注册。如果列表为空，说明settings.json里的 server 命令没跑起来，先单独在终端执行npx -y @modelcontextprotocol/server-filesystem ./workspace看是否报错。

接着验证 ollama 通道。在另一个终端执行：

curl http://127.0.0.1:11434/api/tags

返回的 JSON 里应该包含qwen2.5:7b和llama3.1:8b。然后在 ADK Web UI 里发一条测试消息，比如「列出 workspace 目录下的文件，然后用本地模型总结文件名」。观察执行轨迹：MCP 工具被调用后返回文件列表，模型侧如果走的是 ollama，响应里会带本地推理的特征。如果模型侧仍走云端，检查config.toml里model_name是否被settings.json的default_model覆盖。

一次成功的工具调用结果类似：工具面板显示filesystem.list_directory被调用，返回["README.md", "agent.py", "settings.json"]，随后模型输出一段总结。这说明 MCP 与模型通道已经串通。

5. 本篇常见错排查

5.1 MCP 工具列表为空

最常见的原因是npx或uvx不在 PATH 里。ADK 启动时用子进程拉起 MCP server，如果命令找不到，工具注册会静默失败。排查方法是在终端手动执行settings.json里写的完整命令，看是否报command not found。另一个原因是settings.json的路径写成了相对路径，而 ADK 的工作目录不是项目根目录，改成绝对路径或./开头并确认启动目录。

5.2 ollama 模型未被识别

ADK 探测 ollama 走的是config.toml里的health_check端点。如果 ollama 没启动，或者端口不是默认的11434，探测会失败。先curl http://127.0.0.1:11434/api/tags确认服务活着。如果 ollama 跑在容器里，127.0.0.1可能不通，换成宿主机的实际 IP。另外，模型名要和ollama list输出的完全一致，qwen2.5:7b和qwen2.5是两个不同的 tag。

5.3 模型请求返回 401 或 403

Key 没注入成功。检查export TAOTOKEN_API_KEY是否在当前 shell 生效，echo $TAOTOKEN_API_KEY看有没有值。如果用的是.env文件，确认 ADK 启动前加载了它，比如source .env或用了python-dotenv。还有一种情况是 Key 复制时带了空格，重新从 API Keys 页面复制一次。

5.4 工具调用超时

MCP server 启动慢，或者fetch工具请求的 URL 不可达。把config.toml的日志级别调到DEBUG，看 ADK 输出的子进程 stderr。如果是fetch超时，换一个可访问的 URL 测试。如果是filesystem超时，检查./workspace目录是否存在且有读写权限。

5.5 模型切换后配置不生效

ADK 有缓存机制，改完settings.json后需要重启adk web。另外，config.toml里的model_name和settings.json里的default_model如果同时存在，以代码里实际读取的为准。建议只保留一处模型名配置，避免两处冲突。

6. 接入文档与后续动作

配置骨架跑通后，下一步是把这套结构固化到你的 ADK 项目里。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的字段说明和示例。如果你要长期跑编码类 Agent，Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要稳定模型通道的场景。ClaudeCodeAnthropic 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite 。

实际用下来，这套配置最大的好处是把模型 Key 和 MCP 工具的环境变量收敛到一处，切换模型时只改default_model一个字段。踩过的坑是 MCP server 的启动命令一定要先在终端验证，ADK 的子进程报错不会直接弹到 Web UI 上，得看日志。最后一步验证动作别省：启动 ADK 后先看工具列表，再curl一次 ollama 的 tags 端点，两个都通了再发测试消息，能省掉大量来回排查的时间。