Tutorial de DeepSeek Superagent: observa el CI y autoriza una corrección

¿Qué es DeepSeek Superagent?

DeepSeek Superagent vigila un repositorio de GitHub a través de DeepSeek Harness. Las reglas del equipo deciden si un evento merece trabajo; el trabajo aceptado pasa a una sesión aparte. Este tutorial cubre el prototipo publicado, no ideas solo de diseño.

Harness aporta el tiempo de ejecución; Superagent añade monitorización de eventos y autorización. Nuestro artículo explicativo sobre el harness de agentes cubre herramientas, memoria y control.

¿Cómo funciona DeepSeek Superagent?

Un nuevo evento de GitHub puede pasar por cuatro etapas. Estas etapas mantienen separadas la decisión y el cambio de código:

• Origen y disparador: el sondeo de GitHub convierte cada evento en un Trigger sobre un Issue, un pull request o main.

• Admisión: la compuerta lo etiqueta como solicitud explícita, candidato inferido o nada.

• Evaluación y decisión: el CI inferido se juzga frente a las reglas. Una solicitud explícita se enruta a una Decision de aceptación, con motivo explicitRouted.

• Ticket y ejecutor: el trabajo aceptado obtiene su autorización, sesión de trabajo y directorio.

Un comentario posterior en el hilo del propio Ticket va a su trabajador sin nueva Evaluación. El diagrama muestra tres rutas en GitHub: CI de la rama por defecto, una solicitud explícita y esa revisión. Dentro del camino del CI, observe y auto dejan una regla coincidente en extremos distintos.

El CI se juzga. Las solicitudes inician el trabajo. Imagen del autor.

¿Cuál es la diferencia entre el modo observe y el modo auto?

El modo de aceptación se aplica solo al trabajo que Superagent infiere de un evento. Elige uno de tres ajustes:

• off descarta candidatos inferidos.

• observe los evalúa pero registra un resultado positivo como "se aceptaría".

• auto inicia trabajo tras una evaluación positiva.

Una solicitud de una persona permitida funciona en cualquier modo y crea su propio Ticket. Mantén auto desactivado en este tutorial.

Crea un flujo de reparación de CI en modo observación

El pipeline usa pytest y dos jobs de GitHub Actions para convertir eventos en ingresos diarios. Superagent inserta una decisión antes de que empiece el trabajo. Nuestro tutorial de Claude Code Routines cubre otro flujo de trabajo dirigido por eventos.

Localiza el bug de repetición en los ingresos diarios

El bug cuenta dos veces un pago repetido. Cada fila tiene un event_id, order_id, marcas de tiempo y un importe. Un mismo pedido puede contener varios pagos válidos.

Por eso, desduplicar por order_id puede pasar una prueba de repetición pero borrar pagos reales; la clave correcta es event_id. Calcula los totales esperados con el módulo csv de Python antes de autorizar al agente, para que la salida del agente no sea la plantilla de respuestas.

Define qué es una reparación de CI satisfactoria

El éxito depende de lo que hace el flujo de trabajo, no solo de lo que dice el agente. Fija estas condiciones antes de cambiar el repositorio:

• Ignorar un fallo que sea solo de documentación.

• Detectar revenue-integrity sin iniciar trabajo.

• Abrir un pull request solo tras una solicitud explícita.

• Conservar las aserciones y pasar una batería de holdout preconstruida.

Prepara la batería de holdout antes de dar acceso a Superagent. Así mantienes el comportamiento esperado fuera de las entradas de desarrollo del trabajador.

Requisitos previos y aislamiento de DeepSeek Superagent

Necesitas una clave de la API de DeepSeek, dos cuentas de GitHub y un entorno Linux desechable. Para lo básico de Harness, consulta nuestra guía de configuración básica.

Software y cuentas necesarias

Fija las versiones de software para que una actualización no cambie el flujo de trabajo. La última columna recoge la configuración usada para los resultados que verás más adelante:

El agente necesita su propia cuenta de GitHub con permisos de escritura porque Superagent lee las notificaciones de esa cuenta. Añade a la lista de permitidos solo a las personas mantenedoras que puedan autorizar trabajo.

Aísla al agente de tus archivos personales

Ambos preajustes dan al usuario del sistema operativo acceso completo, y el wrapper gh no aísla el proceso. Usa una distribución WSL limpia con automount e interop desactivados:

Si ya tienes una máquina virtual Linux desechable, sáltate el bloque de WSL y usa esa máquina. Mantén fuera credenciales y archivos no relacionados.

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagentCon la tecnología de

Un usuario dedicado superagent debería guardar solo la clave de DeepSeek y el token del agente. Esto reduce accesos accidentales pero no es un límite de seguridad; el modelo de seguridad de WSL de Microsoft recomienda una máquina virtual gestionada aparte, fuera de WSL, para código no confiable.

En GitHub, protege main con pull request obligatorio, al menos una aprobación independiente y ambas comprobaciones de CI. Da al agente permisos de escritura sin bypass de administrador. Nada de esto impide inyección de prompts a través del texto de Issues.

Paso 1: Construye el pipeline de ingresos en Python y la línea base del CI

El repositorio del tutorial publicado ya tiene la reparación fusionada en main, así que no uses su rama actual como estado inicial. Usa estos commits para separar las tres etapas:

El pipeline y los tests siguientes están simplificados a partir de la línea base en verde (a6d2036), no tomados del main actual. Crea un repositorio desechable desde ese commit antes de seguir los pasos del 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 --pushCon la tecnología de

Usa este nuevo repositorio para los fallos controlados y las ramas del agente. Deja el repositorio publicado sin cambios; sus commits de incidente y solución sirven como referencia.

"""Daily revenue report built from payment events."""
import pandas as pd


def load_events(path):
    """Read payment events; amounts are integer cents."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Return one row per UTC day with total revenue in cents."""
    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 reportCon la tecnología de

El conjunto de datos de la línea base abarca dos días e incluye varios pagos reales para un pedido. Pytest comprueba totales conocidos y ese caso de pedido compartido, y aún no prueba repeticiones:

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]Con la tecnología de

Nombra cada job según el comportamiento que comprueba. Así verás los mismos nombres en GitHub y en el texto del Trigger de 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      # fails if README links a missing fileCon la tecnología de

Si pytest a pelo no puede importar revenue, añade un pytest.ini con pythonpath = .. Confirma que ambos jobs pasan en main antes de instalar Superagent.

El directorio publicado experiment/holdout documenta la ejecución original pero es visible en el clon público. Para un nuevo experimento, crea una batería fresca fuera de cualquier checkout y de cualquier sistema de archivos que el trabajador pueda leer.

Hashea esa batería antes de enviar la solicitud de reparación. Cubre estos casos:

• Entregas repetidas de un mismo evento.
• Eventos distintos con el mismo ID de pedido.
• Un DataFrame de entrada que debe permanecer sin cambios.
• Las columnas de salida esperadas y el orden de clasificación.

Mantén esta batería oculta hasta la revisión. El paso 6 la ejecuta desde el entorno humano separado cuando termine el trabajador.

El siguiente diagrama separa las entradas de desarrollo del trabajador de la comprobación final de la persona mantenedora.

Los datos de holdout permanecen fuera del trabajador. Imagen del autor.

Paso 2: Instala DeepSeek Superagent y conecta GitHub

Instala el bundle en un perfil de Harness dedicado, separado del perfil que usas a diario. Carga el token de la cuenta del agente en AGENT_GH_TOKEN sin escribirlo en el repositorio. Luego ejecuta estos comandos como el usuario 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

# A gh wrapper that only ever sees the agent account
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            # your dedicated agent account

# Dedicated profile, then the bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"Con la tecnología de

Nota: Las ejecuciones de este tutorial usaron el commit 6337fc8, que DeepSeek después aplastó en 8c32a9d.

Usa el ejemplo de perfil del repositorio clonado para establecer un directorio de estado y vincular el panel a 127.0.0.1:3082. Luego inicia el servicio en tmux:

scripts/dsh-superagent start
scripts/dsh-superagent statusCon la tecnología de

Este perfil separa los reinicios del servicio de tus sesiones personales de Harness. También mantiene fuera del perfil normal el PATH del plugin y la configuración de Git.

status puede informar de configuración pendiente o repositoryUnset hasta que guardes la fuente de GitHub en el Paso 3. En este punto, confirma solo que el runtime responde y que se abre el panel de Superagent; aún no esperes una Source ni una línea base de CI.

Abre Settings → Models en el perfil dedicado y selecciona deepseek-flash. En Superagent → Settings → Eval y Execution, confirma que ambos roles heredan el modelo de ese perfil o nómbralo explícitamente como deepseek-flash.

Paso 3: Configura la monitorización de GitHub Actions en modo observación

Deja desactivada la observación del CI de la rama por defecto mientras guardas la Source, la política, la regla y los ajustes del ejecutor. Actívala solo después de que el nuevo repositorio tenga main en verde, para que la primera lectura registre una línea base limpia.

Configura la Source de GitHub

En Settings → Sources, establece el repositorio en EXPERIMENT_REPO, apunta el campo de CLI al wrapper dedicado gh-agent y mantén desactivada la observación del CI de la rama por defecto. Guarda la Source y espera a que termine cualquier reinicio antes de cambiar la política.

Configura la política de admisión del CI

Un resultado de CI no tiene remitente. Su fila de admisión tiene una celda, que por defecto es ignore. Si dejas ese ajuste sin cambios, Eval nunca verá el CI.

Define una regla estricta para revenue-integrity

Sustituye las reglas de ejemplo por una regla con el nombre del check. Indica al evaluador que no adivine causas:

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Revenue integrity CI failures",
    "enabled": true,
    "instruction": "A default-branch CI result in which the check named revenue-integrity newly fails. That check executes the pytest suite guarding the daily revenue totals. Judge only from the check names and results you can read for that commit; do not guess a root cause. Failures limited to other checks, such as docs-check (README links), do not match. A recovery where every check passes does not match. Work, if accepted: investigate the failing revenue-integrity tests, fix the pipeline without weakening or deleting any assertion, add a regression test, and open a pull request for human review. Never merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}Con la tecnología de

Añade un comando de preparación que cree un worktree de Git para cada Ticket. Así cada trabajador empieza desde un checkout del repositorio:

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"Con la tecnología de

Superagent rellena estas variables para cada Ticket. Comprueba que el directorio resultante contiene el checkout esperado antes de autorizar trabajo.

El asistente de configuración opcional escribe la misma Source, política, Eval y bloques de ejecutor. Mantiene la observación del CI desactivada durante la primera pasada; define siempre de forma explícita el repositorio del experimento y la persona autorizada a solicitar:

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh allCon la tecnología de

Mantén desactivada la ejecución proactiva

Deja Eval en observe con el modelo por defecto del perfil. Tras cada evento, revisa la pestaña Eval para la Decision y la pestaña Execution para cualquier Ticket.

Activa la observación del CI y registra la línea base

Después de que ambos jobs de GitHub Actions pasen en main, activa la observación del CI de la rama por defecto. Con el script auxiliar, usa su segunda pasada:

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh showCon la tecnología de

La primera lectura registra estado sin crear trabajo. Verifica estas cuatro condiciones:

• La configuración no muestra requisitos pendientes.

• La Source de GitHub informa ready.

• La Source registra una línea base limpia del CI.

• Las pestañas Trigger y Execution no muestran Trigger ni Ticket de la línea base.

Si alguno de estos chequeos falla, para antes de crear el fallo de documentación. Las capturas de Source y Eval muestran la configuración final.

Tarjeta de GitHub Source con observación del CI. Imagen del autor.

Ajustes de Eval: una regla, modo observe. Imagen del autor.

Paso 4: Prueba un fallo de GitHub Actions no relacionado

Usa un enlace roto en el README como fallo no relacionado. Como la rama protegida rechaza un check fallido, usa el bypass de administración humano solo en este repositorio desechable; nunca se lo des al 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 pushCon la tecnología de

Cuando terminó GitHub Actions, docs-check falló y revenue-integrity pasó. Eso coincidió con la regla que había definido: Superagent ignoró el candidato porque la regla de ingresos no aplicaba.

La Decision usó ignoredFromCard, un atajo para candidatos que no tocan una regla activa. Así, esta comprobación cubre el enrutado, en lugar de la regla en sí.

Revierte el cambio del README y espera a que ambos jobs pasen. Superagent debería ignorar la recuperación y permanecer inactivo.

Paso 5: Provoca un fallo de CI en revenue-integrity

Usa la misma vía solo humana para añadir los datos del incidente desde el repositorio del tutorial. Este resumen muestra la repetición y los pagos separados de un pedido sin las columnas de marca de tiempo:

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,firstCon la tecnología de

El repositorio conserva las columnas completas de marcas de tiempo; se omiten aquí porque no determinan la identidad del evento. El cálculo independiente preparado antes espera 15.100 céntimos, así que fija ese valor en el test y añade 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 passedCon la tecnología de

Los 5.000 céntimos extra son un pago contado dos veces. Editar 15100 a 20100 o borrar la prueba de repetición también pondría el CI en verde, y ninguna de las dos es una reparación.

El workflow fallido de GitHub Actions muestra fallando solo revenue-integrity. Su Trigger llegó tras aproximadamente un intervalo de sondeo.

Eval marcó el candidato como "se aceptaría", mientras que la pestaña Execution quedó vacía. El evaluador vio nombres de checks y conclusiones, no el log de pytest, así que supo qué guardia falló pero no el porqué.

El modo observe solo registra "se aceptaría". Imagen del autor.

Paso 6: Autoriza la reparación y verifica el pull request

La ruta de solicitud explícita que vimos antes ahora autoriza la ejecución. Las notificaciones de GitHub pueden llegar con retraso.

Gestiona una mención en Issue que no llegó

Con Superagent 6337fc8, la Source de GitHub solapa sondeos cinco segundos y lee un hilo notificado desde el cursor más tardío. Las notificaciones por mención llegaron 21–23 segundos después, por lo que un sondeo podía avanzar más allá del mensaje.

Ese timing explica por qué el cuerpo del nuevo Issue y algunos comentarios no llegaron a convertirse en Triggers. Un reporte de la comunidad describe el mismo modo de fallo.

Autoriza la reparación con un comentario en GitHub

Publica de nuevo la solicitud como un comentario nuevo y confirma que aparece su Trigger. Superagent debería aceptarlo como solicitud explícita e iniciar el trabajador.

La mención en comentario crea el Ticket autorizado. Imagen del autor.

Revisa la corrección de desduplicación de eventos del agente

El pull request resultante basó la corrección en event_id. Revisa el diff en lugar de fiarte de la descripción:

 def daily_revenue(events):
     """Return one row per UTC day with total revenue in cents."""
+    # The payment webhook may deliver the same event more than once, with a
+    # different received_at but the same event_id. One event_id is one payment
+    # event, so keep only its first delivery before aggregating.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")Con la tecnología de

Añadió una prueba de repetición y no borró nada. El primer comando de test falló por dependencias faltantes. Tras crear el entorno virtual, la batería visible de tests pasó.

Prueba pagos que comparten un pedido

Pide cambios sin mencionar al agente: demuestra que dos pagos de un mismo pedido, idénticos salvo por event_id, cuentan ambos, y que una repetición de uno cuenta una vez. La revisión debería llegar al mismo Ticket sin nueva Evaluación.

El trabajador respondió con un commit que solo añadió un test y dejó el pipeline sin cambios. Antes de aprobar, comprueba el SHA exacto de la cabecera y vuelve a ejecutar la batería independiente contra esa revisión.

El feedback de revisión continúa en el mismo Ticket. Imagen del autor.

Comprueba la reparación con datos independientes

Ejecuta el holdout desde el entorno humano separado contra la cabecera exacta del pull request. En a43c541, ambas baterías pasaron 5 de 5 tests sin eliminar aserciones; 62bac08 mantuvo el mismo árbol.

Los tests escritos solo por el agente cubren únicamente los casos que el agente eligió.

Paso 7: Fusiona la corrección y mide la recuperación del CI

Tras la fusión, comprueba que main vuelve a estar en verde y que la recuperación no inicia trabajo nuevo. Luego revisa el rastro de eventos, el tiempo transcurrido y el coste del proveedor.

Fusiona la corrección y confirma la recuperación del CI

Tras la aprobación y fusión manual, ambas comprobaciones de la rama por defecto pasaron. Superagent ignoró la recuperación, no inició más trabajo y cerró el Ticket existente con el resultado merged.

Evalúa la ingesta de eventos y las decisiones

Sigue cada evento desde la ingesta hasta el resultado, como describe nuestra guía para evaluar agentes de IA. En tres repeticiones, los eventos que llegaron a Eval siguieron la ruta esperada; las pérdidas ocurrieron durante la ingesta, no en la Decision del modelo.

Mide corrección de la reparación, tiempo y coste

El mismo escenario se ejecutó en tres repositorios y distribuciones WSL nuevas con Superagent 6337fc8, Harness 0.2.1-rc.3, deepseek-flash y una política. Los costes usan la tarifa de DeepSeek fuera de hora punta; son reproducciones, no un benchmark.

Las tres reparaciones usaron event_id; todas las pruebas de holdout pasaron. La ingesta varió más: la mención en el cuerpo del Issue se perdió siempre, y la tercera reproducción también perdió dos comentarios antes de que llegara uno.

La segunda reproducción reescribió commits y la aprobación llegó antes de reejecutar el holdout. La comprobación posterior pasó, pero el orden más seguro es SHA de cabecera, holdout y luego aprobación.

Limitaciones y resolución de problemas de DeepSeek Superagent

Varios fallos aquí parecen silencio, así que empieza por encontrar dónde se detuvo un evento. Lo frustrante es que una notificación perdida y un ignore correcto pueden parecer lo mismo.

Fallos de CI que no producen Trigger

Superagent rastrea cambios en el conjunto que falla, de modo que la lectura de línea base, un check que sigue fallando y checks aún en ejecución no producen nada. Un Trigger sin Decision suele apuntar a la celda de admisión del CI, no al modelo.

Solicitudes de GitHub que no llegan

Las solicitudes pueden fallar si la persona remitente no está permitida, la Source está apagada, el procesamiento está en pausa o GitHub notifica tarde. Si esas comprobaciones pasan, publica un comentario nuevo; editar el cuerpo del Issue no crea evento.

Límites de la reparación autónoma del CI

El prototipo no aporta un límite de seguridad. Los trabajadores tienen acceso completo como usuario del SO y las reglas de divulgación son texto de prompt. Aíslalo en una máquina virtual y limítalo al repositorio desechable.

Antes de pasar a auto, recopila semanas de Decisions observadas, cuenta aceptaciones incorrectas y ignores incorrectos, y mueve el trabajador de WSL a una máquina virtual separada.

Reflexiones finales

Se mantuvo el contraste inicial: dos estados de CI en rojo no llevaron a la misma acción. Superagent ignoró docs-check y marcó revenue-integrity como "se aceptaría", mientras que el modo observe dejó el código intacto hasta que una persona solicitó la reparación.

El parche en event_id fue directo. La ingesta de notificaciones fue menos fiable: la mención en el cuerpo del Issue nunca llegó a Eval, así que una regla correcta no pudo ayudar.

No generalizaría este resultado a reparación autónoma del CI. El repositorio era pequeño, la regla estrecha y la fusión controlada por una persona. En otros contextos, empieza en verde, inspecciona las Decisions, autoriza de forma explícita, mantén los datos de holdout aparte y fusiona tras comprobaciones independientes.

Mi siguiente paso sería arreglar la ruta de notificaciones de GitHub y repetir el flujo con más tipos de fallo. Hasta tener esa evidencia, mantendría el modo auto desactivado.