Quick Start Guide: Enhanced Converse API

This guide shows you how to use aws_bedrock_runtime_mate to build multi-round conversations with Amazon Bedrock models. This library provides a simpler, more intuitive API than the raw boto3 client.

Setup

# Import aws_bedrock_runtime_mate
import aws_bedrock_runtime_mate.api as aws_bedrock_runtime_mate

# Initialize the Bedrock Runtime client
import boto3
from rich import print as rprint

boto_ses = boto3.Session(profile_name="esc_app_dev_us_east_1")
bdrt_client = boto_ses.client("bedrock-runtime")

Example: Multi-Round Conversation

We’ll build a chatbot that remembers information across multiple turns.

# Test messages
msg_1 = "Remember this, my name is Lea Katsurou, my date of birth is 1993-08-14. Say 'Yes I got it' if you understand."
msg_2 = "What is my name?"

1. Non-Streaming Conversations with ChatSession

ChatSession automatically manages conversation history, so you don’t need to manually track messages.

Create a Chat Session

# Initialize session with default configuration
default_converse_kwargs=aws_bedrock_runtime_mate.ConverseKwargs(
    model_id="us.amazon.nova-micro-v1:0",
) # we can reuse this later

chat_session = aws_bedrock_runtime_mate.patterns.ChatSession(
    client=bdrt_client,
    converse_kwargs=default_converse_kwargs,
    verbose=True,
)

Send Messages

# First turn: Store information
response = chat_session.converse_text(msg_1)

===== Send messages, n_msg = 1, hash = 1656d481c066934d1296a1e4359cc31c

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [
        {
            'role': 'user',
            'content': [
                {
                    'text': "Remember this, my name is Lea Katsurou, my date of birth is 1993-08-14. Say 'Yes I got
it' if you understand."
                }
            ]
        }
    ]
}

----- Converse response:

{
    'output': {
        'message': {
            'role': 'assistant',
            'content': [
                {
                    'text': "Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 
1993. If you need anything else or have any questions, feel free to let me know!"
                }
            ]
        }
    },
    'stopReason': 'end_turn',
    'usage': {'inputTokens': 38, 'outputTokens': 49, 'totalTokens': 87},
    'metrics': {'latencyMs': 591}
}

# The .text property provides convenient access to the response text
print(response.text)

Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 1993. If you need anything else or have any questions, feel free to let me know!

Continue the Conversation

The session automatically remembers previous messages!

# Second turn: Test memory
response = chat_session.converse_text(msg_2)

===== Send messages, n_msg = 3, hash = 0853a9d3987dcfd5271cddcc2175743a

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [
        {
            'role': 'user',
            'content': [
                {
                    'text': "Remember this, my name is Lea Katsurou, my date of birth is 1993-08-14. Say 'Yes I got
it' if you understand."
                }
            ]
        },
        {
            'role': 'assistant',
            'content': [
                {
                    'text': "Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 
1993. If you need anything else or have any questions, feel free to let me know!"
                }
            ]
        },
        {'role': 'user', 'content': [{'text': 'What is my name?'}]}
    ]
}

----- Converse response:

{
    'output': {
        'message': {
            'role': 'assistant',
            'content': [
                {
                    'text': 'Your name is Lea Katsurou. If you need any further assistance or have any questions, 
just let me know!'
                }
            ]
        }
    },
    'stopReason': 'end_turn',
    'usage': {'inputTokens': 97, 'outputTokens': 23, 'totalTokens': 120},
    'metrics': {'latencyMs': 342}
}

print(response.text)

Your name is Lea Katsurou. If you need any further assistance or have any questions, just let me know!

2. Streaming Conversations with ChatSession

Streaming is perfect for real-time applications where you want to display responses as they arrive.

Create a New Session

chat_session = aws_bedrock_runtime_mate.patterns.ChatSession(
    client=bdrt_client,
    converse_kwargs=default_converse_kwargs,
    verbose=True,
)

Send Streaming Message

# Send first message with streaming enabled
response = chat_session.converse_text_stream(msg_1)

===== Send messages, n_msg = 1, hash = 1656d481c066934d1296a1e4359cc31c

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [
        {
            'role': 'user',
            'content': [
                {
                    'text': "Remember this, my name is Lea Katsurou, my date of birth is 1993-08-14. Say 'Yes I got
it' if you understand."
                }
            ]
        }
    ]
}

----- Converse response:

{'stream': <botocore.eventstream.EventStream object at 0x107d1a010>}

Option 1: Iterate Text Only (Simplest)

Most of the time, you only care about the text content. Use iterate_text():

# Collect text chunks
chunks = []
for text in chat_session.iterate_text(response):
    chunks.append(text)
    print(text, end="", flush=True)  # Stream to console
print()  # New line

# Full response
full_text = "".join(chunks)
print(f"\n--- Full Response ---\n{full_text}")

Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 1993. If you need anything else or have any questions, feel free to let me know!

--- Full Response ---
Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 1993. If you need anything else or have any questions, feel free to let me know!

Option 2: Iterate All Events (Advanced)

For more control, iterate over all streaming events:

# Process each event
for event in chat_session.iterate_events(response):
    if event.is_messageStart():
        print("🚀 Message starting...")
    elif event.is_contentBlockDelta():
        if event.text:
            print(event.text, end="", flush=True)
    elif event.is_messageStop():
        print(f"\n✅ Done! Stop reason: {event.messageStop.stopReason}")

🚀 Message starting...
Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 1993. If you need anything else or have any questions, feel free to let me know!
✅ Done! Stop reason: end_turn

Option 3: One-Shot Text Extraction

If you don’t need real-time streaming, just get the complete text:

# Send another message
response = chat_session.converse_text_stream(msg_2)

# Get complete text directly (waits for full response)
print(response.text)

===== Send messages, n_msg = 3, hash = 0853a9d3987dcfd5271cddcc2175743a

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [
        {
            'role': 'user',
            'content': [
                {
                    'text': "Remember this, my name is Lea Katsurou, my date of birth is 1993-08-14. Say 'Yes I got
it' if you understand."
                }
            ]
        },
        {
            'role': 'assistant',
            'content': [
                {
                    'text': "Yes, I've got it. Your name is Lea Katsurou, and your date of birth is August 14, 
1993. If you need anything else or have any questions, feel free to let me know!"
                }
            ]
        },
        {'role': 'user', 'content': [{'text': 'What is my name?'}]}
    ]
}

----- Converse response:

{'stream': <botocore.eventstream.EventStream object at 0x107d58110>}

Your name is Lea Katsurou. If you need any further assistance or have any questions, just let me know!

Note: The session automatically adds streaming responses to conversation history after consumption!

3. Advanced: MessageContentBuilder

For complex messages with multiple content types (text, images, documents), use MessageContentBuilder:

# Build a multi-modal message
builder = aws_bedrock_runtime_mate.MessageContentBuilder()
builder.add_text("What's in this image?")
# builder.add_image(format="png", bytes=image_bytes)  # Add image from bytes
# builder.add_document(name="report.pdf", format="pdf", bytes=pdf_bytes)  # Add PDF

# Send the constructed message
builder.to_message()

{'role': 'user', 'content': [{'text': "What's in this image?"}]}

Builder Examples

# Example 1: Text + Image from S3
builder = aws_bedrock_runtime_mate.MessageContentBuilder()
builder.add_text("Analyze this diagram")
builder.add_image(format="png", s3_uri="s3://my-bucket/diagram.png")

# Example 2: Chained construction
message = (
    aws_bedrock_runtime_mate.MessageContentBuilder()
        .add_text("Review this document")
        .add_document(name="contract.pdf", format="pdf", s3_uri="s3://my-bucket/contract.pdf")
        .to_message()
)

# Example 3: Tool results (for function calling)
builder = aws_bedrock_runtime_mate.MessageContentBuilder()
builder.add_tool_result(
    tool_use_id="tool_abc123",
    content=[{"text": "The weather in Paris is 18°C and sunny"}]
)
tool_result_message = builder.to_message()

4. Understanding Stream Events: ConverseStreamOutput

When you iterate over streaming events, each event is a ConverseStreamOutput object with helper methods:

chat_session = aws_bedrock_runtime_mate.patterns.ChatSession(
    client=bdrt_client,
    converse_kwargs=default_converse_kwargs,
    verbose=True,
)
# Create streaming response
response = chat_session.converse_text_stream("Tell me a super short story")

# In a streaming loop:
for event in chat_session.iterate_events(response):
    # Check event type
    if event.is_messageStart():
        print("Message starting...")
    elif event.is_contentBlockStart():
        print("Content block starting...")
    elif event.is_contentBlockDelta():
        # Extract text easily
        if event.text:
            print(event.text, end="")
        # Or extract reasoning content (for advanced models)
        if event.reasoning_content_text:
            print(f"[Thinking: {event.reasoning_content_text}]")
    elif event.is_contentBlockStop():
        print("\nContent block complete")
    elif event.is_messageStop():
        print(f"Stop reason: {event.messageStop.stopReason}")

===== Send messages, n_msg = 1, hash = 9928b30560cbd5f1e0e4938566115560

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [{'role': 'user', 'content': [{'text': 'Tell me a super short story'}]}]
}

----- Converse response:

{'stream': <botocore.eventstream.EventStream object at 0x107daa010>}

Message starting...
Once, a tiny ant named Andy found a tiny acorn. He carried it home, but as he struggled, a gentle rain began. The acorn rolled away, and Andy watched it sink into the earth. Days later, a mighty oak sprouted where the acorn lay. Andy smiled, knowing he had helped it grow.
Content block complete
Stop reason: end_turn

5. Stream Management: ConverseStreamResponse

ConverseStreamResponse intelligently manages streaming:

chat_session = aws_bedrock_runtime_mate.patterns.ChatSession(
    client=bdrt_client,
    converse_kwargs=default_converse_kwargs,
    verbose=True,
)
# Create streaming response
response = chat_session.converse_text_stream("Tell me a super short story")

# First consumption: Reads from API
for text in chat_session.iterate_text(response):
    print(text, end="", flush=True)

# Second consumption: Uses cached events (no new API call!)
full_text = "".join(chat_session.iterate_text(response))
print(f"\n\nCached text length: {len(full_text)}")

# Check if stream was consumed
print(f"Stream consumed: {response.is_stream_consumed()}")  # True

===== Send messages, n_msg = 1, hash = 9928b30560cbd5f1e0e4938566115560

----- Converse kwargs:

{
    'modelId': 'us.amazon.nova-micro-v1:0',
    'messages': [{'role': 'user', 'content': [{'text': 'Tell me a super short story'}]}]
}

----- Converse response:

{'stream': <botocore.eventstream.EventStream object at 0x107e16090>}

Once, a tiny ant named Andy found a giant cookie. Too big to eat alone, he called his friends. Together, they shared the cookie, learning that teamwork makes even the biggest things shareable.

Cached text length: 192
Stream consumed: True

Key Features:

• Automatic Caching: Events are cached on first iteration

• Multiple Iterations: Iterate multiple times without re-fetching

• History Management: Session automatically collects messages for history

• Convenient Properties:

  • response.text - Get complete text (waits if not consumed)

  • response.message - Get complete message structure

  • response.is_stream_consumed() - Check consumption status