Referência do ambiente de execução do Python

É possível usar código Python nas ferramentas do Python e nos callbacks. Esta referência descreve o ambiente de execução do Python, opções e classes de importação, variáveis globais e funções que podem ser usadas no seu código.

Ambiente Python

As ferramentas e os callbacks do Python são executados em um ambiente de sandbox seguro. Esse ambiente está executando o Python 3.12.

Importações

Sua capacidade de importar módulos é limitada ao seguinte:

Classes

AsyncTools

Classe de alias para chamar ferramentas de forma assíncrona. Consulte Variável global async_tools para mais informações.

Blob

Dados de bytes inline.

Atributos:

Atributo Descrição
display_name: Optional[str] Nome de exibição da Blob. Usado para fornecer um rótulo ou nome de arquivo para distinguir blobs.
data: Optional[bytes] Bytes codificados em Base64.
raw_data: Optional[bytes] Bytes brutos decodificados.
mime_type: Optional[str] O tipo MIME padrão da IANA dos dados de origem.

Métodos:

Método Descrição
transcript() -> Optional[str] Retorna uma transcrição armazenada em cache para os dados de Blob, se disponível. Isso só é aplicável a blobs de áudio.
from_json(data: str) -> Blob Um método de classe para criar uma instância Blob de uma string JSON, com mime_type definido como "application/json".

Amostras:

# 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

As informações da sessão disponíveis durante um callback.

Atributos:

Atributo Descrição
user_content: Optional[Content] Entradas mais recentes do usuário.
invocation_id: str Identificador exclusivo da invocação de callback específica, útil para depuração.
agent_name: str Nome de exibição do agente associado ao callback atual.
session_id: str Identificador exclusivo da sessão atual em andamento.
variables: dict[str, Any] Dicionário que contém pares de chave-valor de variáveis definidas no momento do design ou injetadas durante a execução. Esse é o estado atual das variáveis no momento da execução do callback.
state: dict[str, Any] O mesmo que a propriedade variables.
events: list[Event] Eventos de sessão.

Métodos:

Método Descrição
get_variable(key: str, default: Any) -> Any Recebe uma variável do estado. Se a variável não existir, retorne o padrão.
set_variable(key: str, value: Any) -> None Define uma variável no estado.
remove_variable(key: str) -> None Remove uma variável do estado.
get_last_user_input() -> list[Part] Recebe uma lista de todas as partes no último bloco de eventos do usuário.
get_last_agent_output() -> list[Part] Recebe uma lista de todas as partes no último bloco de eventos do agente.
parts() -> list[Part] Uma lista de todas as partes gravadas no histórico da sessão.

Content

Conteúdo da mensagem do usuário ou do agente.

Atributos:

Atributo Descrição
parts: Optional[list[Part]] Lista de partes que constituem uma única mensagem. Cada parte pode ter um tipo MIME IANA diferente.
role: Optional[str] A função do autor do conteúdo. 'user' ou 'agent'.

Métodos:

Método Descrição
is_user() -> bool Retorna True se a função for 'user'.
is_model() -> bool Retorna True se a função for 'model'.

Event

Representação de um evento na sessão.

Atributos:

Atributo Descrição
id: str Identificador do evento.
invocation_id: str Identificador de invocação de evento.
author: str "user" ou o nome do agente, indicando quem participou do evento na sessão.
timestamp: int Carimbo de data/hora do evento.
content: Content O conteúdo associado a este evento.
actions: EventActions As ações realizadas pelo agente.
long_running_tool_ids: set[str] Conjunto de identificadores das chamadas de função de longa duração.
partial: bool True para partes incompletas da resposta de streaming do LLM.
turn_complete: bool True se a rodada atual estiver concluída.
error_code: str Código do erro.
error_message: str Mensagem de erro.
interrupted: bool True se o turno foi interrompido.
branch: str A ramificação do evento.

O formato é como agent_1.agent_2.agent_3, em que agent_1 é o pai de agent_2, e agent_2 é o pai de agent_3.

A ramificação é usada quando vários subagentes não podem ver o histórico de conversas dos agentes colegas.
grounding_metadata: Any Os metadados de embasamento do evento.

Métodos:

Método Descrição
is_user() -> bool True se o autor do evento for "user".
is_agent(agent_name: Optional[str] = None) -> bool True se o autor do evento for um agente. Se agent_name for fornecido, ele vai verificar se o autor corresponde a esse agente específico.
has_error() -> bool True se o evento tiver um código de erro associado.
parts() -> list[Part] Um método conveniente para extrair a lista de objetos Part do content do evento. Retorna uma lista vazia se não houver conteúdo ou partes.

EventActions

Ações que ocorrem para eventos.

Atributos:

Atributo Descrição
skip_summarization: bool Se True, o modelo não será chamado para resumir a resposta da função. Usado apenas para o evento function_response.
state_delta: dict[str,Any] As mudanças nas variáveis causadas por esse evento.
artifact_delta: dict[str,Any] As mudanças nos artefatos feitas por esse evento. A chave é o nome do arquivo, e o valor é a versão.
transfer_to_agent: str Se definido, o evento será transferido para o agente especificado.
escalate: bool O agente está encaminhando para um agente de nível mais alto.
requested_auth_configs: dict[str,dict[str,Any]] Configurações de autenticação solicitadas pelas respostas da ferramenta.

Esse campo só é definido por um evento de resposta da ferramenta que indica a credencial de autenticação da solicitação da ferramenta.

Chaves: o identificador da chamada de função. Como um evento de resposta de função pode conter várias respostas de função que correspondem a várias chamadas de função. Cada chamada de função pode solicitar configurações de autenticação diferentes. Esse identificador é usado para identificar a chamada de função.

Valores: a configuração de autenticação solicitada.
end_invocation: bool O loop do agente é interrompido.

ExternalResponse

Representa uma resposta de fora do ambiente Python, como uma chamada de função ou uma solicitação HTTP.

Atributos:

Atributo Descrição
text: str O corpo da resposta como uma string.
status_code: int O código de status HTTP.
reason: str O motivo do erro. Vazio se não houver erro.
ok: bool True se status_code for menor que 400. Caso contrário, False.

Métodos:

Método Descrição
json() -> Any Analisa o JSON do atributo de texto e retorna o resultado. Se a análise falhar, um erro será gerado.
raise_for_status() Gera um StatusError se a resposta não for "ok" (ok == False).

FunctionCall

Representa uma chamada de função.

Atributos:

Atributo Descrição
id: Optional[str] O identificador exclusivo da chamada de função.
args: Optional[dict[str,Any]] Os parâmetros e valores da função no formato de objeto JSON.
name: Optional[str] Nome da função.

FunctionDeclaration

Um FunctionCall previsto retornado do modelo que contém uma string representando o atributo FunctionDeclaration name com os parâmetros e os valores deles.

Atributos:

Atributo Descrição
name: Optional[str] Nome da função.

FunctionResponse

O resultado de um FunctionCall que contém uma string representando o atributo name FunctionDeclaration e um objeto JSON estruturado com qualquer saída da chamada de função. Ele é usado como contexto para o modelo.

Atributos:

Atributo Descrição
id: Optional[str] Identificador da chamada de função correspondente.
name: Optional[str] Nome da função.
response: Optional[dict[str,Any]] A resposta da função no formato de objeto JSON. Use a chave "output" para especificar a saída da função e a chave "error" para especificar os detalhes do erro (se houver). Se as chaves "output" e "error" não forem especificadas, toda a "response" será tratada como saída da função.

GenerateContentConfig

Parâmetros opcionais de configuração do modelo.

Atributos:

Atributo Descrição
system_instruction: Optional[Content] Instruções para o modelo gerar um desempenho melhor. Por exemplo, "Responda da forma mais concisa possível" ou "Não use termos técnicos na resposta".
tools: Optional[list[ToolDeclaration]] Uma lista de ferramentas disponíveis que o modelo pode executar.
excluded_tools: Optional[list[str]] Uma lista de nomes de ferramentas que serão ignorados pelo modelo. Isso substitui tools.

Métodos:

Método Descrição
hide_tool(tool_name: str) Adiciona tool_name à lista excluded_tools.

HttpMethod

Um enum de string para representar um método HTTP. Os valores possíveis são:

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

LlmRequest

Modelos de dados para representar solicitações ao LLM.

Atributos:

Atributo Descrição
model: Optional[str] Nome do modelo
contents: List[Content] Uma lista de conteúdos enviados ao modelo.
config: Optional[GeneralContentConfig] Parâmetros de configuração do modelo.

LlmResponse

Modelos de dados para representar respostas do LLM.

Atributos:

Atributo Descrição
content: Content O primeiro Content com que o modelo responde.
partial: Optional[bool] Indica se o conteúdo representa uma resposta incompleta do modelo. O agente vai continuar o processamento depois de emitir a resposta parcial.

Métodos:

Método Descrição
from_parts(parts: list[Part]) -> LlmResponse Método de classe que retorna um LlmResponse do modelo.

Amostras:

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

Part

Um tipo de dados que contém conteúdo de mídia. Exatamente um campo em um Part precisa ser definido, representando o tipo específico de conteúdo que está sendo transmitido. Usar vários campos na mesma instância Part é considerado inválido.

Atributos:

Atributo Descrição
function_call: Optional[FunctionCall] Um FunctionCall previsto retornado do modelo que contém uma string que representa o nome da função e um objeto JSON estruturado com os parâmetros e os valores deles.
function_response: Optional[FunctionResponse] A saída resultante de FunctionCall que contém uma string que representa o nome da função e um objeto JSON estruturado com qualquer saída da chamada de função. Ele é usado como contexto para o modelo.
text: Optional[str] Texto da mensagem.
inline_data: Optional[Blob] Dados de bytes inline.

Métodos:

Método Descrição
text_or_transcript() -> Optional[str] Retorna o texto, se disponível. Caso contrário, retorna a transcrição dos dados inline.
has_function_call(name) -> bool Retorna True se a parte tiver uma chamada de função específica.
has_function_response(name) -> bool Retorna True se a parte tiver uma resposta de função específica.
from_text(text: str) -> Part Método de classe que cria um Part de texto.
from_function_call(name: str, args: dict[str, Any]) -> Part Método de classe que cria uma chamada de função Part.
from_function_response(name: str, response: dict[str, Any]) -> Part Método de classe que cria uma resposta de função Part.
from_inline_data(data: bytes, mime_type: str) -> Part Método de classe que cria um dado inline Part.
from_json(data: str) -> Part Método de classe que cria um Part de dados inline JSON.
from_agent_transfer(agent: str) -> Part Método de classe que cria um Part para transferência para outro agente.
from_end_session(*, reason: str, escalated: bool = False) -> Part Método de classe que cria um Part para encerrar a sessão.
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 classe que cria um Part para resposta com comportamento personalizado (por exemplo, desativar a entrada de barging, ativar a entrada de DTMF etc.).

Amostras:

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 de alias para fazer solicitações HTTP. Consulte variável global ces_requests para mais informações.

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

Usado para erros gerados com um código de status.

Atributos:

Atributo Descrição
status_code: int O código de status HTTP associado a esse erro.
reason: str O motivo do erro.

Tool

Representa uma ferramenta com um nome e uma descrição.

Atributos:

Atributo Descrição
name: str O nome da ferramenta.
description: str Uma descrição do que a ferramenta faz.

ToolContext

Derivado de CallbackContext. As informações da sessão disponíveis ao executar uma ferramenta.

Atributos:

Atributo Descrição
function_call_id: str O identificador de chamada de função da chamada de ferramenta atual em execução.

Tools

Classe de alias para chamar ferramentas de forma síncrona. Consulte variável global "tools" para mais informações.

ToolDeclaration

Um esquema de ferramenta que pode ser mostrado ao modelo.

Atributos:

Atributo Descrição
function_declarations: Optional[list[FunctionDeclaration]] Lista de declarações de função compatíveis com a ferramenta.

Funções

get_variable

Essa função recupera um valor do estado da sessão usando a chave fornecida. Ele serve como um atalho para context.state.get(key) ou context.variables.get(key).

Exemplo de código:

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

Essa função remove um par de chave-valor do estado da sessão. Este é um atalho para del context.state[key].

Exemplo de código:

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

set_variable

Essa função define um valor para uma determinada chave no estado da sessão. Se a chave já existir, o valor dela será atualizado. É um atalho para context.state[key] = value.

Exemplo de código:

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

Variáveis globais

async_tools

Uma instância de AsyncTools, que permite fazer chamadas assíncronas para ferramentas.

Amostras:

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

Uma instância de Requests. O Requests permite fazer chamadas HTTP com sintaxe semelhante ao módulo de solicitações Python.

Amostras:

# 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

Uma instância de Tools, que permite fazer chamadas síncronas para ferramentas.

Amostras:

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

No seu código, você pode acessar o contexto do ADK, que pode ser usado para ler e gravar muitos tipos de dados de contexto do ADK. Uma variável global chamada context está disponível para uso no seu código.

Os objetos context.state e context.variables são intercambiáveis. O objeto state é compatível com o código do ADK, mas o novo código deve usar o objeto variables.