Riferimento al runtime Python

Puoi utilizzare il codice Python negli strumenti Python e nei callback. Questo riferimento descrive il runtime Python, le opzioni e le classi di importazione, le variabili globali e le funzioni che puoi utilizzare nel tuo codice.

Ambiente Python

Gli strumenti e i callback Python vengono eseguiti in un ambiente sandbox sicuro. Questo ambiente esegue Python 3.12.

Importazioni

La possibilità di importare moduli è limitata a quanto segue:

Classi

AsyncTools

Classe alias per chiamare gli strumenti in modo asincrono. Per ulteriori informazioni, consulta la variabile globale async_tools.

Blob

Dati dei byte incorporati.

Attributi:

Attributo Descrizione
display_name: Optional[str] Nome visualizzato di Blob. Utilizzato per fornire un'etichetta o un nome file per distinguere i blob.
data: Optional[bytes] Byte con codifica Base64.
raw_data: Optional[bytes] Byte decodificati non elaborati.
mime_type: Optional[str] Il tipo MIME standard IANA dei dati di origine.

Metodi:

Metodo Descrizione
transcript() -> Optional[str] Restituisce una trascrizione memorizzata nella cache per i dati Blob, se disponibile. Questo vale solo per i blob audio.
from_json(data: str) -> Blob Un metodo di classe per creare un'istanza Blob da una stringa JSON, con mime_type impostato su "application/json".

Esempi:

# Create a blob from raw bytes
blob = Blob(mime_type='text/plain')
blob.raw_data = b'hello world'

# Create a blob from a JSON string
Blob.from_json(data='{"key": "value"}')

CallbackContext

Le informazioni sulla sessione disponibili durante un richiamo.

Attributi:

Attributo Descrizione
user_content: Optional[Content] Gli input più recenti dell'utente.
invocation_id: str Identificatore univoco per la chiamata di callback specifica, utile per il debug.
agent_name: str Nome visualizzato dell'agente associato al richiamo corrente.
session_id: str Identificatore univoco della sessione corrente in corso.
variables: dict[str, Any] Dizionario contenente coppie chiave-valore di variabili definite in fase di progettazione o inserite in fase di runtime. Questo è lo stato attuale delle variabili al momento dell'esecuzione del callback.
state: dict[str, Any] Uguale alla proprietà variables.
events: list[Event] Eventi di sessione.

Metodi:

Metodo Descrizione
get_variable(key: str, default: Any) -> Any Recupera una variabile dallo stato. Se la variabile non esiste, restituisci il valore predefinito.
set_variable(key: str, value: Any) -> None Imposta una variabile nello stato.
remove_variable(key: str) -> None Rimuove una variabile dallo stato.
get_last_user_input() -> list[Part] Recupera un elenco di tutte le parti nell'ultimo blocco di eventi utente.
get_last_agent_output() -> list[Part] Restituisce un elenco di tutte le parti dell'ultimo blocco di eventi dell'agente.
parts() -> list[Part] Un elenco di tutte le parti registrate nella cronologia della sessione.

Content

Contenuti del messaggio dell'utente o dell'agente.

Attributi:

Attributo Descrizione
parts: Optional[list[Part]] Elenco delle parti che costituiscono un singolo messaggio. Ogni parte può avere un tipo MIME IANA diverso.
role: Optional[str] Il ruolo dell'autore dei contenuti. 'user' o 'agent'.

Metodi:

Metodo Descrizione
is_user() -> bool Restituisce True se il ruolo è 'user'.
is_model() -> bool Restituisce True se il ruolo è 'model'.

Event

Rappresentazione di un evento nella sessione.

Attributi:

Attributo Descrizione
id: str Identificatore dell'evento.
invocation_id: str Identificatore di chiamata dell'evento.
author: str "user" o il nome dell'agente, che indica chi ha partecipato all'evento nella sessione.
timestamp: int Timestamp dell'evento.
content: Content I contenuti associati a questo evento.
actions: EventActions Le azioni intraprese dall'agente.
long_running_tool_ids: set[str] Set di identificatori delle chiamate di funzione a lunga esecuzione.
partial: bool True per i blocchi incompleti della risposta dinamica dell'LLM.
turn_complete: bool True se il turno corrente è completato.
error_code: str Codice di errore.
error_message: str Messaggio di errore.
interrupted: bool True se la svolta è stata interrotta.
branch: str Il ramo dell'evento.

Il formato è simile a agent_1.agent_2.agent_3, dove agent_1 è il genitore di agent_2 e agent_2 è il genitore di agent_3.

Il ramo viene utilizzato quando più subagenti non devono visualizzare la cronologia delle conversazioni dei loro colleghi.
grounding_metadata: Any I metadati di base dell'evento.

Metodi:

Metodo Descrizione
is_user() -> bool True se l'autore dell'evento è "utente".
is_agent(agent_name: Optional[str] = None) -> bool True se l'autore dell'evento è un agente. Se viene fornito agent_name, viene verificato se l'autore corrisponde a quell'agente specifico.
has_error() -> bool True se l'evento ha un codice di errore associato.
parts() -> list[Part] Un metodo pratico per ottenere l'elenco degli oggetti Part da content dell'evento. Restituisce un elenco vuoto se non sono presenti contenuti o parti.

EventActions

Azioni che si verificano per gli eventi.

Attributi:

Attributo Descrizione
skip_summarization: bool Se True, il modello non viene chiamato per riassumere la risposta della funzione. Utilizzato solo per l'evento function_response.
state_delta: dict[str,Any] Le modifiche alle variabili causate da questo evento.
artifact_delta: dict[str,Any] Le modifiche agli artefatti apportate da questo evento. La chiave è il nome del file, il valore è la versione.
transfer_to_agent: str Se impostato, l'evento viene trasferito all'agente specificato.
escalate: bool L'agente sta riassegnando la richiesta a un agente di livello superiore.
requested_auth_configs: dict[str,dict[str,Any]] Configurazioni di autenticazione richieste dalle risposte dello strumento.

Questo campo può essere impostato solo da un evento di risposta dello strumento che indica le credenziali di autenticazione della richiesta dello strumento.

Chiavi: l'identificatore della chiamata di funzione. Poiché un evento di risposta della funzione potrebbe contenere più risposte della funzione che corrispondono a più chiamate di funzione. Ogni chiamata di funzione può richiedere configurazioni di autenticazione diverse. Questo identificatore viene utilizzato per identificare la chiamata di funzione.

Valori: la configurazione di autenticazione richiesta.
end_invocation: bool Il ciclo dell'agente viene interrotto.

ExternalResponse

Rappresenta una risposta proveniente dall'esterno dell'ambiente Python, ad esempio una chiamata allo strumento o una richiesta HTTP.

Attributi:

Attributo Descrizione
text: str Il corpo della risposta come stringa.
status_code: int Il codice di stato HTTP.
reason: str Il motivo per cui viene generato l'errore. Vuoto se non sono presenti errori.
ok: bool True se status_code è inferiore a 400, altrimenti False.

Metodi:

Metodo Descrizione
json() -> Any Analizza il JSON dell'attributo di testo e restituisce il risultato. Se l'analisi non riesce, verrà generato un errore.
raise_for_status() Genera un StatusError se la risposta non è OK (ok == False).

FunctionCall

Rappresenta una chiamata di funzione.

Attributi:

Attributo Descrizione
id: Optional[str] L'identificatore univoco della chiamata di funzione.
args: Optional[dict[str,Any]] I parametri e i valori della funzione in formato oggetto JSON.
name: Optional[str] Nome della funzione.

FunctionDeclaration

Un FunctionCall previsto restituito dal modello che contiene una stringa che rappresenta l'attributo FunctionDeclaration name con i parametri e i relativi valori.

Attributi:

Attributo Descrizione
name: Optional[str] Nome della funzione.

FunctionResponse

Il risultato di un FunctionCall che contiene una stringa che rappresenta l'attributo FunctionDeclaration name e un oggetto JSON strutturato contenente l'output della chiamata di funzione. Viene utilizzato come contesto per il modello.

Attributi:

Attributo Descrizione
id: Optional[str] Identificatore della chiamata di funzione corrispondente.
name: Optional[str] Nome della funzione.
response: Optional[dict[str,Any]] La risposta della funzione in formato oggetto JSON. Utilizza la chiave "output" per specificare l'output della funzione e la chiave "error" per specificare i dettagli dell'errore (se presenti). Se le chiavi "output" ed "error" non sono specificate, l'intera "response" viene trattata come output della funzione.

GenerateContentConfig

Parametri di configurazione del modello facoltativi.

Attributi:

Attributo Descrizione
system_instruction: Optional[Content] Istruzioni per il modello per indirizzarlo verso prestazioni migliori. Ad esempio, "Rispondi nel modo più conciso possibile" o "Non utilizzare termini tecnici nella risposta".
tools: Optional[list[ToolDeclaration]] Un elenco degli strumenti disponibili che il modello può eseguire.
excluded_tools: Optional[list[str]] Un elenco di nomi di strumenti che verranno ignorati dal modello. Questa azione sostituisce tools.

Metodi:

Metodo Descrizione
hide_tool(tool_name: str) Aggiunge tool_name all'elenco excluded_tools.

HttpMethod

Un enum stringa per rappresentare un metodo HTTP. I valori possibili sono:

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS

LlmRequest

Modelli di dati per rappresentare le richieste al modello LLM.

Attributi:

Attributo Descrizione
model: Optional[str] Nome modello
contents: List[Content] Un elenco dei contenuti inviati al modello.
config: Optional[GeneralContentConfig] Parametri di configurazione del modello.

LlmResponse

Modelli di dati per rappresentare le risposte dell'LLM.

Attributi:

Attributo Descrizione
content: Content Il primo Content con cui risponde il modello.
partial: Optional[bool] Indica se i contenuti rappresentano una risposta incompleta del modello. L'agente continuerà l'elaborazione dopo aver emesso la risposta parziale.

Metodi:

Metodo Descrizione
from_parts(parts: list[Part]) -> LlmResponse Metodo della classe che restituisce un LlmResponse dal modello.

Esempi:

response = LlmResponse.from_parts(
  parts=[
    Part.from_text(text="hello world")
  ]
)

Part

Un tipo di dati contenente contenuti multimediali. Deve essere impostato esattamente un campo all'interno di un Part, che rappresenta il tipo specifico di contenuti trasmessi. L'utilizzo di più campi all'interno della stessa istanza Part è considerato non valido.

Attributi:

Attributo Descrizione
function_call: Optional[FunctionCall] Un FunctionCall previsto restituito dal modello che contiene una stringa che rappresenta il nome della funzione e un oggetto JSON strutturato contenente i parametri e i relativi valori.
function_response: Optional[FunctionResponse] L'output del risultato di FunctionCall che contiene una stringa che rappresenta il nome della funzione e un oggetto JSON strutturato contenente qualsiasi output della chiamata di funzione. Viene utilizzato come contesto per il modello.
text: Optional[str] Testo del messaggio.
inline_data: Optional[Blob] Dati dei byte incorporati.

Metodi:

Metodo Descrizione
text_or_transcript() -> Optional[str] Restituisce il testo, se disponibile, altrimenti restituisce la trascrizione dei dati in linea.
has_function_call(name) -> bool Restituisce True se la parte contiene una chiamata di funzione specifica.
has_function_response(name) -> bool Restituisce True se la parte contiene una risposta di funzione specifica.
from_text(text: str) -> Part Metodo della classe che crea un testo Part.
from_function_call(name: str, args: dict[str, Any]) -> Part Metodo della classe che crea una chiamata di funzione Part.
from_function_response(name: str, response: dict[str, Any]) -> Part Metodo della classe che crea una risposta della funzione Part.
from_inline_data(data: bytes, mime_type: str) -> Part Metodo della classe che crea un Part inline.
from_json(data: str) -> Part Metodo della classe che crea un Part di dati incorporati JSON.
from_agent_transfer(agent: str) -> Part Metodo della classe che crea un Part per il trasferimento a un altro agente.
from_end_session(*, reason: str, escalated: bool = False) -> Part Metodo della classe che crea un Part per terminare la sessione.
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part Metodo della classe che crea un Part per la risposta con un comportamento personalizzato (ad esempio, disattivare l'inserimento di cifre, attivare l'input DTMF e così via).

Esempi:

text_part = ces_public.Part.from_text(text="Hello from the user!")

tool_part = ces_public.Part.from_function_call(
  name="get_weather",
  args={"location": "Mountain View"}
)

Requests

Classe alias per l'esecuzione di richieste HTTP. Per saperne di più, consulta la variabile globale ces_requests.

Metodi:

  • get(url, params=None, **kwargs)
  • post(url, data=None, json=None, **kwargs)
  • put(url, data=None, json=None, **kwargs)
  • delete(url, **kwargs)
  • patch(url, data=None, json=None, **kwargs)
  • head(url, **kwargs)
  • options(url, **kwargs)

StatusError

Utilizzato per gli errori generati con un codice di stato.

Attributi:

Attributo Descrizione
status_code: int Il codice di stato HTTP associato a questo errore.
reason: str Il motivo per cui viene generato l'errore.

Tool

Rappresenta uno strumento con un nome e una descrizione.

Attributi:

Attributo Descrizione
name: str Il nome dello strumento.
description: str Una descrizione di ciò che fa lo strumento.

ToolContext

Derivato da CallbackContext. Le informazioni sulla sessione disponibili durante l'esecuzione di uno strumento.

Attributi:

Attributo Descrizione
function_call_id: str L'identificatore della chiamata di funzione della chiamata allo strumento corrente in esecuzione.

Tools

Classe alias per chiamare gli strumenti di chiamata in modo sincrono. Per ulteriori informazioni, consulta la variabile globale tools.

ToolDeclaration

Uno schema dello strumento che può essere mostrato al modello.

Attributi:

Attributo Descrizione
function_declarations: Optional[list[FunctionDeclaration]] Elenco delle dichiarazioni di funzioni supportate dallo strumento.

Funzioni

get_variable

Questa funzione recupera un valore dallo stato della sessione utilizzando la chiave fornita. Funge da scorciatoia per context.state.get(key) o context.variables.get(key).

Codice di esempio:

def get_a_value() -> int:
  # Retrieve the value of 'my_key' from the state
  my_value = get_variable('my_key')
  return my_value + 5

remove_variable

Questa funzione rimuove una coppia chiave-valore dallo stato della sessione. Questa è una scorciatoia per del context.state[key].

Codice di esempio:

def remove_a_value() -> None:
  # Delete 'my_key' from the state
  remove_variable('my_key')

set_variable

Questa funzione imposta un valore per una determinata chiave nello stato della sessione. Se la chiave esiste già, il suo valore verrà aggiornato. È una scorciatoia per context.state[key] = value.

Codice di esempio:

def set_a_value() -> None:
  # Set the value of 'my_key' to 10
  set_variable('my_key', 10)

Variabili globali

async_tools

Un'istanza di AsyncTools, che ti consente di effettuare chiamate asincrone agli strumenti.

Esempi:

response_future = async_tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)
# ... misc work
response = response_future() # poll for response

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

ces_requests

Un'istanza di Requests. Requests ti consentono di effettuare chiamate HTTP con una sintassi simile a quella del popolare modulo Python requests.

Esempi:

# Make a GET request
response = ces_requests.get('https://api.example.com/data')

# Check if the request was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

tools

Un'istanza di Tools, che ti consente di effettuare chiamate sincrone agli strumenti.

Esempi:

response = tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

context

Nel codice, puoi accedere al contesto ADK, che può essere utilizzato per leggere e scrivere molti tipi di dati di contesto ADK. Una variabile globale denominata context è disponibile per l'utilizzo nel codice.

Gli oggetti context.state e context.variables sono intercambiabili. L'oggetto state è supportato per la compatibilità con il codice ADK, ma il nuovo codice deve utilizzare l'oggetto variables.