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,-authoringe-troubleshootingdã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
- 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.
- Faça login no Console do Google Cloud.
- 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.
- 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
- Clique neste link para acessar diretamente o editor do Cloud Shell.
- Se for preciso autorizar em algum momento, clique em Autorizar para continuar.

- Se o terminal não aparecer na parte de baixo da tela, abra-o:
- Clique em Visualizar.
- Clique em Terminal

- 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}'

- Para listar todos os IDs de projeto, use:
- Formato:
- Você vai receber esta mensagem:
Se você receber umUpdated property [core/project].
WARNINGe a perguntaDo you want to continue (Y/n)?, é provável que tenha inserido o ID do projeto incorretamente. Pressionen, depoisEntere tente executar o comandogcloud config set projectnovamente.
4. Configurar o Application Integration
A Application Integration é regional, então você a configura em uma região. Este laboratório usa us-central1.
- Anote o ID do projeto, porque você vai precisar dele mais tarde:
gcloud config get-value project - Ative a API Application Integration:
gcloud services enable integrations.googleapis.com - Acesse a página Application Integration no console do Google Cloud e selecione seu projeto.
- Na página Visão geral, selecione a região
us-central1e 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.
- Crie um diretório para este laboratório e acesse-o:
mkdir ~/appint-agent-lab && cd ~/appint-agent-lab - Instale as três habilidades:
Para cada habilidade, o instalador faz algumas perguntas. A CLI do Gemini está incluída na opção padrão Universal (.agents/skills). Pressionenpx 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-troubleshootingEnterpara 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
- Inicie a CLI do Gemini no diretório do laboratório:
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, acessegemini~/appint-agent-labe executegemininovamente. Talvez seja necessário pressionarEnterpara aceitar algumas configurações padrão. - Liste as habilidades que a CLI do Gemini pode usar:
As três habilidades de/skillsapplication-integration-*vão aparecer na lista.
7. Criar, publicar e executar a integração
- Cole este comando na CLI do Gemini. Substitua
PROJECT_IDpelo 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. - Quando o agente usa uma habilidade pela primeira vez, a CLI do Gemini pede para você ativá-la. Permita.
- 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, definaenableCloudLoggingcomofalsee removacloudLoggingSeverity. - 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.
- 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 - Execute a integração com uma declaração acima de 1.000:
A resposta contém umcurl -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"executionIdeoutputParameterscomdecisiondefinido comoREVIEW. - Leia o registro de execução. Substitua
EXECUTION_IDpeloexecutionIdda resposta: Na 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"executionDetails.stateéSUCCEEDED, eexecutionDetails.executionSnapshotsmostra 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:
/skillsnão lista as habilidades do Application Integration. Inicie a CLI do Gemini em~/appint-agent-labe 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, setriggerIdéapi_trigger/adjudicate_claime 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
- Na CLI do Gemini, peça ao agente para remover a integração de exemplo:
Depois que você aprovar, o agente vai cancelar a publicação da versão publicada (Unpublish sample-claims-adjudication, then delete every version of it.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) - Digite
/quite pressioneEnterpara sair da CLI do Gemini. - 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
- Criar uma integração com um agente de IA
- Habilidades do agente da Application Integration
- Leia as habilidades no GitHub: noções básicas, criação e solução de problemas.