Utilizza un agente LangChain

Prima di iniziare

Questo tutorial presuppone che tu abbia letto e seguito le istruzioni riportate in:

Recuperare un'istanza di un agente

Per eseguire query su un LangchainAgent, devi prima creare una nuova istanza o recuperare un'istanza esistente.

Per ottenere l'LangchainAgent che corrisponde a un ID risorsa specifico:

SDK Agent Platform

Esegui questo codice:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

agent = client.agent_engines.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(agent)

dove

Libreria delle richieste Python

Esegui questo codice:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

API REST 

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

Quando utilizzi l'SDK Agent Platform, l'oggetto agent corrisponde a una classe AgentEngine che contiene quanto segue:

Il resto di questa sezione presuppone che tu disponga di un'istanza AgentEngine denominata agent.

Operazioni supportate

Sono supportate le seguenti operazioni:

  • query: per ottenere una risposta a una query in modo sincrono.
  • stream_query: per lo streaming di una risposta a una query.

Entrambi i metodi query e stream_query supportano lo stesso tipo di argomenti:

  • input: i messaggi da inviare all'agente.
  • config: la configurazione (se applicabile) per il contesto della query.

Interroga l'agente

Per eseguire query sull'agente con un input, utilizza il metodo LangchainAgent.query:

agent.query(input="What is the exchange rate from US dollars to SEK today?")

equivale a quanto segue (in forma completa):

agent.query(input={
    "input": [ # The input is represented as a list of messages (each message as a dict)
        {
            # The role (e.g. "system", "user", "assistant", "tool")
            "role": "user",
            # The type (e.g. "text", "tool_use", "image_url", "media")
            "type": "text",
            # The rest of the message (this varies based on the type)
            "text": "What is the exchange rate from US dollars to Swedish currency?",
        },
    ]
})

I ruoli vengono utilizzati per aiutare il modello a distinguere i diversi tipi di messaggi quando risponde. Se role viene omesso nell'input, il valore predefinito è "user".

Ruolo Descrizione
system Utilizzato per indicare al modello di chat come comportarsi e fornire un contesto aggiuntivo. Non supportato da tutti i fornitori di modelli di chat.
user Rappresenta l'input di un utente che interagisce con il modello, di solito sotto forma di testo o altro input interattivo.
assistant Rappresenta una risposta del modello, che può includere testo o una richiesta di richiamo di strumenti.
tool Un messaggio utilizzato per restituire i risultati della chiamata di uno strumento al modello dopo il recupero di dati o l'elaborazione esterni.

Il type del messaggio determinerà anche come verrà interpretato il resto del messaggio (vedi Gestire contenuti multimodali).

Interrogare l'agente con contenuti multimodali

Utilizzeremo il seguente agente (che inoltra l'input al modello e non utilizza strumenti) per illustrare come trasmettere input multimodali a un agente:

agent = agent_engines.LangchainAgent(
    model="gemini-2.0-flash",
    runnable_builder=lambda model, **kwargs: model,
)

I messaggi multimodali sono rappresentati da blocchi di contenuti che specificano un type e i dati corrispondenti. In generale, per i contenuti multimodali, devi specificare type come "media", file_uri in modo che punti a un URI Cloud Storage e mime_type per interpretare il file.

Immagine 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "image/jpeg", "file_uri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg"},
]})

Video 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "video/mp4", "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"},
]})

Audio 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "audio/mp3", "file_uri": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3"},
]})

Per l'elenco dei tipi MIME supportati da Gemini, consulta la documentazione su:

Esegui query sull'agente con una configurazione eseguibile

Quando esegui una query sull'agente, puoi anche specificare un config per l'agente (che segue lo schema di un RunnableConfig). Due scenari comuni sono:

  • Parametri di configurazione predefiniti:
  • Parametri di configurazione personalizzati (tramite configurable):

Ad esempio:

import uuid

run_id = uuid.uuid4()  # Generate an ID for tracking the run later.

response = agent.query(
    input="What is the exchange rate from US dollars to Swedish currency?",
    config={  # Specify the RunnableConfig here.
        "run_id": run_id                               # Optional.
        "tags": ["config-tag"],                        # Optional.
        "metadata": {"config-key": "config-value"},    # Optional.
        "configurable": {"session_id": "SESSION_ID"}   # Optional.
    },
)

print(response)

Passaggi successivi