messages api

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

max_tokens hard stop behavior

The max_tokens parameter specifies the absolute maximum number of tokens to generate and is a hard stop, meaning Claude may stop generating mid-word or mid-sentence if the limit is reached. Claude may also stop before reaching this maximum for other reasons.

Messages API required parameters

The Messages API requires three parameters: (1) model - the API model name to call, (2) max_tokens - the maximum number of tokens to generate before stopping (this is a hard stop that may cause Claude to stop mid-word or mid-sentence), and (3) messages - an array of input messages with alternating user and assistant conversational turns.

Messages array structure and alternation rules

Each message in the messages array must be an object with a role and content field. The role must be either 'user' or 'assistant'. Messages must alternate between user and assistant roles, and the first message must always use the user role.

Messages API optional parameters

Optional parameters for the Messages API include system (the system prompt) and temperature (the degree of variability in Claude's response). Additional optional parameters are available in the full API documentation.

Messages API setup code example

To use the Messages API, install the anthropic package with pip, import the anthropic module, create a client with your API key using anthropic.Anthropic(api_key=API_KEY), then call client.messages.create() with model, max_tokens, temperature, system, and messages parameters. The response is accessed via message.content[0].text.

Multiple user messages without alternation causes error

If messages are sent without proper alternation between user and assistant roles, such as two consecutive user messages, the Messages API will return an error. Messages must strictly alternate.

Missing role and content fields causes error

If a message object in the messages array lacks the required role and content fields (for example, just a string instead of an object with these fields), the Messages API will return an error.

How prefill works in messages API

In the messages API, prefill text is passed as content in an assistant message turn that appears after the user message turn. The messages array contains {"role": "user", "content": prompt} followed by {"role": "assistant", "content": prefill}. Claude then continues from where the prefill text ends.

Prefill parameter continues Claude's response at a specific point

The prefill parameter in get_completion allows you to provide partial assistant content that Claude will continue from. This is passed as the content of an assistant message in the messages list, allowing you to guide Claude's response format or starting point.

get_completion helper function signature

The get_completion function accepts three parameters: prompt (required string), system_prompt (optional string, defaults to empty string), and prefill (optional string, defaults to empty string). It creates a message using the Anthropic API with max_tokens=2000 and temperature=0.0.

get_completion implementation with prefill parameter

The get_completion function creates an API message with two turns: a user message containing the prompt, and an assistant message containing the prefill content. The function uses anthropic.Anthropic client with the specified model and returns the text content of the first message response.

Show prefilled response starting point in assistant role

When prefilling Claude's response to steer its behavior, the prefilled text must be placed in the assistant role in the API call, not in the user role. This tells Claude to continue from that starting point. For example, if precognition asks for relevant quotes in tags, start the assistant prefill with '<relevant_quotes>' so Claude continues filling in the content within those tags.

get_completion helper function signature and parameters

The get_completion function takes two parameters: messages (a list of message dictionaries) and system_prompt (a string, defaults to empty string). It calls client.messages.create() with model from MODEL_NAME variable, max_tokens=2000, temperature=0.0, the provided system_prompt, and messages list. It returns message.content[0].text, extracting just the text content of the first content block.

Messages array structure: required fields

Each message in the messages array requires two fields: role (either 'user' or 'assistant') and content (a string containing the message text). For user messages, content contains the prompt or request. For assistant messages, content contains Claude's previous response or a prefilled response to continue from.

Give your agent this brain