APIEval-20

O que é APIEval-20?

APIEval-20 é um benchmark de tarefas projetado para avaliar agentes de IA na geração de suítes de testes de API em cenários reais sob restrição black-box. Em vez de focar na qualidade geral do modelo ou na conformidade superficial com o schema, ele mede se um agente consegue raciocinar sobre a superfície da API e gerar testes que realmente revelam bugs.

Em cada cenário, o agente recebe apenas um schema de requisição de API e um payload de exemplo — sem código-fonte, sem documentação além do que está no schema e sem conhecimento prévio. A suíte de testes gerada é então executada contra uma implementação de referência ao vivo para observar os bugs expostos pelos testes.

Principais Recursos

• Benchmark de tarefas para agentes de IA (não um benchmark de modelos): Avalia o comportamento end-to-end do agente — design de testes e descoberta de bugs — em vez da qualidade de geração de texto.
• Conjunto de 20 cenários de domínios reais: Cenários cobrem e-commerce, pagamentos, autenticação, gerenciamento de usuários, agendamento, notificações e padrões de busca/filtro.
• Restrição de entrada black-box: O agente recebe exatamente duas entradas por cenário — (1) o JSON schema e (2) um payload de requisição de exemplo — sem schemas de resposta, detalhes de implementação, mensagens de erro ou changelogs.
• Espectro de bugs com rotulagem por complexidade: Cada cenário inclui 3–8 bugs plantados classificados por complexidade de raciocínio: problemas estruturais simples, violações moderadas de restrições de campo e interações complexas multifield/lógica de negócios.
• Formato de saída da suíte de testes (casos de teste apenas de requisição): O agente produz uma lista de casos de teste, cada um com um nome curto e um payload de requisição completo como JSON válido; não são necessários resultados esperados.

Como Usar o APIEval-20

1. Selecione um cenário do benchmark APIEval-20. Cada cenário fornece um JSON schema de requisição de API e um payload de exemplo.
2. Forneça essas duas entradas ao seu agente de IA. O benchmark é projetado especificamente para que o agente não possa depender de detalhes de implementação ou documentação extra.
3. Gere uma suíte de testes: Peça ao agente para produzir casos de teste onde cada caso inclui um nome legível por humanos e um payload de requisição JSON completo.
4. Execute os casos de teste produzidos contra a implementação de referência ao vivo: A avaliação baseia-se no que os testes revelam quando executados, não em se o agente prevê resultados esperados.

Casos de Uso

• Avaliar a capacidade de um agente de gerar testes de API significativos: Útil quando você quer saber se um agente vai além da geração formal baseada em schema e produz testes que revelam bugs reais.
• Comparar estratégias de agentes sob a mesma restrição black-box: Como as entradas se limitam a schema + payload de exemplo, diferenças de desempenho refletem raciocínio e cobertura de testes, não acesso a informações adicionais.
• Testar robustez estrutural (detecção de bugs simples): Cenários incluem verificações para campos obrigatórios ausentes, valores vazios (ex.: "", null, []), e tipos de dados errados — útil para validar tratamento básico de requisições.
• Avaliar raciocínio de restrições e validação (detecção de bugs moderados): O benchmark inclui casos como valores numéricos fora de faixa e formatos de campo malformados (ex.: email, código de moeda, formato de data), além de valores de enum em boundary/não documentados.
• Avaliar raciocínio de lógica de negócios e cross-field (detecção de bugs complexos): Alguns cenários exigem detectar problemas envolvendo campos mutuamente exclusivos, descontos aplicados a pedidos inelegíveis ou validade de campo dependente de outros campos.

FAQ

Quais entradas o agente recebe para cada cenário?
O agente recebe exatamente duas entradas: o schema JSON completo de requisição e um exemplo de payload. Não são fornecidos schema de resposta, detalhes de implementação, mensagens de erro ou outra documentação.

O agente precisa prever resultados esperados?
Não. A suíte de testes produzida consiste em casos de teste com payloads de requisição; a avaliação é feita executando esses testes contra a implementação de referência ao vivo e observando o que acontece.

Como os bugs são representados no benchmark?
Cada cenário contém múltiplos bugs plantados (entre 3 e 8), categorizados por complexidade: problemas estruturais simples, violações moderadas de restrições de nível de campo e relacionamentos complexos multifield ou semânticos/lógica de negócios.

O que o APIEval-20 avalia: conformidade com schema ou descoberta de bugs?
Descoberta de bugs. Embora as informações de schema sejam fornecidas para habilitar a geração de testes, o benchmark é projetado para testar se os testes do agente revelam bugs quando executados.

Alternativas

• Geração de testes focada em schema / verificadores de conformidade com schema: Estes se concentram em validar se as requisições geradas correspondem a um schema (ou se um sistema segue um schema). Diferem do APIEval-20 por não avaliarem diretamente o comportamento de detecção de bugs sob restrições black-box.
• Frameworks e ferramentas convencionais de teste de API (ex.: ferramentas de teste de request/contract): Esses fluxos de trabalho geralmente dependem de casos de teste criados por humanos ou conhecimento adicional. Em comparação com o APIEval-20, podem não avaliar a capacidade do agente de gerar suítes de testes direcionadas apenas a partir de schema + exemplo.
• Benchmarks gerais de avaliação de IA para geração de código ou texto: Alguns benchmarks avaliam a qualidade da saída em vez da efetividade de testes executáveis. O APIEval-20 foca especificamente no comportamento end-to-end do agente para gerar e executar testes que exponham bugs.
• Abordagens de teste baseado em propriedades de API / fuzz testing: Estas podem exercitar uma API amplamente gerando muitos inputs, mas podem não avaliar o processo de raciocínio do agente para projetar testes direcionados a partir de schema e payloads de exemplo.