Taxa de sucesso de ferramenta
Tool Success Rate
Métrica agêntica
IntermediárioCategoria: Evals, testes e métricasSubcategoria: Métricas de GenAI e agentes
O que significa
É a proporção de chamadas de ferramenta que foram bem-formadas (esquema válido, parâmetros corretos) e executadas com sucesso.
As falhas se dividem em três tipos: o modelo chamou a ferramenta errada, chamou com parâmetros inválidos, ou a ferramenta em si falhou. Cada tipo aponta para uma correção diferente: descrição da ferramenta, esquema de parâmetros ou infraestrutura.
É a métrica de diagnóstico mais útil para agentes que não estão funcionando bem.
Como usar na prática de produto
Em Produto, quando um agente falha, a primeira coisa a olhar é o registro das chamadas de ferramenta. Uma taxa baixa de chamadas válidas é um problema de descrição e esquema, que se resolve sem trocar de modelo.
Vale medir por ferramenta: uma única ferramenta mal descrita pode derrubar o agente inteiro.
Por exemplo, a ferramenta consultar_contrato tinha 71% de chamadas válidas: o modelo passava o número do cliente onde ia o número do contrato. Renomear o parâmetro resolveu.
Quando usar este termo ou outro
Use taxa de sucesso de ferramenta para depurar agentes e priorizar correções.
Use taxa de sucesso da tarefa para medir o resultado final.
Use registro de execução (trace) para investigar chamadas específicas.
Uma forma simples de diferenciar: taxa de sucesso de ferramenta diz se o agente usa bem suas ferramentas; taxa de sucesso da tarefa diz se ele chega ao resultado.
Exemplos de aplicação
- Parâmetro trocado: 71% de chamadas válidas resolvido ao renomear o parâmetro.
- Por ferramenta: identificar qual ferramenta concentra as falhas.
- Descrição: melhorar a descrição de quando usar cada ferramenta.
- Infraestrutura: separar erros do modelo de erros da ferramenta em si.
- Priorização: corrigir a ferramenta mais usada com mais falhas primeiro.
Como calcular
Fórmulas:
Taxa de sucesso de ferramenta = chamadas válidas e executadas com sucesso ÷ total de chamadas.
Decomposição:
Taxa de chamada bem-formada = chamadas que passaram na validação de esquema ÷ total.
Taxa de seleção correta = chamadas à ferramenta apropriada (julgada no eval) ÷ total.
Taxa de execução = execuções sem erro ÷ chamadas válidas.
Passo a passo:
1. Registre toda chamada de ferramenta com seus parâmetros e resultado.
2. Classifique cada uma: válida e bem-sucedida, esquema inválido, ferramenta errada, erro de execução.
3. Calcule as taxas, no total e por ferramenta.
Exemplo:
A ferramenta consultar_contrato recebeu 1.000 chamadas: 710 válidas e bem-sucedidas, 250 com parâmetro trocado, 40 com erro de execução. Taxa de sucesso = 71%.
Como interpretar:
Falhas de esquema apontam para a descrição e os nomes dos parâmetros. Falhas de seleção apontam para a descrição de quando usar cada ferramenta. Falhas de execução apontam para a infraestrutura.
Origem do termo
Observabilidade de agentes (OpenTelemetry GenAI semantic conventions, 2024).
Fonte técnica
OpenTelemetry, Semantic conventions for GenAI agent and tool spans