Utilizzare un agente

Utilizzo dell'SDK Agent Platform

Quando utilizzi l'SDK Agent Platform, il codice per eseguire query su un agente è lo stesso, indipendentemente dal fatto che venga eseguito localmente o eseguito il deployment da remoto. Poiché l'insieme di operazioni supportate varia a seconda dei framework, forniamo istruzioni per l'utilizzo dei modelli specifici per i framework:

Framework Descrizione
Agent Development Kit (ADK) Progettato in base alle best practice interne di Google per gli sviluppatori che creano applicazioni di AI o per i team che devono creare rapidamente prototipi ed eseguire il deployment di soluzioni solide basate su agenti.
Agent2Agent (anteprima) Il protocollo Agent2Agent (A2A) è uno standard aperto progettato per consentire una comunicazione e una collaborazione fluide tra gli agenti AI.
LangChain Più facile da usare per i casi d'uso di base grazie alle configurazioni e alle astrazioni predefinite.
LangGraph Approccio basato su grafi per la definizione dei workflow, con funzionalità avanzate di human-in-the-loop e riavvolgimento/riproduzione.
AG2 (precedentemente AutoGen) AG2 fornisce un framework di conversazione multi-agente come astrazione di alto livello per la creazione di workflow LLM.
LlamaIndex (anteprima) La pipeline di query di LlamaIndex offre un'interfaccia di alto livello per la creazione di workflow di Retrieval-Augmented Generation (RAG).
Personalizzato Agenti sviluppati e di cui è stato eseguito il deployment senza l'utilizzo di un template specifico per il framework.
Contratto di runtime Specifica dell'API HTTP per gli agenti basati su container personalizzati.

Utilizza gli agenti pubblicati su localhost

Se gestisci gli agenti tramite un server API che ascolta le richieste su http://localhost:PORT_NUMBER, invia le richieste a

http://localhost:PORT_NUMBER/API_PATH

dove

  • PORT_NUMBER è il numero di porta su cui il server è in ascolto (ad es. 8080)
  • API_PATH è il percorso dell'endpoint API corrispondente (ad esempio run o run_sse)

Utilizza gli agenti di cui è stato eseguito il deployment tramite l'API sottostante

Se hai eseguito il deployment di un agente, devi inviare le richieste all'endpoint corrispondente:

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

dove

  • PROJECT_ID è l'ID progetto Google Cloud in cui hai eseguito il deployment dell'agente
  • LOCATION è la regione in cui è stato eseguito il deployment dell'agente
  • RESOURCE_ID è l'ID dell'agente di cui è stato eseguito il deployment come risorsa reasoningEngine
  • API_PATH è il percorso dell'endpoint API corrispondente

Questo endpoint equivale a sostituire l'URL di base localhost con l'URL di base dell'agente di cui è stato eseguito il deployment. Se esegui il deployment di un container personalizzato, gli endpoint API e le strutture di richiesta e risposta sono definiti dal contratto di runtime.

Ecco alcuni esempi: se hai eseguito il deployment del server API ADK da un Dockerfile o da un'immagine container, richiama gli endpoint API come segue:

Esegui l'agente (risposta singola) 

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?"}]
  }
}'

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

Utilizza gli agenti di cui è stato eseguito il deployment nella console Google Cloud

Per gli agenti di cui è stato eseguito il deployment sviluppati utilizzando ADK, puoi utilizzare la consoleGoogle Cloud per interagire con l'agente:

  1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

    Vai ai deployment di Agent Platform

    Nell'elenco vengono visualizzati i runtime che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome del runtime.

  3. Fai clic sulla scheda Playground.

  4. Puoi digitare un messaggio per interagire con l'agente e fare clic su Nuova sessione per avviare una nuova sessione con l'agente.

  5. Se hai attivato le tracce tramite OpenTelemetry, puoi visualizzare i dettagli sul comportamento dell'agente durante le tue interazioni:

    • Traccia: tracce delle tue conversazioni con l'agente.

    • Evento: un grafico delle API richiamate e dei dettagli degli eventi durante le tue conversazioni con l'agente.

    • Stato: informazioni sullo stato dell'agente durante le conversazioni.

    • Sessioni: un elenco di sessioni associate al tuo agente. Per saperne di più, consulta Gestisci utilizzando la console Google Cloud o le chiamate API

Assistenza per Playground

Puoi utilizzare i seguenti framework per provare l'agente:

Framework Chatta con un agente Visualizza le sessioni
ADK Supportato Supportati Richiede che l'agente implementi Agent Platform Sessions per la persistenza.
Agent2Agent (A2A) Supportati Richiede che l'agente implementi Agent Platform Sessions per la persistenza. Supportati Richiede all'agente di utilizzare le sessioni della piattaforma dell'agente e l'agente deve inviare il valore user_id come parte dell'oggetto di contesto. Per un esempio di come passare il valore user_id come parte dell'Agent Executor, consulta il notebook Inizia a utilizzare A2A.

Passaggi successivi