Arquitetura do DeepSeek SuperAgent: como funciona seu agente de código aberto para programação

Atualizado em 2 de novembro de 2026 · Análise da pesquisa e da documentação

O protótipo SuperAgent da DeepSeek transforma atividades de um repositório em trabalho contínuo de programação. Suas decisões mais interessantes vão além da escrita de código: envolvem escolher quais eventos merecem uma ação, preservar o contexto de cada tarefa e saber quando devolver o controle a uma pessoa.

Um assistente de programação pode corrigir um bug em uma única sessão. Uma equipe precisa de mais: uma issue chega, uma correção é revisada, uma verificação falha e um comentário aparece no dia seguinte. Alguém precisa conectar esses acontecimentos e decidir o próximo passo. O SuperAgent é uma tentativa de incorporar essa coordenação ao próprio sistema de agentes.

Este artigo examina o protótipo público e sua documentação e apresenta uma forma prática de avaliá-lo. Os exemplos são ilustrativos; não fizemos uma implantação nem medimos seu desempenho para este artigo.

O que exatamente a DeepSeek disponibilizou como código aberto?

O projeto público, dsh-superagent-prototype, é um agente proativo de programação que trabalha em um único repositório GitHub. O GitHub fornece uma fonte de solicitações e atividades; o Feishu pode ser adicionado como outra fonte. O sistema pode criar um item de trabalho para uma solicitação autorizada, executá-lo em uma sessão e em um diretório separados e responder na conversa original, inclusive com um pull request.

O projeto se apresenta como código de pesquisa, não como um produto oficial. Seu README informa que a versão publicada foi adaptada a partir do trabalho interno e difere tanto dessa implementação quanto daquela descrita na pesquisa que acompanha o projeto. Algumas ideias da pesquisa ainda são propostas para o futuro. Essa distinção importa: uma ideia arquitetural apresentada em um artigo não é necessariamente um recurso disponível nesta versão.

Como uma solicitação vira uma tarefa de programação?

O modelo de domínio do projeto separa a origem de um evento do trabalho que ele pode gerar. Uma Source (fonte) traz atividades para o sistema. Um Trigger (gatilho) representa algo que aconteceu. Um Ticket representa uma tarefa; seu Mandate (mandato) registra a base para aceitá-la. Um Executor trabalha no ticket em sua própria sessão.

O roteador decide se um evento candidato deve iniciar um novo trabalho, ser associado a um trabalho existente, ser ignorado ou, quando cabível, interromper um trabalho. O executor realiza a tarefa aceita e informa seu estado. Separar essas funções permite que o sistema receba novas atividades enquanto uma tarefa de implementação continua.

Exemplo: uma issue seguida de um comentário de revisão

Imagine que um colega autorizado mencione o agente em uma issue do GitHub e peça que ele investigue um teste que falhou. O agente aceita a solicitação, prepara o diretório do ticket e investiga. Se abrir um pull request, discussões posteriores podem chegar ao ticket responsável pelo trabalho. Uma mensagem de acompanhamento dentro do escopo pode ser tratada pelo executor existente; uma solicitação fora do escopo pode ser devolvida para encaminhamento. O exemplo ilustra o modelo documentado, não uma garantia de que toda correção dará certo.

Quem pode autorizar o agente a agir?

O sistema de autorização distingue uma solicitação explícita de um evento candidato inferido. Uma pessoa autorizada que se dirige ao agente pode fazer uma solicitação explícita. Outras atividades, como determinadas mensagens que não mencionam o agente ou mensagens de bots cadastrados, podem se tornar candidatas inferidas, dependendo da política da fonte. Antes de serem aceitas, elas precisam ser avaliadas em relação às regras ativas da equipe.

Solicitações explícitas funcionam nos três modos. O projeto recomenda começar em observe, para que os operadores examinem as decisões antes de ativar a aceitação proativa. Isso ajuda a encontrar regras que geram ruído: um gatilho pode ser tecnicamente válido e ainda assim consumir a atenção da equipe sem necessidade.

Mensagens entregues a um ticket inscrito em uma conversa fornecem contexto; elas não concedem automaticamente uma nova autorização. A política, as listas de permissão e o mandato definem a autorização, enquanto texto de issues, comentários e documentos citados continuam sendo entradas para a decisão. Uma mudança de política também não revoga imediatamente todos os mandatos ativos: a documentação descreve avisos e revalidação antes de algumas retomadas. Vale entender esses detalhes antes de presumir que alterar uma configuração interrompe todo o trabalho em andamento.

O que acontece dentro de uma sessão de execução?

Cada ticket recebe uma sessão de executor e um diretório na raiz de execução configurada. Um comando de preparação pode criar uma Git worktree; se nenhum comando for configurado, o executor começa em um diretório vazio. Uma falha na preparação é registrada como falha do ticket. O guia de execução do projeto descreve o ciclo completo.

Os executores ocupam vagas de concorrência configuradas durante o início ou a execução ativa. O projeto permite uma vaga adicional para uma mensagem de uma pessoa ou uma solicitação de status quando a capacidade normal está cheia. Outras entradas, incluindo resultados de CI, aguardam uma vaga normal. A ideia é evitar que uma fila ocupada impeça uma pessoa de continuar um ticket existente.

O painel distingue trabalhos na fila, em execução, aguardando, prontos para revisão, bloqueados ou com falha. A distinção é útil: um agente que parou porque precisa de uma decisão não deveria parecer igual a outro que ainda está executando um teste.

Como o SuperAgent lida com interrupções e recuperação?

Trabalhos longos com agentes precisam de um plano para falhas. O protótipo registra o trabalho antes de executar ações como iniciar uma atribuição ou entregar uma entrada. Entregas malsucedidas são tentadas novamente com intervalos crescentes; erros temporários do provedor de modelo ou da rede recebem um número limitado de novas tentativas. Um ticket bloqueado ou com falha deixa de receber entradas automáticas até que uma pessoa intervenha, um relatório que atenda às condições seja recebido ou o operador tente novamente.

Após a reinicialização do serviço, atribuições interrompidas são retomadas com uma nota de recuperação que orienta o executor a verificar seu diretório, o histórico do Git e o GitHub antes de repetir ações externas. A documentação informa que sessões, diretórios, inscrições e mensagens pendentes estão entre os dados preservados após a reinicialização. Uma nova tentativa cria uma atribuição na mesma sessão de executor, no mesmo diretório, branch e pull request.

Esses mecanismos reduzem a chance de perder o acompanhamento do trabalho. Eles não tornam ações externas automaticamente seguras nem garantem que uma operação ocorra exatamente uma vez em todos os cenários de falha. Antes de repetir uma ação que possa enviar uma mensagem, modificar dados ou iniciar uma implantação, o operador deve verificar o que de fato aconteceu.

O que é necessário para experimentar o protótipo?

O repositório oferece um guia de configuração assistida por agente e instruções de implantação manual. O guia lista Node.js 22.19+ ou 24+, pnpm, Git 2.32+, tmux, Python 3.8+, GitHub CLI 2.48+, uma versão compatível do DeepSeek Harness e um provedor de modelo configurado. Consulte os arquivos atuais para verificar mudanças de versão e requisitos da plataforma.

O guia recomenda uma conta GitHub dedicada ao agente, uma lista inicial curta de pessoas autorizadas, o modo observe e a mesclagem de alterações por pessoas. Também descreve um perfil separado do Harness e um comando de preparação para criar cópias de trabalho por ticket. O Feishu é opcional. Revise cada etapa e as permissões das credenciais; a lista abaixo não substitui as instruções de implantação do projeto.

Um primeiro experimento que faríamos

1. Use um repositório descartável ou de baixo risco, sem dados sensíveis, e dê à conta dedicada do agente apenas os acessos necessários para o teste.
2. Mantenha a aceitação proativa em observe; escolha um operador autorizado e exija que pessoas façam a mesclagem das alterações.
3. Peça uma tarefa limitada, como diagnosticar a falha reproduzível de um teste, com critérios claros de aceitação e sem implantação.
4. Examine a decisão de encaminhamento do ticket, o diff proposto, a saída real dos testes, as mensagens e o uso do modelo. Registre falhas e sucessos.
5. Revise as decisões proativas observadas antes de adicionar uma regra ou ampliar permissões.

Esses passos são recomendações editoriais, não resultados de um teste em produção. Escolha isolamento de execução e controles de rede adequados ao seu ambiente; os diretórios do protótipo, por si só, não os fornecem.

Ele pode fazer o merge dos próprios pull requests?

O guia de configuração recomenda que pessoas façam o merge até que os pull requests do agente tenham demonstrado consistência. A documentação de execução descreve instruções opcionais de auto-merge com condições, incluindo as aprovações necessárias, mas faz uma distinção importante: essas instruções orientam o agente, enquanto as regras de proteção de branch do GitHub aplicam as exigências do repositório. O sistema não tem uma lógica de decisão separada específica para merge. Se aprovações forem obrigatórias, configure essa exigência no GitHub e considere invalidar aprovações antigas quando houver novas alterações. Para um teste exclusivamente manual, siga as instruções de configuração para remover o parágrafo de auto-merge.

Como uma equipe deve avaliar se ele ajuda?

Meça o trabalho em torno de uma alteração, não apenas o tempo até aparecer um pull request. Compare um pequeno conjunto de tarefas semelhantes com o processo habitual da equipe e inclua execuções malsucedidas ou abandonadas.

Um pull request rápido que leva horas para ser corrigido não representa necessariamente um ganho de produtividade. Da mesma forma, um agente que sabe quando ficar em silêncio pode ser mais útil do que um que abre um ticket para cada evento. Registre a dificuldade das tarefas e o tamanho da amostra antes de tirar conclusões.

Quais são os limites da versão pública?

Ela se destina a um único repositório, depende do Harness e das integrações ao redor e é explicitamente descrita como software de pesquisa. Os responsáveis alertam sobre possíveis bugs e práticas de engenharia inconsistentes. Algumas ideias da pesquisa não estão implementadas no código público. Não encontramos na documentação do projeto uma base para afirmar um percentual geral de ganho de produtividade ou garantir que ele possa administrar sozinho um repositório de produção.

A contribuição arquitetural é mais específica: o projeto trata propriedade das tarefas, autorização, continuidade e atenção humana como problemas de engenharia. As equipes podem estudar essas escolhas mesmo que decidam não implantar este protótipo.

Perguntas frequentes

O DeepSeek SuperAgent é um novo modelo?

Não. O projeto publicado é um protótipo de sistema de agentes empacotado para o DeepSeek Harness. Ele precisa de um provedor de modelo configurado; o modelo e o sistema de orquestração são camadas separadas.

O SuperAgent é de código aberto?

Sim. O repositório público usa a licença MIT. O código publicado foi adaptado da implementação interna da equipe e não é idêntico a ela.

O modo observe impede todo o trabalho?

Não. Ele impede que candidatos inferidos sejam aceitos como trabalho proativo e registra avaliações positivas; solicitações explícitas ainda podem ser aceitas.

O SuperAgent pode trabalhar em vários repositórios?

O README público descreve o protótipo como um agente de programação para um único repositório GitHub. Não presuma que a orquestração de vários repositórios esteja incluída.

Uma worktree separada é suficiente para protegê-lo?

Não. O guia de execução informa que os diretórios e os comandos de encapsulamento não são uma barreira de segurança. Os executores rodam comandos como o usuário do sistema operacional que opera o serviço, portanto isolamento e permissões precisam de atenção separada.