Mensajes de sistema a mitad de conversación

Las instrucciones de sistema normalmente residen en el campo system de nivel superior, antes de todos los mensajes de la conversación. Esa posición es excelente para el prompt caching (almacenamiento en caché de prompts): la indicación del sistema forma parte del prefijo estable, por lo que los turnos posteriores aprovechan la caché. Es una mala posición para instrucciones que solo descubres que necesitas a mitad de una sesión, porque editar el campo system de nivel superior cambia el inicio mismo del prompt e invalida la caché para todo lo que sigue.

Los mensajes de sistema a mitad de conversación cierran esa brecha. Agregas un mensaje {"role": "system"} en el punto de la conversación donde la nueva instrucción se vuelve relevante, en lugar de editar el campo system de nivel superior. El prefijo almacenado en caché permanece igual, por lo que la siguiente solicitud aún lo lee desde la caché, y la nueva instrucción se sigue aplicando como una instrucción de sistema en lugar de como texto ordinario del usuario.

Cuándo usar un mensaje de sistema a mitad de conversación

El almacenamiento en caché de prompts calcula el hash del prefijo de la solicitud en orden: tools, luego system, luego messages. Un acierto de caché requiere que el prefijo coincida exactamente con una solicitud reciente, byte por byte, hasta el punto de interrupción de la caché.

Ese orden significa que el campo system de nivel superior se encuentra muy cerca del inicio del prefijo hasheado. Cualquier cambio en él, incluso agregar una oración, produce un hash diferente, y la solicitud no encuentra la caché para la indicación del sistema ni para ningún mensaje almacenado en caché después de ella.

Los mensajes de sistema a mitad de conversación te permiten agregar la instrucción al final del historial de mensajes. Todo lo que está antes de la nueva instrucción permanece sin cambios, por lo que la entrada de caché existente sigue coincidiendo, y solo el nuevo mensaje se procesa como entrada nueva.

Algunas situaciones en las que esto importa:

• Cambios de política o persona a mitad de sesión. Una sesión agéntica larga necesita una nueva restricción ("de ahora en adelante, escribe todo el SQL como consultas parametrizadas") después de docenas de turnos almacenados en caché. Agregarla al campo system de nivel superior volvería a procesar todo el historial.
• Contexto por turno que debe ser autoritativo. Quieres inyectar una nota de actualidad, una fecha límite de sesión o un cambio de disponibilidad de herramientas con peso de nivel de sistema, y cambia con demasiada frecuencia como para residir en el prefijo almacenado en caché.
• Cambios de estado que tu aplicación observa. Tu aplicación detecta algo que Claude debería tratar como un hecho de nivel de operador: archivos cambiaron en disco, el usuario activó o desactivó una configuración de aprobación automática, las herramientas disponibles cambiaron, o el presupuesto de tokens restante cayó por debajo de un umbral.
• Entrada del usuario que no debería interrumpir un bucle agéntico. Un usuario escribe un seguimiento mientras Claude todavía está ejecutando herramientas para la solicitud anterior. Transmitirlo como un mensaje de sistema después del siguiente resultado de herramienta permite que Claude incorpore la nueva entrada al trabajo que ya está realizando, en lugar de tratarla como una solicitud nueva a la que cambiar. Consulta Ubicación después de los resultados de herramientas más abajo.
• Cambios de modo que otorgan permisos permanentes. Un modo a nivel de sesión puede usar un mensaje de sistema a mitad de conversación para otorgar consentimiento permanente a una capacidad costosa, como lanzar automáticamente flujos de trabajo multiagente, con un breve recordatorio cada varios turnos y un aviso de salida cuando el modo se desactiva. Para ver un ejemplo desarrollado, consulta .

En todos estos casos podrías poner la instrucción en un mensaje user normal, y Claude sí sigue las instrucciones que llegan en turnos de usuario. La diferencia es la prioridad: un mensaje user se trata como proveniente del usuario final, mientras que un mensaje system se trata como proveniente de ti, el operador de la aplicación. Cuando ambos entran en conflicto, las instrucciones de sistema tienen precedencia, así que usa el rol system para hechos y restricciones de nivel de operador que deben mantenerse incluso si el usuario final pide algo diferente. Un mensaje de sistema a mitad de conversación mantiene esa prioridad de nivel de operador sin pagar el costo de fallo de caché que implica editar el campo system de nivel superior.

Cómo funciona

Agrega un mensaje con "role": "system" al array messages. Usa una cadena simple o bloques de contenido para content, igual que en un turno user o assistant. La instrucción se aplica desde ese punto de la conversación en adelante. Cuando las instrucciones entran en conflicto, los mensajes de sistema posteriores tienen precedencia sobre los anteriores, y los mensajes de sistema a mitad de conversación tienen precedencia sobre el campo system de nivel superior para los turnos que los siguen.

Aún puedes establecer el campo system de nivel superior para instrucciones que deben aplicarse a toda la conversación. Reserva los mensajes de sistema a mitad de conversación para instrucciones que solo se vuelven relevantes más adelante, o que quieres agregar sin invalidar el prefijo almacenado en caché.

Este ejemplo habilita el almacenamiento en caché automático con el campo cache_control de nivel superior. El almacenamiento en caché de prompts es opcional: si una solicitud no tiene ningún campo cache_control (automático o un punto de interrupción explícito), nada se almacena en caché y cada solicitud paga el precio regular de tokens de entrada por la conversación completa. Con el almacenamiento en caché habilitado, agregar el mensaje de sistema deja los turnos ya almacenados en caché sin cambios, por lo que la solicitud que lleva la nueva instrucción aún los lee desde la caché en lugar de procesarlos de nuevo. El almacenamiento en caché también requiere que la conversación cumpla con la longitud mínima de prompt almacenable en caché; un ejemplo tan corto como este queda por debajo de ella, por lo que cache_creation_input_tokens y cache_read_input_tokens permanecen en 0 hasta que la conversación crezca.

Un mensaje de sistema a mitad de conversación debe seguir inmediatamente a un turno user (o a un turno assistant que termine en un uso de herramientas de servidor), y debe ser la última entrada en messages o estar seguido inmediatamente por un turno assistant. Un mensaje user que lleva bloques tool_result cuenta: en un bucle agéntico puedes colocar el mensaje de sistema justo después de los resultados de herramientas, antes del siguiente turno de Claude. La única posición que no está permitida es entre un bloque tool_use de assistant y el tool_result que le responde.

Ubicación después de los resultados de herramientas

En un bucle agéntico, el mensaje de sistema va después del mensaje user que entrega los resultados de herramientas. Aquí es también donde tu aplicación puede transmitir la entrada que el usuario escribió mientras Claude estaba trabajando, de modo que el nuevo contexto se absorba sin reiniciar el turno:

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

Redacta el contenido del sistema como contexto en lugar de como un comando que anula al usuario. Indica el hecho ("llegó nueva entrada del usuario: X", "el presupuesto de tokens restante es ahora Y") y deja que Claude actúe en consecuencia. Claude está entrenado para resistir instrucciones que parecen ir en contra del usuario, y esa protección también se aplica al rol de sistema, por lo que un lenguaje como "ignora lo que dijo el usuario" es menos efectivo que indicar qué cambió.

Este patrón es para transmitir entrada del propio usuario final de la conversación. No lo uses para pasar salida de herramientas, documentos recuperados u otro contenido de terceros; mantén ese contenido en bloques tool_result (consulta Limitaciones).

Combinación con el almacenamiento en caché de prompts

Los mensajes de sistema a mitad de conversación y el almacenamiento en caché de prompts están diseñados para usarse juntos:

• Habilita el almacenamiento en caché explícitamente. El almacenamiento en caché solo ocurre cuando la solicitud incluye cache_control, ya sea el campo de almacenamiento en caché automático de nivel superior o un punto de interrupción explícito en un bloque de contenido. Un mensaje de sistema a mitad de conversación no crea una entrada de caché por sí solo, y sin el almacenamiento en caché habilitado no hay ahorros que preservar.
• Almacena en caché el prefijo estable como de costumbre. Coloca cache_control en el último bloque que permanece igual entre solicitudes, ya sea el final del campo system de nivel superior, el final de tus definiciones de herramientas o un punto estable en el historial de mensajes.
• Agrega el mensaje de sistema después del punto de interrupción. Como viene después del prefijo almacenado en caché, no cambia el hash del prefijo y la caché sigue acertando.
• Un mensaje de sistema a mitad de conversación es en sí mismo almacenable en caché. Una vez que está en la conversación, se convierte en parte del historial estable. En el siguiente turno puedes mover tu punto de interrupción de caché más allá de él (o confiar en el almacenamiento en caché automático para hacerlo) y el mensaje de sistema se lee desde la caché como cualquier otro turno.

Evita editar o eliminar un mensaje de sistema a mitad de conversación que ya se haya enviado. Como cualquier otro cambio a mensajes anteriores, eso invalida la caché desde ese punto en adelante. Si la instrucción necesita evolucionar, agrega un nuevo mensaje de sistema en lugar de reescribir el anterior. No se permiten mensajes de sistema consecutivos; combina las instrucciones en un solo mensaje o espera al siguiente turno de usuario antes de agregar otro.

Limitaciones

• No para el primer mensaje. Un mensaje system no puede ser la primera entrada en messages. Usa el campo system de nivel superior para instrucciones que se aplican desde el principio.
• La ubicación está restringida. Un mensaje system debe seguir inmediatamente a un turno user (incluido un turno user que lleva bloques tool_result) o a un turno assistant que termine en uso de herramientas de servidor, y debe preceder a un turno assistant o finalizar el array. No puede ubicarse entre un bloque tool_use y su tool_result. Colocarlo en otro lugar devuelve un error 400.
• No es un lugar para contenido no confiable. Claude trata el contenido de sistema como instrucciones del operador y las sigue. No coloques texto de fuera de la conversación, como salida sin procesar de herramientas, documentos recuperados o contenido web, directamente en un mensaje de sistema; hacerlo le da a ese texto autoridad de nivel de operador. Mantén esos datos en bloques tool_result y continúa siguiendo .

Relacionado