O que é o DeepSeek Harness? O runtime de agente em que tudo é plugin

O que é o DeepSeek Harness?

O DeepSeek Harness, abreviado como dsh, é um runtime de agent harness open source da DeepSeek AI sob licença MIT. Ele fica entre um modelo de linguagem e o mundo externo, fornecendo ferramentas, sessões, sandbox e o loop que mantém a tarefa avançando.

A própria DeepSeek resume como "Agente = Modelo + Harness". O modelo cuida do raciocínio e da geração. O harness é tudo que permite que esse raciocínio atue em um sistema de arquivos real e continue sem você precisar reexplicar a tarefa a cada passo.

Ele roda sobre o Cordis, um framework de plugins que antecede o DeepSeek Harness. O Cordis permite substituir essas partes de forma independente nas configurações. Vou voltar ao custo dessa escolha mais adiante.

Com esse enquadramento, aqui vão duas confusões comuns.

DeepSeek Harness não é um modelo de IA

Como já mencionado, o modelo e o runtime são camadas separadas. Essa divisão permite trocar de provedor sem mudar as ferramentas ou a configuração de sessões. O mesmo runtime pode usar DeepSeek, Anthropic, OpenAI ou um endpoint compatível com OpenAI.

DeepSeek Harness é mais do que um assistente de código

O modo Standard passa a impressão de um assistente de código, mas é só uma configuração. Como vou mostrar adiante, os modos Minimal e Creator mudam o que o agente pode usar. Criar uma nova configuração ainda exige engenharia; os desenvolvedores têm acesso às partes.

Como o Cordis organiza os plugins do DeepSeek Harness

Como dito, o Cordis é o framework de plugins sob o DeepSeek Harness. Ele permite que cada parte solicite um serviço sem ficar presa ao código de um único provedor.

O Cordis veio do ecossistema do chatbot Koishi e foi construído por um desenvolvedor conhecido como Shigma; a DeepSeek o distribui e estende. Os autores descrevem o design no artigo A Programming Paradigm for Spatiotemporal Composability.

Esses fundamentos levam ao principal slogan do projeto e a dois termos do Cordis. Os nomes soam acadêmicos, mas o comportamento é simples.

"Tudo é plugin"

A documentação de arquitetura da DeepSeek diz que você estende o dsh montando um plugin ao lado dos outros. Adaptadores de modelo, ferramentas, sessões, sandboxes, storage, agendamento, o loop do agente e a interface são todos plugins.

Tomado ao pé da letra, o slogan exagera. O Cordis ainda fica por baixo dos plugins. Ele carrega e remove, verifica o que precisam e executa os eventos usados para se comunicarem. O Cordis é obrigatório, não só mais uma peça opcional.

Composabilidade espacial gerencia dependências de plugins

Um plugin declara os serviços de que precisa sem exigir uma sequência de boot escrita à mão. Ele ativa quando esses serviços existem e desativa se um serviço obrigatório some. Suas dependências definem quando pode rodar.

A DeepSeek chama isso de composabilidade espacial. As dependências dizem ao Cordis onde cada componente se encaixa, então os desenvolvedores não precisam ordenar a inicialização manualmente.

Composabilidade temporal desfaz efeitos de plugins

O Cordis também rastreia registros como listeners de eventos, seções de prompt e esquemas de ferramentas. Remover um plugin remove esses efeitos em vez de deixar listeners órfãos. Isso não desfaz uma ação externa como um comando no shell; a reversão vale só para efeitos rastreados pelo Cordis.

Arquitetura do DeepSeek Harness: como o runtime se encaixa

Uma instância em execução é uma árvore de plugins montada a partir de configurações carregadas em uma ordem definida. Essas configurações determinam quais partes ficam ativas.

O Cordis conecta todos os plugins substituíveis do runtime. Imagem do autor.

Serviços do Cordis permitem que plugins se encontrem

O Cordis fornece um diretório compartilhado de serviços. Plugins usam chaves estáveis como ctx.tools, ctx.llm e ctx.sessions em vez de importar o código de um provedor específico. Uma ferramenta que chama ctx.llm não precisa saber qual adaptador de modelo está por trás.

Presets de agente e perfis de runtime controlam camadas diferentes

Se tudo é substituível, alguém ainda precisa decidir o que será montado para cada execução, e o DeepSeek Harness responde isso em duas camadas fáceis de confundir.

Versão curta: um perfil controla como o programa inicia, enquanto um preset controla o que o agente pode fazer. Se você só usa o app web, pode pular as próximas duas subseções.

Perfis de runtime

Um perfil de runtime (web, headless, sdk, sdk-minimal e acp são fornecidos como templates) define como o aplicativo inicia e quais pacotes de plugins do Cordis são empilhados no boot. A maioria só vai tocar essa camada ao rodar dsh web ou um comando similar.

Presets de agente

Um preset de agente (Standard, PTC, Minimal ou Creator) decide o que uma sessão ativa pode usar. Um arquivo de patch pode mudar o preset sem alterar o código-fonte do Harness.

O loop do agente coordena turns, steps e chamadas de ferramentas

A DeepSeek diferencia step de turn. Um step é uma requisição ao modelo mais suas chamadas de ferramentas. Um turn é zero ou mais steps: ele abre antes da primeira entrada ser assumida e fecha quando nada mais está pendente. A maioria dos turns executa vários steps antes de o agente responder, mas uma entrada rejeitada fecha um turn que não gastou steps.

Um turn pode conter vários steps. Imagem do autor.

Sessões usam um log de eventos somente de anexação

Para mim, esta é a parte mais importante. Uma sessão é um log somente de anexação de eventos tipados, não um array de mensagens de chat. O Harness monta o histórico do modelo a partir desse log, e a documentação de sessões exige que tudo enviado ao modelo seja recuperável a partir dele.

Retomar, bifurcar, buscar, reproduzir e a visualização Trajectory se baseiam nesse fluxo de eventos.

Reconstituir o histórico não é uma reexecução determinística. A saída do modelo e o estado externo podem variar, mas o log ainda fornece um registro inspecionável do que aconteceu.

O histórico da sessão é um log somente de anexação. Imagem do autor.

Como o DeepSeek Harness controla ferramentas e sandboxes

Um modelo pode solicitar uma ferramenta pelo nome, mas não executa diretamente. Dois controles separados ficam entre o pedido e uma mudança no sistema de arquivos.

O pipeline de execução de ferramentas

A chamada passa por checagem de política, execução e tratamento do resultado. O modelo escolhe a ferramenta; o runtime decide se e como ela roda.

O runtime decide como as ferramentas rodam. Imagem do autor.

Sandboxing versus aprovações

• Aprovação pergunta se o usuário deve confirmar uma ação. 
• Sandboxing limita onde e como a ação executa. 

A DeepSeek mantém isso separado, embora presets de permissão agrupem ambos os controles, assim como um runtime de contêiner separa permissões de processo de limites de execução.

Vale destacar agora, já que voltarei a isso na seção de limitações: dizer a um modelo num system prompt para "apenas ler arquivos" é uma sugestão que ele pode seguir, não um limite imposto como uma restrição de sandbox no nível do SO.

Modos do DeepSeek Harness: Standard, PTC, Minimal e Creator

O DeepSeek Harness oferece quatro modos. Nenhum deles está acima dos outros. São quatro respostas para "quanto do runtime deve ser exposto a esta sessão" e a escolha certa depende da tarefa. Como a seção de arquitetura mostrou, cada modo altera o conjunto de ferramentas disponível ao agente.

Quatro modos compartilham a mesma base de runtime. Imagem do autor.

Modo Standard

A base para uso geral: 

• Edição de arquivos
• Acesso ao shell
• Busca em arquivos e na web
• Skills
• Planejamento
• Metas
• Subagentes
• Workflows

Para trabalho comum em repositórios, eu começaria por aqui.

Modo PTC

O modo PTC mantém quase todo o conjunto de ferramentas do Standard, mas muda como o modelo chega até elas. (Desde a versão 0.1.2, o Web PTC não expõe mais por padrão a ferramenta genérica workflow.) 

Em vez de solicitar ferramentas individuais ao longo de vários steps, o modelo escreve um programa contra um SDK gerado. Esse programa pode chamar várias ferramentas via run_code. Cada chamada ainda passa pelas mesmas checagens de política, então o PTC muda como o modelo declara o plano, não o que ele está autorizado a fazer.

A página do produto ainda usa o rótulo "Code mode", mas uma versão oficial mais recente renomeou para modo PTC mantendo conversas antigas legíveis. Vou usar modo PTC aqui; o FAQ volta ao que essas iniciais podem significar.

Modo Minimal

O modo Minimal reduz o ambiente a duas ferramentas: um shell persistente e um editor de arquivos por substituição de string. A DeepSeek o usa em benchmarks de modelo porque os resultados de teste dependem em parte do harness do modelo, não só dos seus weights.

Modo Creator

O modo Creator permite inspecionar o runtime e testar plugins do Cordis em memória. Serve para construir presets, e eu não o chamaria de autossuficiente num sentido mais profundo.

O que torna o DeepSeek Harness diferente de outros frameworks de agentes?

O DeepSeek Harness difere de muitos frameworks de agentes por tornar substituíveis as partes mais baixas do runtime. Eu quase coloquei isso na seção de arquitetura, mas a distinção passa fácil despercebida. O Cordis lida com essas trocas por meio de um único sistema de plugins.

Você pode mudar como o agente opera, não só as ferramentas que ele chama. O log de eventos também cria uma execução inspecionável pelos desenvolvedores, em vez de apenas um transcript de chat. Os modos Minimal e Creator permitem então testar o runtime por direções opostas.

DeepSeek Harness vs. Claude Code, Codex e OpenCode

Uma checklist de recursos perde o ponto. Cada concorrente suporta extensões; a pergunta útil é quais partes os desenvolvedores podem trocar. A distinção parece pequena, mas não é. Nossa comparação dedicada entre Harness e Claude Code usa o mesmo modelo em ambos e cobre setup, logs e custo.

DeepSeek Harness vs. Claude Code

Claude Code suporta instruções de projeto, skills, hooks, MCP, subagentes e um Agent SDK, mantendo o loop interno fixo. O DeepSeek Harness permite substituir o loop, o adaptador do modelo e a camada de storage via configurações.

DeepSeek Harness vs. Codex

Codex exige uma comparação mais cuidadosa porque seu CLI e App Server também são open source. Ele fornece um agent harness que os desenvolvedores estendem por pontos de entrada documentados. O DeepSeek Harness é construído em torno de mudar o próprio runtime. Eles oferecem níveis de controle diferentes.

DeepSeek Harness vs. OpenCode

OpenCode já é open source, funciona com vários provedores de modelo e usa arquitetura cliente-servidor. Você pode configurar ferramentas, permissões, sessões e provedores. Seus plugins estendem um core de servidor fixo, enquanto o DeepSeek também torna substituíveis o loop e o armazenamento de sessões.

Quando usar o DeepSeek Harness

Trocar partes do runtime não é útil por si só. O controle extra só importa quando resolve um problema que você já tem.

• Quando o próprio runtime faz parte do projeto. Se você está modificando adaptadores de modelo, o loop do agente, o storage ou o comportamento de sessões — não só construindo sobre um agente — este é o encaixe mais direto.
• Quando estiver comparando modelos em ambiente controlado. Usar o mesmo runtime mantém mais coisas fixas ao trocar o modelo, embora eles ainda possam diferir no uso de ferramentas e no estilo de raciocínio.
• Quando depurar uma execução complexa importa. O log de eventos da sessão e a visualização Trajectory facilitam reconstruir o que o modelo viu e quais ferramentas rodaram.
• Quando você está testando os internos de agentes. O modo Creator e o Cordis são para desenvolvedores estudando como agentes são montados, mais do que para quem só precisa de código pronto.

Pode ser desnecessário para chamadas simples de modelo ou para times que querem um agente de código pronto sem mexer nos internos. Substituir mais partes só vale o esforço quando esse controle resolve um problema real.

Limitações do DeepSeek Harness: status de developer preview e riscos de segurança

Nada disso importa sem uma visão clara de onde o projeto fica aquém hoje.

Ainda é um developer preview

O repositório da DeepSeek afirma claramente que haverá mudanças incompatíveis. Isso já aconteceu: a mudança de Code para PTC veio com alterações nas APIs de sessão e remoção de uma opção opcional de storage em SQLite. Faça o pin das versões. Pular essa etapa e torcer para tudo ficar estável não é plano.

Mais controle também significa mais complexidade

Tornar mais partes do runtime substituíveis também amplia o que o desenvolvedor precisa aprender: dependências de plugins, configurações, diferenças entre provedores e compatibilidade de versões. É a troca usual entre conveniência e controle.

O DeepSeek Harness é local?

Por padrão, o DeepSeek Harness armazena conteúdo de sessões, registros de ferramentas e configurações localmente, de acordo com sua declaração de processamento de dados. Você pode desativar os relatórios anônimos sobre configurações e listas de projetos. 

Mas um provedor de modelo externo, ferramenta web, servidor MCP ou plugin ainda pode enviar dados para fora da sua máquina sob suas próprias políticas. "Local-first" não cobre todos os serviços conectados.

Executar agentes traz riscos de segurança

Um runtime que pode editar arquivos, rodar comandos e carregar plugins de terceiros pode causar danos reais. O aviso de segurança da DeepSeek afirma que o projeto não passou por auditoria. Sandbox, aprovações e controles de permissão reduzem risco, mas não garantem isolamento.

Rodar o software na sua própria máquina não elimina esse risco. Use permissões limitadas e um ambiente descartável para trabalhos não confiáveis, e tenha cuidado com conteúdo que possa conter instruções ocultas.

Por que o comportamento do agente depende de mais do que o modelo

O comportamento do agente depende do runtime tanto quanto do modelo. Isso volta ao "Agente = Modelo + Harness", e a mesma divisão se aplica a agentes com LLM alem do DeepSeek.

O que um modelo produz depende de seus weights. O que um agente faz também depende de qual contexto chega ao modelo, quais ações ele pode tomar e quão rígidas são as restrições de execução. Nada disso vive nos weights.

O DeepSeek Harness evidencia essa camada ao dividi-la em partes nomeadas e substituíveis pelos desenvolvedores. O modo Minimal mostra por que isso importa além do DeepSeek: uma pontuação de benchmark reflete em parte o harness usado no teste, não só o modelo. O harness não deixa o modelo mais inteligente. Ele muda o cenário onde o modelo atua.

Conclusão

A frase de abertura é a que vale guardar: o modelo raciocina, mas o runtime decide a que esse raciocínio tem acesso e o que pode fazer. O DeepSeek Harness torna esse runtime editável — do adaptador do modelo e ferramentas ao armazenamento de sessões e loop do agente.

Esse controle traz o custo. Substituir mais partes do runtime significa assumir mais do setup, das mudanças de versão e dos limites de segurança. Um developer preview com acesso ao shell não é algo para instalar e esquecer.

Meu ponto é simples: use o DeepSeek Harness quando o próprio runtime fizer parte do trabalho. Se você só precisa de edições em repositório, um agente de código pronto exige menos de você.

Nosso tutorial de DeepSeek Harness cobre a configuração. O guia de alternativas ao Claude Code compara mais agentes de código, enquanto Introduction to AI Agents traz os fundamentos assumidos neste artigo.