É possível usar o código Python em ferramentas e callbacks do Python. Esta referência descreve o ambiente de execução do Python, as opções e classes de importação, as variáveis globais e as funções que podem ser usadas no 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
A capacidade de importar módulos é limitada ao seguinte:
Classes
AsyncTools
Classe de alias para chamar ferramentas de forma assíncrona.
Consulte a 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 em cache para os dados de Blob, se disponível. Isso só se aplica 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". |
Exemplos:
# 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] |
As 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 retorno de chamada 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 o ambiente de execução. Esse é o estado atual das variáveis no momento da execução do callback. |
state: dict[str, Any] |
Igual à 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 registradas 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 o papel for 'user'. |
is_model() -> bool |
Retorna True se o papel 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 blocos incompletos da resposta de streaming do LLM. |
turn_complete: bool |
True se a vez atual estiver concluída. |
error_code: str |
Código do erro. |
error_message: str |
Mensagem de erro. |
interrupted: bool |
True se a vez foi interrompida. |
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 devem ver o histórico de conversas dos agentes semelhantes. |
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 do erro associado. |
parts() -> list[Part] |
Um método de conveniência para receber 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 for 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 o caso para um agente de nível superior. |
requested_auth_configs: dict[str,dict[str,Any]] |
Configurações de autenticação solicitadas por respostas de ferramentas. Esse campo só é definido por um evento de resposta de ferramenta que indica a credencial de autenticação da solicitação de 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 do Python, como uma chamada de ferramenta 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 pelo qual o erro está sendo gerado. 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 estiver correta (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 que representa 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 uma FunctionCall
que contém uma string que representa o
atributo name de 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 ignoradas pelo modelo. Isso substitui tools. |
Métodos:
| Método | Descrição |
|---|---|
hide_tool(tool_name: str) |
Adiciona tool_name à lista excluded_tools. |
HttpMethod
Um tipo enumerado de string para representar um método HTTP. Os valores possíveis são:
GETPOSTPUTDELETEPATCHHEADOPTIONS
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 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. |
Exemplos:
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.
O uso de vários campos na mesma instância de 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 contendo 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 Part de dados inline. |
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 interrupção, ativar a entrada DTMF etc.). |
Exemplos:
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 a 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 pelo qual o erro está sendo gerado. |
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 da chamada de função da chamada de ferramenta atual que está sendo executada. |
Tools
Classe de alias para chamar ferramentas de forma síncrona. Consulte variável global de ferramentas 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
_session
É possível acessar o canal e a modalidade atuais de uma conversa,
de forma semelhante ao que é feito em
componentes modulares.
Acesse esses valores usando a variável predefinida chamada _session.
Exemplo de ferramenta Python (usando a variável 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})."
Exemplo de callback (usando 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
Uma instância de AsyncTools,
que permite fazer chamadas assíncronas para ferramentas.
Exemplos:
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.
Requests permite fazer chamadas HTTP com sintaxe semelhante
ao conhecido módulo de solicitações do Python.
Exemplos:
# 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.
Exemplos:
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, é possível 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 precisa usar o objeto variables.