Criar uma integração com um agente de IA

Nesta página, mostramos como criar uma integração usando um agente de programação de IA. Você descreve o que a integração deve fazer, e o agente escreve, faz upload e publica a integração com a API REST do Application Integration, a executa e ajuda você a resolver problemas. Por exemplo, você cria uma integração simples de adjudicação de sinistros de seguro.

O agente recebe o conhecimento sobre o Application Integration de três habilidades de agente públicas no repositório google/skills:

Para ver os arquivos de referência de cada habilidade, consulte Habilidades do agente da Application Integration.

Antes de começar

  1. Use um projeto do Google Cloud em que você possa fazer testes com segurança, não um projeto de produção. O faturamento precisa estar ativado para o projeto.
  2. Configure o Application Integration no projeto, em uma região com disponibilidade. A configuração do Application Integration precisa de papéis próprios, que estão listados nessa página.
  3. Instale a CLI gcloud e faça login com gcloud auth login. O agente chama a API REST como você, com suas credenciais da gcloud ou, se usar uma biblioteca de cliente, com o Application Default Credentials. Se o agente usar uma biblioteca de cliente, ele poderá pedir que você execute gcloud auth application-default login.
  4. Use um agente de programação de IA que ofereça suporte a habilidades de agente.

Funções exigidas

Depois que o Application Integration estiver configurado, você vai precisar dos seguintes papéis para criar e executar integrações.

Para receber as permissões necessárias para fazer upload, publicar e executar integrações e visualizar as execuções delas, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para saber quem precisa do Usuário da Conta de Serviço e como concedê-lo, consulte Conceder Usuário da Conta de Serviço para contas de serviço de execução como.

Instalar as habilidades do agente

No terminal, execute os seguintes comandos para instalar as três 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

Quando solicitado, escolha os agentes a serem configurados e o escopo da instalação. Se o agente não estiver listado, a opção universal padrão será instalada em .agents/skills. O instalador também pode oferecer outras habilidades, como find-skills, mas elas não são necessárias para esta página. Alguns agentes carregam habilidades de uma pasta de projeto somente depois que você confia nela. Se npx não estiver disponível, instale o Node.js, que o inclui. Para atualizar as habilidades mais tarde, execute npx skills update.

Descreva sua integração

Inicie o agente em um diretório de trabalho vazio e descreva a integração. Seja específico sobre o gatilho, as entradas e saídas, as regras e onde implantá-lo. Exemplo:

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.

Substitua PROJECT_ID pelo ID do projeto e LOCATION pela região em que você configurou o Application Integration.

Analisar o plano e aprovar comandos

O agente grava um arquivo de versão de integração, por exemplo, claims-adjudication.json. Ele contém o gatilho (triggerConfigs), as tarefas (taskConfigs) e as variáveis (integrationParameters). Leia antes de continuar e peça ao agente para explicar qualquer coisa que você não entenda. Por exemplo, verifique se o agente ativou o Cloud Logging (cloudLoggingDetails.enableCloudLogging), o que pode aumentar o custo. Para desativá-lo, defina enableCloudLogging como false e remova cloudLoggingSeverity.

As habilidades dizem ao agente para executar verificações somente leitura livremente, como listar integrações ou execuções, mas mostrar o comando ou a solicitação exatos e aguardar sua aprovação antes de mudar qualquer coisa. Isso inclui ativar APIs, alterar políticas do IAM e fazer upload, publicar ou executar uma integração. Se o agente pedir aprovação sem mostrar o comando ou a solicitação exata, peça para ele mostrar. As configurações de permissão do seu agente também podem pedir que você aprove cada comando, incluindo os de somente leitura. Verifique o projeto, a região e o nome da integração em cada comando antes de aprová-lo.

Fazer upload, publicar e executar a integração

Depois que você aprovar, o agente vai fazer as seguintes chamadas de API da Application Integration:

  1. versions.upload faz upload do arquivo JSON como uma nova versão da integração.
  2. versions.publish publica essa versão. Uma versão publicada é ACTIVE, e qualquer versão publicada anteriormente é cancelada.
  3. integrations.execute executa a integração publicada de forma síncrona pelo gatilho de API.

Você também pode executar a integração publicada:

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"

A resposta contém um executionId e as variáveis de saída da integração em outputParameters.

Verificar a execução e resolver problemas

Uma resposta bem-sucedida de integrations.execute nem sempre significa que todas as tarefas fizeram o que você esperava. A estratégia de repetição de uma tarefa pode permitir que a execução continue após a falha da tarefa: com Ignorar, a integração trata a tarefa com falha como bem-sucedida e, com Nenhuma, a integração ainda pode terminar como bem-sucedida por um caminho alternativo. Além disso, se uma solicitação definir doNotPropagateError como true, os erros serão retornados na resposta, em vez de como um status de erro. Peça para o agente verificar a execução, por exemplo:

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

O agente lê o registro de execução com o método executions.list, filtrado pelo ID de execução:

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"

O registro mostra o estado de execução, como SUCCEEDED, FAILED ou SUSPENDED, e o estado de cada tarefa. Também é possível abrir os registros de execução no console do Google Cloud . O Cloud Logging está desativado para integrações por padrão. Para usá-lo, consulte Ver registros de integração no Cloud Logging.

Aplicar uma correção significa fazer upload e publicar uma nova versão. Por isso, as habilidades dizem ao agente para pedir sua aprovação novamente. Depois da publicação, a versão anterior pode continuar em execução por até 10 minutos. Por isso, aguarde antes de testar a correção. A publicação também cancela as execuções suspensas da versão anterior, como as que estão aguardando aprovação.

Práticas recomendadas

  • Comece fora da produção. Crie e teste em um projeto que não seja de produção e, em seguida, promova o arquivo JSON revisado. Consulte Fazer upload e download de integrações.
  • Use uma conta de serviço dedicada para execução. Use uma conta de serviço dedicada com escopo mínimo para cada integração. Consulte Definir uma conta de serviço executar como.
  • Mantenha os secrets fora das variáveis de configuração. As variáveis de configuração são armazenadas e exportadas em texto simples. Use um perfil de autenticação ou a tarefa de acesso do Secret Manager.
  • Revise o JSON gerado. Mantenha-o no controle de origem e revise as mudanças antes de fazer o upload. Os perfis de autenticação não estão incluídos no arquivo, então configure-os em cada projeto.

Limpar

Para remover a integração de exemplo, peça ao agente:

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

Depois que você aprovar, o agente fará a ligação agêntica versions.unpublish na versão publicada e versions.delete em cada versão. Quando não houver mais versões, a integração não vai mais aparecer na sua lista de integrações. Para excluir a integração, é necessário um papel como Administrador do Application Integration. O papel de Editor não pode fazer isso.

A seguir