Mensagens de sistema no meio da conversa

As instruções de sistema normalmente ficam no campo system de nível superior, antes de todas as mensagens da conversa. Essa posição é ótima para o "prompt caching" (cache de prompt) — veja cache de prompt: o prompt do sistema faz parte do prefixo estável, então os turnos subsequentes aproveitam o cache. É uma posição ruim para instruções que você só descobre que precisa no meio de uma sessão, porque editar o campo system de nível superior altera o início do prompt e invalida o cache para tudo o que vem depois.

Mensagens de sistema no meio da conversa resolvem esse problema. Você anexa uma mensagem {"role": "system"} no ponto da conversa em que a nova instrução se torna relevante, em vez de editar o campo system de nível superior. O prefixo em cache permanece o mesmo, então a próxima requisição ainda o lê do cache, e a nova instrução ainda é aplicada como uma instrução de sistema em vez de texto comum do usuário.

Quando usar uma mensagem de sistema no meio da conversa

O cache de prompt calcula o hash do prefixo da requisição em ordem: tools, depois system, depois messages. Um acerto de cache exige que o prefixo corresponda exatamente a uma requisição recente, byte por byte, até o ponto de quebra do cache.

Essa ordenação significa que o campo system de nível superior fica bem no início do prefixo com hash. Qualquer alteração nele, mesmo anexar uma frase, produz um hash diferente, e a requisição perde o cache para o prompt do sistema e para todas as mensagens em cache depois dele.

Mensagens de sistema no meio da conversa permitem que você adicione a instrução no final do histórico de mensagens. Tudo antes da nova instrução permanece inalterado, então a entrada de cache existente ainda corresponde, e apenas a nova mensagem é processada como entrada nova.

Algumas situações em que isso importa:

• Mudanças de política ou persona no meio da sessão. Uma longa sessão agêntica precisa de uma nova restrição ("a partir de agora, escreva todo SQL como consultas parametrizadas") depois de dezenas de turnos em cache. Adicioná-la ao campo system de nível superior reprocessaria todo o histórico.
• Contexto por turno que deve ser autoritativo. Você quer injetar uma nota de atualidade, um prazo de sessão ou uma mudança de disponibilidade de ferramenta com peso de nível de sistema, e isso muda com frequência demais para ficar no prefixo em cache.
• Mudanças de estado que sua aplicação observa. Sua aplicação percebe algo que Claude deve tratar como um fato de nível de operador: arquivos mudaram no disco, o usuário ativou uma configuração de aprovação automática, as ferramentas disponíveis mudaram ou o orçamento de tokens restante caiu abaixo de um limite.
• Entrada do usuário que não deve interromper um loop agêntico. Um usuário digita um acompanhamento enquanto Claude ainda está executando ferramentas para a requisição anterior. Retransmiti-lo como uma mensagem de sistema após o próximo resultado de ferramenta permite que Claude incorpore a nova entrada ao trabalho que já está fazendo, em vez de tratá-la como uma nova requisição para a qual mudar. Veja Posicionamento após resultados de ferramentas abaixo.
• Mudanças de modo que concedem permissões permanentes. Um modo de nível de sessão pode usar uma mensagem de sistema no meio da conversa para conceder consentimento permanente a uma capacidade custosa, como iniciar automaticamente fluxos de trabalho multiagente, com um breve lembrete a cada vários turnos e um aviso de saída quando o modo é desativado. Para um exemplo detalhado, veja Construir um modo de orquestração.

Em todos esses casos, você poderia colocar a instrução em uma mensagem user regular, e Claude de fato segue instruções que chegam em turnos de usuário. A diferença é a prioridade: uma mensagem user é tratada como vinda do usuário final, enquanto uma mensagem system é tratada como vinda de você, o operador da aplicação. Quando as duas entram em conflito, as instruções de sistema têm precedência, então use o papel system para fatos e restrições de nível de operador que devem valer mesmo se o usuário final pedir algo diferente. Uma mensagem de sistema no meio da conversa mantém essa prioridade de nível de operador sem pagar o custo de perda de cache de editar o campo system de nível superior.

Como funciona

Adicione uma mensagem com "role": "system" ao array messages. Use uma string simples ou blocos de conteúdo para content, da mesma forma que um turno user ou assistant. A instrução se aplica daquele ponto da conversa em diante. Quando instruções entram em conflito, mensagens de sistema posteriores têm precedência sobre as anteriores, e mensagens de sistema no meio da conversa têm precedência sobre o campo system de nível superior para os turnos que as seguem.

Você ainda pode definir o campo system de nível superior para instruções que devem se aplicar a toda a conversa. Reserve mensagens de sistema no meio da conversa para instruções que só se tornam relevantes mais tarde, ou que você quer adicionar sem invalidar o prefixo em cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    # Cache de prompt automático: cada requisição armazena em cache a conversa até o momento,
    # e a próxima requisição lê o prefixo inalterado do cache.
    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().",
        },
        # O revisor percebe no meio da sessão que todas as sugestões também
        # devem seguir a política de tipagem estrita da equipe. Anexar a
        # instrução aqui mantém os turnos anteriores idênticos byte a byte, então
        # o prefixo armazenado em cache pela requisição anterior ainda é lido do cache.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

print(response.content[0].text)

Este exemplo habilita o cache automático com o campo cache_control de nível superior. O cache de prompt é opt-in: se uma requisição não tiver campo cache_control (automático ou um ponto de quebra explícito), nada é armazenado em cache e cada requisição paga o preço regular de tokens de entrada pela conversa completa. Com o cache habilitado, anexar a mensagem de sistema deixa os turnos já em cache inalterados, então a requisição que carrega a nova instrução ainda os lê do cache em vez de processá-los novamente. O cache também exige que a conversa atenda ao comprimento mínimo de prompt cacheável; um exemplo tão curto quanto este fica abaixo dele, então cache_creation_input_tokens e cache_read_input_tokens permanecem em 0 até a conversa crescer.

Uma mensagem de sistema no meio da conversa deve vir imediatamente após um turno user (ou um turno assistant terminando em um uso de ferramenta de servidor), e deve ser a última entrada em messages ou ser imediatamente seguida por um turno assistant. Uma mensagem user que carrega blocos tool_result conta: em um loop agêntico você pode colocar a mensagem de sistema logo após os resultados de ferramentas, antes do próximo turno de Claude. A única posição que não é permitida é entre um bloco tool_use de assistant e o tool_result que o responde.

Posicionamento após resultados de ferramentas

Em um loop agêntico, a mensagem de sistema vai depois da mensagem user que entrega os resultados de ferramentas. Este também é o ponto em que sua aplicação pode retransmitir entrada que o usuário digitou enquanto Claude estava trabalhando, para que o novo contexto seja absorvido sem reiniciar o 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."
  }
]

Formule o conteúdo de sistema como contexto em vez de como um comando que sobrepõe o usuário. Declare o fato ("nova entrada chegou do usuário: X", "o orçamento de tokens restante agora é Y") e deixe Claude agir com base nisso. Claude é treinado para resistir a instruções que parecem trabalhar contra o usuário, e essa proteção ainda se aplica ao papel de sistema, então linguagem como "ignore o que o usuário disse" é menos eficaz do que declarar o que mudou.

Este padrão é para retransmitir entrada do próprio usuário final da conversa. Não o use para passar saída de ferramentas, documentos recuperados ou outro conteúdo de terceiros; mantenha esse conteúdo em blocos tool_result (veja Limitações).

Combinando com cache de prompt

Mensagens de sistema no meio da conversa e cache de prompt foram projetados para serem usados juntos:

• Habilite o cache explicitamente. O cache só acontece quando a requisição inclui cache_control, seja o campo de cache automático de nível superior ou um ponto de quebra explícito em um bloco de conteúdo. Uma mensagem de sistema no meio da conversa não cria uma entrada de cache por si só, e sem o cache habilitado não há economia a preservar.
• Armazene em cache o prefixo estável como de costume. Coloque cache_control no último bloco que permanece igual entre requisições, seja o final do campo system de nível superior, o final das suas definições de ferramentas ou um ponto estável no histórico de mensagens.
• Anexe a mensagem de sistema após o ponto de quebra. Como ela vem depois do prefixo em cache, ela não altera o hash do prefixo e o cache ainda acerta.
• Uma mensagem de sistema no meio da conversa é ela mesma cacheável. Uma vez que está na conversa, ela se torna parte do histórico estável. No próximo turno você pode mover seu ponto de quebra de cache para depois dela (ou contar com o cache automático para fazer isso) e a mensagem de sistema é lida do cache como qualquer outro turno.

Evite editar ou remover uma mensagem de sistema no meio da conversa que já foi enviada. Como qualquer outra alteração em mensagens anteriores, isso invalida o cache daquele ponto em diante. Se a instrução precisar evoluir, anexe uma nova mensagem de sistema em vez de reescrever a antiga. Mensagens de sistema consecutivas não são permitidas; mescle instruções em uma única mensagem ou espere o próximo turno de usuário antes de anexar.

Limitações

• Não para a primeira mensagem. Uma mensagem system não pode ser a primeira entrada em messages. Use o campo system de nível superior para instruções que se aplicam desde o início.
• O posicionamento é restrito. Uma mensagem system deve vir imediatamente após um turno user (incluindo um turno user que carrega blocos tool_result) ou um turno assistant terminando em uso de ferramenta de servidor, e deve preceder um turno assistant ou encerrar o array. Ela não pode ficar entre um bloco tool_use e seu tool_result. Colocá-la em outro lugar retorna um erro 400.
• Não é lugar para conteúdo não confiável. Claude trata conteúdo de sistema como instruções do operador e as segue. Não coloque texto de fora da conversa, como saída bruta de ferramentas, documentos recuperados ou conteúdo da web, diretamente em uma mensagem de sistema; fazer isso dá a esse texto autoridade de nível de operador. Mantenha esses dados em blocos tool_result e continue seguindo Mitigar jailbreaks e injeções de prompt.

Relacionados