Experimentos

task é uma união discriminada por type.

Modelo direto — sem ferramentas; o input do caso vira a mensagem do usuário.

{
  "type": "model",
  "model": "anthropic/claude-haiku-4-5",
  "system": "Responda apenas com o número da apólice.",
  "temperature": 0,
  "maxOutputTokens": 512
}

Agent — cada caso roda como uma session real do agent, com tools, skills, memória e o loop durável. A última mensagem do assistente é o que os scorers pontuam.

{
  "type": "agent",
  "agentId": "agent_...",
  "agentVersion": 7,
  "maxTurns": 12,
  "timeoutMs": 600000,
  "confineReadonly": false
}

confineReadonly é false por padrão de propósito: a avaliação vale pela fidelidade ao que o agent faz em produção. Ligue quando o dataset for grande e os efeitos colaterais forem indesejados.

agentVersion é resolvida e congelada na criação: omitida, a API grava a versão corrente daquele instante. O experimento persistido sempre tem um número.

Sem isso, um experimento que guardasse "o agent X" sem versão deixaria de ser reprodutível — bastaria alguém editar o agent para a mesma leitura passar a descrever outra coisa, e a comparação entre a versão N e a N+1 perderia o sentido.

A criação barra na hora se o agent não existir, estiver arquivado ou a versão pedida não existir: não se enfileira um run que só falharia caso a caso, depois de gastar sessão.

Pelo menos um scorer, no máximo 8, todos de tipos distintos (a agregação por scorer chaveia por tipo).

const experiment = await client.experiments.create({
  datasetId: 'ds_...',
  name: 'Extração de apólice — v7 vs v6',
  task: { type: 'agent', agentId: agent.id, agentVersion: 7 },
  scorers: [{ type: 'contains', value: 'apólice' }],
});

Resposta (201): o experimento com status: "pending", caseCount já preenchido e totals: null. Acompanhe por GET /:id até completed ou failed; os resultados por caso saem em GET /:id/results.

• 200 casos é o teto de um experimento de agent (cada caso é uma execução com ferramentas, não uma chamada de modelo). Dataset maior devolve 400 experiment.too_many_cases, e a message traz o teto e a contagem do dataset. Task de modelo não tem esse teto.
• Falha de um caso não derruba o experimento: estouro de turnos, estouro de tempo ou erro do loop viram um resultado com status: "error", e o lote continua.
• requires_action falha na hora. Um caso que pause aguardando ação externa — custom tool sem cliente para executá-la, ou uma tool always_ask sem operador para confirmar — não fica pendurado até o teto de tempo: o caso termina com erro explícito dizendo o que faltou. Agents que dependem de custom tools do cliente não são avaliáveis sem um executor.
• Orçamento. A criação de um experimento de agent passa pelo enforcement de budget — do workspace e do agent alvo. Estourado com ação block, a resposta é 403 budget.exceeded. Ver Usage e orçamentos.

• Agents (API)
• Usage e orçamentos