Actions SDK v2 — Visão Geral

O Actions SDK v2 é a biblioteca Python da Tech4AI para desenvolvimento de Actions — funções Python executadas pelo motor de agentes como tool calls do LLM.

Paradigma ctx-first

O SDK v2 opera com context injection: o motor (t4ai-agents) cria um contexto de execução e o injeta como variável global ctx no namespace da action via exec(). O desenvolvedor não instancia o SDK — usa ctx diretamente, passando-o para cada feature.

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.features.conversational.state import StateManager
from actions_sdk.features.tracing import ActionSpan

ctx: ActionContext  # Injetado pelo motor — declare para type hints


def minha_action(parametro: str):
    span = ActionSpan(ctx)
    state = StateManager(ctx)

    span.event("action.inicio", {"parametro": parametro})
    state.update("progresso", "iniciado")

    # ... lógica da action

    return ResponseToAgent(
        status=ResponseStatus.SUCCESS,
        instruction="Operação concluída com sucesso.",
    )

Declaração de ctx

ctx: ActionContext é apenas uma anotação de tipo — não atribui nenhum valor. O ctx real é injetado pelo motor antes da execução. Inclua sempre essa linha para ativar autocomplete e type checking.

---

ActionContext vs TaskContext

O SDK oferece dois contextos de execução, dependendo do tipo de agente:

	ActionContext	TaskContext
Usado por	Agents conversacionais (chat, WhatsApp)	Agents de tarefa (execução assíncrona)
Tem histórico de mensagens	✅	❌
Tem memória persistente	✅	❌
Tem estado de sessão	✅	❌
Tem seleção de skills	✅	❌
LLMClient	✅	✅
FileManager	✅	✅
ActionSpan	✅	✅

A anotação de tipo muda conforme o agente:

from actions_sdk.core.types.action_context import ActionContext
ctx: ActionContext  # Para agents conversacionais

# — ou —

from actions_sdk.core.types.task_context import TaskContext
ctx: TaskContext  # Para agents de tarefa

Todos os exemplos desta documentação usam ActionContext. Para TaskContext, as features disponíveis são LLMClient, FileManager e ActionSpan.

---

Mapa de features

Feature	Quando usar	Import
StateManager	Estado volátil da sessão: flags, configurações e dados de negócio	from actions_sdk.features.conversational.state import StateManager
MemoryManager	Contexto persistente enviado ao LLM	from actions_sdk.features.conversational.memory import MemoryManager
ActionMessageSender	Enviar mensagens ao usuário durante a execução	from actions_sdk.features.conversational.send_message import ActionMessageSender
SkillSelector	Selecionar skill externa via LLM	from actions_sdk.features.conversational.skill_selector import SkillSelector
HttpClient	Requisições HTTP com retry e IP fixo	from actions_sdk.features.http import HttpClient
CertificateClient	Requisições HTTPS com mTLS	from actions_sdk.features.http.certificate_client import CertificateClient
KnowledgeClient	Consultas RAG a bases de conhecimento	from actions_sdk.features.knowledge import KnowledgeClient
LLMClient	Chamadas LLM diretas na action	from actions_sdk.features.llm import LLMClient
FileManager	Upload e download de arquivos	from actions_sdk.features.files import FileManager
PromptManager	Recuperar prompts publicados na plataforma	from actions_sdk.features.prompts.manager import PromptManager
ActionSpan	Observabilidade: eventos e spans	from actions_sdk.features.tracing import ActionSpan
format_response_message	Formatar mensagens com contexto e timestamp	from actions_sdk.features.utils.formatters import format_response_message

---

Quickstart — Action completa

Exemplo de action real baseado no agente de homologação do SDK v2:

import traceback

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.core.types.responses import ResponseStatus, ResponseToAgent
from actions_sdk.features.conversational.state import StateManager
from actions_sdk.features.http import HttpClient
from actions_sdk.features.tracing import ActionSpan

ctx: ActionContext

TIMEOUT = 10.0


def consultar_api(url: str):
    """Consulta uma API externa e retorna o resultado ao agente."""
    span = ActionSpan(ctx)
    state = StateManager(ctx)

    span.event("action.consultar_api.inicio", {"url": url})

    try:
        client = HttpClient(ctx)
        resposta = client.get(url, timeout=TIMEOUT)

        state.update("ultima_consulta.url", url)
        state.update("ultima_consulta.status", resposta.status_code)

        span.event("action.consultar_api.sucesso", {"status": resposta.status_code})

        return ResponseToAgent(
            status=ResponseStatus.SUCCESS,
            instruction=f"Consulta concluída. Status: {resposta.status_code}",
            detail=f"GET {url} → {resposta.status_code}",
            state_updates=state.get_full_state(),
        )

    except Exception as erro:
        span.event("action.consultar_api.erro", {"erro": str(erro)})
        return ResponseToAgent(
            status=ResponseStatus.ERROR,
            instruction=f"Falha na consulta: {traceback.format_exc()}",
            detail=f"Exceção: {type(erro).__name__}: {erro}",
            state_updates=state.get_full_state(),
        )

Padrões do quickstart

• StateManager — use state_updates=state.get_full_state() no retorno para persistir mudanças de estado
• Try/except explícito — capture exceções e retorne ResponseToAgent com status=ERROR em vez de deixar a action falhar silenciosamente
• ResponseToAgent vs ResponseToUser — use ResponseToAgent quando quiser que o LLM processe o resultado; use ResponseToUser para enviar mensagem diretamente ao usuário

---

Tipos de retorno

Toda action deve retornar um de dois tipos:

Tipo	Quando usar
ResponseToAgent	O resultado volta para o LLM processar e decidir o próximo passo
ResponseToUser	A resposta vai direto ao usuário, encerrando o ciclo atual do LLM

Veja a documentação completa de Respostas.