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

Inlined-Bytedaten.

Attribute:

Attribut Beschreibung
display_name: Optional[str] Anzeigename des Blob. Wird verwendet, um ein Label oder einen Dateinamen zur Unterscheidung von Blobs anzugeben.
data: Optional[bytes] Base64-codierte Byte.
raw_data: Optional[bytes] Decodierte Rohbyte.
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, falls 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“ gesetzt 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 während eines Rückrufs verfügbaren Sitzungsinformationen.

Attribute:

Attribut Beschreibung
user_content: Optional[Content] Die letzten Eingaben des Nutzers.
invocation_id: str Eindeutige Kennung für den spezifischen Callback-Aufruf, nützlich für die Fehlerbehebung.
agent_name: str Anzeigename des KI-Agenten, der mit dem aktuellen Callback verknüpft ist.
session_id: str Eindeutige Sitzungs-ID der aktuellen Sitzung.
variables: dict[str, Any] Dictionary mit Schlüssel/Wert-Paaren von Variablen, die entweder bei der Entwicklung definiert oder zur Laufzeit eingefügt werden. Dies ist der aktuelle Status der Variablen zum Zeitpunkt der Callback-Ausführung.
state: dict[str, Any] Identisch mit 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 Block von Nutzerereignissen ab.
get_last_agent_output() -> list[Part] Ruft eine Liste aller Teile im letzten Block von Agent-Ereignissen ab.
parts() -> list[Part] Eine Liste aller im Sitzungsverlauf aufgezeichneten Teile.

Content

Nachrichteninhalt vom Nutzer oder Agenten.

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 des Ereignisaufrufs.
author: str „user“ oder der Name des KI-Agenten, 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 KI-Agenten ausgeführten Aktionen.
long_running_tool_ids: set[str] Satz von Kennungen der Funktionsaufrufe mit langer Ausführungszeit.
partial: bool True für unvollständige Chunks aus der LLM-Streamingantwort.
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 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.

Der Zweig wird verwendet, wenn mehrere Sub-Agenten den Unterhaltungsverlauf ihrer gleichrangigen Agenten 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 Agenten übereinstimmt.
has_error() -> bool True, wenn dem Ereignis ein Fehlercode zugeordnet ist.
parts() -> list[Part] Eine praktische Methode, um die Liste der Part-Objekte aus dem content des Ereignisses abzurufen. Gibt eine leere Liste zurück, wenn keine Inhalte oder Teile vorhanden sind.

EventActions

Aktionen, die bei Ereignissen ausgeführt werden.

Attribute:

Attribut Beschreibung
skip_summarization: bool Wenn True, wird das Modell nicht aufgerufen, um die Funktionsantwort zusammenzufassen. Wird nur für das Ereignis function_response verwendet.
state_delta: dict[str,Any] Die durch dieses Ereignis verursachten Änderungen an Variablen.
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 Agenten übertragen.
escalate: bool Der KI-Agent eskaliert die Anfrage an einen KI-Agenten einer höheren Stufe.
requested_auth_configs: dict[str,dict[str,Any]] Authentifizierungskonfigurationen, die von Toolantworten angefordert werden.

Dieses Feld wird nur von einem Toolantwort-Ereignis festgelegt, das die Authentifizierungsanmeldedaten für die Toolanfrage angibt.

Schlüssel: Die Kennung des Funktionsaufrufs. 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 Authentifizierungskonfiguration.
end_invocation: bool Die Agentenschleife 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 Textattribut JSON 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 Kennung 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 eines FunctionCall, das einen String enthält, der das Attribut FunctionDeclaration name darstellt, und ein strukturiertes JSON-Objekt, das alle Ausgaben des Funktionsaufrufs enthält. Sie wird als Kontext für das Modell verwendet.

Attribute:

Attribut Beschreibung
id: Optional[str] ID 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 (falls vorhanden) anzugeben. 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 von Toolnamen, 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] Modellkonfigurationsparameter.

LlmResponse

Datenmodelle zur Darstellung von Antworten des LLM.

Attribute:

Attribut Beschreibung
content: Content Die erste Content, mit der das Modell antwortet.
partial: Optional[bool] Gibt an, ob der Inhalt eine unvollständige Modellantwort darstellt. Der Agent setzt die Verarbeitung nach der Ausgabe der Teilantwort fort.

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. In einem Part sollte genau ein Feld festgelegt werden, das den spezifischen Typ des übertragenen Inhalts darstellt. Die Verwendung mehrerer Felder innerhalb 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 enthält, der den Funktionsnamen darstellt, und ein strukturiertes JSON-Objekt, das die 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] Inlined-Bytedaten.

Methoden:

Methode Beschreibung
text_or_transcript() -> Optional[str] Gibt den Text zurück, falls 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, die ein Text-Part erstellt.
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, die ein Inline-Daten-Part erstellt.
from_json(data: str) -> Part Klassenmethode, die ein JSON-Inline-Daten-Part erstellt.
from_agent_transfer(agent: str) -> Part Klassenmethode, die ein Part für die Übertragung an einen anderen Agenten erstellt.
from_end_session(*, reason: str, escalated: bool = False) -> Part Klassenmethode, die ein Part zum Beenden der Sitzung erstellt.
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 eine Part für eine Antwort mit benutzerdefiniertem Verhalten erstellt (z. B. Deaktivieren von Eingriffen, Aktivieren von DTMF-Eingaben 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 Senden 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 Funktionsaufrufkennung des aktuellen Toolaufrufs, der ausgeführt wird.

Tools

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

ToolDeclaration

Ein Toolschema, das dem Modell angezeigt werden kann.

Attribute:

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

Funktionen

get_variable

Diese Funktion ruft einen Wert aus dem Sitzungsstatus mithilfe des angegebenen Schlüssels ab. Er dient als Verknüpfung 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 Verknüpfung für del context.state[key].

Beispielcode:

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

set_variable

Diese Funktion legt einen Wert für einen bestimmten Schlüssel im Sitzungsstatus fest. Wenn der Schlüssel bereits vorhanden ist, wird sein Wert aktualisiert. Es ist eine Verknüpfung 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

_session

Sie können auf den aktuellen Kanal und die aktuelle Modalität für eine Unterhaltung zugreifen, ähnlich wie bei modularen Komponenten. Greifen Sie mit der vordefinierten Variablen _session auf diese Werte zu.

Beispiel für ein Python-Tool (mit der globalen Variable context):

def check_order_status(order_id: str) -> str:
  # Resolve modality and channel from the session state
  session_vars = context.variables.get('_session', {})
  modality = session_vars.get('modality', 'TEXT')
  channel = session_vars.get('channel', 'API')

  status = get_raw_order_status(order_id)  # Internal API lookup

  if modality == 'VOICE':
    # Keep response concise and remove markdown/links for natural TTS playback
    return "Your order has shipped and is estimated to arrive tomorrow."
  else:
    # Rich text with markdown links for Chat/Web interfaces
    return f"Your order shipped [Track it](https://shipper.com/{order_id})."

Beispiel für einen Callback (mit CallbackContext):

def before_agent_callback(callback_context: CallbackContext) -> None:
  session_vars = callback_context.get_variable('_session', {})
  modality = session_vars.get('modality', 'TEXT')
  channel = session_vars.get('channel', 'API')
  callback_context.set_variable('active_modality', modality)

async_tools

Eine Instanz von AsyncTools, mit der Sie asynchrone Aufrufe an Tools senden 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 das beliebte 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 senden 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 ist eine globale Variable namens context verfügbar.

Die Objekte context.state und context.variables sind austauschbar. Das state-Objekt wird aus Kompatibilitätsgründen mit ADK-Code unterstützt, aber neuer Code sollte das variables-Objekt verwenden.