Descripción del bucle del agente

Arquitectura

** SDK de Copilot ** es una capa de transporte: envía el mensaje a CLI de Copilot través de JSON-RPC y expone eventos de vuelta a la aplicación. La CLI es el orquestador que ejecuta el bucle de uso de herramientas por parte del agente, realizando una o varias llamadas a la API de LLM hasta que se completa la tarea.

Bucle de uso de herramientas

Cuando se llama a session.send({ prompt }), CLI de Copilot entra en un bucle:

El modelo ve el historial de conversaciones completo en cada llamada: aviso del sistema, mensaje de usuario y todas las llamadas y resultados de las herramientas anteriores.

Cada iteración de este bucle es exactamente una llamada API de LLM, visible como un assistant.turn_start / assistant.turn_end par en el registro de eventos. No hay llamadas ocultas.

Turnos

Un turno es una sola llamada API de LLM y sus consecuencias:

1. CLI de Copilot envía el historial de conversaciones al LLM
2. El LLM responde (posiblemente con peticiones de herramientas)
3. Si se solicitaron herramientas, CLI de Copilot las ejecuta
4. assistant.turn_end se emite

Un único mensaje de usuario suele dar lugar a varios turnos. Por ejemplo, una pregunta como "¿cómo funciona X en este código base?" puede producir:

Girar	Qué hace el modelo	toolRequests?
1	Llama a grep y a glob para buscar en la base de código	Sí
2	Lee archivos específicos en función de los resultados de la búsqueda.	Sí
3	Lee más archivos para un contexto más profundo.	Sí
4	Genera la respuesta de texto final.	No (termina el bucle)

El modelo decide cada turno si desea solicitar más herramientas o generar una respuesta final. Cada llamada ve el contexto acumulado completo (todas las llamadas a herramientas y resultados anteriores), por lo que puede tomar una decisión informada sobre si tiene suficiente información.

Flujo de eventos para una interacción de varios turnos

Quién desencadena cada turno

Actor	Responsabilidad
La aplicación	Envía el mensaje inicial a través de session.send()
CLI de Copilot	Ejecuta el bucle de uso de herramientas: ejecuta las herramientas y devuelve los resultados al LLM para el siguiente turno.
LLM	Decide si solicitar herramientas (seguir en bucle) o generar una respuesta final (detenerse)
SDK de Copilot	Deja pasar los eventos; no controla el bucle

CLI de Copilot es puramente mecánico: "el modelo solicita herramientas → ejecutar → volver a llamar al modelo". El modelo es quien decide cuándo detenerse.

session.idle frente a session.task_complete

Son dos señales de finalización diferentes con garantías muy diferentes.

session.idle

• Siempre se emite cuando finaliza el bucle de uso de herramientas
• Efímero: no se conserva en el disco, no se reproduce en el reanudación de la sesión
• Significa: "el agente ha detenido el procesamiento y está listo para el siguiente mensaje"

•           **Use esto** como una señal fiable de "finalizado"
  

El método sendAndWait() de SDK de Copilot espera este evento:

// Blocks until session.idle fires
const response = await session.sendAndWait({ prompt: "Fix the bug" });

session.task_complete

• Opcionalmente emitido: requiere que el modelo lo indique explícitamente.

•           **Persistente**: guardado en el registro de eventos de sesión en el disco
  

• Significa: "el agente considera que se ha cumplido la tarea general"
• Lleva un campo opcional summary

session.on("session.task_complete", (event) => {
    console.log("Task done:", event.data.summary);
});

Modo Autopilot

En el modo Autopilot (operación sin cabeza o autónoma), CLI de Copilot realiza un seguimiento activo de si el modelo ha llamado a task_complete. Si el bucle de uso de herramientas finaliza sin lograrlo, CLI de Copilot inserta un mensaje de usuario sintético para instar al modelo a seguir trabajando.

Esto crea un mecanismo de finalización de dos niveles en Autopilot:

1. El modelo llama a task_complete con un resumen → CLI de Copilot emite session.task_complete → hecho
2. El modelo se detiene sin llamarlo → CLI de Copilot lo impulsa → el modelo continúa o llama a task_complete

¿Por qué task_complete podría no aparecer?

En modo interactivo (chat normal), CLI de Copilot no envía recordatorios para task_complete. El modelo puede omitirlo por completo. Motivos comunes:

• Preguntas y respuestas conversacionales: el modelo responde a una pregunta y simplemente se detiene, no hay ninguna "tarea" discreta para completarse.
• Discreción del modelo: el modelo genera una respuesta de texto final sin llamar a la señal de tarea completa.
• Sesiones interrumpidas: la sesión finaliza antes de que el modelo alcance un punto de finalización.

CLI de Copilot emite session.idle de todos modos, porque es una señal mecánica (el bucle ha terminado) y no semántica (el modelo cree que ya ha terminado).

Qué señal se va a usar

Caso de uso	Señal
Espere a que el agente finalice el procesamiento	session.idle
Saber cuándo se realiza una tarea de codificación	session.task_complete (mejor opción)
Tiempo de espera y control de errores	session.idle + session.error

Recuento de llamadas de LLM

El número de pares del registro de eventos es igual al número total de assistant.turn_start / assistant.turn_end llamadas API de LLM realizadas. No hay llamadas ocultas para la planificación, evaluación o comprobación de finalización.

Lectura adicional

• Streaming de eventos en el SDK de Copilot
• Persistencia de sesión en el SDK de Copilot
• Trabajar con enlaces