turn_context y composición del prompt

源码版本v2026.7.20

Responsabilidad

Antes de cada llamada a la API, ensambla «historial + entrada del usuario de este turno + contexto adicional del gateway + marcas de compresión» en los api_messages que se envían al provider. TurnContext es el contenedor del producto de este turno; build_turn_context es la entrada de ensamblaje. También inyecta las notas que el gateway recogió dentro del contenido multimodal.

Archivos clave

• class TurnContext:242-268 — dataclass del contexto del turno
• def build_turn_context:268-400 — entrada de ensamblaje
• compose_user_api_content:44-79 — composición del contenido del mensaje de usuario
• substitute_api_content:79-101 — sustitución de placeholders
• consume_gateway_turn_context_notes:124-164 — consume notas añadidas por el gateway y las inyecta en contenido multimodal
• reanchor_current_turn_user_idx:164-210 — recoloca el índice del mensaje de usuario del turno (corrección tras compresión)
• estimación de progreso de compresión:190-242 — _compression_made_progress / _should_run_preflight_estimate
• prompt_builder — composición del system prompt (referenciado en esta página)

Flujo de datos

1. El bucle principal llama cada turno a build_turn_context:268, obteniendo un TurnContext.
2. compose_user_api_content (agent/turn_context.py:44) ensambla la entrada cruda del usuario en contenido de API.
3. Si el gateway ha acumulado notas (de adjuntos, indicaciones de contexto), consume_gateway_turn_context_notes (agent/turn_context.py:124) las extrae e inyecta vía append_notes_to_multimodal_content.
4. substitute_api_content (agent/turn_context.py:79) sustituye placeholders; drop_stale_api_content limpia contenido caducado.
5. Si el turno anterior sufrió compresión, reanchor_current_turn_user_idx (agent/turn_context.py:164) corrige la posición del mensaje de usuario actual en el historial.
6. Los api_messages ensamblados entran al subbucle de reintentos de API:1227.

Resumen

turn_context es la «fábrica de instantáneas por turno»: solidifica el contexto dinámico en una estructura enviable. Coordina con la compresión de contexto: tras reescribir el historial, turn_context recoloca los punteros para que vuelvan a apuntar correctamente.