Esta é uma série de 10 partes sobre 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 o post mais relevante para o seu caso de uso:
| Título | Foco | |
|---|---|---|
| 1 | Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para Agente | Descoberta do problema |
| 2 | Por Que Desenvolvemos o Novo Apidog CLI | Desenvolvimento de arquitetura |
| 3 | A Regra de Ouro: CLI Produz Fatos, Modelo Atua 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 Loop de Teste: Um Fluxo de Trabalho Completo do Agente com Apidog CLI | Tutorial prático |
| 8 | Por Que a Compatibilidade CI/CD É Inegociável para Ferramentas de Agente | Perspectiva DevOps |
| 9 | AI Branch: 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 |
Ferramentas amigáveis para Agentes precisam continuar funcionando bem em CI/CD. Neste artigo, veja como usar apidog run como base comum para pipelines, scripts, humanos e Agentes de IA.
O problema: um CLI precisa atender mais de um consumidor
Ao criar ferramentas para Agentes, é tentador otimizar apenas a experiência conversacional. Mas, no contexto de engenharia, um CLI também precisa continuar previsível para automação.
O Apidog CLI atende dois públicos principais:
| Público original | Novo público |
|---|---|
| Pipelines CI/CD | Agentes de IA |
| Sistemas de agendamento externos | Fluxos de trabalho conversacionais |
| Scripts e automação | Tarefas orientadas pelo usuário |
Na prática, muitas equipes já usam o Apidog em pipelines para:
- Executar testes automatizados de API
- Gerar relatórios
- Manter portas de qualidade
- Bloquear deploys quando testes falham
Para isso funcionar, o CLI precisa manter alguns contratos estáveis:
| Requisito | Por que importa |
|---|---|
| Saída estável | Scripts dependem de resultados previsíveis |
| Comandos scriptáveis | Pipelines precisam executar sem interação humana |
| Códigos de saída claros | CI decide sucesso ou falha com base no exit code |
| Parâmetros configuráveis | Cada ambiente pode exigir IDs, variáveis e relatórios diferentes |
Regra prática: não quebre automações existentes apenas para tornar a ferramenta mais “amigável para Agentes”.
Princípio de design
A amigabilidade com Agentes deve ser construída sobre a amigabilidade com CI/CD.
Em vez de criar um protocolo exclusivo para IA, o Apidog CLI adiciona recursos úteis para Agentes sobre uma base já validada em engenharia:
- Saída estruturada
- Validação de schema
- Detalhes de erro
- Orientação para próximos passos
- Compatibilidade com relatórios e códigos de saída
Uma boa CLI moderna deve atender quatro tipos de consumidores:
| Consumidor | O que precisa |
|---|---|
| Humanos | Saída legível, ajuda no terminal, feedback direto |
| Scripts | Saída estável e comandos previsíveis |
| Pipelines CI | Exit codes, relatórios e execução configurável |
| Agentes de IA | JSON estruturado, validação e instruções acionáveis |
Comando base: apidog run
O comando central para execução é:
apidog run --project <IDdoProjeto> \
--test-scenario <IDdoCenarioDeTeste> \
--environment <IDdoAmbiente> \
-r "cli,html,junit" \
--out-dir ./apidog-reports
Esse comando pode ser usado em três cenários comuns:
- Localmente, por um desenvolvedor
- Em CI/CD, como porta de qualidade
- Por um Agente, como verificação após alterações
Como usar em CI/CD
Em CI, o mais importante é que a execução seja determinística. O pipeline precisa saber:
- O comando terminou com sucesso?
- Onde estão os relatórios?
- O formato é compatível com a ferramenta de CI?
- A configuração muda por ambiente?
| Requisito CI | Funcionalidade no CLI |
|---|---|
| Códigos de saída |
0 para sucesso, 1 para falha |
| Arquivos de relatório | HTML, JUnit, JSON em --out-dir
|
| Parâmetros estáveis | Opções consistentes para automação |
| Execuções configuráveis | Iterações (-n), atrasos (--delay-request), ambientes (-e) |
Exemplo com GitHub Actions
# GitHub Actions
- name: Executar Testes de API
run: |
apidog run --project $PROJECT_ID \
--test-scenario $SCENARIO_ID \
--environment $ENV_ID \
-r "junit" \
--out-dir ./reports
env:
PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
SCENARIO_ID: ${{ secrets.APIDOG_SCENARIO_ID }}
ENV_ID: production
- name: Publicar Relatório de Teste
uses: mikepenz/action-junit-report@v3
with:
report_paths: './reports/junit.xml'
Fluxo esperado:
apidog run
↓
gera relatório JUnit
↓
retorna exit code 0 ou 1
↓
CI aprova ou falha o pipeline
Esse comportamento é essencial para usar testes de API como porta de qualidade antes de merge, release ou deploy.
Como um Agente usa o mesmo comando
Agentes precisam de algo além do exit code. Eles precisam entender o resultado e decidir a próxima ação.
| Requisito do Agente | Funcionalidade no CLI |
|---|---|
| Resultados estruturados | Saída JSON com objeto data
|
| Motivos de falha | Detalhes no objeto error
|
| Sugestões de próximo passo |
agentHints com nextSteps
|
| Validação antes de escrita | cli-schema validate |
Exemplo de saída estruturada consumível por um Agente:
{
"success": true,
"stats": {
"total": 10,
"passed": 8,
"failed": 2
},
"failures": [
{
"step": "Processamento de pagamento",
"error": "A asserção falhou: status != 'success'",
"response": {}
}
],
"agentHints": {
"summary": "2 testes falharam. Revise os detalhes da falha.",
"nextSteps": [
"Depure a falha da etapa de processamento de pagamento.",
"Verifique a asserção: status esperado 'success'.",
"Atualize o caso de teste ou endpoint após a correção."
]
}
}
Um Agente pode executar o seguinte loop:
executar testes
↓
ler JSON
↓
identificar falhas
↓
corrigir definição, teste ou endpoint
↓
executar novamente
A diferença é que o Agente não depende de linguagem natural ambígua. Ele trabalha sobre fatos estruturados.
Mesmo comando, consumidores diferentes
O mesmo comando pode alimentar múltiplos fluxos:
apidog run --project <IDdoProjeto> --out-dir ./apidog-reports
| Consumidor | O que extrai |
|---|---|
| Pipeline CI | Exit code 0/1 e arquivos de relatório |
| Agente | JSON, agentHints e detalhes de falha |
| Humano | Saída do console e relatório HTML |
| Script |
stdout, stderr e formatos configuráveis |
Essa é a vantagem de projetar o CLI como uma interface estável: cada consumidor usa o mesmo comando, mas extrai informações diferentes.
Pontos de integração
O Apidog CLI pode ser integrado a ferramentas de CI/CD usando a mesma base: apidog run.
| Ferramenta CI | Integração típica |
|---|---|
| Jenkins | Etapas de pipeline e publicação de relatório |
| GitLab CI | Configuração YAML e artefatos |
| GitHub Actions | Workflow steps e secrets |
| CircleCI | Configuração de workflow |
| Azure DevOps | Tarefas de pipeline e resultados de teste |
Exemplo genérico de pipeline:
apidog run \
--project "$PROJECT_ID" \
--test-scenario "$SCENARIO_ID" \
--environment "$ENV_ID" \
-r "cli,junit,html" \
--out-dir ./apidog-reports
Depois disso, o CI pode:
- Ler o exit code
- Publicar o relatório JUnit
- Armazenar o HTML como artefato
- Bloquear o deploy em caso de falha
Porta de qualidade vs. verificação por Agente
O mesmo comando pode ser usado com objetivos diferentes.
| Caso de uso | Significado |
|---|---|
| Porta de qualidade CI | Aprovação/reprovação controla a progressão do pipeline |
| Verificação do Agente | Execução após alterações para confirmar se a correção funcionou |
| Contexto | Quando usado | Propósito |
|---|---|---|
| CI | Após push, PR ou merge | Evitar que código ruim avance |
| Agente | Após criar ou modificar testes | Validar que o trabalho do Agente está correto |
Na prática:
CI usa apidog run para proteger o pipeline.
Agente usa apidog run para fechar o loop de implementação.
Arquitetura: recursos de Agente sobre base CI/CD
Tudo o que vimos nesta série — cli-schema, agentHints, SKILL — depende de uma base CLI confiável:
┌────────────────────────────────────────────┐
│ Recursos do Agente │
│ cli-schema, agentHints, SKILL │
├────────────────────────────────────────────┤
│ Base CI/CD │
│ apidog run, códigos de saída, relatórios │
├────────────────────────────────────────────┤
│ CLI essencial │
│ comandos, parâmetros, execução │
└────────────────────────────────────────────┘
Os recursos para Agentes não substituem os recursos de CI. Eles os estendem.
Checklist de implementação
Ao avaliar ou criar uma CLI para testes de API com suporte a Agentes, verifique:
- [ ] O comando pode rodar sem interação humana?
- [ ] O exit code representa corretamente sucesso ou falha?
- [ ] Os relatórios podem ser salvos em um diretório configurável?
- [ ] Existe formato compatível com CI, como JUnit?
- [ ] A saída estruturada pode ser consumida por um Agente?
- [ ] Erros incluem detalhes suficientes para depuração?
- [ ] Há orientação clara para próximos passos?
- [ ] O mesmo comando funciona localmente, em CI e em automação?
Se a resposta for “sim”, a CLI está pronta para servir tanto pipelines quanto Agentes.
O que vem a seguir
Até aqui, cobrimos o fluxo completo: da descoberta do problema aos workflows práticos e aos princípios de design.
A próxima peça crítica é segurança.
Quando Agentes modificam recursos do projeto, como evitar que eles afetem diretamente o branch principal?
Na Parte 9, AI Branch: Mudanças de Projeto Mais Seguras com Agentes de IA, veremos como o AI Branch fornece um ambiente de edição isolado. As mudanças permanecem em um branch separado até revisão humana, adicionando uma camada de segurança para modificações orientadas por Agentes.
Principais conclusões
- Compatibilidade CI/CD é a base, não um extra.
- A amigabilidade com Agentes deve ser construída sobre contratos estáveis de CLI.
-
apidog runpode atender CI, Agentes, humanos e scripts. - CI precisa de exit codes, relatórios e parâmetros previsíveis.
- Agentes precisam de saída estruturada, detalhes de falha e próximos passos.
- O mesmo comando pode funcionar como porta de qualidade no CI e como verificação no loop do Agente.
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 Agentes de IA.
Top comments (0)