DEV Community

Cover image for Integrando CLIs com Agentes de IA
Lucas
Lucas

Posted on • Originally published at apidog.com

Integrando CLIs com Agentes de IA

Esta série em 10 partes mostra como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes de API e gerenciamento do ciclo de vida da API. Leia em ordem ou pule para o tema que mais interessa:

Experimente o Apidog hoje

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 um Novo Apidog CLI Desenvolvimento da arquitetura
3 A Regra de Ouro: CLI Produz Fatos, Modelo Atua Com Base nos Fatos Filosofia central
4 agentHints: Ensinando CLIs a Conversar 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 Testes: Um Fluxo de Trabalho de Agente Completo 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 & futuro

A saída tradicional da CLI é feita para humanos. Agentes precisam de resultados estruturados, razões de falha e próximos passos executáveis. O agentHints transforma experiência de produto em orientação legível por máquina.

O problema: saída de CLI não orienta agentes

A maioria das CLIs imprime mensagens como:

Sucesso Falha
"Sucesso" ou "Concluído" Mensagem de erro
Talvez o recurso criado Talvez um stack trace
O humano decide o próximo passo O humano depura

Isso funciona para pessoas porque elas conseguem:

  • Interpretar mensagens incompletas
  • Lembrar comandos anteriores
  • Aplicar contexto de domínio
  • Decidir manualmente o que fazer em seguida

Para agentes, isso não basta. Um agente precisa transformar a saída de um comando na próxima ação confiável.

O que um agente precisa receber da CLI

Uma CLI amigável para agentes deve retornar, no mínimo:

Necessidade Por quê
Resultado estruturado Para parsing programático
Razão de falha Para corrigir o erro certo
Sugestão de próximo passo Para continuar o fluxo sem adivinhar

Exemplo: um humano lê “Recurso criado com sucesso” e entende que talvez deva verificar o recurso ou executar testes.

Um agente lê a mesma frase e não sabe se deve:

  • Ler o recurso criado
  • Criar outro recurso
  • Validar schema
  • Executar testes
  • Encerrar o fluxo

É aqui que entra o agentHints.

agentHints: saída JSON com orientação operacional

O Apidog CLI adiciona agentHints à saída para indicar o que aconteceu e o que fazer depois.

Exemplo de resposta:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Caso de teste criado com sucesso.",
    "nextSteps": [
      "Leia o caso de teste criado para confirmar a estrutura.",
      "Adicione asserções se o caso de teste precisar de validação de resposta.",
      "Adicione o caso de teste a um cenário de teste para testes de integração.",
      "Execute testes relacionados após adicionar ao cenário."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

A estrutura separa três responsabilidades:

Campo Função
success + data Resultado real da operação
agentHints.summary Resumo legível por humanos e agentes
agentHints.nextSteps Próximas ações recomendadas

Na prática, o agente não precisa inferir o fluxo. Ele pode ler nextSteps[0] e executar a próxima operação segura.

Padrão de implementação: sempre retornar fato + orientação

Um bom contrato de CLI para agentes pode seguir este formato:

{
  "success": true,
  "data": {},
  "agentHints": {
    "summary": "Resumo curto do resultado.",
    "nextSteps": [
      "Primeira ação recomendada.",
      "Segunda ação recomendada."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Para falhas:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Mensagem específica do erro",
    "details": []
  },
  "agentHints": {
    "summary": "Explique o que falhou.",
    "nextSteps": [
      "Revise os detalhes do erro.",
      "Corrija o arquivo de entrada.",
      "Execute a validação novamente antes de escrever."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

A regra prática é simples:

A CLI deve produzir fatos. O agentHints deve orientar o próximo passo com base nesses fatos.

O problema da inércia de execução

Um comportamento comum em agentes é continuar executando escritas sem verificar o estado real.

Fluxo problemático:

Agente: cria caso de teste
CLI: retorna sucesso
Agente: cria cenário de teste imediatamente
Agente: executa testes imediatamente
Resultado: cenário com estrutura errada, testes falham
Enter fullscreen mode Exit fullscreen mode

Em fluxos de negócio complexos, continuar mecanicamente após um success: true é arriscado.

O fluxo mais seguro é:

  1. Criar o recurso
  2. Ler o recurso de volta
  3. Confirmar a estrutura real
  4. Prosseguir com base em dados reais

Por que “ler de volta” importa

Ignorar a leitura de volta cria bugs difíceis de diagnosticar:

Problema Causa provável
Valores padrão inesperados O servidor preencheu campos não enviados
IDs associados ausentes A importação gerou novos IDs internos
Diferenças estruturais A estrutura retornada não é igual à estrutura enviada
Suposições incorretas O agente continuou com base no que imaginava

Se o agente não lê a estrutura real, ele pode escrever os próximos objetos usando dados incompletos ou incorretos.

Como o agentHints evita saltos cegos

Após criar um caso de teste, a CLI pode retornar:

{
  "agentHints": {
    "nextSteps": [
      "Leia o caso de teste criado com a flag --with-case-detail.",
      "Valide quaisquer atualizações com cli-schema antes de escrever.",
      "Execute testes após completar o cenário de teste."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Um agente pode operar assim:

  1. Executa o comando de criação
  2. Faz parse do JSON
  3. Lê agentHints.nextSteps
  4. Executa a primeira recomendação: ler o caso criado
  5. Usa a estrutura real para continuar

Isso transforma a CLI em parte ativa do fluxo de trabalho, não apenas em um executor de comandos.

Antes e depois: papel da CLI

Papel antigo Novo papel
Executor de comando Navegador de fluxo de trabalho
Imprime resultado Guia o próximo passo
Saída para humanos Estrutura legível por agentes
Resposta isolada Orientação contínua

Com agentHints, a CLI funciona como um navegador de estado leve: ela informa onde o agente está e qual é o próximo movimento seguro.

Árvores de fluxo de trabalho integradas

O Apidog CLI possui milhares de fluxos de trabalho em estrutura de árvore integrados.

Essas sugestões são:

Característica Descrição
Sensíveis ao contexto Variam conforme a operação executada
Específicas do recurso Diferem para endpoints, casos de teste e cenários
Sensíveis ao fluxo Refletem sequências típicas de uso
Informadas por erro Mudam entre sucesso e falha

Exemplo após atualizar um cenário de teste:

{
  "agentHints": {
    "summary": "Cenário de teste atualizado com sucesso.",
    "nextSteps": [
      "Execute o cenário de teste para verificar as mudanças.",
      "Verifique o relatório de teste em busca de falhas.",
      "Se ocorrerem falhas, leia os passos do cenário para depuração."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Exemplo após falha de validação:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'comparator' possui valor inválido",
    "details": []
  },
  "agentHints": {
    "summary": "Validação falhou. Corrija os erros e re-valide.",
    "nextSteps": [
      "Revise os detalhes do erro na saída.",
      "Ajuste o arquivo JSON com base nas sugestões de erro.",
      "Execute novamente a validação do cli-schema antes de escrever."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

O ponto importante: até falhas se tornam navegáveis.

Fluxo seguro com agentHints

Um fluxo completo fica assim:

Passo 1: Agente cria caso de teste
        ↓
CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Leia de volta o caso de teste criado"
        ↓
Passo 2: Agente lê de volta a estrutura real
        ↓
CLI: dados reais + agentHints
        ↓
agentHints.nextSteps[0]: "Adicione asserções se necessário"
        ↓
Passo 3: Agente adiciona asserções com base na estrutura real
        ↓
CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Execute os testes"
        ↓
Passo 4: Agente executa testes
        ↓
CLI: relatório de teste
Enter fullscreen mode Exit fullscreen mode

Cada etapa é guiada por dados reais. Sem suposições. Sem avanço cego.

Comparação: sem e com agentHints

Cenário Sem agentHints Com agentHints
Após criar Agente continua para a próxima escrita Agente lê de volta primeiro
Após atualizar Agente assume que está tudo certo Agente verifica a estrutura
Após validação aprovada Agente escreve imediatamente Agente escreve e depois confirma
Após validação falhar Agente pode não entender a correção Agente recebe próximos passos específicos
Após execução de teste Agente vê aprovado/reprovado Agente recebe orientação de depuração

Checklist para projetar saídas de CLI para agentes

Se você está construindo uma CLI que será usada por agentes, use este checklist:

  • Retorne JSON estruturado por padrão ou via flag
  • Separe data, error e agentHints
  • Inclua success: true/false
  • Use códigos de erro estáveis, como VALIDATION_ERROR
  • Inclua detalhes suficientes para correção automática
  • Sugira próximos passos específicos e ordenados
  • Recomende leitura de volta após escritas importantes
  • Evite mensagens genéricas como “erro desconhecido” sem contexto
  • Faça a saída ser útil tanto para humanos quanto para máquinas

Próximos passos

Agora que a CLI pode guiar agentes pelos próximos passos, a pergunta seguinte é:

Como os agentes sabem qual fluxo de trabalho seguir em primeiro lugar?

Na Parte 5, SKILL: Entregando Experiência Operacional como Código, exploraremos como o SKILL empacota conhecimento de fluxo de trabalho: quando usar comandos, qual sequência seguir e quais campos não devem ser adivinhados.

Principais pontos

  • Saída tradicional de CLI é orientada a humanos; agentes precisam de estrutura.
  • agentHints adiciona resumo e próximos passos à saída JSON.
  • A leitura de volta evita que agentes continuem com suposições.
  • A CLI deixa de ser apenas executora e passa a guiar o fluxo.
  • Árvores de fluxo de trabalho tornam cada etapa navegável.
  • Falhas também podem ser acionáveis quando incluem próximos passos claros.

Baixe o Apidog para projetar, simular, testar e documentar APIs em um único espaço de trabalho. 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.

Top comments (0)