Skip to main content
SDK v1 — Documentação Legacy

Esta página documenta o Actions SDK v1. Para a versão atual (v2), consulte a documentação do SDK v2.

Prompt Management

Visão Geral​

O PromptManager permite buscar e reutilizar prompts cadastrados na plataforma diretamente dentro das actions, sem precisar inserir textos no código. Com ele, você centraliza a gestão de prompts na plataforma e os injeta dinamicamente nas suas actions — inclusive com suporte a variáveis de formatação.

Cadastrando Prompts na Plataforma​

Antes de usar o PromptManager nas suas actions, o prompt precisa estar cadastrado e publicado na plataforma.

Visualizando os Prompts Existentes​

Na página de Prompts, você encontrará uma lista com todos os prompts cadastrados no seu workspace, incluindo nome, slug e status de publicação.

Listagem de Prompts

Criando um Novo Prompt​

Para criar um novo prompt:

  1. Clique no botão "+ Novo Prompt" localizado no canto superior direito da tela

Modal de criação de Prompt

  1. Preencha o formulário de criação com as seguintes informações:

    • Nome (obrigatório): Identificação legível do prompt
    • Slug (obrigatório): Identificador único utilizado para buscar o prompt nas actions (preenchido automaticamente com base no nome)
    • Descrição (obrigatório): Explicação detalhada do propósito e funcionalidades do Prompt

  2. Clique em "Criar" para finalizar o processo

Configurando e Publicando o Prompt​

Após criar o prompt, você será redirecionado para a página de configuração, onde pode escrever o conteúdo.

O prompt suporta parâmetros dinâmicos: adicione os parâmetros desejados nas configurações e, no texto do prompt, referencie-os entre chaves {nome_do_parametro}. Ao chamar get_prompt na sua action, os valores passados serão substituídos automaticamente nos respectivos lugares.

Exemplo:

  • Parâmetros cadastrados: nome, protocolo
  • Texto do prompt: "Olá {nome}, seu protocolo {protocolo} está em andamento."
  • Chamada na action: prompt_manager.get_prompt("meu_prompt", nome="João", protocolo="12345")
  • Resultado: "Olá João, seu protocolo 12345 está em andamento."

Configuração do Prompt

Prompt precisa estar publicado

O PromptManager só consegue buscar prompts que estejam publicados. Um prompt salvo como rascunho não é acessível pelas actions. Certifique-se de clicar em Publicar antes de utilizá-lo.

📖 Métodos Principais​

get_prompt(name_slug, **parametros)​

Busca um prompt pelo seu name_slug e, opcionalmente, substitui os parâmetros definidos no texto do prompt.

Parâmetros:

  • name_slug (str): Obrigatório — Slug do prompt cadastrado na plataforma
  • **parametros: Valores nomeados para substituir no texto do prompt (opcional) — ex: nome="João", protocolo="12345"

Quando utilizar:

  • Buscar system prompts cadastrados na plataforma
  • Reutilizar templates de mensagem em diferentes actions
  • Injetar variáveis dinâmicas em prompts pré-configurados
  • Centralizar a gestão de prompts fora do código

Resultado esperado:

  • Texto do prompt formatado (str)
  • ValueError se o prompt não for encontrado ou não tiver texto publicado

Exemplos:

# Sem parâmetros
system_prompt = prompt_manager.get_prompt("atendimento_inicial")
# Retorna: "Você é um assistente de atendimento ao cliente..."

# Com parâmetros
confirmation = prompt_manager.get_prompt(
    "confirmacao_pedido",
    nome="Maria",
    pedido="12345",
    valor="R$ 99,90"
)
# Template: "Olá {nome}, seu pedido #{pedido} no valor de {valor} foi confirmado."
# Retorna: "Olá Maria, seu pedido #12345 no valor de R$ 99,90 foi confirmado."

💡 Casos de Uso Comuns​

✅ System Prompt Dinâmico​

def processar_solicitacao(mensagem: str):
    # Busca system prompt centralizado — sem hardcode no código
    system_prompt = prompt_manager.get_prompt("triagem_solicitacoes")

    result = llm_helper.completion(
        system_prompt=system_prompt,
        user_prompt=mensagem,
        temperature=0.2,
        generation_name="triagem"
    )

    return result["content"]

✅ Template com Variáveis Dinâmicas​

def notificar_cliente(nome: str, protocolo: str, prazo: str):
    # Template cadastrado:
    # "Olá {nome}! Seu protocolo {protocolo} será resolvido em até {prazo}."
    mensagem = prompt_manager.get_prompt(
        "notificacao_protocolo",
        nome=nome,
        protocolo=protocolo,
        prazo=prazo
    )

    send_message(mensagem)
Prompt Não Publicado

O método get_prompt lança ValueError se o name_slug não existir no banco ou se o prompt não tiver um texto publicado. Sempre trate essa exceção em código crítico ou use um fallback.