Utilizzare un agente LangChain

Prima di iniziare

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

Recupera un'istanza di un agente

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

Per ottenere l'LangchainAgent corrispondente a un ID risorsa specifico:

SDK Vertex AI per Python

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 Vertex AI per Python, l'oggetto agent corrisponde a una classe AgentEngine che contiene quanto segue:

  • un agent.api_resource con informazioni sull'agente di cui è stato eseguito il deployment. Puoi anche chiamare agent.operation_schemas() per restituire l'elenco delle operazioni supportate dall'agente. Per maggiori dettagli, vedi Operazioni supportate.
  • un agent.api_client che consente interazioni di servizio sincrone
  • un agent.async_api_client che consente interazioni di servizio asincrone

Il resto di questa sezione presuppone che tu abbia 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.

Interrogare l'agente

Il comando:

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

è equivalente al seguente (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 tra 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 supportata 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 di una chiamata di strumento al modello dopo che sono stati recuperati dati o elaborazioni esterni.

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

Interrogare l'agente con contenuti multimodali

Utilizzeremo il seguente agente (che inoltra l'input al modello e non utilizza alcuno strumento) 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