Respostas

Toda action deve retornar um objeto de resposta que indica ao motor o que fazer com o resultado. O SDK v2 oferece dois tipos principais: ResponseToAgent e ResponseToUser.

ResponseStatus

Enum que indica o resultado da execução da action:

from actions_sdk.core.types.responses import ResponseStatus

ResponseStatus.SUCCESS   # Execução concluída com sucesso
ResponseStatus.ERROR     # Falha na execução
ResponseStatus.WARNING   # Concluído com ressalvas

---

ResponseToAgent

Retorna o resultado para o LLM processar e decidir o próximo passo. Use quando a action executou uma operação e o agente precisa raciocinar sobre o resultado antes de responder ao usuário.

from actions_sdk.core.types.responses import ResponseStatus, ResponseToAgent

return ResponseToAgent(
    status=ResponseStatus.SUCCESS,
    instruction="Dados recuperados com sucesso.",
    detail="GET /api/dados → 200 OK, 3 registros retornados.",
    state_updates=state.get_full_state(),
)

Campos

Campo	Tipo	Obrigatório	Descrição
status	ResponseStatus	Não (padrão: SUCCESS)	Status da execução
instruction	str	✅	Instrução para o LLM — descreve o que aconteceu e o que fazer
detail	str | None	Não	Informação técnica adicional (não vai para o LLM)
functions	list[SystemFunction] | None	Não	Funções de sistema a executar (EndChat, TransferToHuman, etc.)
state_updates	dict | None	Não	Atualizações de estado da sessão
memory_updates	dict | None	Não	Atualizações de memória
metadata	dict | None	Não	Metadados extras

Boas práticas para instruction

O campo instruction é o que o LLM recebe. Seja descritivo:

# Ruim — pouca informação
instruction="Dados obtidos."

# Bom — o LLM sabe o que aconteceu e o que fazer com isso
instruction=(
    f"Consulta à API concluída com sucesso.\n"
    f"Resultado: {dados}\n"
    f"Informe ao usuário os detalhes encontrados."
)

Exemplo com erro

import traceback

try:
    resultado = operacao()
    return ResponseToAgent(
        status=ResponseStatus.SUCCESS,
        instruction=f"Operação concluída: {resultado}",
        state_updates=state.get_full_state(),
    )
except Exception as erro:
    return ResponseToAgent(
        status=ResponseStatus.ERROR,
        instruction=f"Falha na operação: {traceback.format_exc()}",
        detail=f"Exceção: {type(erro).__name__}: {erro}",
        state_updates=state.get_full_state(),
    )

---

ResponseToUser

Envia uma mensagem diretamente ao usuário, encerrando o ciclo atual do LLM. Use quando a action sabe exatamente o que dizer ao usuário sem precisar de processamento adicional pelo LLM.

from actions_sdk.core.types.responses import ResponseStatus, ResponseToUser
from actions_sdk.core.types.message_components import TextMessage

return ResponseToUser(
    instruction="Action retornou mensagem de confirmação ao usuário.",
    message=TextMessage(body="Sua solicitação foi processada com sucesso!"),
    status=ResponseStatus.SUCCESS,
    state_updates=state.get_full_state(),
)

Campos

Campo	Tipo	Obrigatório	Descrição
message	str | MessageComponent | list	✅	Conteúdo enviado ao usuário
status	ResponseStatus	Não (padrão: SUCCESS)	Status da execução
instruction	str | None	Não	Descrição para o histórico do LLM
functions	list[SystemFunction] | None	Não	Funções de sistema (EndChat, etc.)
files	list[FileContent] | None	Não	Arquivos a enviar ao usuário
state_updates	dict | None	Não	Atualizações de estado
memory_updates	dict | None	Não	Atualizações de memória
topic	str | None	Não	Tópico da mensagem

Normalização automática de message

O campo message aceita múltiplos formatos e é normalizado automaticamente:

# String simples → TextMessage automático
ResponseToUser(message="Olá!")

# MessageComponent direto
ResponseToUser(message=TextMessage(body="Olá!"))

# Lista de componentes
ResponseToUser(message=[
    TextMessage(body="Resultado encontrado:"),
    InteractiveList(...)
])

Veja os Componentes de Mensagem disponíveis.

---

ResponseToAgent vs ResponseToUser

	ResponseToAgent	ResponseToUser
Destino	LLM (agente)	Usuário final
Ciclo LLM	Continua	Encerra
Quando usar	Resultado de operação para o LLM processar	Mensagem já definida para o usuário
Campo message	❌	✅ (obrigatório)
Campo instruction	✅ (obrigatório)	Opcional (registrado no histórico)

---

SystemFunctions

SystemFunctions são ações especiais que o motor executa junto com a resposta. São passadas no campo functions de ResponseToUser ou ResponseToAgent.

EndChat

Encerra a conversa:

from actions_sdk.core.types.responses import EndChat, ResponseToUser

return ResponseToUser(
    instruction="Encerrando atendimento.",
    message="Atendimento finalizado. Obrigado por entrar em contato!",
    functions=[
        EndChat(
            reason="Usuário finalizou o atendimento.",
            session_info={"motivo": "conclusao_natural"},  # opcional
            service_evaluation=False,  # opcional, default true — ex. retorno de HSM informativo
        )
    ],
)

Campo	Tipo	Descrição
reason	str	Motivo do encerramento
session_info	dict | None	Dados extras da sessão
service_evaluation	bool	Se true (default), o servidor consumidor dispara a pesquisa de satisfação (CSAT) ao final do atendimento. Definir false para pular o CSAT — ex. em retorno de HSM informativo, onde a pesquisa não faz sentido

TransferToHuman

Transfere para atendimento humano:

from actions_sdk.core.types.responses import TransferToHuman, ResponseToUser

return ResponseToUser(
    message="Vou transferir você para um atendente.",
    functions=[
        TransferToHuman(
            reason="Usuário solicitou falar com humano.",
            external_skill_name="Suporte Técnico",  # opcional
        )
    ],
)

Campo	Tipo	Descrição
reason	str	Motivo da transferência
external_skill_name	str | None	Nome da fila de destino
external_skill_id	str | None	ID da fila de destino
session_info	dict | None	Dados extras da sessão

RedirectToSkill

Redireciona para outra skill do agente:

from actions_sdk.core.types.responses import RedirectToSkill, ResponseToAgent

return ResponseToAgent(
    status=ResponseStatus.SUCCESS,
    instruction="Redirecionando para skill de suporte.",
    functions=[
        RedirectToSkill(
            skill_name="suporte_tecnico",
            reason="Usuário precisa de suporte técnico especializado.",
        )
    ],
)

Campo	Tipo	Descrição
skill_name	str	Nome da skill de destino
reason	str	Motivo do redirecionamento
session_info	dict | None	Dados extras da sessão

RedirectToAgent

Redireciona para outro agente:

from actions_sdk.core.types.responses import RedirectToAgent, ResponseToAgent

return ResponseToAgent(
    status=ResponseStatus.SUCCESS,
    instruction="Redirecionando para agente especializado.",
    functions=[
        RedirectToAgent(
            agent_id="uuid-do-agente",
            reason="Demanda fora do escopo deste agente.",
        )
    ],
)

Campo	Tipo	Descrição
agent_id	str	ID do agente de destino
reason	str	Motivo do redirecionamento
session_info	dict | None	Dados extras da sessão

SkillTransfer

Transferência para skill com nome amigável:

from actions_sdk.core.types.responses import SkillTransfer, ResponseToAgent

return ResponseToAgent(
    status=ResponseStatus.SUCCESS,
    instruction="Transferindo para skill de vendas.",
    functions=[SkillTransfer(name="Vendas", reason="Usuário quer comprar.")],
)

---

Erros e Exceções

Não há exceções lançadas pelos tipos de resposta em si. Os erros ocorrem dentro da lógica da action. A prática recomendada é capturar todas as exceções e retornar ResponseToAgent(status=ResponseStatus.ERROR, ...) — nunca deixar a exception propagar sem tratamento.