Separate instructions from Converse message content

Learning objective

Format Amazon Bedrock Converse requests with system instructions, roles, and message content.

Core idea

A Converse request is a structured conversation, not a prompt string wrapped in JSON. Its fields distinguish application instructions, conversational turns, and the content inside each turn. Preserve those distinctions when you convert extracted documents or application state into model inputs.

Amazon Bedrock provides a consistent Converse interface for models that support messages. That common envelope does not make every model support every modality or feature. Validate both the request structure and the selected model’s capabilities before invocation. Check feature support in Bedrock’s Models at a glance model cards; see 1.2.1 for model eligibility.

Treat instruction ownership as an application decision. Your application controls its system instructions; a customer message or extracted document remains supplied content. Moving untrusted text into an instruction field changes its intended role without proving that the text deserves authority.

How it works

Assign fields before serializing

The required modelId identifies the inference resource. For a direct model request, put task instructions in the top-level system array and conversation turns in messages. A system text block uses {"text": "..."}; each message has a role and a content array.

The Message API reference lists user, assistant, and system as role values, so a validator that allows only two values rejects a documented value. Put application instructions in the top-level system array, which Converse documents for that purpose, and make your adapter emit only that instruction form.

The following JSON fragment shows a text-only request body for a model that supports system prompts:

{
  "system": [{ "text": "Explain only what the supplied evidence supports." }],
  "messages": [
    {
      "role": "user",
      "content": [{ "text": "What does this warranty cover?" }]
    }
  ],
  "inferenceConfig": { "maxTokens": 512 }
}

Supply the selected inference resource separately as modelId. The value 512 is an illustrative output budget, not a model context limit. inferenceConfig.maxTokens caps generated tokens; it does not truncate your input conversation. Conversation-budget management belongs to 1.3.9.

Represent previous model replies as assistant messages rather than quoted user statements. Maintain their original order. Bedrock’s documented conversation pattern sends prior messages again on subsequent requests, so a request containing only the next question does not reconstruct earlier turns for you.

Validate content blocks independently

ContentBlock is a union: one block specifies one member. Put text and an image in separate objects within the same content array. An object containing both text and image is not the equivalent of two valid blocks.

For images, image.format describes the image format and image.source supplies the content. When you use the documented bytes path through an AWS SDK, pass raw bytes; the SDK handles encoding. For a direct JSON request, the bytes representation is base64. Do not encode bytes twice or confuse a filename with image content.

The Message contract permits images and documents only in a user message. It permits up to 20 images, each no larger than 3.75 MB, 8,000 pixels high, or 8,000 pixels wide. It permits up to five documents, each no larger than 4.5 MB. These are message-contract ceilings, not a promise that a particular model accepts every allowed file.

If a message contains a document block, it must also contain a text block. Use that text to state the task about the document. A document upload without the accompanying prompt is structurally incomplete even if the document bytes are readable.

Choose a neutral document.name. AWS warns that models can interpret the name as instructions, making that field vulnerable to prompt injection. Preserve the source filename in your provenance record if you need it; do not automatically copy an attacker-controlled filename into the model-facing name. Extraction and provenance are covered in 1.3.3 and 1.3.5.

Separate common parameters from model extensions

The base inferenceConfig fields are maxTokens, temperature, topP, and stopSequences. Model-specific parameters belong in additionalModelRequestFields, and still require model-specific validation. A common envelope does not override restrictions on parameter combinations.

There is a separate contract when modelId is a Prompt management prompt-version ARN. In that case, the request cannot include system, inferenceConfig, additionalModelRequestFields, or toolConfig; define those through Prompt management instead. Supply variable values through promptVariables. Any request messages are appended after messages defined in the prompt.

Do not combine these modes by taking a direct-model request and replacing only modelId. Validate the resource kind as well as the JSON shape. The routing boundary is described in 1.2.3.

Key distinctions and trade-offs

Common structure versus common capability: Converse reduces differences in request and response envelopes. It does not establish universal image, document, system-prompt, or tool support. Reject unsupported content before serialization rather than silently converting it to a different modality.

Application instructions versus supplied evidence: system expresses intended application behavior; document and user blocks supply material to process. Field separation helps preserve that distinction, but it is not proof that a model obeys every instruction or ignores every injected instruction.

One message versus one content block: A message can contain several blocks. Keeping a document and its task together in one user message does not require putting them in one union object.

Direct configuration versus managed prompt configuration: A direct-model request carries runtime instructions and inference settings. A prompt-version request obtains those settings from the managed prompt and has explicit restrictions on overrides.

Architecture / decision scenario

A warranty assistant accepts a question, a PDF, and optional product photographs. Its application owns the response policy. Its adapter builds the top-level system array, then a user message containing the question as text, the PDF as a document block, and each photograph as an image block.

Before calling Converse, the adapter checks the document count and size, image count and dimensions, required document text, union membership, and selected model support. It assigns the document a neutral name. An unsupported image fails the input contract; the adapter does not claim that the model examined a photograph it never received.

The application reads output.message for the assistant turn and checks stopReason before treating the reply as complete. A max_tokens result needs handling as a bounded output, while tool_use indicates a different continuation path. It retains the structured assistant message for later conversation assembly; see 1.3.9.

If the team moves the policy into Prompt management, it removes the forbidden runtime fields and supplies promptVariables. A request-contract test catches an accidental leftover system field before the configuration reaches users.

Common exam traps

• Treating Converse as support for every model and modality.
• Assuming the Message role enumeration contains only user and assistant.
• Putting multiple union members into one content block.
• Sending a document without a text block in the same message.
• Using maxTokens as an input-truncation setting.
• Sending runtime system instructions with a Prompt management prompt-version ARN.
• Assuming a source filename is a harmless document name.

What to remember

• Keep application instructions, roles, and message content explicit.
• Validate union shape, message restrictions, and model support separately.
• Preserve ordered assistant messages rather than flattening the conversation.
• Distinguish direct-model requests from managed prompt-version requests.
• Read response content and stopReason together.

Knowledge check

References

• AWS, Converse
• AWS, Message
• AWS, ContentBlock
• AWS, Use the Converse API
• AWS, DocumentBlock