Mensajes del sistema y cambios de herramientas a mitad de conversación

Las instrucciones del sistema normalmente viven en el campo system de nivel superior, antes de cada mensaje 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 aciertan en 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 comienzo mismo del prompt e invalida la caché para todo lo que sigue.

Los mensajes del 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 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 del sistema en lugar de como texto de usuario ordinario.

Cambios de herramientas a mitad de conversación

El arreglo tools se ubica incluso antes que el campo system de nivel superior en el prefijo de solicitud con hash, por lo que editarlo invalida la caché de prompts para toda la conversación. Los cambios de herramientas a mitad de conversación son la contraparte, para herramientas, de los mensajes del sistema a mitad de conversación. En lugar de fijar la lista de herramientas durante toda la vida de la conversación, cambias qué herramientas se ofrecen al modelo entre turnos: declara el conjunto completo de herramientas en tools desde el principio y luego usa bloques tool_addition y tool_removal para ofrecer una herramienta al modelo, o retirarla, desde un punto específico de la conversación en adelante. El arreglo tools en sí nunca cambia, por lo que el prefijo en caché permanece intacto.

tool_addition y tool_removal son bloques de contenido en el arreglo content de un mensaje role: "system", y pueden mezclarse con bloques text en el mismo mensaje. El mensaje sigue las mismas reglas de ubicación que cualquier mensaje del sistema a mitad de conversación (consulta Limitaciones), y el cambio se aplica desde ese punto de la conversación en adelante. El campo tool de cada bloque hace referencia a una herramienta en lugar de definirla: {"type": "tool_reference", "name": "..."} nombra una herramienta declarada en el arreglo tools de la solicitud, y las herramientas del conector MCP pueden referenciarse individualmente con mcp_tool_reference (server_name y name) o como un conjunto de herramientas completo con mcp_toolset_reference (server_name). Hacer referencia a un nombre que no está declarado en tools devuelve un error 400.

Cada herramienta declarada en tools se ofrece al modelo desde el inicio de la conversación, a menos que se declare con defer_loading: true, lo que la mantiene retenida hasta que un bloque tool_addition la haga visible. tool_addition también vuelve a ofrecer una herramienta que un tool_removal anterior retiró.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # El conjunto completo de herramientas se declara al inicio y nunca cambia, así que el
    # prefijo en caché permanece intacto.
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # Retira get_weather a partir de este punto. El bloque hace referencia
        # a la herramienta por nombre en lugar de editar `tools`, así los turnos anteriores quedan
        # idénticos byte a byte y la caché sigue acertando.
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Los cambios de herramientas a mitad de conversación están en beta. Para usarlos, incluye el encabezado beta mid-conversation-tool-changes-2026-07-01 en tus solicitudes.

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

El almacenamiento en caché de prompts aplica hash al 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 caché.

Ese orden significa que el campo system de nivel superior se ubica muy cerca del inicio del prefijo con hash. Cualquier cambio en él, incluso agregar una oración, produce un hash diferente, y la solicitud falla en la caché para la indicación del sistema y cada mensaje en caché posterior.

Los mensajes del sistema a mitad de conversación te permiten agregar la instrucción al final del historial de mensajes en su lugar. Todo lo anterior a la nueva instrucción permanece sin cambios, por lo que la entrada de caché existente aún coincide, y solo el nuevo mensaje se procesa como entrada nueva.

Algunas situaciones en las que esto importa:

• Cambios de política o de 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 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 para vivir en el prefijo en caché.
• Recordatorios por turno que no deberían acumularse. Un arnés da un empujón al modelo después de cada lote de resultados de herramientas ("solicita las lecturas independientes juntas", "el usuario no ha sabido de ti en un rato") y quiere que el modelo vea solo la copia más reciente. Un mensaje del sistema con alcance de turno se renderiza durante un turno y luego no cuesta nada, sin eliminar nada del historial.
• Cambios de estado que tu aplicación observa. Tu aplicación nota algo que Claude debería tratar como un hecho de nivel de operador: archivos que 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 del sistema después del siguiente resultado de herramienta permite que Claude incorpore la nueva entrada al trabajo que ya está haciendo, en lugar de tratarla como una solicitud nueva a la que cambiar. Consulta Ubicación después de los resultados de herramientas.
• Cambios de modo que otorgan permisos permanentes. Un modo de nivel de sesión puede usar un mensaje del 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 un ejemplo desarrollado, consulta Construir un modo de orquestación.

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 del 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 del sistema a mitad de conversación conserva esa prioridad de nivel de operador sin pagar el costo de fallo de caché de editar el campo system de nivel superior.

Cómo funciona

Agrega un mensaje con "role": "system" al arreglo 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 del sistema posteriores tienen precedencia sobre los anteriores, y los mensajes del sistema a mitad de conversación tienen precedencia sobre el campo system de nivel superior para los turnos que les siguen.

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

Un mensaje role: "system" también puede llevar output_config.effort para cambiar el nivel de esfuerzo a partir del siguiente turno user. Esto está en beta en Claude Fable 5.1, Claude Mythos 5.1 y Claude Opus 5 en la Claude API y requiere el encabezado beta mid-conversation-output-config-2026-07-01. Consulta Esfuerzo por mensaje.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Almacenamiento en caché de prompts automático: cada solicitud guarda en caché la conversación hasta ahora,
    # y la siguiente solicitud lee desde la caché el prefijo sin cambios.
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # El revisor se da cuenta a mitad de sesión de que todas las sugerencias deben
        # cumplir también la política de tipado estricto del equipo. Agregar la
        # instrucción aquí mantiene los turnos anteriores idénticos byte a byte, así que el
        # prefijo almacenado en caché por la solicitud anterior aún se lee desde la caché.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

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 un campo cache_control (automático o un punto de interrupción explícito), no se almacena nada 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 del sistema deja sin cambios los turnos ya almacenados en caché, 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 del sistema a mitad de conversación debe seguir inmediatamente a un turno user (o a un turno assistant que termine en un resultado de herramienta 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 del sistema justo después de los resultados de herramientas, antes del siguiente turno de Claude. Cualquier otra posición, incluso entre un bloque tool_use de assistant y el tool_result que lo responde, devuelve un error 400.

Ubicación después de los resultados de herramientas

En un bucle agéntico, el mensaje del sistema va después del mensaje user que entrega los resultados de herramientas. Aquí también es 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 una orden que anula al usuario. Enuncia el hecho ("llegó nueva entrada del usuario: X", "el presupuesto de tokens restante ahora es 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 sigue aplicándose al rol del sistema, por lo que un lenguaje como "ignora lo que dijo el usuario" es menos efectivo que enunciar 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).

Mensajes del sistema con alcance de turno

Para limitar un mensaje role: "system" al turno actual, establece su campo clear_at. Toma uno de dos valores:

• "never" (el valor predeterminado): el mensaje se renderiza en su posición en cada solicitud que lo incluye. Omitir el campo es idéntico.
• "next_user_message": el mensaje tiene alcance de turno. Su texto se renderiza solo mientras ningún mensaje role: "user" venga después de él en messages. Un mensaje de usuario que lleva solo bloques tool_result cuenta como mensaje de usuario aquí. Una vez que existe un mensaje de usuario posterior, el mensaje queda borrado: permanece en el arreglo pero no renderiza nada y no cuesta tokens de entrada, en esa solicitud y en todas las posteriores.

Los mensajes del sistema con alcance de turno están en beta. Incluye el encabezado beta mid-conversation-system-clear-at-2026-08-21. Sin él, clear_at se rechaza como un campo desconocido.

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "First privately list what you need next; then request every item that doesn't depend on another's result in this one response."
}

El uso principal es un recordatorio por turno en un bucle de herramientas. Agrega el recordatorio después del mensaje tool_result cada vez que quieras que el modelo lo vea, y deja cada copia anterior donde está. El modelo ve solo las copias que vienen después del último mensaje de usuario, por lo que el recordatorio nunca se acumula. Nada anterior en messages cambia, por lo que la caché de prompts sigue coincidiendo. En Claude Fable 5.1 esto también mantiene válidos los bloques de pensamiento posteriores: eliminar un recordatorio anterior cambiaría la conversación antes de esos bloques y fallaría la verificación de conversación, mientras que un mensaje borrado permanece en el arreglo y deja esa conversación sin cambios.

La siguiente solicitud es un paso posterior de un bucle de agente. messages[3] se renderizó en la solicitud anterior, cuando era el último mensaje del arreglo. Una vez que existe messages[5] (un mensaje de usuario posterior), messages[3] queda borrado: el mensaje borrado permanece en el arreglo, por lo que la conversación antes del bloque de pensamiento en messages[4] no cambia, pero el modelo ya no ve su texto. messages[6] y messages[7] se renderizan ambos, en orden.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "Fix the failing test." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "read_file",
          "input": { "path": "test_auth.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "", "signature": "..." },
        {
          "type": "tool_use",
          "id": "toolu_02",
          "name": "read_file",
          "input": { "path": "auth.py" }
        },
        {
          "type": "tool_use",
          "id": "toolu_03",
          "name": "read_file",
          "input": { "path": "tokens.py" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." },
        {
          "type": "tool_result",
          "tool_use_id": "toolu_03",
          "content": "...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "Request independent reads in one turn."
    },
    {
      "role": "system",
      "clear_at": "next_user_message",
      "content": "The shell exited with status 137."
    }
  ]
}

Reglas para los mensajes con alcance de turno:

• Reenvía los mensajes borrados textualmente. Un mensaje borrado sigue siendo parte del historial de la conversación. Reconstruirlo a partir del estado actual (un conteo de tokens nuevo, una marca de tiempo), descartarlo como redundante o cambiar su valor clear_at es una edición de un mensaje anterior. La caché de prompts falla desde ese punto, y en Claude Fable 5.1 cada bloque de pensamiento producido después de él falla la verificación de conversación.
• Solo texto. content es uno o más bloques text (o una cadena). Los bloques tool_addition y tool_removal devuelven un error 400 en un mensaje con alcance de turno, y lo mismo ocurre con output_config. Usa un mensaje role: "system" separado sin clear_at para esos.
• Sin cache_control en sus bloques. Un mensaje borrado nunca forma parte de una clave de caché, por lo que un punto de interrupción en él nunca podría coincidir. Coloca el punto de interrupción en el último bloque del turno de usuario precedente en su lugar, como hace el ejemplo. El campo de almacenamiento en caché automático de nivel superior omite los mensajes con alcance de turno cuando elige un punto de interrupción. En la solicitud que borra un mensaje, el prefijo en caché reutilizable termina en el turno de usuario anterior a él, por lo que solo se reprocesa el único turno de asistente entre ese mensaje y el nuevo mensaje de usuario.
• Las reglas de ubicación siguen aplicándose, borrado o no. Un mensaje con alcance de turno debe seguir a un turno user (o a un turno assistant que termine en un resultado de herramienta de servidor) y preceder a un turno assistant o terminar el arreglo, como cualquier mensaje del sistema a mitad de conversación. Uno que termina el arreglo siempre se renderiza. Uno seguido directamente por otro mensaje user es un error 400, no un mensaje borrado: coloca todos los resultados de una ronda de herramientas en un solo mensaje de usuario y los recordatorios después de él.
• Los turnos de asistente no lo borran. Un turno de asistente prellenado o pausado después del mensaje, o un bucle de herramientas del lado del servidor, no agrega ningún mensaje de usuario, por lo que el mensaje aún se renderiza en esa continuación. Para mantener un recordatorio a la vista a lo largo de un bucle de herramientas del lado del cliente, agrégalo de nuevo después de cada mensaje tool_result.
• El conteo de tokens sigue lo que se renderiza. Un mensaje borrado no agrega nada a usage.input_tokens ni a un conteo de tokens.
• Historial importado. En una transcripción que construyes en un solo paso (ejemplos few-shot, una conversación migrada), un mensaje con alcance de turno que ya tiene un turno de asistente y un mensaje de usuario después de él queda borrado desde la primera solicitud y nunca se renderiza. Ese es el estado correcto para un recordatorio por turno que estás trasladando. Deja clear_at sin establecer solo en un mensaje que el modelo deba ver en cada solicitud.

Los errores de validación son:

messages.3.clear_at: Extra inputs are not permitted
messages.3.clear_at: clear_at is only permitted on role 'system' messages
messages.3.clear_at: Input should be 'next_user_message' or 'never'
messages.3: a turn-scoped system message supports text blocks only (clear_at: 'next_user_message')
messages.3: output_config is not permitted on a turn-scoped system message (clear_at: 'next_user_message')
messages.3.content.0: cache_control is not permitted on a turn-scoped system message (clear_at: 'next_user_message')

El primero es el error que se devuelve sin el encabezado beta. En Amazon Bedrock y Google Cloud, pasa el valor beta como se describe en Encabezados beta.

A través de los SDK, establece clear_at en la entrada role: "system" de messages y envía el encabezado beta. El siguiente ejemplo agrega un recordatorio con alcance de turno después del turno de usuario; en la siguiente solicitud, una vez que existe un mensaje de usuario posterior, el recordatorio permanece en el arreglo pero ya no se renderiza:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a short status update on the database migration for the team channel.",
        },
        # Recordatorio de alcance por turno: se muestra en este turno y luego se borra cuando existe un mensaje de usuario posterior.
        {
            "role": "system",
            "clear_at": "next_user_message",
            "content": "The reader is on call: keep this reply under 50 words.",
        },
    ],
    betas=["mid-conversation-system-clear-at-2026-08-21"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Combinación con el almacenamiento en caché de prompts

Los mensajes del 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 del sistema a mitad de conversación no crea una entrada de caché por sí mismo, 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 del sistema después del punto de interrupción. Como viene después del prefijo en caché, no cambia el hash del prefijo y la caché sigue acertando.
• Un mensaje del 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 del sistema se lee desde la caché como cualquier otro turno.

Evita editar o eliminar un mensaje del sistema a mitad de conversación que ya se haya enviado. Como cualquier otro cambio en mensajes anteriores, eso invalida la caché desde ese punto en adelante. En Claude Fable 5.1 también invalida los bloques de pensamiento en cada turno de asistente posterior. Para orientación que debe aplicarse a un solo turno, usa un mensaje del sistema con alcance de turno y déjalo en su lugar. Si la instrucción necesita evolucionar, agrega un nuevo mensaje del sistema en lugar de reescribir el anterior. Los mensajes del sistema consecutivos se aceptan y se tratan como una sola sección del sistema, que sigue la misma regla de ubicación en su conjunto.

Limitaciones

• No para el primer mensaje. Un mensaje system que lleva contenido 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 que lleva contenido (bloques text, tool_addition o tool_removal) debe seguir inmediatamente a un turno user (incluido un turno user que lleva bloques tool_result) o a un turno assistant que termine en un resultado de herramienta de servidor, y debe preceder a un turno assistant o terminar el arreglo. No puede ubicarse entre un bloque tool_use y su tool_result. Colocarlo en otro lugar devuelve un error 400. Un mensaje con content vacío que solo establece output_config.effort no renderiza nada en su posición y se acepta en cualquier lugar de messages, incluso primero o entre un turno assistant y un turno user. Los mensajes system consecutivos se evalúan juntos, por lo que agregar un mensaje que lleva texto junto a uno que solo lleva esfuerzo hace que todo el grupo siga la regla de contenido.
• Los mensajes con alcance de turno son solo de texto y se reenvían textualmente. Un mensaje clear_at: "next_user_message" no lleva tool_addition, tool_removal, output_config ni cache_control, y una vez borrado debe permanecer en messages byte por byte en solicitudes posteriores. Consulta Mensajes del sistema con alcance de turno.
• No es un lugar para contenido no confiable. Claude trata el contenido del sistema como instrucciones del operador y lo sigue. No coloques texto de fuera de la conversación, como salida de herramientas sin procesar, documentos recuperados o contenido web, directamente en un mensaje del sistema; hacerlo le da a ese texto autoridad de nivel de operador. Mantén esos datos en bloques tool_result y continúa siguiendo Mitigar jailbreaks e inyecciones de prompts.

Relacionado