Apigee API Hub tools for ADK¶

适用于 ADK 的 Apigee API Hub 工具¶

Supported in ADKPython v0.1.0

ApiHubToolset lets you turn any documented API from Apigee API hub into a tool with a few lines of code. This section shows you to step by step instructions including setting up authentication for a secure connection to your APIs.

ApiHubToolset 让您只需几行代码就可以将 Apigee API 集线器中的任何文档化 API 转换为工具。本部分向您展示分步说明,包括为安全连接到您的 API 设置身份验证。

Prerequisites 先决条件

Install ADK
安装 ADK
Install Google Cloud CLI.
安装 Google Cloud CLI。
Apigee API hub instance with documented (i.e. OpenAPI spec) APIs
具有文档化(即 OpenAPI 规范)API 的 Apigee API 集线器实例
Set up your project structure and create required files
设置您的项目结构并创建必需的文件

project_root_folder
 |
 `-- my_agent
     |-- .env
     |-- __init__.py
     |-- agent.py
     `__ tool.py

Create an API Hub Toolset¶

创建 API 集线器工具集¶

Note: This tutorial includes an agent creation. If you already have an agent, you only need to follow a subset of these steps.

注意:本教程包括智能体创建。如果您已经有智能体,只需遵循这些步骤的子集。

Get your access token, so that APIHubToolset can fetch spec from API Hub API. In your terminal run the following command
获取您的访问令牌,以便 APIHubToolset 可以从 API 集线器 API 获取规范。在终端中运行以下命令
```
gcloud auth print-access-token
# Prints your access token like 'ya29....'
# 打印您的访问令牌,如 'ya29....'
```
Ensure that account used has required permissions. You can use pre-defined role roles/apihub.viewer or assign following permissions:
确保使用的账户具有所需的权限。您可以使用预定义的角色 roles/apihub.viewer 或分配以下权限:
1. apihub.specs.get (required)
2. apihub.apis.get (optional)
3. apihub.apis.list (optional)
4. apihub.versions.get (optional)
5. apihub.versions.list (optional)
6. apihub.specs.list (optional)
Create a tool with APIHubToolset. Add to below to tools.py
使用 APIHubToolset 创建工具。将以下内容添加到 tools.py

If your API requires authentication, you must configure authentication for tool. The following code sample demonstrates how to configure an API key. ADK supports token based auth (API Key, Bearer token), service account, and OpenID Connect. We will soon add support for various OAuth2 flows.

如果您的 API 需要身份验证,您必须为工具配置身份验证。以下代码示例演示如何配置 API 密钥。ADK 支持基于令牌的身份验证(API 密钥、Bearer 令牌)、服务账户和 OpenID Connect。我们将很快添加对各种 OAuth2 流程的支持。
```
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.apihub_tool.apihub_toolset import APIHubToolset

# Provide authentication for your APIs. Not required if your APIs don't required authentication.
# 为您的 API 提供身份验证。如果您的 API 不需要身份验证,则不需要此项。
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "query", "apikey", apikey_credential_str
)

sample_toolset = APIHubToolset(
    name="apihub-sample-tool",
    description="Sample Tool",
    access_token="...",  # Copy your access token generated in step 1
                         # 复制您在步骤 1 中生成的访问令牌
    apihub_resource_name="...", # API Hub resource name / API 集线器资源名称
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)
```
For production deployment we recommend using a service account instead of an access token. In the code snippet above, use service_account_json=service_account_cred_json_str and provide your security account credentials instead of a token.

对于生产部署,我们建议使用服务账户而不是访问令牌。在上面的代码片段中,使用 service_account_json=service_account_cred_json_str 并提供您的安全账户凭据而不是令牌。

For apihub_resource_name, if you know to specific ID of to OpenAPI Spec being used for your API, use `projects/my-project-id/locations/us-west1/apis/my-api-id/versions/version-id/specs/spec-id`. If you would like to Toolset to automatically pull to first available spec from to API, use `projects/my-project-id/locations/us-west1/apis/my-api-id`

对于 apihub_resource_name,如果您知道为您的 API 使用的 OpenAPI 规范的特定 ID,请使用 projects/my-project-id/locations/us-west1/apis/my-api-id/versions/version-id/specs/spec-id。如果您希望工具集自动从 API 拉取第一个可用的规范,请使用 projects/my-project-id/locations/us-west1/apis/my-api-id。
Create your agent file Agent.py and add to created tools to your agent definition:

创建您的智能体文件 Agent.py 并将创建的工具添加到您的智能体定义:

from google.adk.agents.llm_agent import LlmAgent
from .tools import sample_toolset

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='enterprise_assistant',
    instruction='Help user, leverage to tools you have access to',
    tools=sample_toolset.get_tools(),
)

Configure your __init__.py to expose your agent
配置您的 __init__.py 以暴露您的智能体:
```
from . import agent
```
Start to Google ADK Web UI and try your agent:

启动 Google ADK Web UI 并尝试您的智能体:

# make sure to run `adk web` from your project_root_folder
# 确保从 project_root_folder 运行 `adk web`
adk web

Then go to http://localhost:8000 to try your agent from Web UI. - 然后前往 http://localhost:8000 从 Web UI 尝试您的智能体。