快速入门：使用代理开发套件构建代理

本快速入门将引导您完成以下操作：设置 Google Cloud 项目、安装智能体开发套件 (ADK)、设置基本智能体，以及运行其开发者界面。

本快速入门假设您使用的是本地 IDE（VS Code、PyCharm 等），并且可以访问 Python 3.10+ 和终端。代理完全在您的机器上运行，建议用于本地应用开发。

准备工作

请完成以下步骤：

设置 Google Cloud 项目

设置 Google Cloud 项目并启用 Vertex AI API。

  1. 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.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Vertex AI User

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. 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.

    4. 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

    1. In the Google Cloud console, go to the IAM page.

      前往 IAM
    2. 选择项目。
    3. 点击 授予访问权限。

    4. 在新的主账号字段中，输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。

    5. 在选择角色列表中，选择一个角色。
    6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
    7. 点击 Save（保存）。

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Make sure that billing is enabled for your Google Cloud project.

  8. Enable the Vertex AI API.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Vertex AI User

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. 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.

    4. 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

    1. In the Google Cloud console, go to the IAM page.

      前往 IAM
    2. 选择项目。
    3. 点击 授予访问权限。

    4. 在新的主账号字段中，输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。

    5. 在选择角色列表中，选择一个角色。
    6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
    7. 点击 Save（保存）。

    10. 设置凭据

    在本地终端中，设置 Google Cloud CLI 并通过它进行身份验证。如果您熟悉 Google AI Studio 中的 Gemini API，请注意，Vertex AI 中的 Gemini API 使用 Identity and Access Management（而不是 API 密钥）来管理访问权限。

    1. 安装并初始化 Google Cloud CLI。

    2. 如果您之前安装了 gcloud CLI，请运行此命令，确保您的 gcloud 组件已更新。

      gcloud components update

    3. 运行以下命令以生成本地应用默认凭据 (ADC) 文件。您的代理将在本地应用开发期间使用这些凭据访问 Vertex AI。

      gcloud auth application-default login

      如需了解详情，请参阅设置应用默认凭据。

    设置虚拟环境并安装 ADK

    • 创建并激活虚拟环境（推荐）：

      # 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

    创建代理

    使用终端创建文件夹结构：

    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

    将以下代码复制并粘贴到您创建的以下三个文件中：

    • \_\_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]
)

    该代理配备了两个具有模拟实现的函数工具。

    运行和测试代理

    1. 在终端中，前往代理的父级目录（例如，使用 cd ..）：

      parent_folder/      <-- navigate to this directory
    multi_tool_agent/
        __init__.py
        agent.py
        .env

    2. 运行以下命令以启动开发者 Web 界面。

      adk web

      在浏览器中打开提供的网址（通常为 http://localhost:8000 或 http://127.0.0.1:8000）。此连接完全在本地机器上进行。选择 multi_tool_agent 并与代理互动。

    可尝试的提示示例

    您可以尝试使用以下提示：

    • 纽约的天气怎么样？
    • 纽约现在几点？
    • 巴黎的天气怎么样？
    • Paris 现在是什么时间？

    后续步骤