DocumentaçãoEnviar dados
IA e agentes
Meça o custo de cada entrega dos seus agentes de IA com uma linha no servidor: chamadas de modelo, execuções, prova de que o resultado valeu e adoção da entrega.
Produto que chama modelo de IA tem um custo que evento de tela não mostra: quanto cada resultado custou, quanto foi pago por execução que falhou e quanto foi refeito. Isso acontece no servidor, então é o SDK server (@holdyapp/sdk/server, Node 18+) que lê. O SDK do browser sozinho não enxerga.
Três níveis
Cada nível é uma linha a mais no seu código e destrava uma leitura a mais. Dá pra começar pelo primeiro e subir depois.
| Nível | O que você escreve | O que a Holdy passa a ler |
|---|---|---|
| 1. Chamada | holdy.wrap(client) | Modelo, tokens, custo, latência, ferramentas e erro de cada chamada. Em qual modelo o gasto se concentra. |
| 2. Execução | holdy.run({ name, accountKey }, fn) | Quanto o agente conclui, quanto custa a execução que falha e quanto foi pago duas vezes em execução refeita, por conta. |
| 3. Resultado | proof(), rework(), deliver(), adopt() | Custo por resultado que valeu, entrega sem prova, entrega corrigida por gente e adoção de cada entrega. |
Medir cada chamada
import { Holdy } from '@holdyapp/sdk/server'
const holdy = new Holdy({ apiKey: process.env.HOLDY_API_KEY! })
Se o seu produto chama modelo de IA, uma linha por cliente basta: a Holdy mede cada chamada (modelo, tokens, custo em dólar, latência, ferramentas chamadas e erro) e lê sozinha quanto custa cada resultado que o agente entrega. O texto do prompt e da resposta nunca sai do seu servidor.
import Anthropic from '@anthropic-ai/sdk'
import OpenAI from 'openai'
const anthropic = holdy.wrap(new Anthropic())
const openai = holdy.wrap(new OpenAI())
Com o Vercel AI SDK, embrulhe o modelo, ou passe o middleware no wrapLanguageModel:
import { openai } from '@ai-sdk/openai'
import { generateText } from 'ai'
const model = holdy.wrap(openai('gpt-4.1'))
// ou: wrapLanguageModel({ model: openai('gpt-4.1'), middleware: holdy.aiSdkMiddleware() })
await generateText({ model, prompt })
Execuções de agente
O trabalho de um agente roda no servidor, muitas vezes em background, sem sessão de browser. O run() trata cada tarefa como uma execução: toda chamada de modelo de um cliente embrulhado lá dentro entra nela sozinha, mesmo com várias execuções em paralelo.
const resposta = await holdy.run({ name: 'support_agent', accountKey: 'acme-inc' }, async (run) => {
const reply = await anthropic.messages.create({ model: 'claude-sonnet-4-5', max_tokens: 1024, messages })
await tickets.update(ticket.id, { holdyRunId: run.id })
return reply
})
// quando o resultado valer, mesmo dias depois e de outro processo:
holdy.proof(ticket.holdyRunId)
// quando alguém precisou corrigir o que o agente entregou:
holdy.rework(ticket.holdyRunId)
- Eventos que saem —
support_agent.started, umai_generationpor chamada de modelo e, no fim,support_agent.completedcomduration_mse o total da execução. Se a função lançar, saisupport_agent.failedcom o nome do erro (nunca a mensagem) e o erro continua propagando. - Sem
run()— cada chamada vira uma execução própria, com o id da resposta do provedor como chave. Dê um nome comholdy.wrap(client, { name: 'resumo_de_contrato' }). - Prova — o agente dizer que concluiu não é o resultado valer.
run.proof()dentro da execução, ouholdy.proof()depois, com o id da execução, a resposta do modelo ou o id dela (msg_…,chatcmpl-…). A correção humana sai comrun.rework()ouholdy.rework(); ponhaai_cost_usdnela, com o preço da revisão, e o custo por resultado passa a incluir gente. - Adoção da entrega — quando uma execução produz várias entregas (20 campanhas, 5 documentos), marque cada uma com
run.deliver(outputId, { version })e, quando a pessoa usar,holdy.adopt(outputId, { action: 'publicou', target: 'campanha' }), mesmo dias depois e de outro processo. A Holdy passa a ler a adoção por entrega (adotadas ÷ disponibilizadas na espera), mostra o que a pessoa fez com elas e onde foram usadas, e o custo vira por entrega adotada.run.rework({ output_id })aponta a entrega corrigida. Adoção, sozinha, não prova valor: resultado e receita entram depois, com evidência própria. - Custo — quando o provedor não devolve o custo, o SDK calcula por uma tabela de preços embutida. Modelo fora da tabela sai só com tokens. Quem paga preço negociado passa
aiPricesno construtor. - Conta — vem do
run({ accountKey })ou deholdy.wrap(client, { accountKey }). A prova que chega de outro processo segue a conta da execução. - Streams — os streams da Anthropic, da OpenAI e do AI SDK registram quando terminam. No chat da OpenAI os tokens do stream só chegam com
stream_options: { include_usage: true }. - Sem dependência nova — os clientes são reconhecidos pelo formato; o SDK não instala nem importa os pacotes deles.
Não tem nada pra configurar na Holdy. Com as chamadas chegando, cada execução aparece em Comportamentos › Agentes: quanto o agente conclui, quanto custa cada resultado (e cada resultado aproveitado, quando a prova chega), quanto foi pago duas vezes em execução refeita e em qual modelo o gasto vaza. A Holdy abre a ação quando um desses números pede atenção.
O que a Holdy abre
Quando um desses números pede atenção, a Holdy abre a ação com as contas e o valor em jogo:
- Custo de execução que falha: quanto foi gasto em execução que não concluiu.
- Execução paga duas vezes: a mesma tarefa refeita pra mesma conta.
- Modelo caro onde não precisa: o gasto concentrado num modelo com alternativa mais barata no mesmo trabalho.
- Entrega sem prova: o agente conclui, mas o resultado não é confirmado.
- Entrega corrigida: gente refazendo o que o agente entregou.
Os dois últimos só existem a partir do nível 3: sem proof() e rework(), a Holdy sabe quanto o agente custa, mas não se o que ele entregou valeu.
O que suporta
- Clientes: Anthropic, OpenAI e compatíveis com a API da OpenAI, e o Vercel AI SDK.
- Onde roda: Node 18+ e runtimes Edge. É no servidor, onde a chamada de modelo acontece.
- Privacidade: o texto do prompt e da resposta nunca sai do seu servidor. Vão números e nomes: modelo, tokens, custo, latência, nome da ferramenta e nome do erro.