Crea una integración con un agente de IA

En esta página, se muestra cómo compilar una integración con un agente de programación de IA. Tú describes lo que debe hacer la integración, y el agente la escribe, la sube y la publica con la API de REST de Application Integration, la ejecuta y te ayuda a solucionar problemas. Como ejemplo, compilarás una integración simple de adjudicación de reclamaciones de seguros.

El agente obtiene su conocimiento de Application Integration de tres habilidades de agente públicas en el repositorio google/skills:

Para ver los archivos de referencia de cada habilidad, consulta Habilidades del agente de Application Integration.

Antes de comenzar

  1. Usa un proyecto de Google Cloud en el que puedas experimentar de forma segura, no un proyecto de producción. La facturación debe estar habilitada para el proyecto.
  2. Configura Application Integration en el proyecto, en una región admitida. La configuración de Application Integration necesita sus propios roles, que se indican en esa página.
  3. Instala gcloud CLI y accede con gcloud auth login. El agente llama a la API de REST como tú, con tus credenciales de gcloud o, si usa una biblioteca cliente, con las credenciales predeterminadas de la aplicación. Si el agente usa una biblioteca cliente, es posible que te pida que ejecutes gcloud auth application-default login.
  4. Usa un agente de programación de IA que admita habilidades de agentes.

Roles obligatorios

Después de configurar Application Integration, necesitas los siguientes roles para compilar y ejecutar integraciones.

Para obtener los permisos que necesitas para subir, publicar y ejecutar integraciones, y ver sus ejecuciones, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para saber quién necesita el rol de usuario de cuenta de servicio y cómo otorgarlo, consulta Otorga el rol de usuario de cuenta de servicio para las cuentas de servicio de ejecución como.

Instala las habilidades del agente

En la terminal, ejecuta los siguientes comandos para instalar las tres habilidades:

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

Cuando se te solicite, elige los agentes que deseas configurar y el alcance de la instalación. Si tu agente no aparece en la lista, la opción universal predeterminada se instala en .agents/skills. Es posible que el instalador también ofrezca otras habilidades, como find-skills, pero no las necesitas para esta página. Algunos agentes cargan habilidades desde una carpeta de proyecto solo después de que confías en esa carpeta. Si npx no está disponible, instala Node.js, que lo incluye. Para actualizar las habilidades más adelante, ejecuta npx skills update.

Describe tu integración

Inicia tu agente en un directorio de trabajo vacío y describe la integración. Sé específico sobre el activador, las entradas y salidas, las reglas y dónde implementarlo. Por ejemplo:

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.

Reemplaza PROJECT_ID por el ID del proyecto y LOCATION por la región en la que configuraste Application Integration.

Revisa el plan y aprueba los comandos

El agente escribe un archivo de versión de integración, por ejemplo, claims-adjudication.json. Contiene el activador (triggerConfigs), las tareas (taskConfigs) y las variables (integrationParameters). Léelo antes de continuar y pídele al agente que te explique todo lo que no esperas. Por ejemplo, verifica si el agente activó Cloud Logging (cloudLoggingDetails.enableCloudLogging), lo que puede aumentar el costo. Para desactivarla, establece enableCloudLogging en false y quita cloudLoggingSeverity.

Las habilidades le indican al agente que ejecute verificaciones de solo lectura libremente, como enumerar integraciones o ejecuciones, pero que te muestre el comando o la solicitud exactos y espere tu aprobación antes de cambiar algo. Esto incluye habilitar las APIs, cambiar las políticas de IAM y subir, publicar o ejecutar una integración. Si el agente solicita aprobación sin mostrar el comando o la solicitud exactos, pídele que los muestre. Es posible que la configuración de permisos de tu agente también te pida que apruebes cada comando, incluidos los de solo lectura. Verifica el proyecto, la región y el nombre de la integración en cada comando antes de aprobarlo.

Sube, publica y ejecuta la integración

Después de que apruebes, el agente realizará las siguientes llamadas a la API de Application Integration:

  1. versions.upload sube el archivo JSON como una versión nueva de la integración.
  2. versions.publish publica esa versión. Una versión publicada es ACTIVE, y cualquier versión publicada anteriormente se despublica.
  3. integrations.execute ejecuta la integración publicada de forma síncrona a través de su activador de API.

También puedes ejecutar la integración publicada por tu cuenta:

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"

La respuesta contiene un executionId y las variables de salida de la integración en outputParameters.

Verifica la ejecución y soluciona problemas

Una respuesta correcta de integrations.execute no siempre significa que cada tarea haya hecho lo que esperabas. La estrategia de reintento de una tarea puede permitir que la ejecución continúe después de que falle la tarea: con Ignorar, la integración trata la tarea con errores como exitosa, y con Ninguna, la integración puede finalizar como exitosa a través de una ruta alternativa. Además, si una solicitud establece doNotPropagateError en true, se devuelven errores en la respuesta en lugar de un estado de error. Pídele al agente que verifique la ejecución, por ejemplo:

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

El agente lee el registro de ejecución con el método executions.list, filtrado por ID de ejecución:

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"

En el registro, se muestra el estado de ejecución, como SUCCEEDED, FAILED o SUSPENDED, y el estado de cada tarea. También puedes abrir los registros de ejecución en la consola de Google Cloud . Cloud Logging está inhabilitado para las integraciones de forma predeterminada. Para usarlo, consulta Visualiza los registros de integración en Cloud Logging.

Aplicar una corrección significa subir y publicar una versión nueva, por lo que las habilidades le indican al agente que primero vuelva a solicitar tu aprobación. Después de la publicación, la versión anterior puede seguir ejecutándose durante un máximo de 10 minutos, así que espera antes de probar la corrección. La publicación también cancela las ejecuciones suspendidas de la versión anterior, como las que esperan una aprobación.

Prácticas recomendadas

  • Comienza fuera de la producción. Compila y prueba en un proyecto que no sea de producción y, luego, promociona el archivo JSON revisado. Consulta Sube y descarga integraciones.
  • Usa una cuenta de servicio dedicada para ejecutar como. Usa una cuenta de servicio dedicada y con permisos mínimos para cada integración. Consulta Configura una cuenta de servicio para ejecutar como.
  • Mantén los secretos fuera de las variables de configuración. Las variables de configuración se almacenan y exportan en texto sin formato. En su lugar, usa un perfil de autenticación o la tarea de acceso de Secret Manager.
  • Revisa el JSON generado. Mantenlo en el control de código fuente y revisa los cambios antes de subirlos. Los perfiles de autenticación no se incluyen en el archivo, por lo que debes configurarlos en cada proyecto.

Realiza una limpieza

Para quitar la integración de ejemplo, pídele al agente lo siguiente:

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

Después de que apruebes, el agente llamará a versions.unpublish en la versión publicada y a versions.delete en cada versión. Cuando no queden versiones, la integración ya no aparecerá en tu lista de integraciones. Para borrar la integración, se necesita un rol como Administrador de Application Integration; el rol de Editor no puede hacerlo.

¿Qué sigue?