Utilitários

Funções e recursos auxiliares para o desenvolvimento de actions.

---

format_response_message

Formata uma mensagem de resposta com contexto e timestamp opcionais. Útil para padronizar textos de instrução em ResponseToAgent.

from actions_sdk.features.utils.formatters import format_response_message

Uso

# Mensagem simples
texto = format_response_message("Operação concluída")
# → "Operação concluída"

# Com contexto
texto = format_response_message(
    "Consulta realizada",
    context={"registros": 5, "tempo_ms": 120},
)
# → "Consulta realizada (registros: 5 | tempo_ms: 120)"

# Com timestamp
texto = format_response_message("Log de execução", include_timestamp=True)
# → "[2025-06-07 14:30:00] Log de execução"

# Combinando contexto e timestamp
texto = format_response_message(
    "Resultado",
    context={"status": "ok"},
    include_timestamp=True,
)
# → "[2025-06-07 14:30:00] Resultado (status: ok)"

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
content	str	—	Conteúdo base da mensagem
context	dict | None	None	Dicionário de contexto a anexar à mensagem
include_timestamp	bool	False	Se True, adiciona timestamp [YYYY-MM-DD HH:MM:SS] no início

Retorna: str

---

Code Secrets

Code Secrets são variáveis de ambiente injetadas pelo motor no namespace de execução da action. Use para armazenar credenciais, chaves de API e outros dados sensíveis sem colocá-los no código.

Como definir um Code Secret

Os Code Secrets são configurados na plataforma Tech4AI — na configuração do agente ou da action, na seção de variáveis de ambiente.

Como acessar na action

Code Secrets são disponibilizados como variáveis de módulo — declare a variável no escopo global do arquivo:

# No topo do arquivo da action (escopo global)
MINHA_API_KEY: str  # Declaração — o motor injeta o valor

def minha_action(parametro: str):
    # Usar a variável como string normal
    headers = {"Authorization": f"Bearer {MINHA_API_KEY}"}
    # ...

Segurança

• Nunca imprima Code Secrets em logs ou inclua em payloads de tracing
• Nunca retorne Code Secrets em instruction, detail ou state_updates
• Use o parâmetro sensitive_json_keys do HttpClient para mascarar chaves em requests HTTP

Boas práticas

# Boa prática — declarar no topo com type hint
API_KEY: str
API_URL: str

def consultar_api(query: str):
    from actions_sdk.features.http import HttpClient

    client = HttpClient(ctx)
    resposta = client.get(
        f"{API_URL}/endpoint",
        headers={"X-API-Key": API_KEY},
        sensitive_json_keys=["X-API-Key"],  # Mascara nos logs de tracing
    )
    # ...

Verificar se a variável foi injetada

API_KEY: str

def minha_action():
    try:
        chave = API_KEY
    except NameError:
        return ResponseToAgent(
            status=ResponseStatus.ERROR,
            instruction="Variável API_KEY não foi configurada como Code Secret.",
        )