Compreendendo Papéis e Turnos na API de Mensagens

Cada solicitação para a API de Mensagens do Claude é construída a partir de dois ingredientes: um prompt do sistema e uma lista de mensagens.

O prompt do sistema define o cenário uma vez, no nível superior da solicitação.

A lista de mensagens é onde a conversa real vive, e ela segue uma estrutura rigorosa: um turno de user, depois um turno de assistant, depois user novamente, e assim por diante.

Compreender essa estrutura alternada é o modelo mental mais importante para trabalhar com a API, porque quase todos os bugs em uma integração da API de Mensagens remontam a um mal-entendido de papéis e turnos.

Resumo

Ideia Central: Uma conversa é um array messages de turnos estritamente alternados de user e assistant, mais um prompt system separado no nível superior que não faz parte desse array.
Por que Importa: A API valida a ordem dos turnos e a alternância de papéis; se errar, a solicitação falha antes mesmo que o Claude a veja.
Conceitos-Chave: role (papel), turn (turno), system prompt (prompt do sistema), conversation state (estado da conversa), statelessness (ausência de estado).
Quando Usar: Sempre que você enviar uma solicitação para client.messages.create(), seja uma única pergunta ou uma longa conversa de ida e volta.
Limitações / Trade-offs: A própria API não se lembra de nada entre as solicitações; a estrutura alternada é um contrato que você deve satisfazer em cada chamada.
Tópicos Relacionados: o array de mensagens como estado da conversa, tipos de blocos de conteúdo, formatação do prompt do sistema.

Fundamentos

Um role (papel) é um rótulo em cada entrada no array messages que indica quem está "falando" naquele turno.

Existem dois papéis que você envia: user, que representa a entrada de uma pessoa ou sua aplicação, e assistant, que representa as próprias respostas anteriores do Claude.

Um turn (turno) é uma entrada completa no array, marcada com um papel e contendo conteúdo.

O prompt do sistema é um conceito totalmente separado: é um parâmetro system de nível superior na solicitação, não uma mensagem com um papel, e ele define a persona, restrições ou formato de saída para toda a conversa, em vez de representar uma troca de ida e volta.

Aqui está a solicitação menor possível, mostrando onde os papéis e turnos se encaixam:

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Você é um assistente conciso e amigável.",
    messages=[
        {"role": "user", "content": "Qual é a capital da França?"},
    ],
)

Note que system fica completamente fora de messages.

O array messages aqui tem exatamente um turno, com o papel user.

Essa é a forma válida mais simples: um único turno de usuário, sem turnos de assistente ainda, porque o Claude ainda não respondeu.

Mecânicas e Interações

A API impõe uma regra estrita de alternância no array messages: a primeira mensagem deve ter o papel user, e os papéis devem alternar estritamente a partir daí.

Você não pode enviar dois turnos user seguidos, e não pode enviar um turno assistant como a primeira entrada.

Se você violar isso, a solicitação falha com um erro 400 antes que qualquer inferência do modelo aconteça - a validação é puramente estrutural, verificada contra a forma do array, e não contra o conteúdo dentro dele.

Um segundo detalhe, fácil de perder, é que a API é stateless (sem estado).

O Claude não se lembra da sua solicitação anterior na próxima vez que você chamar o endpoint.

Cada solicitação é avaliada de forma independente, usando apenas o que está no array messages daquela solicitação.

Isso significa que, após o Claude responder, se você quiser continuar a conversa, deve anexar a resposta do Claude como um novo turno assistant e, em seguida, adicionar sua próxima pergunta como um novo turno user - tudo no mesmo array, enviado novamente na próxima chamada.

Solicitação 1:  system: "..."
                messages: [ user: "Qual é a capital da França?" ]
                -> resposta: resposta do assistant ("Paris.")
 
Solicitação 2:  system: "..."                                    (mesmo prompt do sistema)
                messages: [ user: "Qual é a capital da França?",
                            assistant: "Paris.",                  (resposta anterior do Claude, agora no array)
                            user: "Qual é a sua população?" ]     (nova pergunta)
                -> resposta: resposta do assistant, ciente de "Paris" pelo contexto

Cada solicitação carrega todo o histórico até o momento.

O array cresce em duas entradas por ciclo de ida e volta: uma entrada assistant anexada da resposta anterior e uma nova entrada user com sua próxima entrada.

É por isso que o modelo mental é tão importante: se você pensar na API como "lembrando" da conversa, ficará surpreso quando o Claude não tiver ideia do que vocês conversaram um momento atrás.

A verdade é mais próxima de entregar ao Claude uma transcrição do zero em cada chamada, e a transcrição só é tão completa quanto o que você escolher reenviar.

Considerações Avançadas e Aplicações

Uma sutileza que vale a pena internalizar cedo: o content de um turno não precisa ser uma única string.

Pode ser uma lista de blocos de conteúdo, e esses blocos podem ser de diferentes tipos - text, image, tool_use, ou tool_result - misturados dentro de um único turno.

Um turno user respondendo a uma chamada de ferramenta, por exemplo, geralmente carrega um bloco tool_result em vez de texto simples.

Um turno assistant que decide chamar uma ferramenta carrega um bloco tool_use em vez de, ou ao lado de, texto.

A regra de alternância de papel/turno ainda se aplica independentemente de quais tipos de conteúdo estão dentro de cada turno - a alternância é sobre o rótulo do papel, não sobre a forma do conteúdo.

Abordagem	Força	Fraqueza	Melhor Ajuste
Conteúdo de string simples	Mais simples de ler e escrever	Não pode misturar tipos de conteúdo em um único turno	Trocas simples apenas de texto
Lista de blocos de conteúdo	Suporta texto, imagens, tool_use, tool_result juntos	Mais verboso, requer compreensão dos tipos de bloco	Turnos de visão, uso de ferramentas ou qualquer conteúdo misto

A outra consequência da ausência de estado que vale a pena planejar cedo é o custo e o crescimento do contexto: como você reenvia todo o histórico a cada vez, uma conversa longa significa um corpo de solicitação crescente e uso crescente de tokens em cada chamada, mesmo que a maior parte seja idêntica à chamada anterior.

Esse crescimento é gerenciável para trocas curtas e se torna uma preocupação real de design para conversas de longa duração, o que é um tópico abordado em sua própria seção em outro lugar.

Equívocos Comuns

"O Claude lembra automaticamente de nossa conversa anterior." Ele não lembra - a API de Mensagens não tem memória do lado do servidor. Cada resposta que o Claude dá é baseada unicamente no que você colocou no array messages daquela solicitação.
"O prompt do sistema é apenas o primeiro turno do usuário." É um parâmetro de nível superior genuinamente separado, não faz parte do array alternado messages, e não está sujeito à regra de alternância de papéis.
"Posso enviar duas mensagens de usuário uma após a outra se tiver duas coisas a dizer." Você não pode enviá-las como duas entradas separadas no array com o papel user - combine-as no conteúdo de um único turno user, ou espere por um turno assistant no meio.
"Turnos e blocos de conteúdo são a mesma coisa." Um turno é a entrada rotulada com papel em messages; um bloco de conteúdo é uma peça do conteúdo desse turno. Um turno pode conter vários blocos de diferentes tipos.

FAQs

Quais são os únicos dois papéis permitidos no array de mensagens?

user e assistant. O prompt do sistema é configurado separadamente através do parâmetro system de nível superior, não como um papel dentro de messages.

O array de mensagens precisa começar com um turno de usuário?

Sim. A primeira entrada deve ter o papel user, e os papéis devem alternar estritamente user, assistant, user, assistant, e assim por diante a partir daí.

O que acontece se eu enviar dois turnos consecutivos com o mesmo papel?

A API rejeita a solicitação com um erro 400 antes de executar a inferência, porque a sequência de papéis viola a alternância necessária.

O Claude se lembra do que eu disse em uma chamada de API anterior?

Não. A API de Mensagens é stateless do lado do servidor. O Claude "lembra" apenas do que está incluído no array messages da solicitação atual, razão pela qual você reenvia os turnos anteriores em cada chamada.

Onde o prompt do sistema se encaixa em relação ao array de mensagens?

É um parâmetro system separado de nível superior na solicitação, não um turno dentro de messages. Ele se aplica a toda a conversa em vez de representar um lado de uma troca de ida e volta.

Um único turno pode conter mais do que texto simples?

Sim. O content de um turno pode ser uma lista de blocos de conteúdo - text, image, tool_use, ou tool_result - e um único turno pode misturar vários tipos de bloco.

Se eu quiser continuar uma conversa, o que exatamente eu adiciono ao array?

Anexe a resposta anterior do Claude como um novo turno assistant, depois adicione sua próxima entrada como um novo turno user, e envie todo o array novamente em sua próxima solicitação.

Existe um custo de desempenho em reenviar toda a conversa a cada vez?

Sim - como cada solicitação carrega todo o histórico, tanto o tamanho da solicitação quanto o uso de tokens crescem à medida que uma conversa se torna mais longa, mesmo que a maior parte do conteúdo seja inalterada em relação à chamada anterior.

Um turno de assistente pode ser a primeira entrada no array de mensagens?

Não. O array deve começar com um turno user. Enviar um turno assistant primeiro é uma violação estrutural e a solicitação falha na validação.

A alternância de papéis é verificada com base no conteúdo da mensagem ou na estrutura da mensagem?

É puramente estrutural - a API verifica a sequência de rótulos role no array, independentemente de quais tipos de conteúdo ou texto esses turnos realmente contenham.

Por que um turno de assistente às vezes contém um bloco tool_use em vez de texto?

Quando o Claude decide chamar uma ferramenta, ele expressa essa decisão como um bloco de conteúdo tool_use dentro de seu turno assistant, em vez de (ou ao lado de) uma resposta de texto simples.

Sob qual papel um resultado de ferramenta é enviado de volta?

Resultados de ferramentas são enviados de volta como um bloco de conteúdo tool_result dentro de um turno user - a regra de alternância de papéis ainda se aplica, então isso segue o turno assistant precedente que solicitou a ferramenta.

Relacionados

Noções Básicas da API de Mensagens - envie sua primeira solicitação de múltiplos turnos de ponta a ponta.
Construindo Conversas de Múltiplos Turnos com o Array de Mensagens - as mecânicas de reenviar o histórico em cada chamada.
Referência de Papéis e Tipos de Blocos de Conteúdo da API de Mensagens - uma tabela de referência de cada tipo de bloco de conteúdo.
Formatando Prompts do Sistema para Comportamento Consistente do Claude - como escrever bem o parâmetro de sistema separado.

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.