Enviar Mensagem (ActionMessageSender)

O ActionMessageSender envia mensagens de status ao usuário durante a execução de uma action — antes que a action retorne. Use para informar o usuário sobre o progresso de operações longas.

Quando usar

Situação	Usar ActionMessageSender	Usar ResponseToUser
Notificar progresso durante execução	✅	❌
Mensagem final ao encerrar a action	❌	✅
Enviar componentes interativos (botões, listas)	❌	✅
A action ainda continua após a mensagem	✅	❌ (encerra o ciclo)

Exemplo de uso típico: uma action que consulta uma API externa pode enviar "Consultando o sistema..." enquanto aguarda a resposta, e depois retornar ResponseToAgent com o resultado.

Inicialização

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.features.conversational.send_message import ActionMessageSender

ctx: ActionContext

msg = ActionMessageSender(ctx)

O ActionMessageSender extrai ctx.message_sender, ctx.conversation_id e ctx.skill_id automaticamente no construtor.

---

Métodos

send_message_to_user(message)

Envia uma mensagem de texto ao usuário imediatamente.

msg = ActionMessageSender(ctx)
msg.send_message_to_user("Consultando a base de dados, aguarde...")

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
message	str	✅	Texto da mensagem
metadata	dict | None	Não	Metadados opcionais

Os demais parâmetros (client_slug, session_id, skill_id, webhook_url) são herdados automaticamente do ctx e existem apenas por compatibilidade.

Exceções:

• RuntimeError — se ctx.message_sender não foi injetado pelo motor

---

Erros e Exceções

Exceção	Quando ocorre	Como tratar
RuntimeError	ctx.message_sender é None (motor não injetou o sender)	Não é possível tratar na action — indica problema de configuração do motor

---

Exemplo completo

Baseado na action send_status_message_homol do agente de homologação:

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.send_message import ActionMessageSender
from actions_sdk.features.conversational.state import StateManager
from actions_sdk.features.tracing import ActionSpan

ctx: ActionContext

CHAVE_PROGRESSO = "action.consulta.progresso"


def consultar_com_status(query: str):
    span = ActionSpan(ctx)
    state = StateManager(ctx)

    span.event("action.consultar.inicio", {"query": query})

    try:
        # Notificar o usuário antes de operação potencialmente lenta
        msg = ActionMessageSender(ctx)
        msg.send_message_to_user("Consultando o sistema, aguarde um momento...")

        # ... executar operação ...
        resultado = f"Resultado para: {query}"

        state.update(CHAVE_PROGRESSO, "SUCESSO ✓")
        span.event("action.consultar.sucesso", {"query": query})

        return ResponseToAgent(
            status=ResponseStatus.SUCCESS,
            instruction=(
                f"Consulta concluída.\n"
                f"A mensagem de status foi enviada ao usuário antes do processamento.\n"
                f"Resultado: {resultado}"
            ),
            state_updates=state.get_full_state(),
        )

    except Exception as erro:
        state.update(CHAVE_PROGRESSO, "ERRO ✗")
        span.event("action.consultar.erro", {"erro": str(erro)})
        return ResponseToAgent(
            status=ResponseStatus.ERROR,
            instruction=f"Falha na consulta: {traceback.format_exc()}",
            state_updates=state.get_full_state(),
        )