Python-Laufzeitreferenz

Sie können Python-Code in Python-Tools und in Callbacks verwenden. In dieser Referenz werden die Python-Laufzeit, Importoptionen und -klassen, globale Variablen und Funktionen beschrieben, die Sie in Ihrem Code verwenden können.

Python-Umgebung

Python-Tools und ‑Callbacks werden in einer sicheren Sandbox-Umgebung ausgeführt. In dieser Umgebung wird Python 3.12 ausgeführt.

Importe

Sie können nur die folgenden Module importieren:

Klassen

AsyncTools

Alias-Klasse zum asynchronen Aufrufen von Tools. Weitere Informationen finden Sie unter Globale Variable async_tools.

Blob

Inline-Bytedaten.

Attribute:

Attribut Beschreibung
display_name: Optional[str] Anzeigename der Blob. Wird verwendet, um ein Label oder einen Dateinamen zur Unterscheidung von Blobs anzugeben.
data: Optional[bytes] Base64-codierte Bytes.
raw_data: Optional[bytes] Roh decodierte Byte.
mime_type: Optional[str] Der IANA-Standard-MIME-Typ der Quelldaten.

Methoden:

Methode Beschreibung
transcript() -> Optional[str] Gibt ein im Cache gespeichertes Transkript für die Blob-Daten zurück, sofern verfügbar. Dies gilt nur für Audio-Blobs.
from_json(data: str) -> Blob Eine Klassenmethode zum Erstellen einer Blob-Instanz aus einem JSON-String, wobei mime_type auf „application/json“ festgelegt ist.

Beispiele:

# 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

Die Sitzungsinformationen, die während eines Rückrufs verfügbar sind.

Attribute:

Attribut Beschreibung
user_content: Optional[Content] Die letzten Eingaben des Nutzers.
invocation_id: str Eindeutige Kennung für den jeweiligen Callback-Aufruf, die für das Debugging nützlich ist.
agent_name: str Anzeigename des Agents, der mit dem aktuellen Rückruf verknüpft ist.
session_id: str Eindeutige Sitzungs-ID der aktuellen Sitzung.
variables: dict[str, Any] Wörterbuch mit Schlüssel/Wert-Paaren von Variablen, die entweder zur Designzeit definiert oder zur Laufzeit eingefügt werden. Dies ist der aktuelle Status der Variablen zum Zeitpunkt der Callback-Ausführung.
state: dict[str, Any] Entspricht dem Attribut variables.
events: list[Event] Sitzungsereignisse.

Methoden:

Methode Beschreibung
get_variable(key: str, default: Any) -> Any Ruft eine Variable aus dem Status ab. Wenn die Variable nicht vorhanden ist, wird der Standardwert zurückgegeben.
set_variable(key: str, value: Any) -> None Legt eine Variable im Status fest.
remove_variable(key: str) -> None Entfernt eine Variable aus dem Status.
get_last_user_input() -> list[Part] Ruft eine Liste aller Teile im letzten Chunk von Nutzerereignissen ab.
get_last_agent_output() -> list[Part] Ruft eine Liste aller Teile im letzten Chunk von Agent-Ereignissen ab.
parts() -> list[Part] Eine Liste aller Teile, die im Sitzungsverlauf aufgezeichnet wurden.

Content

Nachrichteninhalte von Nutzern oder Kundenservicemitarbeitern.

Attribute:

Attribut Beschreibung
parts: Optional[list[Part]] Liste der Teile, aus denen eine einzelne Nachricht besteht. Jeder Teil kann einen anderen IANA-MIME-Typ haben.
role: Optional[str] Die Rolle des Autors des Inhalts. 'user' oder 'agent'.

Methoden:

Methode Beschreibung
is_user() -> bool Gibt True zurück, wenn die Rolle 'user' ist.
is_model() -> bool Gibt True zurück, wenn die Rolle 'model' ist.

Event

Darstellung eines Ereignisses in der Sitzung.

Attribute:

Attribut Beschreibung
id: str Ereignis-ID.
invocation_id: str Kennung für den Ereignisaufruf.
author: str „user“ oder der Name des Agents, der angibt, wer an der Sitzung teilgenommen hat.
timestamp: int Zeitstempel des Ereignisses.
content: Content Die mit diesem Ereignis verknüpften Inhalte.
actions: EventActions Die vom Agent ausgeführten Aktionen.
long_running_tool_ids: set[str] Eine Reihe von Kennungen der Funktionsaufrufe mit langer Ausführungszeit.
partial: bool True für unvollständige Chunks aus der Streamingantwort des LLM.
turn_complete: bool True, wenn der aktuelle Zug abgeschlossen ist.
error_code: str Fehlercode.
error_message: str Fehlermeldung
interrupted: bool True, wenn der Zug unterbrochen wurde.
branch: str Der Zweig des Ereignisses.

Das Format ist wie agent_1.agent_2.agent_3, wobei agent_1 das übergeordnete Element von agent_2 und agent_2 das übergeordnete Element von agent_3 ist.

„Branch“ wird verwendet, wenn mehrere untergeordnete Kundenservicemitarbeiter den Unterhaltungsverlauf ihrer Kollegen nicht sehen sollen.
grounding_metadata: Any Die Fundierungsmetadaten des Ereignisses.

Methoden:

Methode Beschreibung
is_user() -> bool True, wenn der Autor des Ereignisses „user“ ist.
is_agent(agent_name: Optional[str] = None) -> bool True, wenn der Autor des Ereignisses ein Agent ist. Wenn agent_name angegeben ist, wird geprüft, ob der Autor mit diesem bestimmten Agent übereinstimmt.
has_error() -> bool True, wenn dem Ereignis ein Fehlercode zugeordnet ist.
parts() -> list[Part] Eine Hilfsmethode zum Abrufen der Liste der Part-Objekte aus dem content des Ereignisses. Gibt eine leere Liste zurück, wenn es keinen Inhalt oder keine Teile gibt.

EventActions

Aktionen, die für Ereignisse ausgeführt werden.

Attribute:

Attribut Beschreibung
skip_summarization: bool Bei True wird das Modell nicht aufgerufen, um die Funktionsantwort zusammenzufassen. Wird nur für das function_response-Ereignis verwendet.
state_delta: dict[str,Any] Die Änderungen an Variablen, die durch dieses Ereignis verursacht wurden.
artifact_delta: dict[str,Any] Die Änderungen an Artefakten durch dieses Ereignis. Der Schlüssel ist der Dateiname, der Wert die Version.
transfer_to_agent: str Wenn festgelegt, wird das Ereignis an den angegebenen Agent übertragen.
escalate: bool Der Kundenservicemitarbeiter eskaliert den Fall an einen übergeordneten Kundenservicemitarbeiter.
requested_auth_configs: dict[str,dict[str,Any]] Von Tool-Antworten angeforderte Authentifizierungskonfigurationen.

Dieses Feld wird nur von einem Tool-Antwort-Ereignis festgelegt, das Authentifizierungsanmeldedaten für Tool-Anfragen angibt.

Schlüssel: Die Funktionsaufruf-ID. Ein Funktionsantwort-Ereignis kann mehrere Funktionsantworten enthalten, die mehreren Funktionsaufrufen entsprechen. Für jeden Funktionsaufruf können unterschiedliche Authentifizierungskonfigurationen angefordert werden. Diese Kennung wird verwendet, um den Funktionsaufruf zu identifizieren.

Werte: Die angeforderte Auth-Konfiguration.
end_invocation: bool Die Agent-Schleife wird unterbrochen.

ExternalResponse

Stellt eine Antwort von außerhalb der Python-Umgebung dar, z. B. einen Toolaufruf oder eine HTTP-Anfrage.

Attribute:

Attribut Beschreibung
text: str Der Antworttext als String.
status_code: int Der HTTP-Statuscode.
reason: str Der Grund, warum der Fehler ausgegeben wird. Leer, wenn kein Fehler vorliegt.
ok: bool True, wenn status_code kleiner als 400 ist, andernfalls False.

Methoden:

Methode Beschreibung
json() -> Any Parst das JSON-Attribut „text“ und gibt das Ergebnis zurück. Wenn das Parsen fehlschlägt, wird ein Fehler ausgegeben.
raise_for_status() Löst einen StatusError aus, wenn die Antwort nicht in Ordnung ist (ok == False).

FunctionCall

Stellt einen Funktionsaufruf dar.

Attribute:

Attribut Beschreibung
id: Optional[str] Die eindeutige ID des Funktionsaufrufs.
args: Optional[dict[str,Any]] Die Funktionsparameter und -werte im JSON-Objektformat.
name: Optional[str] Funktionsname.

FunctionDeclaration

Ein vorhergesagter FunctionCall, der vom Modell zurückgegeben wird und einen String enthält, der das Attribut FunctionDeclaration name mit den Parametern und ihren Werten darstellt.

Attribute:

Attribut Beschreibung
name: Optional[str] Funktionsname.

FunctionResponse

Das Ergebnis von FunctionCall, das einen String mit dem FunctionDeclaration-Attribut name und ein strukturiertes JSON-Objekt mit der Ausgabe des Funktionsaufrufs enthält. Sie wird als Kontext für das Modell verwendet.

Attribute:

Attribut Beschreibung
id: Optional[str] Kennung des entsprechenden Funktionsaufrufs.
name: Optional[str] Funktionsname.
response: Optional[dict[str,Any]] Die Funktionsantwort im JSON-Objektformat. Verwenden Sie den Schlüssel „output“, um die Funktionsausgabe anzugeben, und den Schlüssel „error“, um Fehlerdetails anzugeben (falls vorhanden). Wenn die Schlüssel „output“ und „error“ nicht angegeben sind, wird die gesamte „response“ als Funktionsausgabe behandelt.

GenerateContentConfig

Optionale Parameter für die Modellkonfiguration.

Attribute:

Attribut Beschreibung
system_instruction: Optional[Content] Anleitung für das Modell, um es zu einer besseren Leistung zu steuern. Beispiel: „Antworten Sie so kurz wie möglich“ oder „Verwenden Sie in Ihrer Antwort keine technischen Begriffe“.
tools: Optional[list[ToolDeclaration]] Eine Liste der verfügbaren Tools, die das Modell ausführen kann.
excluded_tools: Optional[list[str]] Eine Liste mit Tool-Namen, die vom Modell ignoriert werden. Dadurch wird tools überschrieben.

Methoden:

Methode Beschreibung
hide_tool(tool_name: str) Fügt tool_name zur Liste excluded_tools hinzu.

HttpMethod

Ein String-Enum, das eine HTTP-Methode darstellt. Die möglichen Werte sind:

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

LlmRequest

Datenmodelle zur Darstellung von Anfragen an das LLM.

Attribute:

Attribut Beschreibung
model: Optional[str] Modellname
contents: List[Content] Eine Liste der Inhalte, die an das Modell gesendet wurden.
config: Optional[GeneralContentConfig] Parameter für die Modellkonfiguration.

LlmResponse

Datenmodelle zur Darstellung von Antworten des LLM.

Attribute:

Attribut Beschreibung
content: Content Die erste Content-Instanz, mit der das Modell antwortet.
partial: Optional[bool] Gibt an, ob die Inhalte eine unvollständige Modellantwort darstellen. Der Agent setzt die Verarbeitung fort, nachdem er die Teilantwort ausgegeben hat.

Methoden:

Methode Beschreibung
from_parts(parts: list[Part]) -> LlmResponse Klassenmethode, die ein LlmResponse aus dem Modell zurückgibt.

Beispiele:

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

Part

Ein Datentyp mit Medieninhalten. Genau ein Feld in einem Part sollte festgelegt werden, das den jeweiligen Inhaltstyp darstellt. Die Verwendung mehrerer Felder in derselben Part-Instanz ist ungültig.

Attribute:

Attribut Beschreibung
function_call: Optional[FunctionCall] Ein vorhergesagter FunctionCall, der vom Modell zurückgegeben wird und einen String enthält, der den Funktionsnamen und ein strukturiertes JSON-Objekt enthält, das die Parameter und ihre Werte enthält.
function_response: Optional[FunctionResponse] Die Ergebnisausgabe von FunctionCall, die einen String mit dem Funktionsnamen und ein strukturiertes JSON-Objekt mit der Ausgabe des Funktionsaufrufs enthält. Sie wird als Kontext für das Modell verwendet.
text: Optional[str] Der Text der Nachricht.
inline_data: Optional[Blob] Inline-Bytedaten.

Methoden:

Methode Beschreibung
text_or_transcript() -> Optional[str] Gibt den Text zurück, sofern verfügbar. Andernfalls wird das Transkript der Inline-Daten zurückgegeben.
has_function_call(name) -> bool Gibt True zurück, wenn der Teil einen bestimmten Funktionsaufruf enthält.
has_function_response(name) -> bool Gibt True zurück, wenn der Teil eine bestimmte Funktionsantwort enthält.
from_text(text: str) -> Part Klassenmethode, mit der ein Text-Part erstellt wird.
from_function_call(name: str, args: dict[str, Any]) -> Part Klassenmethode, die einen Funktionsaufruf Part erstellt.
from_function_response(name: str, response: dict[str, Any]) -> Part Klassenmethode, die eine Funktionsantwort Part erstellt.
from_inline_data(data: bytes, mime_type: str) -> Part Klassenmethode zum Erstellen von Inline-Daten Part.
from_json(data: str) -> Part Klassenmethode, mit der Inline-JSON-Daten Part erstellt werden.
from_agent_transfer(agent: str) -> Part Klassenmethode, die ein Part für die Übertragung an einen anderen Agent erstellt.
from_end_session(*, reason: str, escalated: bool = False) -> Part Klassenmethode, mit der ein Part zum Beenden der Sitzung erstellt wird.
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part Klassenmethode, die ein Part für die Antwort mit benutzerdefiniertem Verhalten erstellt (z. B. Deaktivieren von Barge-in, Aktivieren von DTMF-Eingabe usw.).

Beispiele:

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

Alias-Klasse zum Stellen von HTTP-Anfragen. Weitere Informationen finden Sie unter Globale Variable „ces_requests“.

Methoden:

  • 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

Wird für Fehler verwendet, die mit einem Statuscode ausgelöst werden.

Attribute:

Attribut Beschreibung
status_code: int Der mit diesem Fehler verknüpfte HTTP-Statuscode.
reason: str Der Grund, warum der Fehler ausgegeben wird.

Tool

Stellt ein Tool mit einem Namen und einer Beschreibung dar.

Attribute:

Attribut Beschreibung
name: str Der Name des Tools.
description: str Eine Beschreibung der Funktion des Tools.

ToolContext

Abgeleitet von CallbackContext. Die Sitzungsinformationen, die beim Ausführen eines Tools verfügbar sind.

Attribute:

Attribut Beschreibung
function_call_id: str Die Funktionsaufruf-ID des aktuellen Tool-Aufrufs, der ausgeführt wird.

Tools

Alias-Klasse zum synchronen Aufrufen von Tools. Weitere Informationen finden Sie unter Globale Variable „tools“.

ToolDeclaration

Ein Tool-Schema, das dem Modell angezeigt werden kann.

Attribute:

Attribut Beschreibung
function_declarations: Optional[list[FunctionDeclaration]] Liste der Funktionsdeklarationen, die vom Tool unterstützt werden.

Funktionen

get_variable

Mit dieser Funktion wird ein Wert aus dem Sitzungsstatus mit dem angegebenen Schlüssel abgerufen. Sie dient als Abkürzung für context.state.get(key) oder context.variables.get(key).

Beispielcode:

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

Mit dieser Funktion wird ein Schlüssel/Wert-Paar aus dem Sitzungsstatus entfernt. Dies ist eine Abkürzung für del context.state[key].

Beispielcode:

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

set_variable

Mit dieser Funktion wird ein Wert für einen bestimmten Schlüssel im Sitzungsstatus festgelegt. Wenn der Schlüssel bereits vorhanden ist, wird sein Wert aktualisiert. Es ist eine Tastenkombination für context.state[key] = value.

Beispielcode:

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

Globale Variablen

async_tools

Eine Instanz von AsyncTools, mit der Sie asynchrone Aufrufe an Tools ausführen können.

Beispiele:

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

Eine Instanz von Requests. Mit Requests können Sie HTTP-Aufrufe mit einer ähnlichen Syntax wie beim beliebten Python-Modul „requests“ ausführen.

Beispiele:

# 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

Eine Instanz von Tools, mit der Sie synchrone Aufrufe an Tools ausführen können.

Beispiele:

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

In Ihrem Code können Sie auf den ADK-Kontext zugreifen, mit dem viele Arten von ADK-Kontextdaten gelesen und geschrieben werden können. In Ihrem Code können Sie die globale Variable context verwenden.

Die Objekte context.state und context.variables sind austauschbar. Das state-Objekt wird zur Kompatibilität mit ADK-Code unterstützt. In neuem Code sollte jedoch das variables-Objekt verwendet werden.