Prompts (PromptManager)

O PromptManager recupera prompts publicados na plataforma diretamente do banco de dados. Use quando a action precisa de textos de prompt que podem ser editados pelo time sem alterar o código da action.

Inicialização

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.features.prompts.manager import PromptManager

ctx: ActionContext

prompts = PromptManager(ctx)

Funciona com ActionContext e TaskContext. Extrai ctx.prompt_storage automaticamente.

---

Métodos

get_prompt(name_slug, **format_kwargs)

Retorna o texto do prompt identificado por name_slug. Se format_kwargs forem fornecidos, aplica interpolação com str.format_map() antes de retornar.

prompts = PromptManager(ctx)

# Prompt simples
texto = prompts.get_prompt("saudacao_inicial")

# Prompt com variáveis interpoladas
texto = prompts.get_prompt(
    "saudacao_cliente",
    nome="Alice",
    produto="Plano Premium",
)
# Se o prompt for: "Olá, {nome}! Seu {produto} está ativo."
# Retorna: "Olá, Alice! Seu Plano Premium está ativo."

Parâmetros:

Parâmetro	Tipo	Descrição
name_slug	str	Identificador único do prompt na plataforma
**format_kwargs	Any	Variáveis para interpolação no template do prompt

Retorna: str — texto do prompt, opcionalmente formatado.

Exceções:

• RuntimeError — se ctx.prompt_storage não foi injetado
• PromptNotFoundError — se o slug não existir ou o prompt não estiver publicado

---

invalidate(name_slug)

Invalida o cache do prompt, forçando recarga na próxima chamada.

prompts.invalidate("saudacao_inicial")

Útil após publicar uma nova versão do prompt e querer forçar o uso imediato.

---

warm(name_slug, text)

Pré-aquece o cache do prompt com um texto fornecido.

prompts.warm("saudacao_inicial", "Olá! Como posso ajudar?")

---

Erros e Exceções

Exceção	Quando ocorre	Como tratar
PromptNotFoundError	Slug não existe ou prompt não está publicado	Informe o usuário / use texto fallback
RuntimeError	ctx.prompt_storage não injetado	Indica problema de configuração do motor

from actions_sdk.features.prompts.manager import PromptNotFoundError

try:
    texto = prompts.get_prompt("meu_prompt")
except PromptNotFoundError as erro:
    # Prompt não encontrado — use fallback ou informe o usuário
    texto = "Olá! Como posso ajudar você hoje?"
except RuntimeError as erro:
    # Problema de infraestrutura
    return ResponseToAgent(
        status=ResponseStatus.ERROR,
        instruction=f"Falha no acesso ao storage de prompts: {erro}",
    )

---

Exemplo completo

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

import json
import traceback

from actions_sdk.core.types.action_context import ActionContext
from actions_sdk.core.types.message_components import TextMessage
from actions_sdk.core.types.responses import ResponseStatus, ResponseToUser
from actions_sdk.features.conversational.state import StateManager
from actions_sdk.features.prompts.manager import PromptManager, PromptNotFoundError
from actions_sdk.features.tracing import ActionSpan

ctx: ActionContext

CHAVE_PROGRESSO = "action.prompts.progresso"


def buscar_prompt(slug: str, parametros_json: str | None = None):
    span = ActionSpan(ctx)
    state = StateManager(ctx)

    # Parse dos parâmetros opcionais
    parametros = {}
    if parametros_json:
        try:
            parametros = json.loads(parametros_json)
        except json.JSONDecodeError as erro:
            state.update(CHAVE_PROGRESSO, "JSON_INVALIDO ✗")
            return ResponseToUser(
                instruction="Parâmetros JSON inválidos.",
                message=TextMessage(body=f"JSON malformado: {erro}"),
                status=ResponseStatus.ERROR,
                state_updates=state.get_full_state(),
            )

    span.event("action.prompts.inicio", {"slug": slug, "tem_params": bool(parametros)})

    try:
        prompt_manager = PromptManager(ctx)
        texto = prompt_manager.get_prompt(slug, **parametros)

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

        return ResponseToUser(
            instruction=f"Prompt '{slug}' recuperado com sucesso.",
            message=TextMessage(body=texto),
            status=ResponseStatus.SUCCESS,
            state_updates=state.get_full_state(),
        )

    except PromptNotFoundError as erro:
        state.update(CHAVE_PROGRESSO, "NAO_ENCONTRADO ✗")
        span.event("action.prompts.nao_encontrado", {"slug": slug, "erro": str(erro)})
        return ResponseToUser(
            instruction=f"Prompt '{slug}' não encontrado.",
            message=TextMessage(body="O prompt informado não foi localizado ou não está publicado."),
            status=ResponseStatus.ERROR,
            state_updates=state.get_full_state(),
        )

    except Exception as erro:
        state.update(CHAVE_PROGRESSO, "ERRO ✗")
        span.event("action.prompts.erro", {"erro": str(erro)})
        return ResponseToUser(
            instruction=f"Falha ao buscar prompt: {traceback.format_exc()}",
            message=TextMessage(body="Erro inesperado ao buscar o prompt."),
            status=ResponseStatus.ERROR,
            state_updates=state.get_full_state(),
        )