Tutorial DeepSeek Harness: primeiros passos com o agente de IA open source mais popular

Por que o DeepSeek Harness é popular?

O DeepSeek Harness ganhou tração muito rápido, alcançando mais de 160.000 estrelas no GitHub e 18.000 forks na data de publicação deste artigo. 

Um dos motivos é que os desenvolvedores estão conseguindo ótimos resultados com modelos variados, não só com o DeepSeek. Usuários no Reddit relatam sucesso com modelos como o Qwen3.8-27b, especialmente para programação e tarefas agentic mais longas.

Outro motivo é sua autonomia e flexibilidade. Usuários contam que o Harness consegue avançar em tarefas de múltiplas etapas, se recuperar de erros, gerenciar contextos longos e continuar sem precisar de intervenção constante. O design baseado em plugins também facilita trocar modelos, adicionar ferramentas e personalizar o fluxo do agente, em vez de ficar preso a uma configuração fixa.

Se você está comparando o Harness com as ferramentas que ele pretende rivalizar, nosso guia de alternativas ao Claude Code compara lado a lado sete das principais opções.

Principais recursos do DeepSeek Harness

Aqui estão alguns dos destaques:

• Arquitetura baseada em plugins: a maior parte do agente pode ser estendida ou substituída por plugins, o que facilita personalizar a sua configuração.

• Web UI local: executar dsh web oferece uma interface no navegador para gerenciar modelos, sessões, workspaces, configurações e agentes.

• SDK em Python: o deepseek-harness-sdk permite rodar agentes do Harness direto de aplicações Python, scripts, testes e automações.

• Vários provedores de modelos: você não fica limitado aos modelos DeepSeek. É possível usar provedores como OpenAI e Anthropic, ou conectar seu próprio endpoint compatível.

• Chamadas de ferramentas: agentes podem chamar ferramentas para executar ações, e não apenas gerar texto.

• Ferramentas de arquivos e terminal: o Harness inclui ferramentas para ler, buscar e editar arquivos, além de Bash no Linux e macOS e PowerShell no Windows.

• Pesquisa na web integrada: o provedor de busca do DeepSeek já vem na configuração padrão e usa a mesma chave da API do DeepSeek que o modelo.

• Code Mode: o Harness pode expor ferramentas via um modo de execução baseado em código, dando ao agente mais controle sobre como combinar e executar chamadas de ferramentas.

• Trajectory: a visualização Trajectory permite inspecionar o que o agente está fazendo passo a passo, incluindo respostas do modelo, chamadas de ferramentas, atividade aninhada, tempos e uso de tokens.

• Presets de agente: você pode criar configurações de agente com suas próprias ferramentas e prompts e reutilizá-las em diferentes sessões.

• Estatísticas da sessão: o Harness acompanha dados úteis como turns, steps, tempo de modelo, tempo de ferramenta, time to first token e tempo de decodificação.

• Subagentes: um agente principal pode delegar partes de uma tarefa a agentes filhos, útil para fluxos mais complexos.

• Plugins da comunidade: plugins de terceiros adicionam capacidades extras que não existem no modelo base. Neste guia, usamos o ModLens para adicionar suporte a visão.

• Licença MIT: o DeepSeek Harness é open source e distribuído sob a permissiva licença MIT.

A grande vantagem é não ficar preso a um único modelo, conjunto de ferramentas ou tipo de agente. Você pode começar com a configuração padrão e ir adicionando ou trocando componentes conforme experimenta fluxos diferentes.

Como configurar o DeepSeek Harness?

Vamos começar instalando o DeepSeek Harness e preparando tudo que vamos precisar para o restante do guia. Vamos instalar o Node.js, o DeepSeek Harness e o pnpm e depois adicionar nossas chaves de API.

Instale o Node.js

O DeepSeek Harness roda em Node.js. Como também vamos usar o ModLens depois para visão, recomendo Node.js 22.19 ou mais recente.

Se você usa Ubuntu ou Debian, pode instalar o Node.js com:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

Depois de instalar, verifique se o Node.js e o npm estão funcionando:

node --version
npm --version

No meu ambiente, obtive:

v24.19.0
11.17.0

Você não precisa ter exatamente as mesmas versões. Estando em uma versão recente do Node.js, já é o suficiente.

Instale o DeepSeek Harness

Agora, vamos instalar o próprio DeepSeek Harness.

O guia oficial de início rápido usa npx, mas prefiro instalar globalmente para podermos usar o comando dsh ao longo de todo o guia.

Execute:

npm install -g @deepseek-ai/dsh

Depois, confira se instalou corretamente:

dsh --version

Na época em que testei este guia, eu estava usando:

0.1.0-rc.7

Instale o pnpm

Também vamos precisar do pnpm. O DeepSeek Harness o utiliza ao adicionar ou remover plugins. Instale globalmente:

npm install -g pnpm

Configure as chaves de API

Para este tutorial, precisamos de apenas duas chaves de API:

• Chave da API do DeepSeek: usada pelo modelo DeepSeek e pela pesquisa na web integrada.
• Chave da API do Gemini: usada pelo ModLens para entendimento de imagens.

Vamos configurar a chave do DeepSeek agora, já que é o necessário para programar e pesquisar na web, e adicionar a chave do Gemini depois, quando incluirmos visão com o ModLens.

Para o DeepSeek, você precisa criar uma conta, gerar uma chave de API e adicionar crédito. Para este guia, recomendo colocar pelo menos US$ 2 de crédito, o que deve ser mais do que suficiente para testar os exemplos sem um valor alto de início.

Quando tiver a chave de API, adicione-a ao seu ambiente.

No Linux ou macOS:

export DEEPSEEK_API_KEY="your_deepseek_api_key"

No Windows PowerShell:

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

Um ponto positivo dessa configuração é que não precisamos de uma API separada para pesquisa na web. O DeepSeek Harness já inclui o provedor de busca do DeepSeek e usa a mesma DEEPSEEK_API_KEY.

Você também pode adicionar sua chave do DeepSeek depois em Settings → Models dentro da Web UI.

Como iniciar o DeepSeek Harness?

Com tudo configurado, podemos iniciar o DeepSeek Harness e abrir a Web UI. Basta executar dsh web, que inicia a interface do navegador na porta 3080 por padrão.

Você verá a interface ao abrir http://127.0.0.1:3080 no navegador.

A partir daí, crie um novo workspace ou selecione um existente, inicie uma nova sessão e escolha o modelo DeepSeek que deseja usar. 

Com a sessão pronta, podemos começar a testar código, pesquisa na web, visão e suporte a modelos de terceiros. 

Como usar o DeepSeek Harness para programar

Com o DeepSeek Harness rodando, podemos testar as principais capacidades da nossa configuração. Vamos começar com uma tarefa simples de código: 

Create a simple Python calculator with a command-line interface.

O DeepSeek Harness consegue trabalhar diretamente com arquivos e terminal, então ele pode criar o arquivo Python, editar o código e executar comandos dentro do workspace.

Quando a tarefa terminar, você verá o arquivo gerado e as instruções para executá-lo.

Para extrair ainda mais dos modelos DeepSeek que impulsionam o Harness, nosso tutorial da API DeepSeek V4 explica os modos de raciocínio da V4 e parâmetros da API em Python.

Como usar o DeepSeek Harness para pesquisa na web

Agora vamos testar a pesquisa na web. Não é necessário nenhum passo extra, porque o DeepSeek Harness já inclui o provedor de busca do DeepSeek.

Experimente um prompt como:

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

O agente deve pesquisar na web e retornar um resumo com as fontes. 

Enquanto ele trabalha, abra a aba Trajectory. Você deverá ver chamadas de ferramentas como SUBTOOL: web_search.

Isso mostra que o agente está de fato usando a ferramenta de busca na web, e não apenas o conhecimento prévio do modelo. Por padrão, essa busca é feita pelo provedor deepseek-official e usa a mesma DEEPSEEK_API_KEY que configuramos anteriormente. 

Como usar o DeepSeek para tarefas de visão

Os modelos de chat do DeepSeek no Harness são apenas de texto, então não entendem imagens enviadas por conta própria. Para adicionar visão, vamos usar o ModLens, que atua como uma ponte entre o DeepSeek e um modelo com capacidade de visão.

Instale o plugin ModLens

Quando você envia uma imagem, o ModLens a processa com um modelo de visão, extrai as informações visuais úteis e repassa isso ao DeepSeek para que ele raciocine sobre a imagem.

Comece instalando o plugin ModLens no perfil web:

dsh plugin --profile web add @liustack/modlens@3.20.0

Depois de instalado, o ModLens adiciona a ferramenta modlens_read_image e cria opções de modelo como ``DeepSeek-V4-Flash (modlens vision)`.

Essas variantes permitem enviar imagens usando o DeepSeek como modelo principal de raciocínio.

Registre seu backend de visão

Neste guia, vamos usar a API do Gemini como backend de visão, então precisamos de uma chave da API do Gemini. Você pode começar pelo Free Tier da API Gemini. O Google oferece acesso gratuito aos modelos compatíveis dentro dos limites do Free Tier, então não é preciso adicionar pagamento só para testar a configuração de visão deste guia.

Quando tiver a chave, adicione-a ao ambiente.

No Linux ou macOS:

export GEMINI_API_KEY="your_gemini_api_key"

No Windows PowerShell:

$env:GEMINI_API_KEY="your_gemini_api_key"

Instale e configure o ModLens CLI

Em seguida, instale o ModLens CLI:

npm install -g @liustack/modlens

Depois, configure usando a chave da API do Gemini.

No Linux ou macOS:

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

No Windows PowerShell:

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

Por fim, verifique se está tudo ok:

modlens doctor

Você deverá ver gemini-api selecionado como provedor e pronto para uso.

Testando o DeepSeek Harness com ModLens

Agora vamos testar o entendimento de imagens.

No seletor de modelos, escolha uma das opções com (modlens vision) no nome, por exemplo, DeepSeek-V4-Flash (modlens vision).

Cole ou envie uma imagem e então peça: Explain what is shown in this image.

Como no exemplo acima, o DeepSeek agora consegue descrever e raciocinar sobre a imagem enviada.

Nos bastidores, o ModLens envia a imagem ao Gemini para entendimento visual e repassa as informações extraídas ao DeepSeek. Assim, mantemos o DeepSeek como modelo principal de raciocínio e usamos o Gemini apenas para a parte de visão.

Como usar o DeepSeek Harness com um modelo de terceiros

Por fim, vamos testar um modelo de outro provedor. Abra Settings → Models.

Aqui você pode adicionar provedores como OpenAI e Anthropic, ou configurar outro provedor compatível usando suas próprias credenciais de API. 

Você também pode adicionar um provedor customizado para conectar um modelo self-hosted ou outro endpoint compatível. Dá para configurar detalhes como ID do provedor, URL base, tipo de API, credenciais e nome do modelo. 

Depois de adicionar o provedor, volte para a sessão e selecione o novo modelo no seletor.

Por exemplo, experimente o seguinte prompt:

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

No exemplo acima, um modelo Kimi-K3 de terceiros executa a tarefa de programação, mostrando que o DeepSeek Harness não fica restrito aos modelos da DeepSeek.

Você pode alternar entre modelos configurados direto no seletor, e as mudanças valem para sua próxima solicitação sem reiniciar o servidor do Harness.

Considerações finais

Depois de testar o DeepSeek Harness, ainda prefiro o Pi Coding Agent e o OpenCode para meus próprios fluxos.

O DeepSeek Harness me lembra muito o Pi Coding Agent, porque ambos são construídos ao redor de um ecossistema de plugins. Você instala extensões diferentes e dá capacidades extras ao seu agente de código conforme a necessidade. Essa flexibilidade é útil, mas, nos meus testes, eu ainda não entendi totalmente o hype em torno do DeepSeek Harness. A experiência geral pareceu bem normal comparada a outros agentes de código que já usei.

Também encontrei alguns pontos frustrantes. Às vezes o agente parava no meio da tarefa sem explicar o motivo, e eu tinha que digitar continue para ele retomar. Instalar e configurar plugins foi outro gargalo. Pode ser bem difícil se você não souber exatamente o que está fazendo, e a documentação ainda não ajuda muito.

Dito isso, o DeepSeek Harness ainda é um produto muito novo, então dá para entender esses problemas. Espero que a experiência, a documentação e o ecossistema de plugins evoluam bastante com o tempo. Também é possível que a DeepSeek esteja criando um harness que funcione especialmente bem com seus próprios modelos, o que pode explicar parte da empolgação.