Revisa a tu agente mientras trabaja

A las 10:40 lanzas una ejecución gestionada sobre el servicio de facturación: "Documenta cómo configurar y ejecutar el servicio en local". A las 11:02 llega una pull request con un docs/setup.md nuevo. Está bien. La línea 12 les dice a las nuevas incorporaciones que ejecuten go build ./..., que se salta los build tags que necesita el servicio, así que su primer build falla de una forma que el documento nunca explica. Y en algún momento hacia el minuto seis, el agente decidió que la sección de Docker del README estaba desactualizada y la reescribió. Nadie se lo había pedido.

Nada de esto es difícil de arreglar en la revisión. Lo que la revisión no puede devolver son los veinte minutos de en medio. El agente tomó esas decisiones pronto, sin nadie que las comprobara, y construyó todo lo demás encima. El arreglo es entonces una segunda ejecución que empieza de cero, vuelve a leer los mismos archivos y abre una segunda pull request.

Así funcionaban hasta ahora las ejecuciones de agentes gestionadas de Archyl. La página de la ejecución tenía un feed de eventos y un cuadro de dirección, así que podías seguir las llamadas a tools si mantenías la pestaña abierta, en un portátil o desde el móvil. Pero lo que el agente pretendía hacer, y lo que llevaba escrito, tenías que reconstruirlo a partir de los payloads de las llamadas a tools o descubrirlo en la pull request. Para una auditoría nocturna de dependencias, eso está bien. Para un cambio que vas a revisar de todas formas, coloca la revisión justo donde más cuesta.

Las ejecuciones tienen ahora un bucle de revisión. Esto es lo que ha cambiado:

El resto de este post vuelve a hacer la misma tarea, de la nueva forma, en el orden en que la vivirías. La tarea es un ejemplo; cada mensaje que se cita a continuación tiene el formato que el agente recibe de verdad.

Primero, el plan

Antes de tocar un archivo, se le pide al agente que llame a propose_plan con un resumen de una frase y unos cuantos pasos concretos. El prompt pide de 3 a 8, y la tool rechaza más de 12, para que un plan se pueda leer de un vistazo. El panel Plan, en la parte superior de la página de la ejecución, lo convierte en una checklist. A medida que trabaja, el agente marca cada paso como En curso, Hecho u Omitido, a veces con una nota breve, y el panel muestra el paso en el que está y el progreso (2/4).

Por defecto, el plan se comparte y el agente empieza enseguida. Activa Revisar el plan primero, en Coordinación dentro del perfil del agente, y en su lugar te esperará. El panel pasa al modo de revisión, donde puedes renombrar pasos, añadir detalles, y añadir, quitar o reordenar pasos.

Para el documento de configuración, el agente propuso cinco pasos. El cuarto era "Actualizar la sección de Docker del README", la reescritura que nadie había pedido. Lo quitas, añades un detalle al paso 2, y el botón que decía Aprobar plan ahora dice Aprobar plan editado. Esto es lo que recibe el agente:

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

Tu versión editada es el plan que sigue el agente y el que refleja la checklist. Cuando un plan está mal, y no solo un poco desviado, Solicitar cambios envía feedback en su lugar. El agente lo rehace y propone una nueva revisión, y las revisiones anteriores siguen en el feed, así que puedes ver qué cambió tu feedback.

Hasta que un plan está aprobado, el agente no puede escribir archivos, cambiar el modelo de arquitectura con las tools de Archyl ni hacer push a un repositorio a través de un conector. No es una línea del prompt que pueda convencerse de saltarse. Las llamadas se rechazan, y el agente lee:

changes are refused until your plan is approved: call propose_plan and wait for the review

Si nadie revisa el plan en una hora, la ejecución falla sin haber cambiado nada. Un perfil que pide revisión no se la salta porque no se haya presentado nadie.

Preguntas, cuando tiene que decidir una persona

Hay decisiones que el agente no debería tomar solo: un requisito ambiguo, una disyuntiva sin un ganador claro, algo destructivo. Para eso tiene ask_human. Sus instrucciones le dicen que nunca pregunte algo que pueda consultar, y tiene como máximo 5 preguntas por ejecución, así que no puede devolverte el trabajo pregunta a pregunta.

A mitad del paso 2, el agente encuentra una STAGING_DATABASE_URL en la configuración. Documentarla sería útil, salvo que staging requiere un acceso por VPN que las nuevas incorporaciones no reciben en su primera semana. Nada en el repositorio lo dice, así que pregunta.

La pregunta aparece encima del feed, con Respuestas sugeridas cuando el agente ofrece algunas ("Deja staging fuera", "Menciónalo, con una nota sobre el acceso por VPN"), y un cuadro para tu propia respuesta (Cmd/Ctrl + Enter la envía). Cualquiera que pueda editar el proyecto puede responder, y el feed registra quién lo hizo. El agente lee The human answered: Leave staging out y sigue adelante.

Una pregunta que nadie responde en una hora no hace fallar la ejecución. El agente continúa según su propio criterio e indica en su resultado la suposición que hizo. Es lo contrario que con el plan, y la diferencia está en lo que hay en juego: un plan sin revisar significa que no se acordó nada, mientras que una pregunta sin responder es una decisión más del tipo que el agente toma durante toda la ejecución.

Lo que cuesta esperar

Mientras el agente espera una revisión del plan o una respuesta, la ejecución muestra Esperándote, y la lista de ejecuciones la coloca en Te necesitan. Un aviso encima del feed indica qué está esperando, Esperando tu revisión del plan o El agente tiene una pregunta, y te lleva hasta ahí.

La espera no cuenta para el límite de tiempo de la ejecución. Su fecha límite se retrasa lo que dure la espera, así que una ejecución con un límite de 30 minutos que te esperó 20 minutos sigue teniendo 30 minutos de trabajo. Lo que sí conserva es su plaza de ejecución simultánea. Una ejecución en Pendiente de aprobación todavía no ha empezado, así que no retiene nada, pero una ejecución en espera está a mitad de conversación, con su espacio de trabajo abierto, lista para seguir en cuanto le llegue tu respuesta.

El diff, a medida que se escribe

La página de la ejecución tiene ahora dos vistas: Actividad, el feed de eventos, y Cambios. Cambios lista cada archivo que escribe el agente, en el momento en que lo escribe, con un estado (Añadido, Modificado o Bloqueado) y las líneas añadidas y eliminadas, por archivo y para toda la ejecución. Selecciona un archivo para ver qué cambió cada escritura (Edición 2 de 3), no solo el estado final.

El Guard, la comprobación de conformidad de cada escritura de archivo que ahora se ejecuta dentro del worker, aparece aquí también. Una escritura que rechazó aparece como Bloqueado: el diff muestra lo que el agente intentó escribir, con la regla que incumplió, aunque ese contenido nunca llegara al archivo. Una escritura que solo marcó sigue adelante, con un aviso en el archivo. Un rechazo que antes encontrabas en el resultado de una tool es ahora un diff que puedes leer.

Dos límites: los diffs largos se cortan a partir de 600 líneas, y los archivos de más de 128 KB aparecen sin diff.

Un comentario en la línea 12

Volvamos a go build ./.... No tienes que esperar a la pull request. En Cambios, haz clic en el número de línea, escribe el comentario y pulsa Enviar al agente (Cmd/Ctrl + Enter). En su siguiente paso, el agente lo recibe como un comentario de code review, con el archivo, la línea y su contenido:

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

Corrige la línea y vuelve a su paso. Bajo la línea, el comentario muestra En cola hasta que el agente lo recoge, y después Entregado. También aparece en Actividad, y cada archivo de la lista muestra cuántos comentarios tiene. La corrección, cuando llega, lo hace como la siguiente edición del archivo, así que el diff donde dejaste el comentario es también donde la compruebas.

Puedes comentar líneas añadidas, sin cambios y eliminadas. Un comentario en una línea eliminada le llega al agente como un comentario sobre "the lines you removed", que es como le dices que vuelva a poner una comprobación. Los comentarios se aceptan mientras el agente trabaja o te espera, y un agente en espera los lee cuando continúa. Un comentario que sigue En cola cuando termina la ejecución muestra No entregado. Las escrituras que bloqueó el Guard no admiten comentarios.

El cuadro de dirección sigue ahí, para reorientar al agente con texto libre sin cancelar la ejecución ("sáltate la migración, céntrate en el handler"). Un comentario de línea es el mismo mecanismo anclado a una línea. Lo que te ahorra es el preámbulo: "en docs/setup.md, donde escribiste go build" ya va en el mensaje.

La ejecución que no tenía nada que revisar

Mientras construía Cambios, le pedí a una ejecución que añadiera documentación a uno de nuestros repositorios Git, y vi cómo la vista se quedaba vacía. Ni archivos, ni diff, nada que comentar.

El proyecto no tenía ningún repositorio vinculado, así que Archyl no había clonado nada. Lo que sí tenía la ejecución era un conector de GitHub, y el agente hizo lo razonable con las tools que tenía delante: escribió los archivos directamente en GitHub con la tool push_files del conector. Nada pasó por un espacio de trabajo. Así que nada pasó por el Guard, nada apareció en Cambios, y el bucle de revisión que estaba construyendo no tenía nada que revisar.

Ahora el agente trabaja en un espacio de trabajo en ambos casos:

• Hay un repositorio vinculado al proyecto. Archyl lo clona cuando empieza la ejecución, como antes.
• No hay repositorio vinculado, pero hay un conector de GitHub adjunto. El propio agente clona el repositorio del que trata la tarea, llamando a open_repository con las credenciales del conector, antes de tocar ningún archivo. Esto solo funciona con el servidor MCP alojado de GitHub (api.githubcopilot.com), y el token necesita acceso al repositorio.

Una vez abierto un espacio de trabajo, las tools del conector que escriben en un repositorio (push_files, create_or_update_file, delete_file, create_pull_request) se rechazan, y el agente lee:

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

Esa regla es la que hace que cada cambio pase por el Guard, aparezca en Cambios y acabe en una única pull request.

Cuando termina la ejecución

Archyl hace commit de los cambios del espacio de trabajo en archyl/agent-<run id>, usando los ocho primeros caracteres del ID de la ejecución, y abre una pull request contra la rama de la que partió el clon. El enlace está en la parte superior de Cambios (Abrir pull request) y en el resultado. Cómo termina la ejecución decide qué se publica:

En GitLab, el borrador es una merge request Draft:. En Bitbucket, la rama se sube sin pull request. Una ejecución que no cambió ningún archivo no publica nada.

Tus comentarios se convierten en la siguiente ejecución

La revisión no se detiene cuando se detiene la ejecución. La pull request está abierta y estás leyendo el diff final en Cambios. Un comentario en una ejecución terminada no tiene ningún agente al que llegar, así que se convierte en una nota para la siguiente: Guardar para continuar lo conserva en tu navegador. Una barra encima de los archivos los cuenta (3 comentarios para una continuación) y ofrece Continuar con ellos.

Toda ejecución terminada, sea cual sea su resultado, ofrece dos botones. Volver a ejecutar abre el diálogo de inicio con la misma tarea y el mismo perfil, para una ejecución nueva desde cero: la opción correcta cuando el primer intento fue por un camino sobre el que no quieres construir. Continuar inicia una ejecución nueva que retoma el trabajo de esta, con las instrucciones rellenadas a partir de tus comentarios para continuar, si dejaste alguno, uno por línea:

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

Edítalos como quieras. El perfil es por defecto el de la ejecución, y puedes elegir conectores.

Misma rama, misma pull request

Una continuación es más que una ejecución nueva con un prompt más largo. Parte de la rama que publicó la ejecución anterior, hace commit en ella y añade sus cambios a la misma pull request en lugar de abrir otra. Si la ejecución anterior abrió su repositorio a través del conector de GitHub, la continuación lo vuelve a abrir en esa rama antes de que arranque el agente.

Al agente también se le dice sobre qué está construyendo. La tarea anterior, lo que hizo esa ejecución (el resumen de su resultado, o por qué se detuvo) y dónde está su trabajo van todos al principio de su prompt (los IDs, la URL y el resumen son ejemplos):

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

Los revisores ven crecer una pull request, no un reguero de ellas. El Copilot cloud agent de GitHub gestiona los seguimientos de la misma manera: mencionas a @copilot en un comentario de una pull request y, por defecto, hace push de commits a la rama de esa pull request (GitHub Docs). Una pull request por unidad de trabajo es la forma correcta, y las continuaciones la respetan.

Qué esperar en los casos límite:

• La rama ya no existe, por ejemplo porque se fusionó y se eliminó. La continuación parte de la rama por defecto y abre una nueva pull request, y una línea ámbar en el feed lo indica: "No se pudo obtener la rama archyl/agent-4f1c2a9e de la ejecución anterior. Esta ejecución parte de la rama por defecto y abrirá una nueva pull request."
• La pull request es un borrador. Sigue siéndolo. Márcala como lista para revisión cuando el trabajo esté terminado.
• Solo ramas de agentes. Archyl continúa en ramas que crearon sus agentes, las que están bajo archyl/, y nunca hace commit en una rama creada por una persona.

Las dos ejecuciones se enlazan entre sí: la nueva muestra Continúa la ejecución, la anterior Continuada en. Una ejecución todavía en curso no se puede continuar. Comenta sus líneas en su lugar.

La continuación también conserva su contexto de arquitectura. Su sesión de trabajo se abre para la tarea anterior más el seguimiento, no solo para el seguimiento, así que encuentra los mismos elementos de arquitectura y la misma memoria que la ejecución que continúa. Eso importa más de lo que parece. "Indica que make seed necesita el container de la base de datos en marcha" no nombra ningún servicio, y una sesión abierta solo con esa línea tendría poco con lo que relacionarse.

Lo que no hace

El worker no tiene shell. Lee, escribe, edita, lista y busca archivos, pero no puede compilar el proyecto ni ejecutar los tests. En este ejemplo puede leer el Makefile, pero no ejecutar make build para comprobar que el documento es correcto. Un diff limpio no es un build que pasa, y de eso se sigue encargando la CI.

Un comentario de línea es una indicación, no un gate. No hay estado de resuelto, y nada comprueba que el agente haya atendido un comentario. Ves su siguiente edición en el diff, y la juzgas tú.

Las notas para continuar viven en un solo navegador. Hasta que continúas la ejecución, tus compañeros no ven los comentarios que guardaste para continuar. Los comentarios enviados a un agente en marcha son distintos: están en el feed, a la vista de todos.

La revisión del plan da por hecho que hay alguien. Es un ajuste por perfil, desactivado por defecto, y todas las ejecuciones de ese perfil lo respetan, incluidas las programadas. Una ejecución a las 3 de la madrugada en un perfil con la revisión activada espera una hora y luego falla sin cambiar nada. Las preguntas también esperan una hora, y después el agente decide solo.

El clon a través de conector solo funciona con GitHub. open_repository funciona con el servidor MCP alojado de GitHub. Para cualquier otro host, vincula el repositorio al proyecto.

Por dónde empezar

Elige una tarea pequeña que revisarías de todas formas y ejecútala en un perfil con Revisar el plan primero activado. Deja la página de la ejecución abierta. Edita el plan antes de aprobarlo, aunque lo único que hagas sea quitar el paso que no habrías pedido. En Cambios, comenta la primera línea que habrías señalado en la pull request y mira cómo pasa de En cola a Entregado. Cuando termine la ejecución, deja el resto como comentarios para continuar y pulsa Continuar.

Deja la revisión del plan desactivada en los perfiles que usan tus programaciones, a menos que alguien vaya a estar despierto para revisar.

Los planes, las preguntas, el diff en directo, los comentarios de línea y las continuaciones forman parte de las ejecuciones de agentes gestionadas de Archyl. Todos los ajustes y etiquetas mencionados están en la documentación de las ejecuciones de agentes gestionadas. Lecturas relacionadas: los agentes gestionados ahora responden ante el Harness, sobre el Guard y las sesiones de trabajo en los que se apoya todo esto, y el lanzamiento de las ejecuciones de agentes gestionadas.