Criar uma integração com um agente de IA e habilidades de agente do Application Integration

1. Introdução

Neste laboratório, você vai criar uma integração do Application Integration descrevendo-a para um agente de IA. Instale as três habilidades públicas do agente da Application Integration do repositório google/skills e peça para a CLI do Gemini escrever, fazer upload, publicar e executar uma pequena integração de amostra.

A amostra, sample-claims-adjudication, recebe uma solicitação de seguro e retorna APPROVE, REVIEW ou DENY.

Atividades deste laboratório

  • Configurar o Application Integration em um projeto do Google Cloud.
  • Instale as habilidades do agente da Application Integration.
  • Pedir à CLI do Gemini para criar, fazer upload, publicar e executar uma integração.
  • Verifique a execução por conta própria e peça para o agente resolver problemas.
  • Limpar a integração de amostra.

O que você vai aprender

  • O que as habilidades application-integration-basics, -authoring e -troubleshooting dão a um agente.
  • Como revisar o JSON da versão de integração e os comandos que o agente executa antes de aprová-los.
  • Como ler um registro de execução.

2. Configurar o projeto

  1. Se você ainda não tiver uma Conta do Google, crie uma.
    • Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
  2. Faça login no Console do Google Cloud.
  3. Ative o faturamento no console do Cloud.
    • A conclusão deste laboratório custa menos de US $1 em recursos do Cloud.
    • Siga as etapas no final deste laboratório para excluir recursos e evitar cobranças adicionais.
    • Novos usuários estão qualificados para o teste sem custo financeiro de US$ 300.
  4. Crie um novo projeto ou reutilize um atual.
    • Se você receber um erro sobre a cota do projeto, reutilize um projeto atual ou exclua um projeto atual para criar um novo.

Use um projeto novo ou um projeto atual em que você possa fazer testes com segurança, não um projeto de produção. O agente faz upload, publica e executa integrações nele com suas credenciais.

3. Abrir editor do Cloud Shell

  1. Clique neste link para acessar diretamente o editor do Cloud Shell.
  2. Se for preciso autorizar em algum momento, clique em Autorizar para continuar. Clique para autorizar o Cloud Shell
  3. Se o terminal não aparecer na parte de baixo da tela, abra-o:
    • Clique em Visualizar.
    • Clique em TerminalAbrir um novo terminal no editor do Cloud Shell
  4. No terminal, defina o projeto com este comando:
    • Formato:
      gcloud config set project [PROJECT_ID]
      
    • Exemplo:
      gcloud config set project lab-project-id-example
      
    • Se você não se lembrar do ID do projeto:
      • Para listar todos os IDs de projeto, use:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Defina o ID do projeto no terminal do editor do Cloud Shell
  5. Você vai receber esta mensagem:
    Updated property [core/project].
    
    Se você receber um WARNING e a pergunta Do you want to continue (Y/n)?, é provável que tenha inserido o ID do projeto incorretamente. Pressione n, depois Enter e tente executar o comando gcloud config set project novamente.

4. Configurar o Application Integration

A Application Integration é regional, então você a configura em uma região. Este laboratório usa us-central1.

  1. Anote o ID do projeto, porque você vai precisar dele mais tarde:
    gcloud config get-value project
    
  2. Ative a API Application Integration:
    gcloud services enable integrations.googleapis.com
    
  3. Acesse a página Application Integration no console do Google Cloud e selecione seu projeto.
  4. Na página Visão geral, selecione a região us-central1 e clique em Configuração rápida. Quando a configuração for concluída, o console vai mostrar a lista Integrações. Se você reutilizar um projeto, verifique se tem os papéis listados em Configurar a Application Integration antes de clicar em Configuração rápida.

Para saber mais, consulte Configurar a Application Integration.

5. Instalar as habilidades do agente

As habilidades dão ao agente o conhecimento sobre a Application Integration:

  • application-integration-basics: conceitos, ativação de APIs, provisionamento de uma região, papéis do IAM e limites.
  • application-integration-authoring: gravar versões de integração como JSON, além de fazer upload, publicar e executar essas versões.
  • application-integration-troubleshooting: diagnosticar execuções com falha, travadas ou silenciosas.
  1. Crie um diretório para este laboratório e acesse-o:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Instale 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
    
    Para cada habilidade, o instalador faz algumas perguntas. A CLI do Gemini está incluída na opção padrão Universal (.agents/skills). Pressione Enter para mantê-la, escolha Projeto como o escopo da instalação e confirme.

As habilidades agora estão em ~/appint-agent-lab/.agents/skills.

6. Iniciar a CLI do Gemini

  1. Inicie a CLI do Gemini no diretório do laboratório:
    gemini
    
    Quando a CLI do Gemini perguntar se você confia nessa pasta, escolha Confiar na pasta. A CLI do Gemini carrega as habilidades de uma pasta de projeto somente depois que você confia nela e, em seguida, é reiniciada. Se ele não reiniciar, abra um novo terminal, acesse ~/appint-agent-lab e execute gemini novamente. Talvez seja necessário pressionar Enter para aceitar algumas configurações padrão.
  2. Liste as habilidades que a CLI do Gemini pode usar:
    /skills
    
    As três habilidades de application-integration-* vão aparecer na lista.

7. Criar, publicar e executar a integração

  1. Cole este comando na CLI do Gemini. Substitua PROJECT_ID pelo ID do projeto que você anotou em Configurar a Application Integration.
    Using the Application Integration skills, build an integration named
    sample-claims-adjudication in project PROJECT_ID, region us-central1.
    
    - 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.
    
  2. Quando o agente usa uma habilidade pela primeira vez, a CLI do Gemini pede para você ativá-la. Permita.
  3. O agente grava um arquivo de versão de integração, como sample-claims-adjudication.json. Ele contém o gatilho (triggerConfigs), as tarefas (taskConfigs) e as variáveis (integrationParameters). Leia o arquivo e peça ao agente para explicar o que você não entende. Por exemplo, verifique se o agente ativou o Cloud Logging (cloudLoggingDetails.enableCloudLogging), o que pode aumentar o custo. Para desativar, defina enableCloudLogging como false e remova cloudLoggingSeverity.
  4. Aprove os comandos. A CLI do Gemini pede permissão antes de executar cada comando, incluindo os de somente leitura. As habilidades também instruem o agente a mostrar o comando ou a solicitação exata antes de fazer qualquer alteração, como upload, publicação ou execução da integração. Se o agente pedir aprovação sem mostrar o comando, peça para ele mostrar o comando. Verifique o projeto, a região e o nome da integração antes de aprovar e recuse comandos que leiam ou alterem integrações que não são suas.

Depois que você aprova, o agente faz upload do arquivo JSON como uma nova versão (versions.upload), publica (versions.publish) e executa o arquivo pelo gatilho da API (integrations.execute). Em seguida, ele mostra a decisão, o motivo e o ID de execução.

8. Verificar a execução

Executar a integração publicada e ler o registro de execução dela.

  1. Abra uma nova guia do terminal do Cloud Shell, acesse o diretório do laboratório e salve o ID do projeto e a região em variáveis:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Execute a integração com uma declaração acima de 1.000:
    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/sample-claims-adjudication:execute"
    
    A resposta contém um executionId e outputParameters com decision definido como REVIEW.
  3. Leia o registro de execução. Substitua EXECUTION_ID pelo executionId da resposta:
    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/sample-claims-adjudication/executions"
    
    Na resposta, executionDetails.state é SUCCEEDED, e executionDetails.executionSnapshots mostra o estado de cada tarefa.

Também é possível ver a execução nos registros de execução no console do Google Cloud.

9. Resolver problemas

Uma resposta bem-sucedida nem sempre significa que todas as tarefas fizeram o que você esperava. Peça para o agente verificar a execução. Na CLI do Gemini, insira este comando, substituindo EXECUTION_ID:

Check execution EXECUTION_ID of sample-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 executions.list, filtrado pelo ID de execução, e resume o estado da execução e de cada tarefa.

Se algo der errado neste laboratório, verifique estas causas comuns:

  • /skills não lista as habilidades do Application Integration. Inicie a CLI do Gemini em ~/appint-agent-lab e confie na pasta.
  • Uma chamada falha com PERMISSION_DENIED. Verifique se você está usando o projeto certo e se tem o papel de Editor do Application Integration (roles/integrations.integrationEditor) nele.
  • A execução da integração falha com No integrations found for the requested trigger_id. Verifique se o projeto e a região na solicitação correspondem ao local em que a integração foi publicada, se triggerId é api_trigger/adjudicate_claim e se uma versão da integração foi publicada. Você vai receber o mesmo erro se tiver feito upload de uma versão, mas não a tiver publicado.

10. Limpar

  1. Na CLI do Gemini, peça ao agente para remover a integração de exemplo:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Depois que você aprovar, o agente vai cancelar a publicação da versão publicada (versions.unpublish) e excluir cada versão (versions.delete). Quando não houver mais versões, a integração não vai mais aparecer na sua lista de integrações.Se você criou um projeto apenas para este laboratório, pode excluir o projeto em vez de remover a integração. Execute este comando na guia do terminal que você abriu em Verificar a execução:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Digite /quit e pressione Enter para sair da CLI do Gemini.
  3. Exclua o diretório do laboratório:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Parabéns

Você criou, publicou, executou e verificou uma integração ao enviar um comando para um agente de IA com as habilidades de agente do Application Integration.

A seguir