Tutorial do DeepSeek Superagent: observe o CI e autorize uma correção

O que é o DeepSeek Superagent?

O DeepSeek Superagent observa um repositório do GitHub por meio do DeepSeek Harness. Regras do time decidem se um evento merece trabalho; o trabalho aceito vai para uma sessão separada. Este tutorial cobre o protótipo publicado, não ideias só de design.

O Harness fornece o runtime; o Superagent adiciona monitoramento de eventos e autorização. Nosso guia do agent harness cobre ferramentas, memória e controle.

Como o DeepSeek Superagent funciona?

Um novo evento do GitHub pode passar por quatro etapas. Essas etapas mantêm separadas a decisão e a mudança de código:

• Source e Trigger: o polling do GitHub transforma cada evento em um Trigger em uma Issue, pull request ou no main.

• Admission: o gate rotula como pedido explícito, candidato inferido ou nada.

• Eval e Decision:  o CI inferido é julgado contra as regras. Um pedido explícito é roteado para uma Decision de aceitação, motivo explicitRouted.

• Ticket e Executor: trabalho aceito recebe autorização, sessão de worker e diretório próprios.

Um comentário posterior na Thread do próprio Ticket vai para seu worker sem novo Eval. O diagrama mostra três caminhos no GitHub: CI do branch padrão, um pedido explícito e essa revisão. No caminho do CI, observe e auto deixam uma regra correspondente em pontas diferentes.

O CI é julgado. Pedidos iniciam o trabalho. Imagem do Autor.

Qual a diferença entre observe e auto?

O modo de aceitação se aplica apenas ao trabalho que o Superagent inferiu de um evento. Escolha uma das três opções:

• off descarta candidatos inferidos.

• observe avalia e registra um resultado positivo como "aceitaria".

• auto inicia o trabalho após uma avaliação positiva.

Um pedido de uma pessoa autorizada funciona em qualquer modo e cria seu próprio Ticket. Mantenha o auto desligado neste tutorial.

Crie um fluxo de correção de CI em observe

O pipeline usa pytest e dois jobs do GitHub Actions para transformar eventos em receita diária. O Superagent insere uma decisão antes do trabalho começar. Nosso tutorial de Claude Code Routines cobre outro fluxo orientado a eventos.

Rastreie o bug de replay na receita diária

O bug conta duas vezes um pagamento reenviado. Cada linha tem um event_id, order_id, timestamps e um valor. Um pedido pode ter vários pagamentos válidos.

Por isso, deduplicar por order_id pode passar num teste de replay, mas apagar pagamentos reais; a chave correta é event_id. Calcule os totais esperados com o módulo csv do Python antes de autorizar o agente, para que a saída do agente não vire o gabarito.

Defina o que é uma correção de CI bem-sucedida

Sucesso depende do que o workflow faz, não só do que o agente diz. Defina estas condições antes de mudar o repositório:

• Ignorar uma falha apenas de documentação.

• Reconhecer revenue-integrity sem iniciar trabalho.

• Abrir um pull request só após um pedido explícito.

• Preservar asserções e passar em uma suíte de holdout pré-criada.

Prepare a suíte de holdout antes de o Superagent ter acesso. Assim o comportamento esperado fica fora dos insumos de desenvolvimento do worker.

Pré-requisitos e isolamento do DeepSeek Superagent

Você precisa de uma chave de API da DeepSeek, duas contas do GitHub e um ambiente Linux descartável. Para o básico do Harness, veja nosso guia de configuração.

Softwares e contas necessárias

Fixe as versões para que uma atualização não altere o fluxo. A última coluna registra a configuração usada nos resultados adiante:

O agente precisa de seu próprio usuário do GitHub com permissão de escrita porque o Superagent lê as notificações dessa conta. Adicione à lista de permitidos apenas os mantenedores humanos que podem autorizar trabalho.

Isole o agente de arquivos pessoais

Os dois presets dão ao usuário do sistema operacional acesso total, e o wrapper gh não isola o processo. Use uma distribuição WSL nova com automount e interop desativados:

Se você já tem uma VM Linux descartável, ignore o bloco do WSL e use essa máquina. Mantenha credenciais e arquivos não relacionados fora dela.

# /etc/wsl.conf dentro da distribuição descartável
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagentTecnologia

Um usuário dedicado superagent deve guardar apenas a chave da DeepSeek e o token do agente. Isso reduz acessos acidentais, mas não é um limite de segurança; o modelo de segurança do WSL da Microsoft recomenda uma VM separada fora do WSL para código não confiável.

No GitHub, proteja o main com PR obrigatório, pelo menos uma aprovação independente e ambos os checks do CI. Dê ao agente acesso de escrita sem bypass de administrador. Nada disso impede prompt injection via texto de Issue.

Passo 1: construa o pipeline de receita em Python e a base do CI

O repositório do tutorial publicado agora já tem a correção mesclada no main, então não use o branch atual como estado inicial. Use estes commits para separar as três etapas:

O pipeline e os testes abaixo são simplificados da baseline verde (a6d2036), não retirados do main atual. Crie um repositório descartável a partir desse commit antes de seguir os passos do CI:

git clone https://github.com/KhalidAbdelaty/superagent-revenue-lab.git revenue-lab
cd revenue-lab
git switch -C main a6d2036
git remote remove origin

export EXPERIMENT_REPO="YOUR_LOGIN/superagent-revenue-lab"
gh repo create "$EXPERIMENT_REPO" --private --source=. --remote=origin --pushTecnologia

Use esse novo repositório para as falhas controladas e os branches do agente. Deixe o repositório publicado intacto; seus commits de incidente e solução servem de referência para comparação.

"""Relatório de receita diária a partir de eventos de pagamento."""
import pandas as pd


def load_events(path):
    """Lê eventos de pagamento; valores em centavos (inteiros)."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Retorna uma linha por dia em UTC com a receita total em centavos."""
    days = events["occurred_at"].dt.strftime("%Y-%m-%d")
    report = (
        events.assign(day=days)
        .groupby("day", as_index=False)["amount_cents"]
        .sum()
        .rename(columns={"amount_cents": "revenue_cents"})
    )
    return reportTecnologia

O conjunto de dados da baseline cobre dois dias e inclui múltiplos pagamentos reais para um pedido. O Pytest confere totais conhecidos e esse caso de pedido compartilhado, e ainda não testa replays:

import pandas as pd


def test_daily_totals_match_known_values():
    report = daily_revenue(load_events(DATA))
    assert report["revenue_cents"].tolist() == [20398, 27550]


def test_events_on_the_same_order_are_all_counted():
    t = pd.Timestamp(0, unit="s", tz="UTC")
    events = pd.DataFrame({
        "event_id": ["evt_a", "evt_b"],
        "order_id": ["ord_1", "ord_1"],
        "occurred_at": [t, t],
        "received_at": [t, t + pd.Timedelta(seconds=1)],
        "amount_cents": [1000, 250],
    })
    assert daily_revenue(events)["revenue_cents"].tolist() == [1250]Tecnologia

Dê a cada job o nome do comportamento que ele verifica. Os mesmos nomes aparecerão no GitHub e no texto do Trigger do Superagent:

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  revenue-integrity:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt   # pandas==2.3.3, pytest==8.4.2
      - run: pytest -v

  docs-check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python scripts/check_docs.py      # falha se o README linkar um arquivo ausenteTecnologia

Se o pytest puro não conseguir importar revenue, adicione um pytest.ini com pythonpath = .. Confirme que ambos os jobs passam no main antes de instalar o Superagent.

O diretório publicado experiment/holdout documenta a execução original, mas fica visível no clone público. Para um novo experimento, crie uma suíte nova fora de qualquer checkout e filesystem que o worker possa ler.

Faça o hash dessa suíte antes de enviar o pedido de correção. Cubra estes casos:

• Entregas repetidas de um mesmo evento.
• Eventos diferentes com o mesmo ID de pedido.
• Um DataFrame de entrada que deve permanecer inalterado.
• As colunas e a ordem de ordenação esperadas na saída.

Mantenha essa suíte oculta até a revisão. O passo 6 a executa a partir do ambiente humano separado depois que o worker termina.

O diagrama a seguir separa os insumos de desenvolvimento do worker da checagem final do mantenedor.

Dados de holdout ficam fora do worker. Imagem do Autor.

Passo 2: instale o DeepSeek Superagent e conecte o GitHub

Instale o bundle em um perfil dedicado do Harness, separado do perfil usado no dia a dia. Carregue o token da conta do agente em AGENT_GH_TOKEN sem gravá-lo no repositório. Depois, execute estes comandos como o usuário superagent:

npm install -g @deepseek-ai/[email protected] [email protected]

git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git ~/dsh-superagent
cd ~/dsh-superagent
git checkout --detach 8c32a9dc5d72c033816c6a8110b37f40cf94fba4
pnpm install && pnpm build

# Um wrapper do gh que só enxerga a conta do agente
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > ~/.local/bin/gh-agent <<'W'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
W
chmod +x ~/.local/bin/gh-agent
printf '%s' "$AGENT_GH_TOKEN" | gh-agent auth login --hostname github.com --with-token
gh-agent api user --jq .login            # sua conta dedicada do agente

# Perfil dedicado e depois o bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"Tecnologia

Observação: as execuções deste tutorial usaram o commit 6337fc8, que a DeepSeek depois fez squash em 8c32a9d.

Use o exemplo de perfil no repositório clonado para definir um diretório de estado e ligar o painel a 127.0.0.1:3082. Depois inicie o serviço no tmux:

scripts/dsh-superagent start
scripts/dsh-superagent statusTecnologia

Este perfil separa reinícios do serviço das suas sessões pessoais do Harness. Também mantém o PATH do plugin e as configurações do Git fora do perfil normal.

status pode relatar setup pendente ou repositoryUnset até você salvar o Source do GitHub no Passo 3. Por enquanto, confirme apenas que o runtime responde e que o painel do Superagent abre; não espere um Source ou baseline do CI ainda.

Abra Settings → Models no perfil dedicado e selecione deepseek-flash. Em Superagent → Settings → Eval e Execution, confirme que ambos os papéis herdam o modelo do perfil ou nomeie deepseek-flash explicitamente.

Passo 3: configure o monitoramento do GitHub Actions em observe

Deixe a observação do CI do branch padrão desligada enquanto você salva o Source, a policy, a rule e as configurações do executor. Ligue só depois que o novo repositório estiver verde no main, para que a primeira leitura registre um baseline limpo.

Configure o GitHub Source

Em Settings → Sources, defina o repositório como EXPERIMENT_REPO, aponte o campo de CLI para o wrapper dedicado gh-agent e mantenha a observação de CI do branch padrão desligada. Salve o Source e espere qualquer reinício terminar antes de mudar a policy.

Configure a policy de admission do CI

Um resultado de CI não tem remetente. Sua linha de admission tem uma célula, que por padrão é ignore. Se você deixar assim, o Eval nunca vê o CI.

Defina uma regra enxuta de revenue-integrity

Substitua os exemplos por uma regra com o nome do check. Diga ao avaliador para não adivinhar causas:

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Falhas de CI em revenue-integrity",
    "enabled": true,
    "instruction": "Um resultado de CI no branch padrão em que o check chamado revenue-integrity falha pela primeira vez. Esse check executa a suíte de pytest que protege os totais de receita diária. Julgue apenas pelos nomes de checks e resultados que você consegue ler para aquele commit; não deduza a causa raiz. Falhas limitadas a outros checks, como docs-check (links no README), não correspondem. Uma recuperação em que todos os checks passam não corresponde. Trabalho, se aceito: investigar os testes com falha em revenue-integrity, corrigir o pipeline sem enfraquecer ou apagar qualquer asserção, adicionar um teste de regressão e abrir um pull request para revisão humana. Nunca faça merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}Tecnologia

Adicione um comando de prepare que crie um worktree Git para cada Ticket. Assim cada worker começa de um checkout do repositório:

C=/home/superagent/src/superagent-revenue-lab
git -C $C fetch --no-tags "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C $C worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"Tecnologia

O Superagent preenche essas variáveis para cada Ticket. Verifique se o diretório resultante contém o checkout esperado antes de autorizar o trabalho.

O helper opcional grava o mesmo Source, policy, Eval e blocos de executor. Ele mantém a observação do CI desligada na primeira passagem; sempre defina explicitamente o repositório do experimento e o solicitante permitido:

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh allTecnologia

Mantenha a execução proativa desativada

Mantenha o Eval em observe com o modelo padrão do perfil. Após cada evento, confira a aba Eval para a Decision e a aba Execution para qualquer Ticket.

Ligue a observação do CI e registre o baseline

Depois que os dois jobs do GitHub Actions passarem no main, ligue a observação do CI do branch padrão. Com o script auxiliar, use a segunda passagem:

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh showTecnologia

A primeira leitura registra o estado sem criar trabalho. Verifique as quatro condições:

• Setup sem requisito pendente.

• O GitHub Source reporta ready.

• O Source registra um baseline limpo do CI.

• As abas Trigger e Execution não mostram Trigger nem Ticket do baseline.

Se alguma dessas checagens falhar, pare antes de criar a falha de documentação. As capturas de tela de Source e Eval mostram a configuração final.

Cartão do GitHub Source com observação do CI. Imagem do Autor.

Configurações de Eval: uma regra, modo observe. Imagem do Autor.

Passo 4: teste uma falha não relacionada no GitHub Actions

Use um link quebrado no README como falha não relacionada. Como o branch protegido rejeita um check com falha, use o bypass de administrador humano apenas neste repositório descartável; nunca dê esse bypass ao agente.

sed -i 's|^- Tests: .*|&\n- Data dictionary: [docs/data-dictionary.md](docs/data-dictionary.md)|' README.md
git commit -am "docs: link the data dictionary from the README" && git pushTecnologia

Quando o GitHub Actions terminou, o docs-check falhou e o revenue-integrity passou. Isso casou com a regra definida: o Superagent ignorou o candidato porque a regra de receita não correspondia.

A Decision usou ignoredFromCard, um atalho para candidatos que não tocam uma regra ativa. Então essa verificação cobre o roteamento, e não a regra em si.

Reverta a mudança no README e espere ambos os jobs passarem. O Superagent deve ignorar a recuperação e permanecer inativo.

Passo 5: dispare uma falha de CI em revenue-integrity

Use o mesmo caminho apenas humano para adicionar os dados de incidente do repositório do tutorial. Este resumo mostra o replay e pagamentos separados em um pedido, sem as colunas de timestamp:

event_id,order_id,amount_cents,delivery
evt_1009,ord_507,5000,first
evt_1010,ord_508,6400,first
evt_1011,ord_508,1600,first
evt_1009,ord_507,5000,replay
evt_1012,ord_509,2100,firstTecnologia

O repositório mantém as colunas completas de timestamp; elas foram omitidas aqui porque não determinam a identidade do evento. O cálculo independente preparado antes espera 15.100 centavos, então coloque esse valor no teste e adicione test_replayed_event_is_counted_once().

E       actual daily total: 20100
E       expected daily total: 15100
E       replay total: 8000 != 4000
FAILED tests/test_revenue.py::test_daily_totals_match_known_values
FAILED tests/test_revenue.py::test_replayed_event_is_counted_once
2 failed, 1 passedTecnologia

Os 5.000 centavos extras são um pagamento contado duas vezes. Editar de 15100 para 20100 ou deletar o teste de replay também deixaria o CI verde, e nenhuma dessas opções é correção.

O workflow do GitHub Actions com falha mostra apenas o revenue-integrity falhando. Seu Trigger chegou após cerca de um intervalo de polling.

O Eval marcou o candidato como "aceitaria", enquanto a aba Execution ficou vazia. O avaliador viu nomes de checks e conclusões, não o log do pytest, então soube qual guarda falhou, mas não o motivo.

O modo observe registra apenas "aceitaria". Imagem do Autor.

Passo 6: autorize a correção e verifique o pull request

O caminho de pedido explícito, visto antes, agora autoriza a execução. Notificações do GitHub podem chegar com atraso.

Lide com uma menção na Issue que não foi capturada

No Superagent 6337fc8, o GitHub Source sobrepõe polls em cinco segundos e lê uma thread notificada a partir do cursor posterior. Notificações de menção chegaram 21 a 23 segundos depois, então um poll poderia avançar além da mensagem.

Esse timing explica por que o corpo da nova Issue e alguns comentários nunca viraram Triggers. Um relato da comunidade descreve o mesmo modo de falha.

Autorize a correção com um comentário no GitHub

Publique o pedido novamente como um comentário novo e confirme que o Trigger aparece. O Superagent deve aceitá-lo como um pedido explícito e iniciar o worker.

Menção em comentário cria o Ticket autorizado. Imagem do Autor.

Verifique a correção de deduplicação de eventos do agente

O pull request resultante baseou a correção em event_id. Revise o diff em vez de confiar na descrição:

 def daily_revenue(events):
     """Retorna uma linha por dia em UTC com a receita total em centavos."""
+    # O webhook de pagamento pode entregar o mesmo evento mais de uma vez, com um
+    # received_at diferente, mas o mesmo event_id. Um event_id é um evento de
+    # pagamento, então mantenha apenas sua primeira entrega antes de agregar.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")Tecnologia

Ele adicionou um teste de replay e não deletou nada. O primeiro comando de teste falhou por falta de dependências. Depois que o worker criou um ambiente virtual, a suíte visível de testes passou.

Teste pagamentos que compartilham um pedido

Solicite mudanças sem mencionar o agente: prove que dois pagamentos em um pedido, idênticos exceto por event_id, contam ambos, e que um replay conta uma vez. A revisão deve chegar ao mesmo Ticket sem novo Eval.

O worker respondeu com um commit que apenas adicionou um teste e deixou o pipeline inalterado. Antes da aprovação, confira o exato head SHA e rode a suíte independente contra essa revisão.

Feedback de revisão continua no mesmo Ticket. Imagem do Autor.

Confira a correção com dados independentes

Execute o holdout a partir do ambiente humano separado contra o head exato do pull request. No a43c541, ambas as suítes passaram 5 de 5 testes sem remover asserção; o 62bac08 manteve a mesma árvore.

Testes escritos só pelo agente cobrem apenas os casos que o próprio agente escolheu.

Passo 7: faça o merge da correção e meça a recuperação do CI

Após o merge, verifique se o main volta a ficar verde e se a recuperação não inicia novo trabalho. Depois, revise o rastro de eventos, o tempo decorrido e o custo do provider.

Faça o merge e confirme a recuperação do CI

Depois da aprovação manual e do merge, ambos os checks do branch padrão passaram. O Superagent ignorou a recuperação, não iniciou mais trabalho e fechou o Ticket existente com o resultado merged.

Avalie a entrada de eventos e as decisões

Acompanhe cada evento da entrada ao desfecho, como nosso guia de avaliação de agentes de IA descreve. Ao longo de três repetições, eventos que chegaram ao Eval seguiram o caminho esperado; perdas ocorreram na entrada, não na Decision do modelo.

Meça correção, tempo e custo

O mesmo cenário rodou em três repositórios e distribuições WSL novos com Superagent 6337fc8, Harness 0.2.1-rc.3, deepseek-flash e uma única policy. Os custos usam a tarifa reduzida off-peak da DeepSeek; são reproduções, não um benchmark.

Todas as três correções usaram event_id; todos os testes de holdout passaram. A entrada variou mais: a menção no corpo da Issue falhou todas as vezes, e a terceira reprodução também perdeu dois comentários antes de um chegar.

A segunda reprodução reescreveu commits, e a aprovação chegou antes do rerun do holdout. A checagem posterior passou, mas a ordem mais segura é head SHA, holdout e, então, aprovação.

Limitações e troubleshooting do DeepSeek Superagent

Várias falhas aqui parecem silêncio, então comece descobrindo onde o evento parou. O frustrante é que uma notificação perdida e um ignore correto podem parecer iguais.

Falhas de CI que não geram Trigger

O Superagent acompanha mudanças no conjunto que falha, então a leitura do baseline, um check que continua falhando e checks ainda em execução não produzem nada. Um Trigger sem Decision geralmente aponta para a célula de admission do CI, não para o modelo.

Pedidos do GitHub que nunca chegam

Pedidos podem falhar quando o remetente não é permitido, o Source está desligado, o processamento está pausado ou o GitHub notifica com atraso. Se essas verificações passarem, poste um comentário novo; editar o corpo da Issue não cria evento.

Limites da correção autônoma de CI

O protótipo não oferece limite de segurança. Workers têm acesso total como usuário do SO, e regras de disclosure são texto de prompt. Isole a conta do agente e limite-a ao repositório descartável.

Antes de mudar para auto, colete semanas de Decisions observadas, conte aceitações erradas e ignores errados, e mova o worker do WSL para uma VM separada.

Considerações finais

O contraste inicial se manteve: dois estados vermelhos no CI não levaram à mesma ação. O Superagent ignorou o docs-check e marcou revenue-integrity como "aceitaria", enquanto o modo observe manteve o código intocado até uma pessoa solicitar a correção.

O patch em event_id foi direto. A entrada de notificações foi menos confiável: a menção no corpo da Issue nunca chegou ao Eval, então uma regra correta não pôde ajudar.

Eu não generalizaria este resultado para correção autônoma de CI. O repositório era pequeno, a regra, enxuta, e o merge, controlado por humanos. Em outros contextos, comece com tudo verde, inspecione as Decisions, autorize explicitamente, mantenha dados de holdout separados e faça o merge após checagens independentes.

Meu próximo passo seria corrigir o caminho de notificações do GitHub e repetir o fluxo com mais tipos de falha. Até que existam essas evidências, eu manteria o modo auto desligado.