构建与 AI 智能体的集成

本页面介绍了如何通过提示 AI 编码智能体来构建集成。您描述集成应执行的操作，智能体便会编写集成，使用 Application Integration REST API 上传并发布集成，运行集成，并帮助您排查问题。例如，您可以构建一个简单的保险理赔集成。

该智能体从 google/skills 代码库中的三个公开智能体技能中获取其 Application Integration 知识：

• application-integration-basics：概念、启用 API、预配区域、IAM 角色和运行身份服务账号以及限制。
• application-integration-authoring：将集成版本编写为 JSON，并上传、发布和运行它们。
• application-integration-troubleshooting：诊断失败、卡住或静默运行。

如需了解每项技能的参考文件，请参阅 Application Integration 代理技能。

准备工作

1. 使用 Google Cloud 项目，您可以在其中安全地进行实验，而不是生产项目。必须为项目启用结算功能。
2. 在受支持的国家/地区中，在项目中设置 Application Integration。设置 Application Integration 需要其自己的角色，这些角色列在该页面上。
3. 安装 gcloud CLI 并使用 gcloud auth login 登录。代理会使用您的 gcloud 凭据或应用默认凭据（如果使用客户端库）以您的身份调用 REST API。如果代理使用客户端库，则可能会要求您运行 gcloud auth application-default login。
4. 使用支持智能体技能的 AI 编码智能体。

所需的角色

设置 Application Integration 后，您需要以下角色来构建和运行集成。

如需获得上传、发布和运行集成以及查看其执行情况所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 针对项目的 Application Integration Editor (roles/integrations.integrationEditor)
• 如果集成具有运行身份服务账号：针对运行身份服务账号的 Service Account User (roles/iam.serviceAccountUser)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需了解哪些用户需要 Service Account User 角色以及如何授予该角色，请参阅为运行身份服务账号授予 Service Account User 角色。

安装代理技能

在终端中，运行以下命令来安装这三项技能：

npx skills add google/skills --skill application-integration-basics
npx skills add google/skills --skill application-integration-authoring
npx skills add google/skills --skill application-integration-troubleshooting

出现提示时，选择要配置的代理和安装范围。如果您的代理未列出，则默认的通用选项会安装到 .agents/skills。安装程序可能还会提供其他技能，例如 find-skills；您在此页面中不需要这些技能。只有在您信任某个项目文件夹后，部分代理才会从该文件夹加载技能。如果 npx 不可用，请安装 Node.js（其中包含该工具）。如需稍后更新技能，请运行 npx skills update。

描述您的集成

在空工作目录中启动智能体，并描述集成。具体说明触发器、输入和输出、规则以及部署位置。 例如：

Using the Application Integration skills, build an integration named
claims-adjudication in project PROJECT_ID, region LOCATION.

- Start it with an API trigger named adjudicate_claim.
- Inputs: claimId (string), claimAmount (double), policyActive (boolean).
- Outputs: decision (string) and reason (string).
- Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
  return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
- Save the integration version JSON in this directory so I can review it.
- Show me every command before you run it, then upload, publish, and run it
  once with a sample claim.

将 PROJECT_ID 替换为您的项目 ID，并将 LOCATION 替换为您设置 Application Integration 的区域。

查看计划并批准命令

代理会写入集成版本文件，例如 claims-adjudication.json。其中包含触发器 (triggerConfigs)、任务 (taskConfigs) 和变量 (integrationParameters)。请先阅读该文件，然后再继续操作，并让代理说明任何不符合预期的内容。例如，检查代理是否开启了 Cloud Logging (cloudLoggingDetails.enableCloudLogging)，这可能会增加费用。 如需将其关闭，请将 enableCloudLogging 设置为 false 并移除 cloudLoggingSeverity。

这些技能会指示智能体自由运行只读检查（例如列出集成或执行），但在进行任何更改之前，向您显示确切的命令或请求并等待您的批准。这包括启用 API、更改 IAM 政策以及上传、发布或运行集成。如果代理在未显示确切命令或请求的情况下请求批准，请让其显示这些内容。智能体自身的权限设置也可能会要求您批准每条命令，包括只读命令。在批准每个命令之前，请检查其中的项目、区域和集成名称。

上传、发布和运行集成

您批准后，代理会发出以下 Application Integration API 调用：

1. versions.upload 会将 JSON 文件作为集成的新版本上传。
2. versions.publish 会发布该版本。已发布的版本为 ACTIVE，之前发布的任何版本都将取消发布。
3. integrations.execute 通过其 API 触发器同步运行已发布的集成。

您也可以自行运行已发布的集成：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "triggerId": "api_trigger/adjudicate_claim",
      "inputParameters": {
        "claimId": {"stringValue": "CLM-1001"},
        "claimAmount": {"doubleValue": 2500},
        "policyActive": {"booleanValue": true}
      }
    }' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication:execute"

响应包含 executionId 和 outputParameters 中的集成输出变量。

提示：如需将高价值理赔转给人工处理，请让智能体添加审批任务。审批者需要拥有 Application Integration Approver 角色 (roles/integrations.suspensionResolver)。如果集成具有 run-as 服务账号，还需向审批者授予该服务账号的 Service Account User 角色 (roles/iam.serviceAccountUser)；此要求将在授予 Service Account User 角色中所述的发布过程中生效。运行的其余部分会在批准后异步恢复，因此其结果不会返回到 integrations.execute。请求获得批准或被拒绝后，请检查执行记录以了解结果：executionDetails.state，以及 executionDetails.executionSnapshots 中的变量值。

检查执行情况并排查问题

integrations.execute 的成功响应并不总是意味着每个任务都执行了您预期的操作。任务的重试策略可以让运行在任务失败后继续：如果选择忽略，集成会将失败的任务视为成功；如果选择无，集成仍可以通过备用路径以成功状态结束。此外，如果请求将 doNotPropagateError 设置为 true，则错误会在响应中返回，而不是作为错误状态返回。让智能体检查执行情况，例如：

Check execution EXECUTION_ID of claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

代理使用 executions.list 方法读取执行记录，并按执行 ID 进行过滤：

curl -G \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
    "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/claims-adjudication/executions"

该记录会显示执行状态（例如 SUCCEEDED、FAILED 或 SUSPENDED）以及每个任务的状态。您还可以在 Google Cloud 控制台中打开执行日志。默认情况下，集成会停用 Cloud Logging；如需使用该功能，请参阅在 Cloud Logging 中查看集成日志。

应用修复意味着上传并发布新版本，因此技能会指示代理先再次请求您的批准。发布后，之前的版本最多可以继续运行 10 分钟，因此请等待一段时间，然后再测试修复。发布还会取消上一版本的暂停运行，例如等待批准的运行。

最佳做法

• 从外景开始。在非生产项目中构建和测试，然后提升经过审核的 JSON 文件。请参阅上传和下载集成。
• 使用专用运行身份服务账号。为每个集成使用专用的、范围最小的服务账号。请参阅设置运行身份服务账号。
• 请勿将 Secret 存储在配置变量中。配置变量以纯文本形式存储和导出。请改用身份验证配置文件或 Secret Manager 访问任务。
• 查看生成的 JSON。请将其保留在源代码控制系统中，并在上传之前检查更改。身份验证配置文件不包含在文件中，因此请在每个项目中配置它们。

清理

如需移除示例集成，请向代理询问：

Unpublish claims-adjudication, then delete every version of it.

在您批准后，代理会在已发布版本上调用 versions.unpublish，并在每个版本上调用 versions.delete。当没有剩余版本时，该集成将不再显示在集成列表中。删除集成本身需要 Application Integration Admin 等角色；Editor 角色无法执行此操作。

后续步骤

• 在 GitHub 上阅读相关技能：基础知识、编写和问题排查。
• 了解 API 触发器。
• 了解集成版本。
• 在 Google Cloud 控制台中使用 Gemini Code Assist 构建集成。