Paperclip: cómo organizar un equipo de agentes de IA
Arquitectura de Paperclip: de tarea a heartbeat y resultado
Seguir la ruta de control que convierte una petición del panel en trabajo de un agente.
Qué aprenderás
- El panel expresa la intención
- El runtime ejecuta
- La gobernanza cierra el ciclo
Antes de empezar
- Fundamentos de Node.js y agentes
- Una empresa de prueba sin datos sensibles
Pasar de la lectura del código a un ensayo con límites y condición de salida.
Conclusiones clave
- Un heartbeat es un evento del plano de control.
- Ejecución terminada no significa trabajo aceptado.
- Los IDs permiten auditar la cadena.
El panel expresa la intención
Objetivos y tareas dicen qué hacer; los cargos indican quién responde por ello. El README describe disparadores programados y por eventos que ponen despertares en cola. Conserva el ID de la tarea en cada ejecución.
Antes de invocar el adaptador, el heartbeat debería encontrar una tarea elegible. Si dos agentes toman la misma, examina asignación y planificación, no solo la respuesta final del modelo.
El runtime ejecuta
La ruta documentada comprueba presupuesto, resuelve un directorio de trabajo, inyecta secretos acotados e invoca un adaptador. Logs, costes y estado de sesión permiten reconstruir lo sucedido.
Puede fallar por ausencia de tareas, ruta errónea, credencial ausente o error del adaptador. Una ejecución terminada técnicamente puede carecer de trabajo útil.
La gobernanza cierra el ciclo
Aprobaciones, comentarios y eventos de auditoría permiten revisar una salida antes de actuar otra vez. Un límite presupuestario puede pausar el trabajo; no decide si el borrador es correcto.
El diagrama interpreta el README y los servicios examinados. No representa una traza distribuida obtenida de un despliegue activo.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Elegir una tarea y señalar su responsable.
- 2
Seguir cola, adaptador y coste en registros locales.
- 3
Vincular salida y aprobación con la tarea inicial.
Ejemplo para copiar
issue -> wakeup queue -> budget/workspace checks -> adapter run
run -> logs + cost event -> review/approvalPreguntas frecuentes
¿Dónde corre el modelo?
En el entorno del agente conectado mediante el adaptador; Paperclip coordina.
¿Cada heartbeat inicia trabajo nuevo?
Puede no encontrar tareas o quedar detenido por una política.
Fuentes
- Paperclip / README.mdFuente verificada 2026-09-26
- Paperclip / server/src/services/approvals.tsFuente verificada 2026-09-26
- Paperclip / server/src/services/budgets.tsFuente verificada 2026-09-26