企业官网建设流程全解析

1. 零基础跑通 Google ADK Web 界面：10 行代码到底能做什么

如果你刚接触 AI Agent，大概率会被 LangChain、AutoGen 这些框架的抽象层劝退：光是理解 Chain、Tool、Memory 的关系就要花掉一整个周末。Google ADK（Agent 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-adk==1.17.0和litellm==1.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_BASE="https://taotoken.net/api" export OPENAI_API_KEY="你创建的Key"

Windows 用户如果用 PowerShell，换成$env:OPENAI_API_BASE="..."的写法。如果你打算长期用，建议写进.env文件或者 shell 的 profile 里，避免每次开终端都要重新 export。

注意：不要把 API Key 硬编码进agent.py然后提交到 Git。哪怕只是本地练习，养成用环境变量或.env的习惯，后面接真实项目时能省掉很多安全事故。

如果你更习惯用配置文件管理，也可以在项目根目录建一个.env：

OPENAI_API_BASE=https://taotoken.net/api OPENAI_API_KEY=sk-xxxxxxxx

然后在 Python 里用python-dotenv加载。不过 ADK 的adk web命令本身不会自动读.env，所以要么在agent.py顶部手动load_dotenv()，要么就在启动终端里先 export 好。对零基础来说，直接在终端 export 最不容易出错。

这一步做完，模型接入的「三件套」就齐了：Base URL 指向 TaoToken 的 API 根地址，Key 用于鉴权，Model ID 在代码里指定。接下来装依赖、建目录、写代码。

3. 可复制配置：目录结构、依赖清单与 10 行 agent.py

ADK 对项目结构有硬性要求，我把它总结成「三个必须」，这是新手最容易忽略、也最容易导致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.txt

agents这个目录名可以换，比如叫my_agent、demo都行，只要agent.py在它里面。但为了和官方示例保持一致，建议先用agents。

依赖清单requirements.txt内容如下：

google-adk==1.17.0 litellm==1.79.0

安装命令：

pip install -r requirements.txt -i https://pypi.mirrors.ustc.edu.cn/simple

如果你用 conda 管理环境，完整流程是：

conda create -n adk-demo python=3.11 -y conda activate adk-demo pip install google-adk==1.17.0 litellm==1.79.0 -i https://pypi.mirrors.ustc.edu.cn/simple

这里 Python 版本我写的是 3.11，比 excerpt 里的 3.13 更保守一些。原因是部分依赖在 3.13 上还没有预编译 wheel，装的时候会现场编译，新手容易卡在编译错误上。3.11 的兼容性目前最稳。

然后是核心的agents/agent.py：

import 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( model=LiteLlm(model="openai/gpt-4o-mini"), name="root_agent", description="你是一个优秀的AI Agent", instruction="请开始你的表演！", )

数一下，去掉 import 和空行，核心逻辑确实在 10 行左右。这里有几个细节值得展开：

LiteLlm(model="openai/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

如果你没指定--port，ADK 默认用 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 CTRL+C 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 refused

litellm.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 'choices'

KeyError: 'choices'

或者：

litellm.exceptions.APIError: OpenAIException - Error reading choices

这个通常说明返回的 JSON 结构不符合 OpenAI 协议预期。可能原因：Model ID 写错，服务端返回了错误信息而不是正常的 completion 结构；或者 Base URL 指向了一个不兼容 OpenAI 协议的端点。排查方法：用上一节的 curl 命令直接打，看返回的 JSON 里有没有choices字段。如果没有，看error字段写了什么。

报错四：No agents found

No 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。如果你要长期跑编码类 Agent，Coding Plan 会更划算，入口在https://taotoken.net/coding-plan。

最后给一个实用建议：把agent.py里的instruction当成你的「产品需求文档」来写。Agent 的行为差异，八成来自这句提示词，而不是模型本身。先花十分钟把 instruction 写清楚——角色、边界、输出格式、遇到不确定时怎么办——比后面调一堆参数都管用。