Documentation de référence sur l'environnement d'exécution Python

Vous pouvez utiliser du code Python dans les outils Python et dans les rappels. Cette référence décrit l'environnement d'exécution Python, les options et classes d'importation, les variables globales et les fonctions que vous pouvez utiliser dans votre code.

Environnement Python

Les outils et les rappels Python s'exécutent dans un environnement de bac à sable sécurisé. Cet environnement exécute Python 3.12.

Importations

Vous ne pouvez importer que les modules suivants :

Classes

AsyncTools

Classe d'alias pour appeler des outils de manière asynchrone. Pour en savoir plus, consultez la section Variable globale async_tools.

Blob

Données d'octets intégrés.

Attributs :

Attribut Description
display_name: Optional[str] Nom à afficher du Blob. Permet de fournir un libellé ou un nom de fichier pour distinguer les blobs.
data: Optional[bytes] Octets encodés en base64.
raw_data: Optional[bytes] Octets bruts décodés.
mime_type: Optional[str] Type MIME standard IANA des données sources.

Méthodes :

Méthode Description
transcript() -> Optional[str] Renvoie une transcription mise en cache pour les données Blob, si disponible. Cela ne s'applique qu'aux blobs audio.
from_json(data: str) -> Blob Méthode de classe permettant de créer une instance Blob à partir d'une chaîne JSON, avec mime_type défini sur "application/json".

Exemples :

# 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

Informations sur la session disponibles lors d'un rappel.

Attributs :

Attribut Description
user_content: Optional[Content] Entrées les plus récentes de l'utilisateur.
invocation_id: str Identifiant unique de l'invocation de rappel spécifique, utile pour le débogage.
agent_name: str Nom à afficher de l'agent associé au rappel actuel.
session_id: str Identifiant de session unique de la session en cours.
variables: dict[str, Any] Dictionnaire contenant des paires clé/valeur de variables définies au moment de la conception ou injectées lors de l'exécution. Il s'agit de l'état actuel des variables au moment de l'exécution du rappel.
state: dict[str, Any] Identique à la propriété variables.
events: list[Event] Événements de session.

Méthodes :

Méthode Description
get_variable(key: str, default: Any) -> Any Récupère une variable de l'état. Si la variable n'existe pas, renvoie la valeur par défaut.
set_variable(key: str, value: Any) -> None Définit une variable dans l'état.
remove_variable(key: str) -> None Supprime une variable de l'état.
get_last_user_input() -> list[Part] Obtient la liste de toutes les parties du dernier bloc d'événements utilisateur.
get_last_agent_output() -> list[Part] Obtient la liste de toutes les parties du dernier bloc d'événements de l'agent.
parts() -> list[Part] Liste de toutes les parties enregistrées dans l'historique des sessions.

Content

Contenu du message de l'utilisateur ou de l'agent.

Attributs :

Attribut Description
parts: Optional[list[Part]] Liste des parties qui composent un seul message. Chaque partie peut avoir un type MIME IANA différent.
role: Optional[str] Rôle de l'auteur du contenu. 'user' ou 'agent'.

Méthodes :

Méthode Description
is_user() -> bool Renvoie True si le rôle est 'user'.
is_model() -> bool Renvoie True si le rôle est 'model'.

Event

Représentation d'un événement dans la session.

Attributs :

Attribut Description
id: str Identifiant de l'événement.
invocation_id: str Identifiant d'invocation de l'événement.
author: str "user" ou le nom de l'agent, indiquant qui a participé à l'événement de la session.
timestamp: int Code temporel de l'événement.
content: Content Contenu associé à cet événement.
actions: EventActions Actions effectuées par l'agent.
long_running_tool_ids: set[str] Ensemble d'identifiants des appels de fonction de longue durée.
partial: bool True pour les blocs incomplets de la réponse en streaming du LLM.
turn_complete: bool True si le tour actuel est terminé.
error_code: str Code d'erreur.
error_message: str Message d'erreur
interrupted: bool True si le tour a été interrompu.
branch: str Branche de l'événement.

Le format est semblable à agent_1.agent_2.agent_3, où agent_1 est le parent de agent_2 et agent_2 est le parent de agent_3.

La branche est utilisée lorsque plusieurs sous-agents ne doivent pas voir l'historique des conversations de leurs agents pairs.
grounding_metadata: Any Métadonnées d'ancrage de l'événement.

Méthodes :

Méthode Description
is_user() -> bool True si l'auteur de l'événement est "user".
is_agent(agent_name: Optional[str] = None) -> bool True si l'auteur de l'événement est un agent. Si agent_name est fourni, il vérifie si l'auteur correspond à cet agent spécifique.
has_error() -> bool True si l'événement est associé à un code d'erreur.
parts() -> list[Part] Méthode pratique pour obtenir la liste des objets Part à partir de content de l'événement. Renvoie une liste vide s'il n'y a pas de contenu ni de pièces.

EventActions

Actions qui se produisent pour les événements.

Attributs :

Attribut Description
skip_summarization: bool Si la valeur est True, le modèle n'est pas appelé pour résumer la réponse de la fonction. Utilisé uniquement pour l'événement function_response.
state_delta: dict[str,Any] Modifications apportées aux variables par cet événement.
artifact_delta: dict[str,Any] Modifications apportées aux artefacts par cet événement. La clé correspond au nom de fichier et la valeur à la version.
transfer_to_agent: str Si ce champ est défini, l'événement est transféré à l'agent spécifié.
escalate: bool L'agent transmet la demande à un agent de niveau supérieur.
requested_auth_configs: dict[str,dict[str,Any]] Configurations d'authentification demandées par les réponses de l'outil.

Ce champ ne peut être défini que par un événement de réponse d'outil indiquant les identifiants d'authentification de la requête de l'outil.

Clés : identifiant de l'appel de fonction. Étant donné qu'un événement de réponse de fonction peut contenir plusieurs réponses de fonction correspondant à plusieurs appels de fonction. Chaque appel de fonction peut demander des configurations d'authentification différentes. Cet identifiant permet d'identifier l'appel de fonction.

Valeurs : la configuration d'authentification demandée.
end_invocation: bool La boucle de l'agent est interrompue.

ExternalResponse

Représente une réponse provenant de l'extérieur de l'environnement Python, comme un appel d'outil ou une requête HTTP.

Attributs :

Attribut Description
text: str Corps de la réponse sous forme de chaîne.
status_code: int Code d'état HTTP.
reason: str Raison pour laquelle l'erreur est générée. Vide si aucune erreur.
ok: bool True si status_code est inférieur à 400, sinon False.

Méthodes :

Méthode Description
json() -> Any Analyse le JSON de l'attribut de texte et renvoie le résultat. Si l'analyse échoue, une erreur est générée.
raise_for_status() Génère une StatusError si la réponse n'est pas OK (ok == False).

FunctionCall

Représente un appel de fonction.

Attributs :

Attribut Description
id: Optional[str] Identifiant unique de l'appel de fonction.
args: Optional[dict[str,Any]] Paramètres et valeurs de la fonction au format d'objet JSON.
name: Optional[str] Nom de la fonction.

FunctionDeclaration

FunctionCall prédit renvoyé par le modèle et qui contient une chaîne représentant l'attribut FunctionDeclaration name avec les paramètres et leurs valeurs.

Attributs :

Attribut Description
name: Optional[str] Nom de la fonction.

FunctionResponse

Résultat d'un FunctionCall contenant une chaîne représentant l'attribut FunctionDeclaration name et un objet JSON structuré contenant tout résultat de l'appel de fonction. Il sert de contexte au modèle.

Attributs :

Attribut Description
id: Optional[str] Identifiant de l'appel de fonction correspondant.
name: Optional[str] Nom de la fonction.
response: Optional[dict[str,Any]] Réponse de la fonction au format d'objet JSON. Utilisez la clé "output" pour spécifier la sortie de la fonction et la clé "error" pour spécifier les détails de l'erreur (le cas échéant). Si les clés "output" et "error" ne sont pas spécifiées, l'ensemble de la "response" est traité comme une sortie de fonction.

GenerateContentConfig

Paramètres de configuration du modèle facultatifs.

Attributs :

Attribut Description
system_instruction: Optional[Content] Instructions permettant au modèle d'améliorer ses performances. Par exemple, "Réponds de manière aussi concise que possible" ou "N'utilise pas de termes techniques dans ta réponse".
tools: Optional[list[ToolDeclaration]] Liste des outils disponibles que le modèle peut exécuter.
excluded_tools: Optional[list[str]] Liste des noms d'outils qui seront ignorés par le modèle. Cela remplace tools.

Méthodes :

Méthode Description
hide_tool(tool_name: str) Ajoute tool_name à la liste excluded_tools.

HttpMethod

Énumération de chaînes représentant une méthode HTTP. Les valeurs possibles sont :

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

LlmRequest

Modèles de données pour représenter les requêtes adressées au LLM.

Attributs :

Attribut Description
model: Optional[str] Nom du modèle
contents: List[Content] Liste des contenus envoyés au modèle.
config: Optional[GeneralContentConfig] Paramètres de configuration du modèle.

LlmResponse

Modèles de données pour représenter les réponses du LLM.

Attributs :

Attribut Description
content: Content Le premier Content auquel le modèle répond.
partial: Optional[bool] Indique si le contenu représente une réponse incomplète du modèle. L'agent poursuit le traitement après avoir émis la réponse partielle.

Méthodes :

Méthode Description
from_parts(parts: list[Part]) -> LlmResponse Méthode de classe qui renvoie un LlmResponse à partir du modèle.

Exemples :

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

Part

Type de données contenant du contenu multimédia. Un seul champ d'un Part doit être défini. Il représente le type de contenu spécifique transmis. L'utilisation de plusieurs champs dans la même instance Part est considérée comme non valide.

Attributs :

Attribut Description
function_call: Optional[FunctionCall] FunctionCall prédit renvoyé par le modèle et qui contient une chaîne représentant le nom de la fonction et un objet JSON structuré contenant les paramètres et leurs valeurs.
function_response: Optional[FunctionResponse] Résultat de FunctionCall contenant une chaîne représentant le nom de la fonction et un objet JSON structuré contenant tout résultat de l'appel de fonction. Il sert de contexte au modèle.
text: Optional[str] Texte du message.
inline_data: Optional[Blob] Données d'octets intégrés.

Méthodes :

Méthode Description
text_or_transcript() -> Optional[str] Renvoie le texte s'il est disponible, sinon renvoie la transcription des données intégrées.
has_function_call(name) -> bool Renvoie True si la partie contient un appel de fonction spécifique.
has_function_response(name) -> bool Renvoie True si la partie contient une réponse de fonction spécifique.
from_text(text: str) -> Part Méthode de classe qui crée un Part de texte.
from_function_call(name: str, args: dict[str, Any]) -> Part Méthode de classe qui crée un appel de fonction Part.
from_function_response(name: str, response: dict[str, Any]) -> Part Méthode de classe qui crée une réponse de fonction Part.
from_inline_data(data: bytes, mime_type: str) -> Part Méthode de classe qui crée une Part de données intégrées.
from_json(data: str) -> Part Méthode de classe qui crée des données JSON intégrées Part.
from_agent_transfer(agent: str) -> Part Méthode de classe qui crée un Part pour le transfert à un autre agent.
from_end_session(*, reason: str, escalated: bool = False) -> Part Méthode de classe qui crée un Part pour mettre fin à la session.
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part Méthode de classe qui crée un Part pour la réponse avec un comportement personnalisé (par exemple, désactiver la saisie vocale, activer la saisie DTMF, etc.).

Exemples :

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 d'alias pour effectuer des requêtes HTTP. Pour en savoir plus, consultez la section Variable globale ces_requests.

Méthodes :

  • 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

Utilisé pour les erreurs générées avec un code d'état.

Attributs :

Attribut Description
status_code: int Code d'état HTTP associé à cette erreur.
reason: str Raison pour laquelle l'erreur est générée.

Tool

Représente un outil avec un nom et une description.

Attributs :

Attribut Description
name: str Nom de l'outil.
description: str Description de ce que fait l'outil.

ToolContext

Dérivé de CallbackContext. Informations sur la session disponibles lors de l'exécution d'un outil.

Attributs :

Attribut Description
function_call_id: str Identifiant de l'appel de fonction de l'appel d'outil en cours d'exécution.

Tools

Classe d'alias pour appeler des outils de manière synchrone. Pour en savoir plus, consultez la section Variable globale "tools".

ToolDeclaration

Schéma d'outil pouvant être présenté au modèle.

Attributs :

Attribut Description
function_declarations: Optional[list[FunctionDeclaration]] Liste des déclarations de fonctions compatibles avec l'outil.

Fonctions

get_variable

Cette fonction récupère une valeur de l'état de la session à l'aide de la clé fournie. Il sert de raccourci pour context.state.get(key) ou context.variables.get(key).

Exemple de code :

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

Cette fonction supprime une paire clé-valeur de l'état de la session. Il s'agit d'un raccourci pour del context.state[key].

Exemple de code :

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

set_variable

Cette fonction définit une valeur pour une clé donnée dans l'état de la session. Si la clé existe déjà, sa valeur sera mise à jour. Il s'agit d'un raccourci pour context.state[key] = value.

Exemple de code :

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

Variables globales

async_tools

Instance de AsyncTools, qui vous permet d'effectuer des appels asynchrones aux outils.

Exemples :

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

Instance de Requests. Requests vous permet d'effectuer des appels HTTP avec une syntaxe semblable à celle du module Python requests populaire.

Exemples :

# 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

Instance de Tools, qui vous permet d'effectuer des appels synchrones aux outils.

Exemples :

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

Dans votre code, vous pouvez accéder au contexte ADK, qui peut être utilisé pour lire et écrire de nombreux types de données de contexte ADK. Une variable globale appelée context est disponible dans votre code.

Les objets context.state et context.variables sont interchangeables. L'objet state est compatible avec le code ADK, mais le nouveau code doit utiliser l'objet variables.