Referencia del entorno de ejecución de Python

Puedes usar código de Python en las herramientas de Python y en las devoluciones de llamada. En esta referencia, se describen el entorno de ejecución de Python, las opciones y clases de importación, las variables globales y las funciones que puedes usar en tu código.

Entorno de Python

Las herramientas y las devoluciones de llamada de Python se ejecutan en un entorno de zona de pruebas seguro. Este entorno ejecuta Python 3.12.

Importaciones

Tu capacidad para importar módulos se limita a lo siguiente:

Clases

AsyncTools

Clase de alias para llamar a herramientas de forma asíncrona. Consulta la variable global async_tools para obtener más información.

Blob

Son los datos de bytes intercalados.

Atributos:

Atributo Descripción
display_name: Optional[str] Nombre visible de Blob. Se usa para proporcionar una etiqueta o un nombre de archivo para distinguir los blobs.
data: Optional[bytes] Son bytes codificados en Base64.
raw_data: Optional[bytes] Son los bytes decodificados sin procesar.
mime_type: Optional[str] Es el tipo de MIME estándar de IANA de los datos de origen.

Métodos:

Método Descripción
transcript() -> Optional[str] Devuelve una transcripción almacenada en caché para los datos de Blob si está disponible. Esto solo se aplica a los BLOB de audio.
from_json(data: str) -> Blob Es un método de clase para crear una instancia de Blob a partir de una cadena JSON, con mime_type establecido en "application/json".

Ejemplos:

# 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

Es la información de la sesión disponible durante una devolución de llamada.

Atributos:

Atributo Descripción
user_content: Optional[Content] Son las entradas más recientes del usuario.
invocation_id: str Es el identificador único de la invocación de devolución de llamada específica, útil para la depuración.
agent_name: str Es el nombre visible del agente asociado a la devolución de llamada actual.
session_id: str Es el identificador único de la sesión actual en curso.
variables: dict[str, Any] Diccionario que contiene pares clave-valor de variables definidas en el momento del diseño o insertadas durante el tiempo de ejecución. Este es el estado actual de las variables en el momento de la ejecución de la devolución de llamada.
state: dict[str, Any] Es igual que la propiedad variables.
events: list[Event] Son los eventos de sesión.

Métodos:

Método Descripción
get_variable(key: str, default: Any) -> Any Obtiene una variable del estado. Si la variable no existe, se devuelve el valor predeterminado.
set_variable(key: str, value: Any) -> None Establece una variable en el estado.
remove_variable(key: str) -> None Quita una variable del estado.
get_last_user_input() -> list[Part] Obtiene una lista de todas las partes del último fragmento de eventos del usuario.
get_last_agent_output() -> list[Part] Obtiene una lista de todas las partes del último fragmento de eventos del agente.
parts() -> list[Part] Es una lista de todas las partes grabadas en el historial de la sesión.

Content

Es el contenido del mensaje del usuario o del agente.

Atributos:

Atributo Descripción
parts: Optional[list[Part]] Es una lista de las partes que constituyen un solo mensaje. Cada parte puede tener un tipo de MIME de IANA diferente.
role: Optional[str] Es el rol del autor del contenido. 'user' o 'agent'

Métodos:

Método Descripción
is_user() -> bool Devuelve True si el rol es 'user'.
is_model() -> bool Devuelve True si el rol es 'model'.

Event

Es la representación de un evento en la sesión.

Atributos:

Atributo Descripción
id: str Es el identificador del evento.
invocation_id: str Es el identificador de invocación del evento.
author: str "user" o el nombre del agente, que indica quién asistió al evento de la sesión.
timestamp: int Es la marca de tiempo del evento.
content: Content Es el contenido asociado a este evento.
actions: EventActions Son las acciones que realiza el agente.
long_running_tool_ids: set[str] Es el conjunto de identificadores de las llamadas a funciones de larga duración.
partial: bool True para fragmentos incompletos de la respuesta de transmisión del LLM
turn_complete: bool True si el turno actual está completo.
error_code: str Es el código de error.
error_message: str Mensaje de error
interrupted: bool True si se interrumpió el giro.
branch: str Es la rama del evento.

El formato es como agent_1.agent_2.agent_3, donde agent_1 es el elemento superior de agent_2 y agent_2 es el elemento superior de agent_3.

La rama se usa cuando varios subagentes no deben ver el historial de conversaciones de sus agentes pares.
grounding_metadata: Any Son los metadatos de fundamentación del evento.

Métodos:

Método Descripción
is_user() -> bool True si el autor del evento es "usuario".
is_agent(agent_name: Optional[str] = None) -> bool True si el autor del evento es un agente Si se proporciona agent_name, se verifica si el autor coincide con ese agente específico.
has_error() -> bool True si el evento tiene un código de error asociado.
parts() -> list[Part] Es un método de conveniencia para obtener la lista de objetos Part del content del evento. Devuelve una lista vacía si no hay contenido ni partes.

EventActions

Son las acciones que ocurren para los eventos.

Atributos:

Atributo Descripción
skip_summarization: bool Si es True, no se llama al modelo para resumir la respuesta de la función. Solo se usa para el evento function_response.
state_delta: dict[str,Any] Son los cambios en las variables provocados por este evento.
artifact_delta: dict[str,Any] Son los cambios que este evento realiza en los artefactos. La clave es el nombre del archivo y el valor es la versión.
transfer_to_agent: str Si se configura, el evento se transfiere al agente especificado.
escalate: bool El agente está derivando el caso a un agente de nivel superior.
requested_auth_configs: dict[str,dict[str,Any]] Son las configuraciones de autenticación solicitadas por las respuestas de la herramienta.

Este campo solo se establece mediante un evento de respuesta de la herramienta que indica la credencial de autenticación de la solicitud de la herramienta.

Claves: Es el identificador de la llamada a la función. Dado que un evento de respuesta de función podría contener varias respuestas de función que corresponden a varias llamadas a funciones. Cada llamada a la función podría solicitar diferentes parámetros de configuración de autenticación. Es el identificador que se usa para identificar la llamada a la función.

Valores: Es la configuración de autorización solicitada.
end_invocation: bool Se interrumpe el bucle del agente.

ExternalResponse

Representa una respuesta desde fuera del entorno de Python, como una llamada a herramienta o una solicitud HTTP.

Atributos:

Atributo Descripción
text: str Es el cuerpo de la respuesta como una cadena.
status_code: int El código de estado HTTP.
reason: str Es el motivo por el que se arroja el error. Este campo estará vacío si no hay errores.
ok: bool True si status_code es menor que 400; de lo contrario, False.

Métodos:

Método Descripción
json() -> Any Analiza el JSON del atributo de texto y devuelve el resultado. Si falla el análisis, se generará un error.
raise_for_status() Genera un StatusError si la respuesta no es correcta (ok == False).

FunctionCall

Representa una llamada a una función.

Atributos:

Atributo Descripción
id: Optional[str] Es el identificador único de la llamada a la función.
args: Optional[dict[str,Any]] Los parámetros y valores de la función en formato de objeto JSON
name: Optional[str] Nombre de la función

FunctionDeclaration

Un FunctionCall predicho que muestra el modelo y que contiene una cadena que representa el atributo FunctionDeclaration name con los parámetros y sus valores.

Atributos:

Atributo Descripción
name: Optional[str] Nombre de la función

FunctionResponse

Es el resultado de un FunctionCall que contiene una cadena que representa el atributo FunctionDeclaration name y un objeto JSON estructurado que contiene cualquier resultado de la llamada a función. Se usa como contexto para el modelo.

Atributos:

Atributo Descripción
id: Optional[str] Es el identificador de la llamada a la función correspondiente.
name: Optional[str] Nombre de la función
response: Optional[dict[str,Any]] La respuesta de la función en formato de objeto JSON. Usa la clave "output" para especificar el resultado de la función y la clave "error" para especificar los detalles del error (si hay alguno). Si no se especifican las claves "output" y "error", toda la "response" se trata como resultado de la función.

GenerateContentConfig

Son parámetros de configuración opcionales del modelo.

Atributos:

Atributo Descripción
system_instruction: Optional[Content] Instrucciones para que el modelo mejore su rendimiento. Por ejemplo, "Responde de la forma más concisa posible" o "No uses términos técnicos en tu respuesta".
tools: Optional[list[ToolDeclaration]] Es una lista de herramientas disponibles que el modelo puede ejecutar.
excluded_tools: Optional[list[str]] Es una lista de nombres de herramientas que el modelo ignorará. Esto anula tools.

Métodos:

Método Descripción
hide_tool(tool_name: str) Agrega tool_name a la lista excluded_tools.

HttpMethod

Es un enum de cadena para representar un método HTTP. Los siguientes son los valores posibles:

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

LlmRequest

Son modelos de datos para representar solicitudes al LLM.

Atributos:

Atributo Descripción
model: Optional[str] Nombre del modelo
contents: List[Content] Es una lista del contenido enviado al modelo.
config: Optional[GeneralContentConfig] Son los parámetros de configuración del modelo.

LlmResponse

Son modelos de datos para representar las respuestas del LLM.

Atributos:

Atributo Descripción
content: Content Es el primer Content con el que responde el modelo.
partial: Optional[bool] Indica si el contenido representa una respuesta incompleta del modelo. El agente continuará el procesamiento después de emitir la respuesta parcial.

Métodos:

Método Descripción
from_parts(parts: list[Part]) -> LlmResponse Método de clase que devuelve un LlmResponse del modelo.

Ejemplos:

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

Part

Es un tipo de datos que contiene contenido multimedia. Se debe establecer exactamente un campo dentro de un Part, que represente el tipo específico de contenido que se transmite. Se considera no válido usar varios campos dentro de la misma instancia de Part.

Atributos:

Atributo Descripción
function_call: Optional[FunctionCall] Un FunctionCall predicho que muestra el modelo que contiene una cadena que representa el nombre de la función y un objeto JSON estructurado que contiene los parámetros y sus valores.
function_response: Optional[FunctionResponse] Es el resultado de FunctionCall que contiene una cadena que representa el nombre de la función y un objeto JSON estructurado que contiene cualquier resultado de la llamada a función. Se usa como contexto para el modelo.
text: Optional[str] Texto del mensaje.
inline_data: Optional[Blob] Son los datos de bytes intercalados.

Métodos:

Método Descripción
text_or_transcript() -> Optional[str] Devuelve el texto si está disponible; de lo contrario, devuelve la transcripción de los datos intercalados.
has_function_call(name) -> bool Devuelve True si la parte contiene una llamada a función específica.
has_function_response(name) -> bool Devuelve True si la parte contiene una respuesta de función específica.
from_text(text: str) -> Part Método de clase que crea un objeto Part de texto.
from_function_call(name: str, args: dict[str, Any]) -> Part Método de clase que crea una llamada a función Part.
from_function_response(name: str, response: dict[str, Any]) -> Part Método de clase que crea una respuesta de función Part.
from_inline_data(data: bytes, mime_type: str) -> Part Método de clase que crea datos intercalados Part.
from_json(data: str) -> Part Método de clase que crea un objeto Part de datos intercalados en JSON.
from_agent_transfer(agent: str) -> Part Método de clase que crea un objeto Part para transferir a otro agente.
from_end_session(*, reason: str, escalated: bool = False) -> Part Es un método de clase que crea un objeto Part para finalizar la sesión.
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étodo de clase que crea un Part para la respuesta con un comportamiento personalizado (por ejemplo, inhabilitar el ingreso de dígitos, habilitar la entrada de DTMF, etcétera).

Ejemplos:

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

Clase de alias para realizar solicitudes HTTP. Consulta la variable global ces_requests para obtener más información.

Métodos:

  • 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

Se usa para los errores que se generan con un código de estado.

Atributos:

Atributo Descripción
status_code: int Es el código de estado HTTP asociado a este error.
reason: str Es el motivo por el que se genera el error.

Tool

Representa una herramienta con un nombre y una descripción.

Atributos:

Atributo Descripción
name: str Es el nombre de la herramienta.
description: str Es una descripción de lo que hace la herramienta.

ToolContext

Se deriva de CallbackContext. Es la información de la sesión disponible cuando se ejecuta una herramienta.

Atributos:

Atributo Descripción
function_call_id: str Es el identificador de la llamada a función de la llamada a herramienta actual que se está ejecutando.

Tools

Clase de alias para llamar a herramientas de forma síncrona. Consulta la variable global de herramientas para obtener más información.

ToolDeclaration

Es un esquema de herramienta que se le puede mostrar al modelo.

Atributos:

Atributo Descripción
function_declarations: Optional[list[FunctionDeclaration]] Es la lista de declaraciones de funciones que admite la herramienta.

Funciones

get_variable

Esta función recupera un valor del estado de la sesión con la clave proporcionada. Sirve como acceso directo para context.state.get(key) o context.variables.get(key).

Código de muestra:

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

Esta función quita un par clave-valor del estado de la sesión. Este es un acceso directo para del context.state[key].

Código de muestra:

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

set_variable

Esta función establece un valor para una clave determinada en el estado de la sesión. Si la clave ya existe, se actualizará su valor. Es un acceso directo para context.state[key] = value.

Código de muestra:

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

Variables globales

async_tools

Es una instancia de AsyncTools, que te permite realizar llamadas asíncronas a herramientas.

Ejemplos:

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

Es una instancia de Requests. Requests te permite realizar llamadas HTTP con una sintaxis similar a la del popular módulo de solicitudes de Python.

Ejemplos:

# 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

Es una instancia de Tools, que te permite realizar llamadas síncronas a herramientas.

Ejemplos:

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

En tu código, puedes acceder al contexto del ADK, que se puede usar para leer y escribir muchos tipos de datos de contexto del ADK. Hay una variable global llamada context disponible para usar en tu código.

Los objetos context.state y context.variables son intercambiables. El objeto state se admite para la compatibilidad con el código del ADK, pero el código nuevo debe usar el objeto variables.