Using the Converse API - Amazon Nova
Request structureUsing system promptsInference parametersUsing reasoning

Using the Converse API

The Converse API provides a unified interface for interacting with Amazon Nova models. It abstracts away model-specific details and provides a consistent way to handle multi-turn conversations, system prompts and streaming responses across all Amazon Nova models.

The Converse API supports the following features:

  • Multi-turn conversations: Maintain context across multiple exchanges

  • System prompts: System instructions such as personas or response guidelines

  • Document chat: Interact with and query documents or collections of documents

  • Vision: Process and analyze images and video

  • Tool use: Enable models to use external tools and APIs

  • Guardrails: Apply content filtering and safety controls

  • Reasoning: Extended thinking for complex problem-solving

Request structure

A basic Converse API request includes the model ID and a list of messages:

import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'What is machine learning?'}]
        }
    ]
)

content_list = response["output"]["message"]["content"]
# Extract the first text block
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)

Using system prompts

System prompts provide context and instructions to the model:

import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    system=[
        {'text': 'You are a helpful AI assistant specializing in cloud computing.'}
    ],
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'Explain serverless computing.'}]
        }
    ]
)

# Print the response text
content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)

Inference parameters

Control the model's output using inference parameters:

import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'Write a short story.'}]
        }
    ],
    inferenceConfig={
        'maxTokens': 512,
        'temperature': 0.7,
        'topP': 0.9,
        'stopSequences': ['END']
    }
)

content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)

Available inference parameters:

  • maxTokens (integer): Maximum number of tokens to generate (up to 65,000). If not specified, the model uses a dynamic default based on the request context.

  • temperature (float): Controls randomness (0.0-1.0, default 0.7). Lower values make output more deterministic

  • topP (float): Nucleus sampling threshold (0-1, default 0.9). Lower values make output more focused

  • stopSequences (array): Sequences that stop generation when encountered

Amazon Nova also supports topK (1-128, not used by default) via additionalModelRequestFields:

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[{'role': 'user', 'content': [{'text': 'Hello'}]}],
    inferenceConfig={'maxTokens': 100},
    additionalModelRequestFields={'inferenceConfig': {'topK': 50}}
)

Using reasoning

Nova 2 Lite supports extended thinking for complex problem-solving. Enable reasoning with reasoningConfig.

By default, reasoning is disabled to optimize for speed and cost on simple queries. When you need more complex reasoning, you can enable it with three effort levels:

Low effort (maxReasoningEffort: "low")

Use for tasks requiring structured thinking, such as code review, multi-factor analysis, or methodical problem-solving.

Medium effort (maxReasoningEffort: "medium")

Use for multi-step tasks like software development, debugging, multi-file code generation, or agentic workflows coordinating multiple tools.

High effort (maxReasoningEffort: "high")

Use for advanced problem-solving like mathematical proofs, scientific analysis, complex system design, or critical decision-making requiring thorough validation.

The following examples show different reasoning effort levels:

Low effort
import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    system=[{"text": "You are a highly capable personal assistant"}],
    messages=[{
        "role": "user",
        "content": [{"text": "Provide a meal plan for a gluten free family of 4."}]
    }],
    inferenceConfig={
        "temperature": 0.7,
        "topP": 0.9,
        "maxTokens": 10000
    },
    additionalModelRequestFields={
        "reasoningConfig": {
            "type": "enabled",
            "maxReasoningEffort": "low"
        }
    }
)

content_list = response["output"]["message"]["content"]

for item in content_list:
    if "reasoningContent" in item:
        reasoning_text = item["reasoningContent"]["reasoningText"]["text"]
        print("=== REASONING ===")
        print(reasoning_text)
        print()
    elif "text" in item:
        print("=== ANSWER ===")
        print(item["text"])
High effort
import boto3
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.converse(
    modelId='us.amazon.nova-2-lite-v1:0',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'Solve this logic puzzle: If all roses are flowers and some flowers fade quickly, what can we conclude?'}]
        }
    ],
    additionalModelRequestFields={
        'reasoningConfig': {
            'type': 'enabled',
            'maxReasoningEffort': 'high'
        }
    }
)

content_list = response["output"]["message"]["content"]
text = next((item["text"] for item in content_list if "text" in item), None)
if text is not None:
    print(text)

Reasoning parameters:

  • type: enabled or disabled (default: disabled)

  • maxReasoningEffort: low, medium, or high

Note

Temperature, topP and topK cannot be used with maxReasoningEffort set to high. Using these parameters together causes an error.

The response includes reasoning content showing step-by-step analysis:

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "reasoningContent": {
                        "reasoningText": {
                            "text": "[REDACTED]"
                        }
                    }
                },
                {
                    "text": "Based on the premises, we can conclude..."
                }
            ]
        }
    },
    "stopReason": "end_turn"
}
Note

With Amazon Nova 2, reasoning content displays as [REDACTED]. You're still charged for reasoning tokens as they contribute to improved output quality. We include this field in the response structure now to preserve the option of exposing reasoning content in the future. We are actively working with customers to determine the best approach for surfacing the model's reasoning process.