1. 零基础跑通 Google ADK Web 界面10 行代码到底能做什么如果你刚接触 AI Agent大概率会被 LangChain、AutoGen 这些框架的抽象层劝退光是理解 Chain、Tool、Memory 的关系就要花掉一整个周末。Google ADKAgent Development Kit走的是另一条路——它把「定义一个能对话的 Agent」压缩到几乎只剩模型配置本身再配一条命令直接拉起 Web 界面。你不需要写前端不需要搭 FastAPI甚至不需要理解什么是流式响应浏览器里就能和你的 Agent 对话。这篇教程面向的是完全没碰过 ADK 的读者。核心目标只有一个用大约 10 行 Python 代码在本机启动一个带 Web 交互界面的 AI Agent并且能真实发消息、看到回复。整个过程我会拆成环境准备、依赖安装、项目结构、代码编写、启动验证、报错排查六个环节每一步都给可复制的命令和配置。你跟着敲一遍大概 15 分钟内能看到浏览器里的聊天窗口。需要提前说清楚的是ADK 本身是 Agent 的开发框架它负责的是「Agent 怎么定义、怎么被调度、怎么暴露成 Web 服务」而 Agent 背后真正干活的模型可以是本地跑的也可以是云端 API。为了让零基础读者不被模型部署卡住我会用 LiteLLM 作为适配层把模型请求指向一个兼容 OpenAI 协议的接口。这样你既可以用本地模型也可以换成任何提供 OpenAI 兼容端点的服务代码几乎不用改。搜索「Google ADK 教程」「ADK Web 界面」「AI Agent 零基础」这类关键词的人通常卡在两个地方一是不知道 ADK 的项目结构有什么硬性要求二是adk web启动后页面空白或者报错不知道怎么查。这两个坑我都会在正文里单独讲并且给出真实的报错文本和对应处理方式。另外提醒一句ADK 的版本迭代比较快不同版本对目录结构、依赖包名的要求会有细微差别。本文以google-adk1.17.0和litellm1.79.0为基准如果你装的是更新版本遇到 API 变化时优先看官方文档的迁移说明。下面正式开始。2. 环境准备与 TaoToken 前置配置让 Agent 有模型可用在写那 10 行代码之前得先解决一个现实问题Agent 的root_agent里指定了模型这个模型请求最终要发到一个能响应 OpenAI 协议的服务上。很多零基础读者在这一步会卡住——本地没有 GPU云端 API 又要处理 Key、Base URL、模型名三件套的对应关系。我试过把模型接入层单独抽出来配置后面换模型只改环境变量代码一行不动这样最省心。这里我用 TaoToken 作为模型接入的统一入口。它的作用是提供一个兼容 OpenAI 协议的 API 端点你拿到 API Key 和 Base URL 之后LiteLLM 就能直接把请求转发过去。对 ADK 来说它只关心「有一个 OpenAI 兼容的 endpoint 和 model id」不关心背后是谁在提供服务。这种解耦对新手特别友好你不需要为了跑通一个 Web 界面去折腾模型权重下载和推理环境。具体要准备三样东西第一是 API Key。访问https://taotoken.net/api-keys创建复制出来先存到记事本。注意这个 Key 只在创建时完整显示一次关掉页面就看不到了所以别急着关。第二是 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不要加任何多余的路径后缀LiteLLM 会自己拼接/v1/chat/completions这类路径。如果你在代码里写成https://taotoken.net/api/v1反而可能因为路径重复导致 404。第三是 Model ID。这个取决于你在 TaoToken 控制台里能看到哪些模型常见的有gpt-4o-mini、claude-3-5-sonnet这类标识。Model ID 必须和平台上的名称完全一致大小写敏感写错了会直接报模型不存在。把这三样东西对应到环境变量上就是export OPENAI_API_BASEhttps://taotoken.net/api export OPENAI_API_KEY你创建的KeyWindows 用户如果用 PowerShell换成$env:OPENAI_API_BASE...的写法。如果你打算长期用建议写进.env文件或者 shell 的 profile 里避免每次开终端都要重新 export。注意不要把 API Key 硬编码进agent.py然后提交到 Git。哪怕只是本地练习养成用环境变量或.env的习惯后面接真实项目时能省掉很多安全事故。如果你更习惯用配置文件管理也可以在项目根目录建一个.envOPENAI_API_BASEhttps://taotoken.net/api OPENAI_API_KEYsk-xxxxxxxx然后在 Python 里用python-dotenv加载。不过 ADK 的adk web命令本身不会自动读.env所以要么在agent.py顶部手动load_dotenv()要么就在启动终端里先 export 好。对零基础来说直接在终端 export 最不容易出错。这一步做完模型接入的「三件套」就齐了Base URL 指向 TaoToken 的 API 根地址Key 用于鉴权Model ID 在代码里指定。接下来装依赖、建目录、写代码。3. 可复制配置目录结构、依赖清单与 10 行 agent.pyADK 对项目结构有硬性要求我把它总结成「三个必须」这是新手最容易忽略、也最容易导致adk web找不到 Agent 的原因。第一个必须入口文件必须叫agent.py。ADK 在扫描目录时会固定查找这个名字你叫main.py、my_agent.py都不行。第二个必须文件里必须有一个名为root_agent的模块级变量。ADK 通过这个名字定位根 Agent变量名写错就加载不到。第三个必须agent.py必须放在一个子目录下不能直接扔在项目根目录。ADK 会把子目录当作一个「Agent 应用」来加载adk web默认扫描当前目录下的所有子目录。按这个规范项目结构长这样my-adk-demo/ ├── agents/ │ └── agent.py └── requirements.txtagents这个目录名可以换比如叫my_agent、demo都行只要agent.py在它里面。但为了和官方示例保持一致建议先用agents。依赖清单requirements.txt内容如下google-adk1.17.0 litellm1.79.0安装命令pip install -r requirements.txt -i https://pypi.mirrors.ustc.edu.cn/simple如果你用 conda 管理环境完整流程是conda create -n adk-demo python3.11 -y conda activate adk-demo pip install google-adk1.17.0 litellm1.79.0 -i https://pypi.mirrors.ustc.edu.cn/simple这里 Python 版本我写的是 3.11比 excerpt 里的 3.13 更保守一些。原因是部分依赖在 3.13 上还没有预编译 wheel装的时候会现场编译新手容易卡在编译错误上。3.11 的兼容性目前最稳。然后是核心的agents/agent.pyimport os from google.adk.agents.llm_agent import Agent from google.adk.models.lite_llm import LiteLlm os.environ[OPENAI_API_BASE] https://taotoken.net/api os.environ[OPENAI_API_KEY] os.getenv(OPENAI_API_KEY, EMPTY) root_agent Agent( modelLiteLlm(modelopenai/gpt-4o-mini), nameroot_agent, description你是一个优秀的AI Agent, instruction请开始你的表演, )数一下去掉 import 和空行核心逻辑确实在 10 行左右。这里有几个细节值得展开LiteLlm(modelopenai/gpt-4o-mini)里的openai/前缀是 LiteLLM 的 provider 标识表示走 OpenAI 兼容协议。后面的gpt-4o-mini要换成你在 TaoToken 控制台里实际可用的 Model ID。如果你用的是别的模型比如claude-3-5-sonnet就写成openai/claude-3-5-sonnet——前缀仍然是openai/因为走的是兼容协议不是 Anthropic 原生协议。os.environ[OPENAI_API_KEY]这行我用了os.getenv兜底意思是优先读系统环境变量读不到才用EMPTY。这样你既可以在终端 export也可以临时改代码测试。但生产环境千万别留EMPTY。instruction是系统提示词决定 Agent 的人设和行为。这里写「请开始你的表演」只是占位你可以改成任何角色设定比如「你是一个耐心的 Python 助教回答要带可运行代码」。如果你想把配置抽成 JSON 或 TOML 方便管理可以建一个config.json{ base_url: https://taotoken.net/api, model_id: gpt-4o-mini, instruction: 你是一个优秀的AI Agent }然后在agent.py里读取。不过对 10 行代码的目标来说直接写在 Python 里更直观等你要管理多个 Agent 时再抽配置也不迟。提示adk web启动时会读取当前工作目录下的子目录。所以你的终端必须停在my-adk-demo/这一层而不是agents/里面。停错目录会看到「No agents found」之类的提示。配置齐了下一步启动并验证。4. 启动 adk web 并验证请求从浏览器发消息到看到回复启动命令很简单adk web --port 8000如果你没指定--portADK 默认用 8000。端口被占用时可以换成 8080、9000 等。启动成功后终端会打印类似这样的信息INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)这时候打开浏览器访问http://localhost:8000。页面加载后左上角应该能看到一个 Agent 选择器里面列出agents目录下的应用。选中之后下方会出现聊天输入框。第一次发消息建议用一句简单的测试比如「你好介绍一下你自己」。点击发送后观察三个地方第一浏览器 Network 面板里应该有一个发往/run或类似路径的 POST 请求状态码 200。如果状态码是 401说明 API Key 没生效如果是 500通常是模型调用出错需要看终端日志。第二终端里会打印模型请求的日志包括请求的 endpoint、model id、token 消耗等。如果看到LiteLLM completion() model...这类输出说明请求已经发出去了。第三聊天窗口里应该逐步出现 Agent 的回复。ADK 的 Web 界面支持流式输出所以你会看到文字一个字一个字蹦出来而不是等整段生成完才显示。如果回复正常出现恭喜你10 行代码的 Agent 已经跑通了。这时候你可以试着改instruction比如改成「你是一个只会用文言文回答的助手」然后重启adk web再发消息验证行为变化。这个「改配置→重启→验证」的循环就是后面做复杂 Agent 的基本工作流。再进一步你可以测试多轮对话。ADK 的 Web 界面默认会维护会话上下文你问「刚才我说了什么」它应该能答上来。如果答不上来检查是不是每次请求都新建了 session。关于验证请求还有一个更底层的方式直接用 curl 打 TaoToken 的 API确认模型侧是通的。这样能把「ADK 的问题」和「模型接入的问题」分开排查curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }如果这条命令能返回正常的 JSON说明 Key、Base URL、Model ID 三件套没问题问题就在 ADK 侧。如果这条也报错那先解决模型接入别在 ADK 里绕。注意curl 里的路径是/api/v1/chat/completions而环境变量OPENAI_API_BASE只写到/api。LiteLLM 会自动补/v1/chat/completions所以两者不冲突。手动 curl 时要写全。验证通过后你就有了一个可交互的 Web Agent。接下来讲几个高频报错。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节列的报错都是我在实际搭建过程中真实遇到过的按出现频率排序。报错一401 Unauthorized终端或浏览器里看到litellm.exceptions.AuthenticationError: OpenAIException - Error code: 401 - {error: {message: Invalid API key}}原因通常是三种Key 没设置、Key 复制时带了空格、Key 对应的环境变量名写错。排查步骤先在终端echo $OPENAI_API_KEY确认输出非空且没有多余空格再确认agent.py里读的是同一个变量名。如果你在代码里硬编码了EMPTY而没走环境变量那必然 401。报错二local proxy failed / Connection refusedlitellm.exceptions.APIConnectionError: OpenAIException - Connection error这个报错的意思是 LiteLLM 连不上你配置的 Base URL。常见原因是OPENAI_API_BASE写成了http://localhost:11434/v1这类本地地址但本地并没有跑对应的服务。如果你用的是 TaoToken确认地址是https://taotoken.net/api并且网络能正常访问。另外检查有没有多余的路径后缀比如写成/api/v1可能导致路径拼接后变成/api/v1/v1/chat/completions。报错三Error reading choices / KeyError choicesKeyError: choices或者litellm.exceptions.APIError: OpenAIException - Error reading choices这个通常说明返回的 JSON 结构不符合 OpenAI 协议预期。可能原因Model ID 写错服务端返回了错误信息而不是正常的 completion 结构或者 Base URL 指向了一个不兼容 OpenAI 协议的端点。排查方法用上一节的 curl 命令直接打看返回的 JSON 里有没有choices字段。如果没有看error字段写了什么。报错四No agents foundNo agents found in the current directory这是目录结构问题。确认你停在项目根目录有agents/子目录的那一层并且agents/agent.py里确实定义了root_agent变量。变量名拼写、大小写都要对。报错五OAuth / 认证相关如果你看到OAuth字样通常是因为 ADK 尝试用 Google 的默认认证流程。在纯本地 LiteLLM 的场景下你不需要 Google Cloud 的 OAuth。确认没有引入google.adk.auth相关的模块并且模型走的是LiteLlm而不是 Google 原生模型类。关于 CC Switch / Cline MCP / Codex auth.json 的说明如果你后续要把这个 Agent 接到 Claude Code、Cline 这类编码工具里会涉及三件套的配置Base URL、API Key、Model ID。以 Codex 的auth.json为例结构大致是{ openai_api_key: sk-xxxxxxxx, base_url: https://taotoken.net/api, model: gpt-4o-mini }Cline 的 MCP 配置里也是同样的三件套只是字段名不同。核心原则不变Base URL 指向 TaoToken 的 API 根地址Key 用你创建的Model ID 和平台一致。任何一处对不上都会表现为 401 或模型不存在。提示排查时养成「先 curl 再框架」的习惯。curl 通了问题一定在框架配置curl 不通问题在接入三件套。这样能省掉大量在框架里瞎试的时间。6. 从 10 行到可用 Agent下一步该往哪走跑通 Web 界面只是起点。你现在有了一个能对话的 Agent接下来可以根据需求往上加东西。想让它调用工具ADK 支持在Agent里注册 function tool把 Python 函数暴露给模型调用。想让它记住长期信息可以接 memory 模块。想让它处理多轮复杂任务可以了解 ADK 的 workflow agent 和 sub-agent 机制。这些都不需要改 Web 层的代码adk web会自动把新能力暴露到界面上。如果你打算把这个 Agent 用到日常编码里可以把它接到支持 MCP 的编辑器或 CLI 工具中。这时候三件套的配置会从环境变量变成对应工具的配置文件但 Base URL、Key、Model ID 的对应关系完全一样。TaoToken 的接入文档里有各工具的配置示例路径是https://taotoken.net/doc需要的时候对照着改字段名就行。想验证不同模型的表现可以直接在模型对话页里切换 Model ID 试效果不用每次改代码重启。地址是https://taotoken.net/chat。如果你要长期跑编码类 AgentCoding Plan 会更划算入口在https://taotoken.net/coding-plan。最后给一个实用建议把agent.py里的instruction当成你的「产品需求文档」来写。Agent 的行为差异八成来自这句提示词而不是模型本身。先花十分钟把 instruction 写清楚——角色、边界、输出格式、遇到不确定时怎么办——比后面调一堆参数都管用。 
长河君 · 2026/10/9 17:50:49 · 阅读 1.2k 【保姆级教程】10行代码搞定！零基础用Google ADK创建带Web界面的AI Agent！
1. 零基础跑通 Google ADK Web 界面10 行代码到底能做什么如果你刚接触 AI Agent大概率会被 LangChain、AutoGen 这些框架的抽象层劝退光是理解 Chain、Tool、Memory 的关系就要花掉一整个周末。Google ADKAgent Development Kit走的是另一条路——它把「定义一个能对话的 Agent」压缩到几乎只剩模型配置本身再配一条命令直接拉起 Web 界面。你不需要写前端不需要搭 FastAPI甚至不需要理解什么是流式响应浏览器里就能和你的 Agent 对话。这篇教程面向的是完全没碰过 ADK 的读者。核心目标只有一个用大约 10 行 Python 代码在本机启动一个带 Web 交互界面的 AI Agent并且能真实发消息、看到回复。整个过程我会拆成环境准备、依赖安装、项目结构、代码编写、启动验证、报错排查六个环节每一步都给可复制的命令和配置。你跟着敲一遍大概 15 分钟内能看到浏览器里的聊天窗口。需要提前说清楚的是ADK 本身是 Agent 的开发框架它负责的是「Agent 怎么定义、怎么被调度、怎么暴露成 Web 服务」而 Agent 背后真正干活的模型可以是本地跑的也可以是云端 API。为了让零基础读者不被模型部署卡住我会用 LiteLLM 作为适配层把模型请求指向一个兼容 OpenAI 协议的接口。这样你既可以用本地模型也可以换成任何提供 OpenAI 兼容端点的服务代码几乎不用改。搜索「Google ADK 教程」「ADK Web 界面」「AI Agent 零基础」这类关键词的人通常卡在两个地方一是不知道 ADK 的项目结构有什么硬性要求二是adk web启动后页面空白或者报错不知道怎么查。这两个坑我都会在正文里单独讲并且给出真实的报错文本和对应处理方式。另外提醒一句ADK 的版本迭代比较快不同版本对目录结构、依赖包名的要求会有细微差别。本文以google-adk1.17.0和litellm1.79.0为基准如果你装的是更新版本遇到 API 变化时优先看官方文档的迁移说明。下面正式开始。2. 环境准备与 TaoToken 前置配置让 Agent 有模型可用在写那 10 行代码之前得先解决一个现实问题Agent 的root_agent里指定了模型这个模型请求最终要发到一个能响应 OpenAI 协议的服务上。很多零基础读者在这一步会卡住——本地没有 GPU云端 API 又要处理 Key、Base URL、模型名三件套的对应关系。我试过把模型接入层单独抽出来配置后面换模型只改环境变量代码一行不动这样最省心。这里我用 TaoToken 作为模型接入的统一入口。它的作用是提供一个兼容 OpenAI 协议的 API 端点你拿到 API Key 和 Base URL 之后LiteLLM 就能直接把请求转发过去。对 ADK 来说它只关心「有一个 OpenAI 兼容的 endpoint 和 model id」不关心背后是谁在提供服务。这种解耦对新手特别友好你不需要为了跑通一个 Web 界面去折腾模型权重下载和推理环境。具体要准备三样东西第一是 API Key。访问https://taotoken.net/api-keys创建复制出来先存到记事本。注意这个 Key 只在创建时完整显示一次关掉页面就看不到了所以别急着关。第二是 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不要加任何多余的路径后缀LiteLLM 会自己拼接/v1/chat/completions这类路径。如果你在代码里写成https://taotoken.net/api/v1反而可能因为路径重复导致 404。第三是 Model ID。这个取决于你在 TaoToken 控制台里能看到哪些模型常见的有gpt-4o-mini、claude-3-5-sonnet这类标识。Model ID 必须和平台上的名称完全一致大小写敏感写错了会直接报模型不存在。把这三样东西对应到环境变量上就是export OPENAI_API_BASEhttps://taotoken.net/api export OPENAI_API_KEY你创建的KeyWindows 用户如果用 PowerShell换成$env:OPENAI_API_BASE...的写法。如果你打算长期用建议写进.env文件或者 shell 的 profile 里避免每次开终端都要重新 export。注意不要把 API Key 硬编码进agent.py然后提交到 Git。哪怕只是本地练习养成用环境变量或.env的习惯后面接真实项目时能省掉很多安全事故。如果你更习惯用配置文件管理也可以在项目根目录建一个.envOPENAI_API_BASEhttps://taotoken.net/api OPENAI_API_KEYsk-xxxxxxxx然后在 Python 里用python-dotenv加载。不过 ADK 的adk web命令本身不会自动读.env所以要么在agent.py顶部手动load_dotenv()要么就在启动终端里先 export 好。对零基础来说直接在终端 export 最不容易出错。这一步做完模型接入的「三件套」就齐了Base URL 指向 TaoToken 的 API 根地址Key 用于鉴权Model ID 在代码里指定。接下来装依赖、建目录、写代码。3. 可复制配置目录结构、依赖清单与 10 行 agent.pyADK 对项目结构有硬性要求我把它总结成「三个必须」这是新手最容易忽略、也最容易导致adk web找不到 Agent 的原因。第一个必须入口文件必须叫agent.py。ADK 在扫描目录时会固定查找这个名字你叫main.py、my_agent.py都不行。第二个必须文件里必须有一个名为root_agent的模块级变量。ADK 通过这个名字定位根 Agent变量名写错就加载不到。第三个必须agent.py必须放在一个子目录下不能直接扔在项目根目录。ADK 会把子目录当作一个「Agent 应用」来加载adk web默认扫描当前目录下的所有子目录。按这个规范项目结构长这样my-adk-demo/ ├── agents/ │ └── agent.py └── requirements.txtagents这个目录名可以换比如叫my_agent、demo都行只要agent.py在它里面。但为了和官方示例保持一致建议先用agents。依赖清单requirements.txt内容如下google-adk1.17.0 litellm1.79.0安装命令pip install -r requirements.txt -i https://pypi.mirrors.ustc.edu.cn/simple如果你用 conda 管理环境完整流程是conda create -n adk-demo python3.11 -y conda activate adk-demo pip install google-adk1.17.0 litellm1.79.0 -i https://pypi.mirrors.ustc.edu.cn/simple这里 Python 版本我写的是 3.11比 excerpt 里的 3.13 更保守一些。原因是部分依赖在 3.13 上还没有预编译 wheel装的时候会现场编译新手容易卡在编译错误上。3.11 的兼容性目前最稳。然后是核心的agents/agent.pyimport os from google.adk.agents.llm_agent import Agent from google.adk.models.lite_llm import LiteLlm os.environ[OPENAI_API_BASE] https://taotoken.net/api os.environ[OPENAI_API_KEY] os.getenv(OPENAI_API_KEY, EMPTY) root_agent Agent( modelLiteLlm(modelopenai/gpt-4o-mini), nameroot_agent, description你是一个优秀的AI Agent, instruction请开始你的表演, )数一下去掉 import 和空行核心逻辑确实在 10 行左右。这里有几个细节值得展开LiteLlm(modelopenai/gpt-4o-mini)里的openai/前缀是 LiteLLM 的 provider 标识表示走 OpenAI 兼容协议。后面的gpt-4o-mini要换成你在 TaoToken 控制台里实际可用的 Model ID。如果你用的是别的模型比如claude-3-5-sonnet就写成openai/claude-3-5-sonnet——前缀仍然是openai/因为走的是兼容协议不是 Anthropic 原生协议。os.environ[OPENAI_API_KEY]这行我用了os.getenv兜底意思是优先读系统环境变量读不到才用EMPTY。这样你既可以在终端 export也可以临时改代码测试。但生产环境千万别留EMPTY。instruction是系统提示词决定 Agent 的人设和行为。这里写「请开始你的表演」只是占位你可以改成任何角色设定比如「你是一个耐心的 Python 助教回答要带可运行代码」。如果你想把配置抽成 JSON 或 TOML 方便管理可以建一个config.json{ base_url: https://taotoken.net/api, model_id: gpt-4o-mini, instruction: 你是一个优秀的AI Agent }然后在agent.py里读取。不过对 10 行代码的目标来说直接写在 Python 里更直观等你要管理多个 Agent 时再抽配置也不迟。提示adk web启动时会读取当前工作目录下的子目录。所以你的终端必须停在my-adk-demo/这一层而不是agents/里面。停错目录会看到「No agents found」之类的提示。配置齐了下一步启动并验证。4. 启动 adk web 并验证请求从浏览器发消息到看到回复启动命令很简单adk web --port 8000如果你没指定--portADK 默认用 8000。端口被占用时可以换成 8080、9000 等。启动成功后终端会打印类似这样的信息INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)这时候打开浏览器访问http://localhost:8000。页面加载后左上角应该能看到一个 Agent 选择器里面列出agents目录下的应用。选中之后下方会出现聊天输入框。第一次发消息建议用一句简单的测试比如「你好介绍一下你自己」。点击发送后观察三个地方第一浏览器 Network 面板里应该有一个发往/run或类似路径的 POST 请求状态码 200。如果状态码是 401说明 API Key 没生效如果是 500通常是模型调用出错需要看终端日志。第二终端里会打印模型请求的日志包括请求的 endpoint、model id、token 消耗等。如果看到LiteLLM completion() model...这类输出说明请求已经发出去了。第三聊天窗口里应该逐步出现 Agent 的回复。ADK 的 Web 界面支持流式输出所以你会看到文字一个字一个字蹦出来而不是等整段生成完才显示。如果回复正常出现恭喜你10 行代码的 Agent 已经跑通了。这时候你可以试着改instruction比如改成「你是一个只会用文言文回答的助手」然后重启adk web再发消息验证行为变化。这个「改配置→重启→验证」的循环就是后面做复杂 Agent 的基本工作流。再进一步你可以测试多轮对话。ADK 的 Web 界面默认会维护会话上下文你问「刚才我说了什么」它应该能答上来。如果答不上来检查是不是每次请求都新建了 session。关于验证请求还有一个更底层的方式直接用 curl 打 TaoToken 的 API确认模型侧是通的。这样能把「ADK 的问题」和「模型接入的问题」分开排查curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }如果这条命令能返回正常的 JSON说明 Key、Base URL、Model ID 三件套没问题问题就在 ADK 侧。如果这条也报错那先解决模型接入别在 ADK 里绕。注意curl 里的路径是/api/v1/chat/completions而环境变量OPENAI_API_BASE只写到/api。LiteLLM 会自动补/v1/chat/completions所以两者不冲突。手动 curl 时要写全。验证通过后你就有了一个可交互的 Web Agent。接下来讲几个高频报错。5. 本篇常见错排查401、local proxy failed 与 reading choices这一节列的报错都是我在实际搭建过程中真实遇到过的按出现频率排序。报错一401 Unauthorized终端或浏览器里看到litellm.exceptions.AuthenticationError: OpenAIException - Error code: 401 - {error: {message: Invalid API key}}原因通常是三种Key 没设置、Key 复制时带了空格、Key 对应的环境变量名写错。排查步骤先在终端echo $OPENAI_API_KEY确认输出非空且没有多余空格再确认agent.py里读的是同一个变量名。如果你在代码里硬编码了EMPTY而没走环境变量那必然 401。报错二local proxy failed / Connection refusedlitellm.exceptions.APIConnectionError: OpenAIException - Connection error这个报错的意思是 LiteLLM 连不上你配置的 Base URL。常见原因是OPENAI_API_BASE写成了http://localhost:11434/v1这类本地地址但本地并没有跑对应的服务。如果你用的是 TaoToken确认地址是https://taotoken.net/api并且网络能正常访问。另外检查有没有多余的路径后缀比如写成/api/v1可能导致路径拼接后变成/api/v1/v1/chat/completions。报错三Error reading choices / KeyError choicesKeyError: choices或者litellm.exceptions.APIError: OpenAIException - Error reading choices这个通常说明返回的 JSON 结构不符合 OpenAI 协议预期。可能原因Model ID 写错服务端返回了错误信息而不是正常的 completion 结构或者 Base URL 指向了一个不兼容 OpenAI 协议的端点。排查方法用上一节的 curl 命令直接打看返回的 JSON 里有没有choices字段。如果没有看error字段写了什么。报错四No agents foundNo agents found in the current directory这是目录结构问题。确认你停在项目根目录有agents/子目录的那一层并且agents/agent.py里确实定义了root_agent变量。变量名拼写、大小写都要对。报错五OAuth / 认证相关如果你看到OAuth字样通常是因为 ADK 尝试用 Google 的默认认证流程。在纯本地 LiteLLM 的场景下你不需要 Google Cloud 的 OAuth。确认没有引入google.adk.auth相关的模块并且模型走的是LiteLlm而不是 Google 原生模型类。关于 CC Switch / Cline MCP / Codex auth.json 的说明如果你后续要把这个 Agent 接到 Claude Code、Cline 这类编码工具里会涉及三件套的配置Base URL、API Key、Model ID。以 Codex 的auth.json为例结构大致是{ openai_api_key: sk-xxxxxxxx, base_url: https://taotoken.net/api, model: gpt-4o-mini }Cline 的 MCP 配置里也是同样的三件套只是字段名不同。核心原则不变Base URL 指向 TaoToken 的 API 根地址Key 用你创建的Model ID 和平台一致。任何一处对不上都会表现为 401 或模型不存在。提示排查时养成「先 curl 再框架」的习惯。curl 通了问题一定在框架配置curl 不通问题在接入三件套。这样能省掉大量在框架里瞎试的时间。6. 从 10 行到可用 Agent下一步该往哪走跑通 Web 界面只是起点。你现在有了一个能对话的 Agent接下来可以根据需求往上加东西。想让它调用工具ADK 支持在Agent里注册 function tool把 Python 函数暴露给模型调用。想让它记住长期信息可以接 memory 模块。想让它处理多轮复杂任务可以了解 ADK 的 workflow agent 和 sub-agent 机制。这些都不需要改 Web 层的代码adk web会自动把新能力暴露到界面上。如果你打算把这个 Agent 用到日常编码里可以把它接到支持 MCP 的编辑器或 CLI 工具中。这时候三件套的配置会从环境变量变成对应工具的配置文件但 Base URL、Key、Model ID 的对应关系完全一样。TaoToken 的接入文档里有各工具的配置示例路径是https://taotoken.net/doc需要的时候对照着改字段名就行。想验证不同模型的表现可以直接在模型对话页里切换 Model ID 试效果不用每次改代码重启。地址是https://taotoken.net/chat。如果你要长期跑编码类 AgentCoding Plan 会更划算入口在https://taotoken.net/coding-plan。最后给一个实用建议把agent.py里的instruction当成你的「产品需求文档」来写。Agent 的行为差异八成来自这句提示词而不是模型本身。先花十分钟把 instruction 写清楚——角色、边界、输出格式、遇到不确定时怎么办——比后面调一堆参数都管用。