Referencia del entorno de ejecución de Python

Puedes usar código de Python en las herramientas y las devoluciones de llamada de Python. 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 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

Es la clase de alias para llamar a las 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 BLOB.
data: Optional[bytes] Bytes codificados en Base64.
raw_data: Optional[bytes] 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 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 con la devolución de llamada actual.
session_id: str Es el identificador único de la sesión actual en curso.
variables: dict[str, Any] Es un diccionario que contiene pares clave-valor de variables definidas en el momento del diseño o insertadas durante el entorno 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 de usuario.
get_last_agent_output() -> list[Part] Obtiene una lista de todas las partes del último fragmento de eventos del agente.
parts() -> list[Part] Una lista de todas las partes registradas 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 la lista de 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 con 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 los fragmentos incompletos de la respuesta de transmisión del LLM.
turn_complete: bool True si se completó el turno actual.
error_code: str Es el código de error.
error_message: str Mensaje de error
interrupted: bool True si se interrumpió el turno
branch: str Es la rama del evento.

El formato es como agent_1.agent_2.agent_3, en el que 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 agentes secundarios 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 "user".
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 se producen 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 que provoca 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 establece, 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 que solicitan las respuestas de las herramientas.

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

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

Valores: La configuración de autenticación solicitada.
end_invocation: bool El bucle del agente se interrumpe.

ExternalResponse

Representa una respuesta desde fuera del entorno de Python, como una llamada a una 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 genera el error. Está 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 atributo de texto JSON y devuelve el resultado. Si el análisis falla, se arrojará un error.
raise_for_status() Genera un StatusError si la respuesta no es correcta (ok == False).

FunctionCall

Representa una llamada a función.

Atributos:

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

FunctionDeclaration

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

Atributos:

Atributo Descripción
name: Optional[str] Es el nombre de la función.

FunctionResponse

Es el resultado de una FunctionCall que contiene una cadena que representa el atributo name de FunctionDeclaration 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] Identificador de la llamada a función correspondiente.
name: Optional[str] Es el 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 los hay). Si no se especifican las claves "output" y "error", toda la "response" se trata como resultado de la función.

GenerateContentConfig

Son parámetros opcionales de configuración 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á. Esta acción anula tools.

Métodos:

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

HttpMethod

Es una enumeración de cadenas para representar un método HTTP. Los siguientes son los valores posibles:

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

LlmRequest

Modelos de datos para representar solicitudes al LLM.

Atributos:

Atributo Descripción
model: Optional[str] Nombre del modelo
contents: List[Content] Es una lista de contenidos que se envían al modelo.
config: Optional[GeneralContentConfig] Son los parámetros de configuración del modelo.

LlmResponse

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á con el procesamiento después de emitir la respuesta parcial.

Métodos:

Método Descripción
from_parts(parts: list[Part]) -> LlmResponse Es un 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 Es el método de clase que crea un Part de texto.
from_function_call(name: str, args: dict[str, Any]) -> Part Es el 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 Es el método de clase que crea un Part de datos intercalados.
from_json(data: str) -> Part Método de clase que crea un Part de datos intercalados de JSON.
from_agent_transfer(agent: str) -> Part Es el método de clase que crea un Part para transferir a otro agente.
from_end_session(*, reason: str, escalated: bool = False) -> Part Es el método de clase que crea un 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 Es un método de clase que crea un Part para la respuesta con un comportamiento personalizado (por ejemplo, inhabilitar la interrupción, 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

Es la 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 con 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 Una descripción de lo que hace la herramienta.

ToolContext

Derivado 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 la herramienta actual que se está ejecutando.

Tools

Es la clase de alias para llamar a las 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 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

_session

Puedes acceder al canal y la modalidad actuales de una conversación, de forma similar a como se hace en los componentes modulares. Accede a estos valores con la variable predefinida llamada _session.

Ejemplo de herramienta de Python (con la variable global 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})."

Ejemplo de devolución de llamada (con 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

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 al 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

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 de ADK, pero el código nuevo debe usar el objeto variables.