Esta é uma série de 10 partes que compartilha como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para teste de API e gerenciamento do ciclo de vida da API. Leia em ordem ou pule para qualquer post que lhe interesse:
| Título | Foco | |
|---|---|---|
| 1 | Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para Agente | Descoberta de problemas |
| 2 | Por Que Desenvolvemos o Novo Apidog CLI | Desenvolvimento da arquitetura |
| 3 | A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base em Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Falar com Agentes |
Saída estruturada |
| 5 | SKILL: Transformando Experiência Operacional em Código | Experiência operacional |
| 6 | Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens | Resultados quantitativos |
| 7 | Do PRD ao Ciclo de Teste: Um Fluxo de Trabalho Completo de Agente com Apidog CLI | Tutorial prático |
| 8 | Por Que a Compatibilidade CI/CD É Inegociável para Ferramentas de Agente | Perspectiva DevOps |
| 9 | Ramificação de IA: Mudanças de Projeto Mais Seguras com Agentes de IA | Camada de segurança |
| 10 | Spec-First Foi Ontem. Bem-vindo ao Skill-First. | Visão e futuro |
Comparamos MCP vs. CLI + SKILL em tarefas típicas de usuário. Os resultados: menos chamadas de ferramentas, menos desperdício de tokens, melhor recuperação de erros—e os dados explicam o porquê.
A Pergunta Que Importa
Toda a filosofia e os princípios de design que compartilhamos—eles realmente funcionam?
Comparamos internamente muitas tarefas típicas de usuário em ambas as abordagens:
| Tipo de Tarefa | Descrição |
|---|---|
| Adicionar caso de teste + verificação | Criar caso de teste para endpoint, executar testes |
| Manter cenários de teste | Atualizar cenários complexos de várias etapas |
| Importar/verificar ativos do projeto | Importar dados, confirmar estrutura, executar testes |
Os resultados não foram apenas melhorias subjetivas. Foram reduções mensuráveis.
Tarefa 1: Adicionar Caso de Teste com Base no Endpoint
Solicitação do usuário:
"Adicionar um teste para este endpoint e executar a verificação"
Rota MCP
| Estágio | O Que Acontece |
|---|---|
| Descoberta da ferramenta | Agente pesquisa na lista de ferramentas |
| Seleção da ferramenta | Múltiplas rodadas de seleção da ferramenta correta |
| Descoberta de campo | Agente lê o esquema da ferramenta |
| Adivinhação de campo | Agente adivinha os campos necessários |
| Tentativa de escrita | Agente chama a ferramenta de criação |
| Resposta de erro | Servidor rejeita (campo errado/necessário faltando) |
| Tentativa novamente | Agente ajusta, tenta novamente |
| Mais tentativas | Repete até o sucesso |
| Executar testes | Agente encontra a ferramenta de execução, executa |
Padrão típico:
Buscar ferramentas → Selecionar ferramenta → Ler esquema → Adivinhar campos → Escrever → Erro → Tentar novamente → Escrever → Erro → Tentar novamente → Sucesso → Encontrar ferramenta de execução → ExecutarRota CLI + SKILL
| Estágio | O Que Acontece |
|---|---|
| Orientação SKILL | SKILL identifica o tipo de tarefa, fornece fluxo de trabalho |
| Ler endpoint | CLI lê os fatos do endpoint |
| Gerar caso de teste | Agente gera com base nos dados reais do endpoint |
| Validar localmente | cli-schema valida antes da escrita |
| Escrever | CLI cria o caso de teste |
| Ler de volta | CLI retorna a estrutura criada + agentHints |
| Executar testes | agentHints sugere a execução, Agente segue |
Padrão típico:
SKILL guia → Ler endpoint → Gerar → Validar → Escrever → Ler de volta → ExecutarResultados
| Métrica | Rota MCP | CLI + SKILL | Melhoria |
|---|---|---|---|
| Etapas de chamada de ferramenta | ~15-20 | ~10-12 | ↓ ~30% |
| Tokens de descrições | ~50.000 carregados | ~2.000 carregados | ↓ ~96% |
| Tokens de tentativas | ~5.000+ de desperdício | ~500 de desperdício | ↓ ~90% |
| Desperdício total de tokens | ~55.000 | ~2.500 | ↓ ~25% |
As etapas de chamada de ferramenta diminuíram em cerca de 30%. O consumo de tokens devido a descrições de ferramentas inválidas e tentativas de erro diminuiu em cerca de 25%.
Tarefa 2: Escritas Estruturadas (Processador, Assertiva, Extrator)
Solicitação do usuário:
"Adicionar assertivas de pós-operação e extração de variáveis a este caso de teste"
Rota MCP
| Estágio | O Que Acontece |
|---|---|
| Adivinhar nomes de campo | Agente não sabe os nomes exatos |
| Adivinhar valores de enumeração | Agente adivinha comparador, tipo |
| Tentativa de escrita | Servidor rejeita valores errados |
| Tentativa de rede | Viagem de ida e volta para cada erro |
| Múltiplas tentativas | 3-5 tentativas comuns |
Erros comuns:
| Palpite Errado | Valor Correto | Contagem de Tentativas |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
Cada erro = 1 viagem de ida e volta de rede + resposta + processamento do Agente.
Rota CLI + SKILL
| Estágio | O Que Acontece |
|---|---|
| Ler caso de teste | CLI obtém a estrutura real |
| Gerar adições | Agente gera com base no formato real |
| Validar localmente | cli-schema detecta erros antes da rede |
| Corrigir localmente | Agente ajusta com base na saída da validação |
| Re-validar | Confirmar correção |
| Escrever | Apenas escritas válidas vão para o servidor |
Todos os erros detectados localmente. Nenhuma tentativa de rede para erros de campo.
Resultados
| Métrica | Rota MCP | CLI + SKILL | Melhoria |
|---|---|---|---|
| Tentativas de rede de erros estruturais | 3-5 | 0 | ↓ ~100% |
| Tokens de respostas de erro | ~2.000 | ~0 | ↓ ~100% |
| Total de chamadas repetidas | ~5 | ~1 | ↓ ~40% |
As chamadas repetidas devido a erros estruturais diminuíram em cerca de 40%.
Tarefa 3: Operações Contínuas Após a Criação
Solicitação do usuário:
"Criar um cenário de teste com estes endpoints"
Rota MCP
| Estágio | O Que Acontece |
|---|---|
| Criar cenário | Agente chama a ferramenta de criação |
| Resposta de sucesso | Agente vê "criado" |
| Continuar escrevendo | Agente atualiza/adiciona mais imediatamente |
| Pular leitura de volta | Agente não lê a estrutura real |
| Escrever com base em suposição | Agente escreve com IDs/estrutura adivinhados |
| Erro ou incompleto | Resultado não corresponde à expectativa |
Problema: Inércia de execução.
O modelo tende a continuar diretamente após o sucesso, pulando a etapa de leitura de volta.
Rota CLI + SKILL
| Estágio | O Que Acontece |
|---|---|
| Criar cenário | CLI cria cenário |
| Sucesso + agentHints | CLI retorna sucesso + sugestões para o próximo passo |
agentHints: "Ler de volta primeiro" |
Agente vê a sugestão |
| Seguir sugestão | Agente lê de volta |
| Trabalhar com estrutura real | Agente prossegue com dados precisos |
agentHints sugere explicitamente a leitura de volta. Agente segue.
Resultados
| Métrica | Rota MCP | CLI + SKILL | Melhoria |
|---|---|---|---|
| Proporção que lê de volta antes de continuar | ~20% | ~85% | ↑ ~425% |
| Tentativas de erro de pulos diretos | ~3-5 | ~0-1 | ↓ ~21% |
A proporção de Agentes que proativamente leem de volta, validam e executam a verificação aumentou significativamente. As tentativas de erro de pular diretamente para a próxima etapa diminuíram em cerca de 21%.
Resumo: De Onde Vêm as Economias
| Fonte de Economia | Explicação |
|---|---|
| Descoberta de ferramentas | Comandos CLI têm nomes claros; SKILL guia a seleção |
| Validação de esquema | Validação local detecta erros antes da chamada de rede |
| Recuperação de erros | agentHints fornece sugestões acionáveis, não apenas "falhou" |
| Orientação de leitura de volta | Evita escritas baseadas em suposições |
| Sequência de fluxo de trabalho | SKILL reduz os pontos de decisão |
A Análise Real de Custos
Insight chave:
A habilitação de produtos por Agentes não se trata de quanto mais ferramentas, melhor.
O que o modelo realmente consome:
| Tipo de Custo | Carga MCP | Carga CLI + SKILL |
|---|---|---|
| Contexto | Descrições de ferramentas, esquemas | SKILL focado na tarefa apenas |
| Atenção | Selecionar entre muitas ferramentas | Seguir fluxo de trabalho guiado |
| Seleção de caminho | Adivinhar sequências | Sequência definida por SKILL |
| Custos de tokens do usuário | Tentativas, chamadas falhas | Escritas validadas, menos chamadas |
Depois que a contagem de ferramentas aumenta, o que o modelo realmente consome não é a capacidade de chamada de API, mas sim os trade-offs entre contexto, atenção, seleção de caminho e custos de tokens do usuário.
O Princípio de Engenharia
Objetivo:
Mover esses custos para fora do contexto do modelo e de volta para posições que o sistema de engenharia pode suportar.
| Custo | Localização MCP | Localização CLI + SKILL |
|---|---|---|
| Descoberta de ferramentas | Modelo precisa pesquisar | SKILL fornece |
| Validação de campo | Modelo precisa saber | cli-schema valida |
| Orientação para o próximo passo | Modelo precisa decidir | agentHints sugere |
| Semântica do produto | Modelo precisa entender | CLI trata |
O sistema de engenharia absorve a complexidade. O modelo foca na geração e julgamento.
O Que Estes Números Significam
Os números explicam um problema mais específico:
| Insight | Implicação |
|---|---|
| 30% menos chamadas de ferramentas | Complexidade movida da descoberta para a orientação |
| 25% menos tokens desperdiçados | Erros detectados antes da rede |
| 40% menos tentativas estruturais | A validação funciona |
| 21% menos erros de pulo | agentHints evita a continuação cega |
CLI + SKILL não é apenas elegância arquitetônica. É eficiência mensurável.
O Que Vem a Seguir
Agora que validamos a abordagem com números, vamos vê-la em ação.
Na Parte 7, Do PRD ao Ciclo de Teste: Um Fluxo de Trabalho Completo de Agente, vamos percorrer um exemplo real—uma equipe tem um PRD de "Reembolso de Pedido", e o Agente usa CLI + SKILL para gerar OpenAPI, criar testes, validar e verificar.
Principais Conclusões
- Etapas de chamada de ferramenta diminuíram em ~30%
- Desperdício de tokens de descrições e tentativas diminuiu em ~25%
- Tentativas de erro estrutural diminuíram em ~40%
- Erros de pulo por ignorar a leitura de volta diminuíram em ~21%
- As economias vêm de: descoberta guiada, validação local, dicas acionáveis
- Complexidade movida do contexto para o sistema de engenharia
Baixe o Apidog para projetar, simular, testar e documentar APIs em um único workspace. Saiba mais sobre o Apidog CLI para teste de API via linha de comando, automação CI e fluxos de trabalho de Agente de IA.