Como Usar a CLI do Apidog no Hermes Agent

O Hermes Agent é executado a partir do seu terminal, lembra-se do que aprende entre sessões e utiliza comandos de shell reais para realizar tarefas. Essa última parte é a chave: se ele pode executar um comando, ele pode executar seus testes de API.

O executor que os conecta é a CLI do Apidog, um pacote npm chamado apidog-cli. Ele executa os cenários de teste que você construiu visualmente no Apidog diretamente de um terminal e sai com um código de status sobre o qual o Hermes pode agir. Este guia cobre a parte específica do Hermes: a ferramenta terminal que executa o comando, o arquivo de contexto que ensina ao Hermes seu fluxo de trabalho, como a execução se encaixa em seu loop e o servidor Apidog MCP opcional que entrega a especificação da sua API ao Hermes enquanto ele trabalha.

Se a CLI ainda não estiver instalada, comece com como instalar a CLI do Apidog com um agente de codificação de IA, que orienta um agente na instalação e autenticação. Volte assim que apidog --version imprimir um número. Você também precisa de uma conta Apidog com pelo menos um cenário de teste salvo; baixe o Apidog se não tiver um.

O que significa “usar a CLI no Hermes”

O Hermes Agent, construído pela Nous Research, é executado no seu terminal, conversa com seus modelos de IA e age através de ferramentas integradas. A que importa aqui é a ferramenta terminal: o Hermes executa comandos de shell chamando-a em seu diretório de trabalho, e então lê a saída de volta em seu raciocínio. Não há plugin Apidog para instalar, e você não precisa de um. Usar a CLI do Apidog no Hermes significa três coisas:

1. Ensine o fluxo de trabalho ao Hermes uma única vez escrevendo-o em um arquivo de contexto que o Hermes carrega na inicialização, para que ele conheça o comando, os flags e que o código de saída é a fonte da verdade.
2. Faça com que o Hermes execute apidog run através da ferramenta terminal, como qualquer outro comando.
3. Conecte opcionalmente o servidor Apidog MCP, para que o Hermes possa ler a especificação da sua API enquanto escreve o código que esses testes verificam.

O arquivo de contexto é o que torna isso algo adaptado ao Hermes, em vez de um guia genérico de "abrir um terminal e digitar", transformando um "executar meus testes" avulso em algo que ele busca por conta própria.

O mecanismo: um arquivo de contexto, não um lembrete de chat

O Hermes carrega o contexto do projeto no início de uma sessão. Seu motor de contexto verifica seu diretório de trabalho em busca de arquivos de instrução, incluindo CLAUDE.md e AGENTS.md, e os injeta no prompt do sistema. Essa é a mesma convenção que o Claude Code e o Codex usam, então se seu repositório já tiver um AGENTS.md, o Hermes também o lê.

É por isso que você escreve a CLI em um arquivo de contexto em vez de mencioná-la no chat. Um ID de cenário digitado em uma sessão se perde quando ela termina; um em AGENTS.md está lá para cada colega de equipe e para cada execução do Hermes a partir de agora. (O Hermes também lê um SOUL.md, mas isso é para a persona do agente, não para o seu projeto. Mantenha as instruções de teste em AGENTS.md.)

Passo 1: Adicionar um bloco Apidog ao seu arquivo de contexto

Abra AGENTS.md na raiz do seu repositório, ou crie-o, e adicione uma seção informando ao Hermes que a CLI existe, como executá-la e como ler o resultado. Forneça o comando e o ID reais, não uma descrição.

## API testing with the Apidog CLI

This repo uses the Apidog CLI (`apidog-cli`, the `apidog` command) to run API
test scenarios. The scenarios live in our Apidog project, not in this repo.

When you change an API handler, route, or response shape, run the relevant
Apidog scenario through the terminal tool before considering the change done:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` is the checkout-flow test scenario.
- `-e 1629989` is the staging environment.
- The machine is already authenticated via `apidog login`, so do NOT pass
  an access token and do NOT print one.

Treat the exit code as the source of truth: `0` means every assertion passed,
non-zero means a failure. If it exits non-zero, read the failing assertion in
the report and fix the code, then re-run. Do not report a pass on a non-zero
exit.

Substitua 605067 pelo ID real do seu cenário e 1629989 pelo ambiente que o Hermes deve atingir durante o trabalho normal, geralmente staging ou desenvolvimento local, nunca produção. Para obter os IDs corretos, copie o comando apidog run que o Apidog gera na aba CI/CD do cenário (abordado a seguir) e remova o token de acesso antes de colar, já que a máquina já está logada e um token não deve pertencer a um arquivo commitado.

Duas coisas fazem este bloco funcionar. Ele nomeia o comando exatamente, para que o Hermes não adivinhe os flags. E ele declara a regra de aprovação/reprovação em linguagem clara, para que o Hermes saiba que o código de saída supera seu próprio resumo, o que o salva da falha de agente mais comum: um confiante "testes passaram" em cima de uma execução vermelha.

Passo 2: Obter o comando do Apidog

Obtenha um comando comprovadamente bom antes de pedir ao Hermes para executar qualquer coisa. Abra seu cenário no Apidog, mude para a aba CI/CD e escolha a opção de linha de comando. O Apidog constrói o comando apidog run completo com os IDs e um token de acesso já preenchidos:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

605067 é o ID do cenário e 1629989 é o ID do ambiente; os seus serão diferentes. Como você autenticou a CLI durante a instalação, remova a parte --access-token e mantenha os IDs. Esse é o comando que seu arquivo de contexto instruiu o Hermes a usar.

Passo 3: Fazer o Hermes executar o teste

Inicie o Hermes em seu repositório e peça a ele para executar a verificação. Com o bloco no lugar, o prompt é curto:

Execute nosso cenário de teste de API do Apidog da maneira que AGENTS.md descreve. Já estou autenticado, então não passe um token de acesso. Use apidog run -t 605067 -e 1629989 -n 1 -r cli. Mostre-me a saída completa e diga-me o código de saída.

O Hermes chama sua ferramenta terminal para executar o comando em seu diretório de trabalho, e o reporter -r cli transmite um resultado passo a passo de volta ao seu contexto, onde você observa cada requisição e asserção. Como o Hermes roteia comandos através de uma camada de aprovação, você pode ver um prompt antes de ele executar, dependendo da sua configuração. Um cenário de teste somente leitura contra staging é exatamente o tipo de comando seguro e no espaço de trabalho que é aceitável permitir.

Sua verificação: olhe para o código de saída, não para o resumo. apidog run sai com 0 quando todas as asserções passam e diferente de zero quando uma falha. Esse comportamento é a razão pela qual isso funciona como um portão, tanto para CI quanto para Hermes. Se o Hermes disser "testes passaram", mas o código de saída não for zero, ele está errado; confie no código. Esta é a falha que o bloco do Passo 1 previne.

Para um formato de relatório diferente ou mais iterações, peça ao Hermes para executar apidog run --help para que ele leia a lista real de flags. O guia completo da CLI do Apidog documenta cada flag, incluindo os reporters html, json e junit.

Passo 4: Testando com Hermes dentro de seu próprio loop

O ponto é o que acontece quando você para de pedir e o Hermes executa o cenário por conta própria porque o AGENTS.md o instruiu. Imagine-o editando um handler que constrói uma resposta de checkout: ele edita o código, executa seu cenário Apidog contra o ambiente de staging através da ferramenta terminal, lê o código de saída e age sobre ele. Verde, ele segue em frente. Vermelho, ele abre o relatório, lê qual asserção falhou (o código de status, o campo ausente, o valor incorreto), tenta uma correção e executa novamente. O teste de API se torna parte do mesmo loop de edição-teste-correção que ele já executa com seus testes de unidade. Você escreveu uma instrução e ele incorporou o comando em como ele já funciona.

Este é o modelo de "delegar e verificar" que torna qualquer fluxo de trabalho de agente seguro. O Hermes executa o comando e lê o resultado; você continua criando cenários no Apidog e verifica se ele lê os códigos de saída honestamente. Para uma execução lenta, uma pasta grande ou uma alta contagem de iterações, a ferramenta terminal aceita um flag background=true, para que o Hermes possa iniciar a varredura, continuar trabalhando e sondar o código de saída em vez de bloquear. Para o padrão mais amplo, veja como usar agentes de IA para teste de API e o harness de teste de IA do Apidog.

Opcional: conectar o servidor Apidog MCP

A CLI permite ao Hermes executar seus testes; o servidor Apidog MCP permite que ele leia a especificação da sua API enquanto escreve código. Os dois se complementam: o MCP alimenta o Hermes com seu esquema para que ele gere código que corresponda ao contrato, e a CLI verifica esse código contra cenários reais.

O Hermes suporta o Protocolo de Contexto do Modelo (MCP) pronto para uso. Edite ~/.hermes/config.yaml e adicione uma entrada sob a seção mcp_servers. Para um servidor stdio local como o do Apidog, isso é um command, um array de args e quaisquer valores de env:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"

Após salvar, execute /reload-mcp dentro do Hermes, ou reinicie-o. O Hermes descobre os servidores MCP na inicialização e registra suas ferramentas em seu registro normal, com namespace como mcp_apidog_<tool>, para que o agente as utilize durante o raciocínio normal. Para a configuração completa, incluindo o ID do projeto e o token, consulte o guia do servidor Apidog MCP. Para uma versão empacotada deste loop, consulte o guia da CLI do Apidog com Habilidades Claude.

Do loop local para a CI

Depois que o Hermes executa o cenário localmente e age sobre o código de saída, você validou o comando exato que sua pipeline usará. O salto para a CI é pequeno: o mesmo apidog run, com o token passado como um segredo mascarado em vez de um login armazenado. Peça ao Hermes para escrever o passo, já que ele conhece o comando do seu arquivo de contexto:

Escreva um passo do GitHub Actions que instale o apidog-cli e execute apidog run -t 605067 -e 1629989 -r junit, lendo o token de acesso de um segredo do repositório chamado APIDOG_ACCESS_TOKEN.

Os mecanismos desse passo (segredos, reporters, gating por código de saída) estão em CLI do Apidog no GitHub Actions. O mesmo comando então é executado em três lugares: seu terminal, o loop do Hermes e a CI, todos com base em um único código de saída.

Armadilhas comuns

Hermes ignora o bloco de contexto. Se ele executar um comando genérico ou nenhum, confirme se o arquivo tem o nome exato AGENTS.md (ou CLAUDE.md) e está no diretório onde o Hermes foi iniciado. Reiniciar a sessão força uma nova leitura.

Ele apenas sugere o comando em vez de executá-lo. O Hermes executa comandos através da ferramenta terminal por trás de uma camada de aprovação. Aprovando uma execução pendente; se sua configuração nega comandos de terminal, relaxe a permissão para apidog run.

apidog whoami mostra que você não está autenticado. O login é armazenado na sua máquina, não no Hermes. Execute apidog login --with-token você mesmo com um token novo, então peça ao Hermes para confirmar com apidog whoami. Mantenha o token fora do chat.

Ele inventa um flag. Um erro de "opção desconhecida" significa que o Hermes adivinhou um flag que não existe em sua versão. Faça-o executar apidog run --help e copie o flag real.

Ele relata aprovação em uma execução falha. A mais custosa, e a razão pela qual a regra do código de saída está tanto no seu AGENTS.md quanto na sua verificação manual. Quando o resumo e o código de saída discordam, o código vence.

Conclusão

A configuração do Hermes consiste em um arquivo e um hábito: um bloco AGENTS.md que fixa o comando, a fonte de autenticação e a regra do código de saída, mais o hábito de deixar o Hermes executar apidog run através de sua ferramenta terminal e verificar o código de saída você mesmo. Adicione o servidor Apidog MCP via ~/.hermes/config.yaml e ele também poderá ler sua especificação enquanto codifica.

Você continua criando cenários visualmente no Apidog; o Hermes apenas os executa. A partir daqui, aponte o mesmo comando para sua pipeline com a CLI do Apidog no GitHub Actions, ou leia a referência completa dos flags no guia completo.

Perguntas frequentes

Preciso de um plugin Hermes para usar a CLI do Apidog?

Não. O Hermes executa comandos de shell através de sua ferramenta terminal, então ele chama apidog run diretamente. A única configuração específica do Hermes é o bloco AGENTS.md, mais o servidor MCP opcional.

Onde coloco as instruções que ensinam o fluxo de trabalho ao Hermes?

Em um arquivo de contexto que o Hermes carrega na inicialização. Seu motor de contexto verifica o diretório de trabalho em busca de arquivos como AGENTS.md e CLAUDE.md e os injeta no prompt do sistema. Coloque seu bloco Apidog em AGENTS.md na raiz do repositório e cada sessão nesse repositório o lerá.

Como garanto que o Hermes não simule um teste aprovado?

Faça-o reportar o código de saída, não apenas um resumo, e verifique esse código você mesmo. apidog run sai com 0 apenas quando todas as asserções passam. Quando a prosa e o código discordam, confie no código.

Como conecto o servidor Apidog MCP ao Hermes?

Adicione uma entrada mcp_servers em ~/.hermes/config.yaml com o comando apidog-mcp-server e o ID do seu projeto, então execute /reload-mcp ou reinicie o Hermes. Ele descobre o servidor na inicialização e registra suas ferramentas. O guia do servidor Apidog MCP cobre o ID do projeto e o token.

Isso funciona da mesma forma em outros agentes de codificação de IA?

A CLI é a mesma em todos os lugares; apenas a forma como você ensina o agente difere. O Hermes lê AGENTS.md e executa comandos através de sua ferramenta terminal; outros agentes usam seus próprios arquivos de instrução. A instalação e autenticação são idênticas, então o guia de instalação se aplica a qualquer agente.