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 Agentes | Descoberta do problema |
| 2 | Por Que Desenvolvemos o Novo Apidog CLI | Desenvolvimento da arquitetura |
| 3 | A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base nos Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Falar com Agentes |
Saída estruturada |
| 5 | SKILL: Entregando Experiência Operacional como 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 |
Construímos CLI + SKILL para lidar com o que o MCP não otimiza: fluxos de trabalho complexos com validações e execução estruturada.
O MCP Continua a Servir ao Seu Propósito
Antes de mergulharmos em CLI + SKILL, vamos esclarecer: o Apidog MCP ainda está disponível e sendo mantido.
O MCP oferece conexões de ferramentas padronizadas seguindo o protocolo—isso é valioso para:
- Operações simples e bem definidas
- Usuários que preferem fluxos de trabalho baseados em MCP
- Integração de ecossistemas com clientes compatíveis com MCP
Nós não substituímos o MCP. Construímos CLI + SKILL para complementá-lo.
O que descobrimos é que o MCP se destaca em conectar ferramentas, mas para fluxos de trabalho complexos de P&D—processos multi-etapas com validação, leitura e verificação—os Agentes se beneficiam de processos de engenharia executáveis. É aí que CLI + SKILL se encaixa.
Pense da seguinte forma:
| Tipo de Tarefa | Abordagem Recomendada |
|---|---|
| Chamada de ferramenta simples (ex: obter endpoint) | MCP ou CLI—ambos funcionam |
| Fluxo de trabalho multi-etapas (ex: criar teste, validar, executar) | CLI + SKILL—melhor experiência |
| Integração CI/CD | CLI—ajuste nativo |
| Integração de ecossistema MCP | MCP—padrão de protocolo |
O Antigo CLI: Executando Testes no Final
O Apidog CLI há muito tempo é o ponto de entrada de linha de comando para executar testes de API.
apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>Essa base ainda é importante. As equipes precisam de uma forma confiável de:
- Executar testes de API a partir do terminal
- Gerar relatórios em pipelines CI
- Manter portas de qualidade dentro dos fluxos de trabalho de automação
Mas o antigo CLI se concentrava principalmente na execução de testes. Ele aparecia perto do final do fluxo de trabalho:
Design → Documentar → Mock → Depurar → Testar → [CLI executa testes]O CLI era a última etapa—depois que todo o resto estava feito.
O Novo Requisito: Agentes Precisam de Mais
O desenvolvimento de API está mudando.
Agentes de IA agora estão participando em:
| Etapa | Atividade do Agente |
|---|---|
| Design de API | Gerando definições de endpoint a partir do PRD |
| Geração de testes | Criando casos de teste a partir de especificações de API |
| Depuração | Analisando falhas, sugerindo correções |
| Migração | Movendo APIs entre projetos |
| Manutenção | Atualizando testes quando as APIs mudam |
Para esses fluxos de trabalho, um CLI não pode ser apenas a última etapa que executa testes existentes.
Ele também precisa fornecer aos Agentes uma maneira estável de:
- Ler ativos de API (endpoints, esquemas, ambientes)
- Criar ou atualizar ativos de teste (casos de teste, cenários de teste)
- Validar alterações estruturadas antes de gravar
- Gravá-las de volta no projeto
- Verificar o resultado
Expansão Sistemática, Não Adição Incremental
O novo Apidog CLI não está apenas adicionando alguns comandos ao antigo CLI.
Está introduzindo sistematicamente as capacidades centrais do Apidog no CLI, tornando-o uma camada de fluxo de trabalho para desenvolvedores, scripts e Agentes de IA.
| Antiga Pergunta do CLI | Nova Pergunta do CLI |
|---|---|
| "Como executo testes Apidog externamente?" | "Como Agentes de IA podem usar o Apidog de forma estável?" |
As fronteiras arquitetônicas por trás mudaram dramaticamente.
MCP VS CLI: Comparação da Cadeia de Execução
Vamos comparar as cadeias de execução típicas para fluxos de trabalho complexos.
Rota MCP (Boa para Conexão de Ferramentas)
Inicializar sessão MCP
↓
Carregar lista de ferramentas + descrições de ferramentas
↓
Agente seleciona ferramenta
↓
Buscar mais ferramentas (listOpenApiEndpoints)
↓
Obter esquema (getOpenApiDetails)
↓
Executar chamada HTTP (executeOpenApi)Força do MCP: Protocolo padronizado para conectar ferramentas a Agentes.
Colocação da complexidade: A maior parte da complexidade está no contexto do modelo e na fase de seleção da ferramenta. O Agente precisa entender:
- Listas de ferramentas
- Descrições de ferramentas
- Esquemas de entrada
- Sequências de chamada
- Estruturas de retorno
Onde funciona bem: Operações simples com mapeamento claro de ferramenta para tarefa.
Onde se torna desafiador: Fluxos de trabalho complexos onde o Agente deve orquestrar múltiplas ferramentas, entender a semântica do produto e lidar com a validação.
Rota CLI + SKILL (Melhor para Fluxos de Trabalho Complexos)
SKILL julga o tipo de tarefa
↓
CLI executa comandos semânticos de produto
↓
cli-schema valida a estrutura
↓
agentHints oferece sugestões de próximo passo
↓
Loop de verificação (obter feedback ou apidog run)Força do CLI + SKILL: Distribui a complexidade no sistema de engenharia.
Colocação da complexidade:
- SKILL: Metodologia e orientação de fluxo de trabalho
- CLI: Execução semântica do produto
- cli-schema: Validação antes da gravação
- agentHints: Navegação após a execução
Onde funciona bem: Fluxos de trabalho multi-etapas, operações com alta validação, testes conduzidos por Agentes.
A Principal Diferença: Onde a Complexidade Reside
A diferença entre essas duas abordagens é onde a complexidade é colocada.
| Abordagem | Onde a Complexidade Reside | Melhor Para |
|---|---|---|
| MCP | Contexto do modelo + fase de seleção da ferramenta | Chamadas de ferramenta simples, ecossistema MCP |
| CLI + SKILL | Sistema de engenharia (SKILL, CLI, validação, dicas) | Fluxos de trabalho complexos, operações multi-etapas |
No MCP, o modelo deve carregar:
- Qual ferramenta usar
- O que a descrição da ferramenta diz
- Quais campos são obrigatórios
- Qual sequência seguir
- O que a estrutura de retorno significa
Isso funciona quando o mapeamento de tarefa para ferramenta é direto.
No CLI + SKILL, o sistema de engenharia carrega:
- Qual tipo de tarefa é esta (SKILL)
- Qual comando executar (CLI)
- Qual estrutura é válida (cli-schema)
- O que fazer em seguida (agentHints)
Isso funciona melhor quando os fluxos de trabalho têm validações, requisitos de leitura e loops de verificação.
Um Exemplo de Fluxo de Trabalho Típico
Aqui está um exemplo concreto do fluxo de trabalho CLI + SKILL:
# Etapa 1: Ler fatos
apidog endpoint get <endpointId> --project <projectId>
# Etapa 2: Validar antes de escrever
apidog cli-schema validate test-case-create --file ./test-case-create.json
# Etapa 3: Executar verificação
apidog run --project <projectId> --out-dir ./apidog-reportsEsses três comandos representam três ações de engenharia:
| Comando | Ação |
|---|---|
endpoint get |
Ler fatos do projeto |
cli-schema validate |
Validar estrutura antes de escrever |
apidog run |
Executar verificação |
Caminho do Agente para Fluxos de Trabalho Complexos
Para fluxos de trabalho complexos e multi-etapas, o caminho do Agente se beneficia da estrutura CLI + SKILL.
Caminho MCP para Fluxos de Trabalho Complexos
"Selecionar ferramentas → Entender esquemas → Orquestrar sequência → Lidar com erros"O Agente:
- Seleciona as ferramentas apropriadas entre muitas opções
- Entende as descrições e esquemas das ferramentas
- Orquestra a sequência correta
- Lida com erros através de retentativas
Isso pode funcionar, mas exige um raciocínio significativo do modelo para cada ponto de decisão.
Caminho CLI + SKILL para Fluxos de Trabalho Complexos
"Ler fatos → Gerar mudanças → Validar estrutura → Escrever → Executar verificação"O Agente:
- Lê os fatos existentes primeiro (guiado por SKILL)
- Gera mudanças com base nos fatos
- Valida a estrutura localmente (cli-schema)
- Escreve para o projeto
- Executa a verificação (agentHints guia o próximo passo)
O sistema de engenharia lida com a validação, orientação e verificação—reduzindo a carga de raciocínio do modelo.
Ambos os caminhos podem concluir a tarefa. CLI + SKILL reduz a complexidade na fase de contexto do modelo.
O Que o CLI Agora Abrange
Com a atualização, o CLI agora abrange mais recursos centrais do Apidog:
| Recurso | Capacidade do CLI |
|---|---|
| Projetos e metadados | Listar, ler |
| APIs e definições de API | Obter, criar, atualizar |
| Ambientes e variáveis | Listar, gerenciar |
| Casos de teste | Criar, atualizar, validar |
| Cenários de teste | Criar, atualizar, importar etapas, obter com detalhes |
| Conjuntos de testes | Gerenciar |
| Relatórios | Gerar a partir de apidog run |
| Importar/exportar | Exportar projeto, importar arquivos |
Isso muda o papel do Apidog CLI.
Não é simplesmente uma maneira de executar testes depois que tudo o mais foi feito.
Agora ele pode participar mais cedo no ciclo de desenvolvimento—onde um Agente precisa:
- Compreender o projeto
- Gerar ou atualizar ativos de teste
- Validar alterações
- Executar verificação
O Resumo da Arquitetura
| Dimensão | MCP | CLI + SKILL |
|---|---|---|
| Força principal | Conexão de ferramentas | Execução de fluxo de trabalho |
| Local da complexidade | Contexto do modelo | Sistema de engenharia |
| Caminho do Agente para tarefas complexas | Selecionar, orquestrar, retentar | Ler, validar, escrever, verificar |
| Cobertura | 126 ferramentas geradas + ferramentas nativas | Gerenciamento completo de recursos + validação |
| Melhor adequação | Operações simples, ecossistema MCP | Fluxos de trabalho complexos, CI/CD |
Ambos estão disponíveis. Escolha com base na sua tarefa.
O Que Vem a Seguir
Agora que estabelecemos como o CLI + SKILL complementa o MCP, a próxima pergunta é:
Qual é o princípio central que torna o CLI + SKILL eficaz para fluxos de trabalho complexos?
Na Parte 3, A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base nos Fatos, exploraremos a filosofia de design que guia cada decisão do CLI + SKILL—começando com cli-schema validate, a porta de qualidade que captura erros antes que se tornem gravações falhas.
Principais Conclusões
- O MCP continua funcionando—use-o para operações simples e integração com o ecossistema MCP
- O CLI + SKILL complementa o MCP—melhor para fluxos de trabalho complexos com validação
- A principal diferença é onde a complexidade reside: contexto do modelo vs. sistema de engenharia
- O CLI + SKILL reduz a carga de raciocínio do modelo através de validação, orientação e verificação
- O CLI agora abrange projetos, APIs, ambientes, casos de teste, cenários e muito mais
- Ambas as abordagens disponíveis—escolha com base na complexidade da tarefa
Baixe o Apidog para projetar, simular, testar e documentar APIs em um único workspace. Saiba mais sobre o Apidog CLI para testes de API via linha de comando, automação CI e fluxos de trabalho de Agentes de IA.