Build an integration with an AI agent

This page shows you how to build an integration by prompting an AI coding agent. You describe what the integration should do, and the agent writes the integration, uploads and publishes it with the Application Integration REST API, runs it, and helps you troubleshoot it. As an example, you build a simple insurance claims-adjudication integration.

The agent gets its Application Integration knowledge from three public agent skills in the google/skills repository:

For each skill's reference files, see Application Integration agent skills.

Before you begin

  1. Use a Google Cloud project where you can safely experiment, not a production project. Billing must be enabled for the project.
  2. Set up Application Integration in the project, in a supported region. Setting up Application Integration needs its own roles, which are listed on that page.
  3. Install the gcloud CLI and sign in with gcloud auth login. The agent calls the REST API as you, with your gcloud credentials or, if it uses a client library, Application Default Credentials. If the agent uses a client library, it might ask you to run gcloud auth application-default login.
  4. Use an AI coding agent that supports agent skills.

Required roles

After Application Integration is set up, you need the following roles to build and run integrations.

To get the permissions that you need to upload, publish, and run integrations and view their executions, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

For who needs Service Account User and how to grant it, see Grant Service Account User for run-as service accounts.

Install the agent skills

In your terminal, run the following commands to install the three skills:

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

When prompted, choose the agents to configure and the installation scope. If your agent isn't listed, the default Universal option installs to .agents/skills. The installer might also offer other skills, such as find-skills; you don't need them for this page. Some agents load skills from a project folder only after you trust that folder. If npx isn't available, install Node.js, which includes it. To update the skills later, run npx skills update.

Describe your integration

Start your agent in an empty working directory and describe the integration. Be specific about the trigger, the inputs and outputs, the rules, and where to deploy it. For example:

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.

Replace PROJECT_ID with your project ID and LOCATION with the region where you set up Application Integration.

Review the plan and approve commands

The agent writes an integration version file, for example claims-adjudication.json. It contains the trigger (triggerConfigs), the tasks (taskConfigs), and the variables (integrationParameters). Read it before you continue, and ask the agent to explain anything you don't expect. For example, check whether the agent turned on Cloud Logging (cloudLoggingDetails.enableCloudLogging), which can add cost. To turn it off, set enableCloudLogging to false and remove cloudLoggingSeverity.

The skills tell the agent to run read-only checks freely, such as listing integrations or executions, but to show you the exact command or request and wait for your approval before it changes anything. That includes enabling APIs, changing IAM policies, and uploading, publishing, or running an integration. If the agent asks for approval without showing the exact command or request, ask it to show them. Your agent's own permission settings might also ask you to approve each command, including read-only ones. Check the project, region, and integration name in each command before you approve it.

Upload, publish, and run the integration

After you approve, the agent makes the following Application Integration API calls:

  1. versions.upload uploads the JSON file as a new version of the integration.
  2. versions.publish publishes that version. A published version is ACTIVE, and any previously published version is unpublished.
  3. integrations.execute runs the published integration synchronously through its API trigger.

You can also run the published integration yourself:

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"

The response contains an executionId and the integration's output variables in outputParameters.

Check the execution and troubleshoot

A successful response from integrations.execute doesn't always mean that every task did what you expected. A task's retry strategy can let the run continue after the task fails: with Ignore, the integration treats the failed task as succeeded, and with None, the integration can still end as succeeded through an alternate path. Also, if a request sets doNotPropagateError to true, errors are returned in the response instead of as an error status. Ask the agent to check the execution, for example:

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

The agent reads the execution record with the executions.list method, filtered by execution 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"

The record shows the execution state, such as SUCCEEDED, FAILED, or SUSPENDED, and the state of each task. You can also open the execution logs in the Google Cloud console. Cloud Logging is disabled for integrations by default; to use it, see View integration logs in Cloud Logging.

Applying a fix means uploading and publishing a new version, so the skills tell the agent to ask for your approval again first. After you publish, the previous version can keep running for up to 10 minutes, so wait before you test the fix. Publishing also cancels the previous version's suspended runs, such as runs waiting for an approval.

Best practices

  • Start outside production. Build and test in a non-production project, then promote the reviewed JSON file. See Upload and download integrations.
  • Use a dedicated run-as service account. Use a dedicated, minimally scoped service account for each integration. See Set a run-as service account.
  • Keep secrets out of config variables. Config variables are stored and exported in plain text. Use an authentication profile or the Secret Manager access task instead.
  • Review the generated JSON. Keep it in source control and review changes before you upload them. Authentication profiles aren't included in the file, so configure them in each project.

Clean up

To remove the example integration, ask the agent:

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

After you approve, the agent calls versions.unpublish on the published version and versions.delete on each version. When no versions are left, the integration no longer appears in your list of integrations. Deleting the integration itself needs a role such as Application Integration Admin; the Editor role can't.

What's next