Referência
SDK JavaScript/TypeScript
Todas as opções e métodos da classe Compose. Roda em Node.js 18+, no servidor ou em funções serverless.
new Compose(options)
| Opção | Tipo | Descrição |
|---|---|---|
generate | (prompt) => Promise<string> | Modelo principal: escreve os programas. Obrigatório para run com intent e para explore. |
judge | (prompt) => Promise<string> | Modelo barato usado por ai() e classify() dentro do programa. |
apiKey | string | Chave vdy_live_… do painel: regras, receitas e registro das execuções. |
apiUrl | string | Endereço do painel (padrão: o do Vardy). |
onApproval | (req) => boolean | Promise<boolean> | Chamado quando o plano precisa de aprovação. Recebe effects, summary e reasons. |
approvals | 'local' | 'dashboard' | Sem onApproval: 'local' (padrão) devolve PENDING_APPROVAL; 'dashboard' também envia o pedido para aprovação no painel (plano Business). |
shareApprovalDetails | boolean | Envia o pedido em texto e os argumentos para o aprovador ver. Padrão false. Apagados após a decisão. |
approvalRequester | (user) => string | null | Id de quem pediu, mostrado ao aprovador. Padrão: user.id. |
onResult | (result) => void | Recebe o resultado completo de cada execução (para seu log local). |
reportRuns | boolean | Enviar metadados ao painel (padrão: true com apiKey). |
configTtlMs | number | Por quanto tempo reutilizar a configuração do painel (padrão 30.000). |
limits | ComposeLimits | Limites abaixo. |
Limites (limits)
| Limite | Padrão | Descrição |
|---|---|---|
timeoutMs | 10.000 | Tempo máximo do programa. |
memoryBytes | 64 MiB | Memória da sandbox. |
maxCalls | 200 | Chamadas de função por execução. |
maxWrites | 50 | Limite absoluto de alterações por execução (acima disso, bloqueia). |
approvalAboveWrites | 3 | Acima disso, todas as alterações pedem aprovação. 0 = todas; -1 = desligado. |
maxAiCalls | 100 | Chamadas a ai()/classify() por execução. |
aiMaxInputChars | 12.000 | Tamanho máximo de entrada por chamada a ai(). |
aiConcurrency | 8 | Chamadas simultâneas ao modelo barato. |
Métodos
| Método | Descrição |
|---|---|
register(fn) | Cadastra uma função do seu sistema (read ou write). |
connectDatabase(opts) | Conecta um banco somente leitura (postgres, mysql, mssql, sqlite). |
connectMcp(opts) | Usa um servidor MCP como fonte de funções. |
run(input) | Pedido direto: intent, code ou recipe. Opções: params, user, mode ("auto" | "plan"), readOnly, limits. |
explore(input) | Pergunta aberta em rodadas. Opções: goal, user, maxRounds (6), allowWrites (true), observationChars (3.000). |
commit(result, user) | Executa o plano de um resultado PENDING_APPROVAL depois de aprovado. |
waitForApproval(result, user, { timeoutMs?, intervalMs? }) | Espera a decisão do painel. Aprovado: executa o plano aprovado. Rejeitado ou expirado: POLICY_BLOCKED. Tempo esgotado: devolve o resultado pendente. |
checkApproval(result, user) | Igual ao anterior, mas checa uma vez só. Para serverless e filas. |
validate(code) | Valida um programa sem executar (útil para revisar receitas). |
prompt(intent) | Mostra o prompt que seria enviado ao modelo (só descrições, sem dados). |
flush() | Espera o envio dos metadados ao painel (use antes de encerrar uma função serverless). |
close() | Fecha conexões MCP e chama flush(). |
Funções: register
typescript
vardy.register({
name: 'listarPedidos', // identificador JavaScript
kind: 'read', // 'read' | 'write'
description: 'Lista pedidos de um cliente',
parameters: { type: 'object', required: ['clienteId'], properties: { clienteId: { type: 'string' } } },
returns: { type: 'array' }, // opcional, conferido a cada chamada
policy: { /* max_value, allowed_values, blocked_values, active_hours */ },
requiresApproval: false,
onViolation: 'block', // ou 'escalate'
handler: async (args, { user, runId, idempotencyKey }) => { /* seu código */ },
})
Resultado de run
Campos principais: status, output, effects (alterações com decisão e status), steps (cada chamada), code, params, template, aiCalls, latencyMs, error. Os status estão descritos em Conceitos.
Resultado de explore
status (ANSWERED, ACTED, PENDING_APPROVAL, POLICY_BLOCKED, MAX_ROUNDS, GENERATION_ERROR), answer, rounds (ação, nota, código, status e o resumo visto pela IA), finalRun, aiCalls, latencyMs.