本快速入门将引导您完成以下操作:设置 Google Cloud 项目、安装智能体开发套件 (ADK)、设置基本智能体,以及运行其开发者界面。
本快速入门假设您使用的是本地 IDE(VS Code、PyCharm 等),并且可以访问 Python 3.10+ 和终端。代理完全在您的机器上运行,建议用于本地应用开发。
准备工作
请完成以下步骤:
设置 Google Cloud 项目
设置 Google Cloud 项目并启用 Vertex AI API。
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI API.
-
Make sure that you have the following role or roles on the project: Vertex AI User
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
前往 IAM - 选择项目。
- 点击 授予访问权限。
-
在新的主账号字段中,输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。
- 在选择角色列表中,选择一个角色。
- 如需授予其他角色,请点击 添加其他角色,然后添加其他各个角色。
- 点击 Save(保存)。
-
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Vertex AI API.
-
Make sure that you have the following role or roles on the project: Vertex AI User
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
前往 IAM - 选择项目。
- 点击 授予访问权限。
-
在新的主账号字段中,输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。
- 在选择角色列表中,选择一个角色。
- 如需授予其他角色,请点击 添加其他角色,然后添加其他各个角色。
- 点击 Save(保存)。
-
-
安装并初始化 Google Cloud CLI。
-
如果您之前安装了 gcloud CLI,请运行此命令,确保您的
gcloud
组件已更新。gcloud components update
-
运行以下命令以生成本地应用默认凭据 (ADC) 文件。您的代理将在本地应用开发期间使用这些凭据访问 Vertex AI。
gcloud auth application-default login
如需了解详情,请参阅设置应用默认凭据。
创建并激活虚拟环境(推荐):
# Create python -m venv .venv # Activate (uncomment the line relevant to your environment) # macOS/Linux: source .venv/bin/activate # Windows CMD: .venv\Scripts\activate.bat # Windows PowerShell: .venv\Scripts\Activate.ps1
安装 ADK:
pip install google-adk
\_\_init\_\_.py
from . import agent
.env
# If using Gemini via Vertex AI on Google CLoud GOOGLE_CLOUD_PROJECT="your-project-id" GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1 GOOGLE_GENAI_USE_VERTEXAI="True"
agent.py
from google.adk.agents import Agent def get_weather(city: str) -> dict: """Retrieves the current weather report for a specified city. Returns: dict: A dictionary containing the weather information with a 'status' key ('success' or 'error') and a 'report' key with the weather details if successful, or an 'error_message' if an error occurred. """ if city.lower() == "new york": return {"status": "success", "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."} else: return {"status": "error", "error_message": f"Weather information for '{city}' is not available."} def get_current_time(city:str) -> dict: """Returns the current time in a specified city. Args: dict: A dictionary containing the current time for a specified city information with a 'status' key ('success' or 'error') and a 'report' key with the current time details in a city if successful, or an 'error_message' if an error occurred. """ import datetime from zoneinfo import ZoneInfo if city.lower() == "new york": tz_identifier = "America/New_York" else: return {"status": "error", "error_message": f"Sorry, I don't have timezone information for {city}."} tz = ZoneInfo(tz_identifier) now = datetime.datetime.now(tz) return {"status": "success", "report": f"""The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}"""} root_agent = Agent( name="weather_time_agent", model="gemini-2.0-flash", description="Agent to answer questions about the time and weather in a city.", instruction="I can answer your questions about the time and weather in a city.", tools=[get_weather, get_current_time] )
在终端中,前往代理的父级目录(例如,使用
cd ..
):parent_folder/ <-- navigate to this directory multi_tool_agent/ __init__.py agent.py .env
运行以下命令以启动开发者 Web 界面。
adk web
在浏览器中打开提供的网址(通常为
http://localhost:8000
或http://127.0.0.1:8000
)。此连接完全在本地机器上进行。选择multi_tool_agent
并与代理互动。- 纽约的天气怎么样?
- 纽约现在几点?
- 巴黎的天气怎么样?
- Paris 现在是什么时间?
设置凭据
在本地终端中,设置 Google Cloud CLI 并通过它进行身份验证。如果您熟悉 Google AI Studio 中的 Gemini API,请注意,Vertex AI 中的 Gemini API 使用 Identity and Access Management(而不是 API 密钥)来管理访问权限。
设置虚拟环境并安装 ADK
创建代理
使用终端创建文件夹结构:
mkdir multi_tool_agent/
touch \
multi_tool_agent/__init__.py \
multi_tool_agent/agent.py \
multi_tool_agent/.env
您的结构:
parent_folder/
multi_tool_agent/
__init__.py
agent.py
.env
将以下代码复制并粘贴到您创建的以下三个文件中:
该代理配备了两个具有模拟实现的函数工具。
运行和测试代理
可尝试的提示示例
您可以尝试使用以下提示: