Usar um agente

Como usar o SDK da Agent Platform

Ao usar o SDK da Agent Platform, o código para consultar um agente é o mesmo, esteja ele em execução localmente ou implantado remotamente. Como o conjunto de operações compatíveis varia de acordo com o framework, fornecemos instruções de uso para modelos específicos de framework:

Framework Descrição
Kit de Desenvolvimento de Agente (ADK) Projetado com base nas práticas recomendadas internas do Google para desenvolvedores que criam aplicativos de IA ou equipes que precisam criar protótipos e implantar rapidamente soluções robustas baseadas em agentes.
Agent2Agent (pré-lançamento) O protocolo Agent2Agent (A2A) é um padrão aberto projetado para permitir a comunicação e a colaboração perfeitas entre agentes de IA.
LangChain Mais fácil de usar em casos de uso básicos devido às configurações e abstrações predefinidas.
LangGraph Abordagem baseada em gráficos para definir fluxos de trabalho, com recursos avançados de human-in-the-loop e retrocesso/reprodução.
AG2 (antigo AutoGen) O AG2 oferece um framework de conversação multiagente como uma abstração de alto nível para criar fluxos de trabalho de LLM.
LlamaIndex (pré-lançamento) O pipeline de consulta do LlamaIndex oferece uma interface de alto nível para criar fluxos de trabalho de geração aumentada por recuperação (RAG).
Personalizado Agentes que foram desenvolvidos e implantados sem o uso de um modelo específico de framework.
Contrato de ambiente de execução Especificação da API HTTP para agentes personalizados baseados em contêiner.

Usar agentes disponibilizados no localhost

Se você disponibilizar agentes por um servidor de API que está detectando solicitações em http://localhost:PORT_NUMBER, envie solicitações para

http://localhost:PORT_NUMBER/API_PATH

em que

  • PORT_NUMBER é o número da porta em que o servidor está detectando (por exemplo, 8080).
  • API_PATH é o caminho do endpoint de API correspondente (como run ou run_sse)

Usar agentes implantados pela API deles

Se você implantou um agente, envie solicitações para o endpoint correspondente:

https://LOCATION-aiplatform.googleapis.com/reasoningEngines/v1/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID/api/API_PATH

em que

  • PROJECT_ID é o ID do projeto do Google Cloud em que você implantou o agente.
  • LOCATION é a região em que o agente está implantado.
  • RESOURCE_ID é o ID do agente implantado como um recurso reasoningEngine.
  • API_PATH é o caminho do endpoint de API correspondente

Esse endpoint equivale a substituir o URL de base do localhost pelo URL de base do agente implantado. Se você estiver implantando um contêiner personalizado, os endpoints de API e as estruturas de solicitação e resposta serão definidos pelo contrato de ambiente de execução.

Por exemplo, se você implantou o servidor de API do ADK de um Dockerfile ou de uma imagem de contêiner, invoque os endpoints de API da seguinte maneira:

Executar agente (resposta única) 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/api/run -d '{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "What is the capital of France?"}]
  }
}'

Executar agente (streaming) 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/api/run_sse -d '{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "What is the weather in New York?"}]
  },
  "streaming": true
}'

Usar agentes implantados no console do Google Cloud

Para agentes implantados desenvolvidos com o ADK, use o console doGoogle Cloud para interagir com seu agente:

  1. No console do Google Cloud , acesse a página Implantações da Plataforma de Agentes.

    Acessar as implantações da Agent Platform

    Os ambientes de execução que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome do ambiente de execução.

  3. Clique na guia Playground.

  4. Você pode Digitar uma mensagem para interagir com o agente e clicar em Nova sessão para iniciar uma nova sessão com ele.

  5. Se você ativou os traces pelo OpenTelemetry, é possível conferir detalhes sobre o comportamento do agente durante as interações:

    • Trace: traces das suas conversas com o agente.

    • Evento: um gráfico de APIs invocadas e detalhes de eventos durante suas conversas com o agente.

    • Estado: informações sobre o estado do agente durante as conversas.

    • Sessões: uma lista de sessões associadas ao seu agente. Para mais informações, consulte Gerenciar usando o console do Google Cloud ou chamadas de API.

Suporte do Playground

Use os seguintes frameworks para testar seu agente:

Framework Conversar com um agente Ver sessões
ADK Com suporte Compatível. Exige que o agente implemente as sessões da Agent Platform para persistência.
Agent2Agent (A2A) Compatível. Exige que o agente implemente as sessões da Agent Platform para persistência. Compatível. Exige que o agente use as sessões da plataforma de agentes e envie o valor user_id como parte do objeto de contexto. Para ver um exemplo de como transmitir o valor user_id como parte do Agent Executor, consulte o notebook Introdução ao A2A.

A seguir