30分钟快速搭建AI Agent：Google ADK入门指南

1. 项目概述：30分钟搭建你的第一个AI Agent

在当今AI技术快速发展的时代，AI Agent（人工智能代理）正成为改变我们与数字世界交互方式的关键技术。不同于传统的聊天机器人，AI Agent具备自主决策、执行任务和持续学习的能力，能够真正代表用户完成复杂工作流程。Google推出的Agent Development Kit（ADK）为开发者提供了一个快速构建AI Agent的框架，让即使没有深厚AI背景的开发者也能在短时间内创建功能强大的智能代理。

这个30分钟的快速入门指南将带你从零开始，使用Google ADK搭建你的第一个AI Agent——一个能够理解自然语言并做出智能响应的个人助手。我们将重点放在实际搭建过程上，避开复杂的理论讲解，确保你能够在最短时间内看到成果。整个过程只需要基础的Python知识和对命令行的一些了解，不需要预先掌握AI或机器学习专业知识。

2. 环境准备与Google Cloud配置

2.1 创建Google Cloud项目

首先，我们需要一个Google Cloud项目作为AI Agent的运行环境。访问Google Cloud控制台并按照以下步骤操作：

1. 点击顶部导航栏的项目选择器，然后点击"新建项目"
2. 输入项目名称（如"my-first-ai-agent"），位置选择"无组织"
3. 点击"创建"按钮，等待项目创建完成

注意：虽然Google Cloud提供免费试用额度，但需要绑定有效的信用卡。确保你的账户有足够的权限创建项目并启用计费。

创建完成后，记下自动生成的项目ID（通常形如"my-first-ai-agent-123456"），后续步骤会用到。你可以在项目仪表板的"项目信息"部分找到这个ID。

2.2 启用必要的API服务

AI Agent需要访问Google的AI平台服务，因此我们需要启用Vertex AI API：

1. 在Google Cloud控制台左侧导航栏，选择"API和服务" > "库"
2. 搜索"Vertex AI API"，点击进入详情页
3. 点击"启用"按钮，等待API启用完成

启用过程通常需要1-2分钟。你可以在"API和服务" > "仪表板"中查看已启用的API列表，确认Vertex AI API已成功启用。

2.3 设置Cloud Shell开发环境

为了简化环境配置，我们推荐使用Google Cloud Shell——一个基于浏览器的命令行环境，预装了所有必要的开发工具：

1. 在Google Cloud控制台顶部工具栏，点击"激活Cloud Shell"图标（>_形状）
2. 首次使用可能需要授权，点击"授权"按钮
3. 等待终端初始化完成（约30秒）

Cloud Shell提供了5GB的持久化存储空间，即使关闭会话后文件也会保留。它还预装了Python、git等开发工具，省去了本地环境配置的麻烦。

3. 安装ADK与创建Python虚拟环境

3.1 安装uv工具和ADK

在Cloud Shell终端中，执行以下命令安装uv——一个快速的Python包管理工具：

bash复制curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，重新加载shell配置使uv可用：

bash复制source ~/.bashrc

接下来，创建项目目录并安装Google ADK：

bash复制mkdir -p ai-agent-project
cd ai-agent-project
uv venv --python 3.12
source .venv/bin/activate
uv pip install google-adk

提示：如果关闭终端后需要重新进入项目，记得先执行cd ai-agent-project然后source .venv/bin/activate重新激活虚拟环境。

3.2 创建你的第一个AI Agent

ADK提供了一个简单的命令行工具来生成Agent基础代码。执行以下命令创建一个名为"personal_assistant"的Agent：

bash复制adk create personal_assistant

在交互式提示中，按照以下选择配置你的Agent：

1. 模型选择：输入"1"选择gemini-3.5-flash（一个快速高效的对话模型）
2. 后端服务：输入"2"选择Vertex AI
3. 项目ID：确认显示的Project ID是否正确，或手动输入你的Project ID
4. 区域：输入"global"使用全局端点

命令执行完成后，你会在当前目录下看到一个名为"personal_assistant"的新文件夹，包含三个关键文件：

• agent.py：Agent的主逻辑代码
• __init__.py：Python包初始化文件
• .env：环境变量配置文件

4. 理解与定制你的AI Agent

4.1 解析Agent核心代码

打开agent.py文件，你会看到类似以下内容：

python复制from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-3.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

这段代码定义了一个最基本的AI Agent，关键参数包括：

• model：指定使用的AI模型（gemini-3.5-flash）
• name：Agent的唯一标识符
• description：Agent的功能描述
• instruction：指导Agent行为的系统提示

你可以修改instruction参数来改变Agent的行为方式。例如，如果你想创建一个专门回答技术问题的Agent，可以改为：

python复制instruction='你是一个技术专家助手，专门回答编程和技术问题。回答要专业准确，对不确定的内容要明确说明。'

4.2 配置环境变量

.env文件包含了Agent运行所需的关键配置：

code复制GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

确保GOOGLE_CLOUD_PROJECT的值与你之前创建的Google Cloud项目ID一致。如果使用不同区域（非global），也需要相应调整GOOGLE_CLOUD_LOCATION。

注意：.env文件默认是隐藏的。在Cloud Shell编辑器中，可以通过点击"View" > "Toggle Hidden Files"来显示隐藏文件。

5. 运行与测试你的AI Agent

5.1 命令行交互模式

最简单的测试方式是通过命令行与Agent交互。在项目根目录下执行：

bash复制adk run personal_assistant

等待初始化完成后，你会看到[user]:提示符，表示Agent已准备好接收输入。尝试输入一些问候语或简单问题，如"Hello, what can you do?"，Agent会立即给出回应。输入"exit"可以结束会话。

5.2 Web界面交互模式

ADK还提供了一个更友好的Web界面。首先确保命令行会话已退出（输入exit），然后运行：

bash复制adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

启动后，终端会显示访问URL（通常是http://localhost:8000）。在Cloud Shell中，你可以点击终端上方的"Web Preview"按钮，选择端口8000来打开Web界面。

Web界面提供了更丰富的功能：

• 完整的聊天历史记录
• 消息的Markdown格式渲染
• 调试信息查看
• 多轮对话管理

5.3 常见问题排查

如果遇到问题，首先检查以下几点：

1. 确保Vertex AI API已启用（见2.2节）
2. 确认.env文件中的Project ID正确
3. 检查Cloud Shell中是否激活了正确的Python虚拟环境
4. 如果看到计费相关错误，确认项目已关联有效的结算账户

对于"Vertex AI API has not been used in project"错误，运行：

bash复制gcloud services enable aiplatform.googleapis.com

然后重试启动Agent。

6. 扩展你的AI Agent能力

6.1 添加记忆功能

默认情况下，Agent不会记住之前的对话。要实现简单的对话记忆，可以修改agent.py：

python复制from google.adk.agents import Agent

class PersonalAssistant(Agent):
    def __init__(self):
        super().__init__(
            model='gemini-3.5-flash',
            name='personal_assistant',
            description='A helpful assistant with memory.',
            instruction='You are a helpful assistant. Keep track of conversation history and maintain context.'
        )
        self.conversation_history = []

    def respond(self, user_input):
        self.conversation_history.append(f"User: {user_input}")
        response = super().respond(user_input)
        self.conversation_history.append(f"Assistant: {response}")
        return response

root_agent = PersonalAssistant()

这个修改为Agent添加了基本的对话历史记录功能，使其能够参考之前的交流内容。

6.2 集成外部工具

ADK支持为Agent添加"工具"（Tools），使其能够执行更复杂的任务。例如，添加一个天气查询工具：

python复制from google.adk.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a given city"""
    # 这里应该是实际的天气API调用
    return f"Weather in {city}: Sunny, 25°C"

root_agent.add_tool(get_weather)

添加工具后，Agent会自动学习何时以及如何使用这个工具。用户可以说"今天纽约的天气怎么样？"，Agent会调用get_weather工具并返回结果。

6.3 多Agent系统

ADK支持创建多个Agent协同工作的系统。例如，创建一个专门处理技术问题的Agent：

python复制tech_agent = Agent(
    model='gemini-3.5-flash',
    name='tech_expert',
    description='Specialist in technical questions.',
    instruction='You are a technical expert. Answer programming and IT questions in detail with code examples when needed.'
)

root_agent.add_child(tech_agent, route="/tech")

这样，当用户的问题涉及技术主题时，主Agent可以将对话路由给tech_agent处理。

7. 生产环境部署考虑

7.1 性能优化

当你的Agent开始处理真实用户请求时，考虑以下优化措施：

• 升级模型：从gemini-3.5-flash切换到gemini-3.0-pro获得更强的能力
• 实现缓存：对常见问题的回答进行缓存，减少API调用
• 设置速率限制：防止滥用，控制成本

7.2 监控与日志

添加监控以跟踪Agent性能：

• 记录对话数量、响应时间
• 监控API调用错误
• 设置关键指标的警报

可以在.env中添加：

code复制ADK_LOG_LEVEL=INFO
ADK_LOG_FILE=agent.log

7.3 安全考虑

生产环境部署时：

• 保护.env文件，不要提交到公开代码库
• 实施用户认证
• 对用户输入进行适当的清理和检查
• 设置对话内容审核机制

8. 学习路径与进阶资源

完成这个基础Agent后，你可以进一步探索：

1. 工具集成：连接日历、邮件、数据库等外部系统
2. 多模态能力：处理图像、音频输入
3. 自定义模型：微调模型以适应特定领域
4. 复杂工作流：设计多步骤任务自动化

Google提供了完整的ADK文档和示例代码库，是深入学习的绝佳资源。此外，参与ADK开发者社区可以获取最新的使用技巧和最佳实践。