DEV Community

Cover image for Como Usar a CLI do Apidog no DeepSeek Harness
Lucas
Lucas

Posted on Originally published at apidog.com

Como Usar a CLI do Apidog no DeepSeek Harness

DeepSeek Harness é um loop: o agente lê o espaço de trabalho, edita arquivos, executa comandos com a ferramenta bash e decide o próximo passo com base na saída. Seus testes de API também devem fazer parte desse loop, em vez de ficarem apenas na GUI do Apidog aguardando alguém clicar em Executar.

Experimente o Apidog hoje

A integração depende de um único bloco de configuração. O CLI do Apidog, o pacote npm apidog-cli, executa cenários de teste criados no Apidog diretamente no terminal. Depois de instalar o CLI e informar sua existência ao DeepSeek Harness, o agente pode executar um cenário do Apidog como executa testes de unidade: roda o comando, verifica o código de saída e corrige o código quando houver falhas.

Isso também economiza contexto. Em vez de reler handlers e inferir se os formatos de resposta ainda estão corretos, o agente executa um comando e recebe uma resposta objetiva. O CLI transforma a pergunta “a API está correta?” em um código de saída e em um relatório de asserções. Assim, o agente usa o contexto para corrigir o problema, não para especular sobre ele.

Este guia cobre a configuração específica do harness: qual arquivo de instruções o DeepSeek Harness lê, como a ferramenta bash executa apidog run e como validar que o agente realmente testou a API. Antes de continuar, instale e autentique o CLI. Veja como instalar o Apidog CLI com um agente de codificação de IA. Este artigo pressupõe que apidog --version retorna uma versão e que a máquina já está autenticada.

Sobre qual DeepSeek Harness este artigo trata

DeepSeek Harness, disponível como dsh na linha de comando, é o harness de agente de código aberto lançado pela DeepSeek em 13 de agosto de 2026, junto com o V4-Pro na API. Ele é licenciado sob MIT, está em github.com/deepseek-ai/deepseek-harness e já havia ultrapassado 169 mil estrelas em 20 de agosto.

Inicie a interface web local com:

npx @deepseek-ai/dsh web
Enter fullscreen mode Exit fullscreen mode

A interface fica disponível em:

http://127.0.0.1:3080
Enter fullscreen mode Exit fullscreen mode

Nela, selecione o espaço de trabalho — normalmente o diretório do projeto — e deixe o agente trabalhar dentro dele. O agente pode ler e editar arquivos, executar comandos e solicitar aprovação para operações cobertas pela política de permissões ativa.

Dois pontos são importantes:

  1. O harness é uma prévia para desenvolvedores. O README avisa que mudanças incompatíveis podem ocorrer. Os nomes de arquivos e chaves de configuração deste artigo refletem o final de agosto de 2026. Se algo não funcionar, consulte a documentação do repositório.
  2. Tudo no dsh é um plugin, baseado na arquitetura Cordis. Isso permite identificar exatamente qual plugin carrega regras de projeto e quais arquivos ele procura.

Para uma visão geral, veja o que é DeepSeek Harness. Para uma comparação com outro harness, veja DeepSeek Harness vs Claude Code.

Passo 1: adicione o Apidog CLI ao AGENTS.md

O DeepSeek Harness carrega instruções do workspace por meio do plugin @deepseek-ai/dsh-agent-instructions.

Segundo o código do plugin e o catálogo de configuração, o carregador percorre o caminho entre o diretório de trabalho da sessão e a raiz do projeto, identificada por .git. Em cada diretório, ele procura:

  • AGENTS.md
  • CLAUDE.md como fallback
  • AGENTS.local.md como overlay local
  • CLAUDE.local.md como overlay local

Também é possível manter um arquivo global em:

$DSH_HOME/AGENTS.md
Enter fullscreen mode Exit fullscreen mode

Por padrão, DSH_HOME é:

~/.dsh
Enter fullscreen mode Exit fullscreen mode

Arquivos com mais de 1 MiB são ignorados.

Na prática, se o repositório já possui um AGENTS.md usado por Codex ou um CLAUDE.md usado por Claude Code, o DeepSeek Harness pode reutilizá-lo sem configuração adicional.

Adicione um bloco explícito para os testes da API:

## Testes de API com o Apidog CLI

- Para testar a API, execute o cenário do Apidog. Não use a GUI.
- Comando: apidog run -t <scenario_id> -e <env_id> -r cli
- Código de saída 0 significa que todas as asserções passaram.
- Um código diferente de zero indica falha: leia o relatório e corrija o código.
- A máquina já está autenticada. Nunca adicione --access-token e nunca armazene tokens neste arquivo.
Enter fullscreen mode Exit fullscreen mode

Substitua <scenario_id> e <env_id> pelos IDs reais do seu projeto.

Esse arquivo é mais confiável do que instruções enviadas no chat. Uma mensagem da sessão desaparece ao final da conversa. Um comando documentado em AGENTS.md é carregado em novas sessões, por colegas de equipe e em máquinas que clonam o repositório.

Se você trabalha em muitos projetos, use o arquivo global ~/.dsh/AGENTS.md para a regra geral:

Sempre valide mudanças de API com o comando apidog run definido no projeto.
Enter fullscreen mode Exit fullscreen mode

Depois, mantenha os IDs específicos de cenário e ambiente no AGENTS.md de cada repositório.

Passo 2: copie o comando gerado pelo Apidog

Não adivinhe os IDs do cenário e do ambiente.

  1. Abra o cenário de teste no Apidog.
  2. Acesse a aba CI/CD.
  3. Copie o comando gerado.

O comando terá este formato:

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

Onde:

  • -t é o ID do cenário de teste.
  • -e é o ID do ambiente.
  • -r cli seleciona o reporter de terminal.

O reporter cli é importante porque imprime requisições, asserções e erros diretamente na saída que o agente consegue ler.

Cole o comando real no AGENTS.md. Dessa forma, o agente executa o comando gerado pelo Apidog, e não uma combinação de IDs inventada ou inferida.

Passo 3: faça o agente executar o teste

Inicie uma sessão na interface web do dsh com o workspace correto selecionado. Como o AGENTS.md já foi carregado, o agente saberá que o Apidog CLI está disponível.

Depois de alterar um endpoint, handler ou contrato de API, envie uma solicitação direta:

Execute o cenário de teste do Apidog e informe o código de saída.
Enter fullscreen mode Exit fullscreen mode

O agente executará o comando pela ferramenta bash.

Segundo o catálogo de ferramentas, a ferramenta bash padrão executa cada chamada em um shell limpo. Isso significa que diretório atual, variáveis e funções não persistem entre chamadas.

Por exemplo, isto não é confiável como duas chamadas separadas:

cd services/api
Enter fullscreen mode Exit fullscreen mode 
apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

A segunda chamada não herdará o cd.

Se o cenário precisar ser executado em um subdiretório, informe o caminho completo em uma única instrução no arquivo de regras:

- Execute o teste a partir de services/api:
  cd services/api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

Ou use o parâmetro workdir da ferramenta quando ele estiver disponível.

Também observe estes comportamentos:

  • Falhas retornam um marcador explícito como [exit code: 1].
  • O código de saída continua visível mesmo se uma saída longa for truncada.
  • Operações bloqueadas por sandbox são reportadas como negação de política, não como falha do comando.
  • Um teste somente leitura geralmente não deve ser bloqueado, mas um reporter que grava arquivos pode depender da política de permissões ativa.

A interface web pode solicitar aprovação antes de executar apidog run. Conforme o guia do usuário, isso depende da política configurada. Aprovar a execução de um cenário contra staging é um caso esperado para esse fluxo.

Passo 4: leia o relatório e corrija a falha

Quando o comando falhar, use o reporter inline para localizar a causa.

Com -r cli, o agente recebe informações como:

  • requisição executada;
  • status retornado;
  • asserção que falhou;
  • valor esperado;
  • valor real.

Isso normalmente é suficiente para encontrar a correção no handler, no schema ou na lógica de negócio.

Para também gerar um relatório navegável, inclua o reporter HTML:

apidog run -t 123456 -e 789012 -r cli,html
Enter fullscreen mode Exit fullscreen mode

O reporter html grava um relatório autocontido em:

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Mantenha cli na lista. O HTML é útil para revisão humana, mas o agente precisa da saída inline para decidir o próximo passo.

O loop completo: editar, testar, corrigir

Com a configuração pronta, o fluxo fica assim:

  1. O agente edita um handler, por exemplo, de checkout.
  2. Ele executa o cenário: 
   apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode
  1. Ele lê o resultado.
  2. Se o comando retornar 0, ele segue para a próxima tarefa.
  3. Se retornar algo como [exit code: 1], ele identifica a asserção quebrada.
  4. Ele corrige o código.
  5. Ele executa o cenário novamente.

Uma falha pode indicar, por exemplo:

  • retorno 500 onde era esperado 200;
  • campo total ausente;
  • código de moeda incorreto;
  • schema de resposta incompatível.

O cenário de teste já codifica o contrato esperado. Em vez de o agente reler todas as rotas para tentar provar que a API funciona, ele delega a validação a uma ferramenta determinística.

A divisão de responsabilidades fica clara:

  • o dsh escreve e altera código;
  • o Apidog CLI verifica o comportamento da API;
  • sua equipe cria e mantém cenários visualmente no Apidog, sem escrever código de teste.

Verifique se o dsh realmente executou o cenário

Não aceite apenas um resumo como “os testes passaram”. Valide a execução em três etapas.

1. Confirme a chamada do comando

A interface do dsh mostra chamadas de ferramentas e suas saídas. Procure pelo comando bash literal:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

Se o agente afirma que executou os testes, mas não existe uma chamada correspondente, ele não executou o cenário. Peça para rodar novamente e mostrar a saída bruta.

2. Confirme o código de saída

Pergunte diretamente:

Qual foi o código de saída do comando apidog run?
Enter fullscreen mode Exit fullscreen mode

Em falhas, o harness retorna um marcador como:

[exit code: 1]
Enter fullscreen mode Exit fullscreen mode

Se o resumo disser que os testes passaram, mas o marcador indicar valor diferente de zero, confie no código de saída.

3. Confirme os IDs do cenário e do ambiente

Um erro como “cenário não encontrado” normalmente significa que o agente usou IDs errados.

Compare os valores de:

-t <scenario_id> -e <env_id>
Enter fullscreen mode Exit fullscreen mode

com:

  • o bloco em AGENTS.md;
  • o comando exibido na aba CI/CD do Apidog.

Os IDs documentados no arquivo de regras são a fonte de verdade. Qualquer outro valor digitado pelo agente é uma suposição.

Opcional: adicione o servidor Apidog MCP para acessar a especificação

O CLI resolve a parte de verificação. Se você também quer que o agente consulte a especificação da API enquanto implementa endpoints, use MCP.

A partir do final de agosto de 2026, o suporte a MCP não está documentado no README principal nem no guia do usuário do DeepSeek Harness. Existe, porém, um plugin da comunidade: hyqhyq3/dsh-mcp-manager.

Esse plugin, descoberto pelo tópico dsh-plugin no GitHub, adiciona uma página MCP em Configurações e oferece suporte a:

  • servidores HTTP remotos;
  • servidores stdio locais;
  • ferramentas registradas como mcp__<name>__*;
  • definições por projeto em: 
  <workspace>/.dsh/dshmm/mcp.json
Enter fullscreen mode Exit fullscreen mode

Com ele, você pode conectar o servidor Apidog MCP. Isso permite que o agente consulte especificações de API por MCP antes de escrever um handler.

Trate essa integração como complementar. Um plugin comunitário em um harness de prévia pode sofrer incompatibilidades em atualizações. O caminho essencial continua sendo o CLI: ele depende apenas de um shell e de um comando apidog run.

Ressalvas da prévia e próximos passos

O DeepSeek Harness evolui rapidamente e declara que pode introduzir mudanças incompatíveis. As partes mais propensas a mudar são:

  • arquivos carregados pelo plugin de instruções;
  • comportamento do sandbox da ferramenta bash;
  • detalhes do plugin MCP da comunidade.

O padrão principal, porém, é portátil:

  1. Documente no arquivo de regras como validar a API.
  2. Execute um único comando determinístico.
  3. Use o código de saída como sinal objetivo de sucesso ou falha.

Isso funciona no dsh pela mesma razão que funciona no Claude Code e em outros harnesses: agentes leem bem a saída de comandos, mas não devem validar a própria implementação apenas por raciocínio.

Para implementar:

  1. Baixe o Apidog.
  2. Crie um cenário de teste visualmente.
  3. Copie o comando apidog run da aba CI/CD.
  4. Adicione esse comando ao AGENTS.md.
  5. Peça ao DeepSeek Harness para executar o cenário após cada alteração relevante na API.

Na próxima vez que o agente modificar código de API, ele poderá verificar o próprio trabalho antes de informar que concluiu a tarefa.

FAQ

O DeepSeek Harness lê AGENTS.md nativamente?

Sim. O plugin @deepseek-ai/dsh-agent-instructions carrega AGENTS.md ou usa CLAUDE.md como fallback. Ele procura arquivos desde a raiz do projeto até os diretórios acima do diretório de trabalho da sessão.

Também reconhece os overlays:

AGENTS.local.md
CLAUDE.local.md
Enter fullscreen mode Exit fullscreen mode

Além disso, carrega um AGENTS.md global em:

~/.dsh
Enter fullscreen mode Exit fullscreen mode

Se você já mantém um AGENTS.md para outros agentes, o dsh pode reutilizá-lo sem alterações.

Preciso de um plano pago do DeepSeek para usar o Apidog CLI no dsh?

Não. O harness é de código aberto e licenciado sob MIT. Você fornece o modelo que deseja usar: provedores de catálogo incluem Anthropic, OpenAI, Bedrock, Vertex e Azure, enquanto gateways personalizados funcionam por meio de settings.yaml.

Veja como executar qualquer modelo no DeepSeek Harness.

O Apidog CLI é um pacote npm gratuito. Ele exige um cenário de teste do Apidog e autenticação, não um modelo específico.

Por que o segundo comando esquece o diretório alterado pelo primeiro?

Isso acontece por design. A ferramenta bash padrão do dsh executa cada chamada em um shell limpo, então um cd não persiste entre comandos.

Use uma das opções:

cd services/api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

Ou passe o workdir para a ferramenta bash, quando disponível.

A opção mais simples é manter toda a invocação em uma linha no arquivo de regras.

O dsh pode executar o cenário sem pedir aprovação toda vez?

Depende da política de permissão ativa. A interface web solicita aprovação para operações que exigem consentimento conforme a política configurada.

O guia do usuário não enumera todos os níveis dessa política. Verifique as Configurações da sua compilação para entender o que sua implantação permite.

Quando o dsh solicitar aprovação, executar apidog run contra um ambiente de staging é um caso adequado para permitir.

Top comments (0)