Templates

Prompts reutilizaveis com variaveis — defina uma vez, use em qualquer chamada.

Copiar como .md

Templates sao prompts reutilizaveis com variaveis. Crie uma vez e use em qualquer chamada de `/process` ou `/chat`. ## Sintaxe de variaveis Use `{{nomeVariavel}}` no `promptTemplate`: ``` Escreva um email profissional para {{empresa}} sobre {{assunto}}. Tom: {{tom}}. ``` ## Listar templates ```bash curl https://api.buildship.com.br/api/v1/templates \ -H "X-API-Key: bld_sua_chave" ``` ## Criar template ```bash curl -X POST https://api.buildship.com.br/api/v1/templates \ -H "X-API-Key: bld_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "name": "Gerador de email", "promptTemplate": "Escreva um email para {{empresa}} sobre {{assunto}}. Tom: {{tom}}.", "variables": { "empresa": "Nome da empresa destinataria", "assunto": "Assunto do email", "tom": "formal" }, "description": "Gera emails profissionais", "tags": ["email", "comercial"] }' ``` **Resposta:** ```json { "id": "tmpl_abc123", "name": "Gerador de email", "slug": "gerador-de-email", "promptTemplate": "...", "variables": { "empresa": "...", "assunto": "...", "tom": "formal" }, "usageCount": 0, "createdAt": "2026-04-28T10:00:00Z" } ``` ## Criar template via upload de arquivo Pra prompts longos, voce pode enviar um `.md` ou `.txt`: ```bash curl -X POST https://api.buildship.com.br/api/v1/templates/upload \ -H "X-API-Key: bld_sua_chave" \ -F "file=@meu-prompt.md" \ -F "name=Gerador de email v2" \ -F "variables={\"empresa\":\"\",\"assunto\":\"\",\"tom\":\"formal\"}" ``` O conteudo do arquivo vira o `promptTemplate`. Variaveis sao parseadas do JSON em `variables`. ## Atualizar template ```bash curl -X PUT https://api.buildship.com.br/api/v1/templates/tmpl_abc123 \ -H "X-API-Key: bld_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "promptTemplate": "Escreva um email curto para {{empresa}}...", "variables": { "empresa": "..." } }' ``` ## Deletar template ```bash curl -X DELETE https://api.buildship.com.br/api/v1/templates/tmpl_abc123 \ -H "X-API-Key: bld_sua_chave" ``` ## Usar template numa chamada Em vez de passar `prompt`, passa `templateId` + `templateVars`: ```bash curl -X POST https://api.buildship.com.br/api/v1/chat \ -H "X-API-Key: bld_sua_chave" \ -H "Content-Type: application/json" \ -d '{ "templateId": "tmpl_abc123", "templateVars": { "empresa": "Acme Corp", "assunto": "Proposta comercial", "tom": "formal" }, "endUserId": "user-456" }' ``` A IA recebe o `promptTemplate` com as variaveis substituidas. ## Defaults nas variaveis No campo `variables` do template, o **valor** funciona como descricao OU default: ```json { "variables": { "tom": "formal", // default = "formal" se nao passar "empresa": "Empresa X" // descricao da variavel } } ``` ## Boas praticas - **Nomes descritivos**: `gerador-email-comercial` em vez de `tmpl1` - **Variaveis claras**: `{{empresa_destino}}` em vez de `{{e}}` - **Versione**: tags como `v1`, `v2` em `tags` pra trackear evolucao - **Teste antes de publicar**: rode `/chat` com `templateId` + `templateVars` mockados e veja a saida ## Exemplo: Pipeline de extracao de CV ```json { "name": "Extrator de CV", "promptTemplate": "Extraia do curriculo anexo:\n- Nome\n- Email\n- Telefone\n- Anos de experiencia em {{area}}\n- Formacao\n\nRetorne em JSON com chaves: name, email, phone, experience_years, education.", "variables": { "area": "engenharia de software" } } ``` Use: ```bash curl -X POST .../api/v1/process \ -F "file=@cv.pdf" \ -F "templateId=tmpl_extrator" \ -F "templateVars={\"area\": \"data science\"}" ```