Claude Messages: Roles, Content and Context
A Messages request contains model, max_tokens and messages. Put application instructions in the top-level system field. Use user and assistant roles for the conversation itself.
#A conversation is input, not a stored session
Each request must contain the context needed for that turn. Saving a conversation in your application does not automatically make it available to the model.
json[ {"role": "user", "content": "My sample project uses Python."}, {"role": "assistant", "content": "What would you like to build?"}, {"role": "user", "content": "Suggest a small command-line tool."} ]
This is a request fragment, not a complete HTTP call. In an actual application, use the assistant content returned by the previous response rather than inventing a prior answer.
#Content can contain several blocks
Plain strings are convenient for text-only input. Typed blocks are needed for images and tool interactions. Inspect the block type before reading its fields. Preserve assistant tool requests and return results with their matching identifiers.
Separate trusted instructions from source material. Clear headings or XML-style delimiters help distinguish the task, documents and output requirements; delimiters alone do not make an untrusted document safe.
#Manage the context window
Reserve space for the output and account for tools and images as well as text. Keep the current objective, confirmed constraints and relevant observations. Summaries should retain uncertainty and source references, not turn guesses into facts.
Check stop_reason before treating a response as complete. Validate structured output in application code and handle an empty or interrupted result explicitly.
