Bedrock Basics

Your first Converse call against a foundation model via SDK.

This page is a hands-on tour of the Bedrock Runtime data plane. Each example is small and builds on the last: a single reply, then a system prompt, then a full multi-turn conversation, then reading usage, and finally listing models and a first stream. The same client-request-response shape repeats throughout, so once the first call clicks the rest are variations.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-bedrock-runtime @aws-sdk/client-bedrock (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK finds them automatically. Your identity needs bedrock:InvokeModel (and bedrock:ListFoundationModels for the control-plane example).
Model access must be enabled for the models you call, in the Bedrock console under Model access, for your region. A model you have not enabled returns an access error even with correct IAM.
A region where the model exists - examples assume us-east-1. Model IDs and inference-profile requirements are region/version-specific.

Basic Examples

1. Your First Converse Call

Send one user message to a model and print its reply.

# --- Python (boto3) ---
import boto3
 
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",  # representative id - verify per region
    messages=[{"role": "user", "content": [{"text": "Name three primary colors."}]}],
)
print(resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
 
const brt = new BedrockRuntimeClient({ region: "us-east-1" });
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0", // representative id - verify per region
  messages: [{ role: "user", content: [{ text: "Name three primary colors." }] }],
}));
console.log(resp.output?.message?.content?.[0]?.text);

The data-plane client is bedrock-runtime, distinct from the bedrock control-plane client.
A message has a role and a content array of blocks; a text block is {"text": ...}.
The reply lives at output.message.content[0].text for a simple text answer.
If this fails with an access error, enable model access for this id in your region.

Related: Bedrock's Unified Model-Invocation API - the mental model behind this call.

2. Add a System Prompt and Inference Config

Steer behavior with system, and cap length and randomness with inferenceConfig.

# --- Python (boto3) ---
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    system=[{"text": "You are a terse assistant. Answer in one sentence."}],
    messages=[{"role": "user", "content": [{"text": "Why is the sky blue?"}]}],
    inferenceConfig={"maxTokens": 200, "temperature": 0.2, "topP": 0.9},
)
print(resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  system: [{ text: "You are a terse assistant. Answer in one sentence." }],
  messages: [{ role: "user", content: [{ text: "Why is the sky blue?" }] }],
  inferenceConfig: { maxTokens: 200, temperature: 0.2, topP: 0.9 },
}));
console.log(resp.output?.message?.content?.[0]?.text);

system is a top-level list of instruction blocks, kept separate from the conversation turns.
inferenceConfig uses normalized names - maxTokens, temperature, topP, stopSequences - across all model families.
Lower temperature makes output more deterministic; higher values make it more varied.
maxTokens caps the reply length and your output-token cost, so always set it.

3. Hold a Multi-Turn Conversation

Keep context by appending the model's reply and the next question to the same list.

# --- Python (boto3) ---
messages = [{"role": "user", "content": [{"text": "My name is Ada."}]}]
first = brt.converse(modelId="amazon.nova-lite-v1:0", messages=messages)
 
messages.append(first["output"]["message"])            # the assistant turn
messages.append({"role": "user", "content": [{"text": "What is my name?"}]})
 
second = brt.converse(modelId="amazon.nova-lite-v1:0", messages=messages)
print(second["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const messages: any[] = [{ role: "user", content: [{ text: "My name is Ada." }] }];
const first = await brt.send(new ConverseCommand({ modelId: "amazon.nova-lite-v1:0", messages }));
 
messages.push(first.output!.message!);                 // the assistant turn
messages.push({ role: "user", content: [{ text: "What is my name?" }] });
 
const second = await brt.send(new ConverseCommand({ modelId: "amazon.nova-lite-v1:0", messages }));
console.log(second.output?.message?.content?.[0]?.text);

Bedrock is stateless per call - you resend the whole conversation each time.
Append the returned output.message verbatim so roles alternate correctly.
Longer histories cost more input tokens, so trim or summarize old turns when needed.
The same pattern carries tool-use turns, covered on the tool-use page.

4. Read Token Usage and Stop Reason

Every response reports what it cost and why it stopped.

# --- Python (boto3) ---
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Write a haiku about the sea."}]}],
    inferenceConfig={"maxTokens": 60},
)
u = resp["usage"]
print("stop:", resp["stopReason"])
print("tokens in/out/total:", u["inputTokens"], u["outputTokens"], u["totalTokens"])

// --- TypeScript (AWS SDK v3) ---
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Write a haiku about the sea." }] }],
  inferenceConfig: { maxTokens: 60 },
}));
const u = resp.usage!;
console.log("stop:", resp.stopReason);
console.log("tokens in/out/total:", u.inputTokens, u.outputTokens, u.totalTokens);

usage reports inputTokens, outputTokens, and totalTokens - the basis for on-demand billing.
stopReason is end_turn for a natural finish or max_tokens when the cap was hit.
A max_tokens stop means the reply was cut off; raise maxTokens if you need more.
resp["metrics"]["latencyMs"] reports server-side latency for the call.

Intermediate Examples

5. List Available Foundation Models

Use the control-plane client to see what you can call.

# --- Python (boto3) ---
import boto3
 
bedrock = boto3.client("bedrock", region_name="us-east-1")  # control plane
for m in bedrock.list_foundation_models()["modelSummaries"][:10]:
    print(m["modelId"], "-", m.get("modelName"))

// --- TypeScript (AWS SDK v3) ---
import { BedrockClient, ListFoundationModelsCommand } from "@aws-sdk/client-bedrock";
 
const bedrock = new BedrockClient({ region: "us-east-1" }); // control plane
const out = await bedrock.send(new ListFoundationModelsCommand({}));
for (const m of (out.modelSummaries ?? []).slice(0, 10)) console.log(m.modelId, "-", m.modelName);

The bedrock client (not bedrock-runtime) is the control plane for discovery and management.
ListFoundationModels returns current, region-specific model IDs - the authoritative source, never a hardcoded list.
ListInferenceProfiles shows the cross-region profile IDs some models require for on-demand access.
Filter results by provider or output modality to narrow the catalog.

6. Stream a Reply Token by Token

Use converse_stream when you want to show output as it is generated.

# --- Python (boto3) ---
resp = brt.converse_stream(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Count from 1 to 5."}]}],
)
for event in resp["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"]["text"], end="", flush=True)

// --- TypeScript (AWS SDK v3) ---
import { ConverseStreamCommand } from "@aws-sdk/client-bedrock-runtime";
 
const resp = await brt.send(new ConverseStreamCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Count from 1 to 5." }] }],
}));
for await (const event of resp.stream!) {
  if (event.contentBlockDelta) process.stdout.write(event.contentBlockDelta.delta?.text ?? "");
}

ConverseStream returns an event stream instead of a single response object.
Text arrives in contentBlockDelta events; assemble it as it comes.
The full streaming lifecycle and final usage event get their own page.
Streaming improves perceived latency but does not change token cost.

Related: Streaming Responses with ConverseStream - the complete streaming walkthrough.

7. Swap Model Families With One String

Because Converse is model-agnostic, changing families is a config change.

# --- Python (boto3) ---
messages = [{"role": "user", "content": [{"text": "Summarize AWS in one line."}]}]
for model_id in ["amazon.nova-lite-v1:0", "meta.llama3-1-8b-instruct-v1:0"]:
    resp = brt.converse(modelId=model_id, messages=messages,
                        inferenceConfig={"maxTokens": 80})
    print(model_id, "->", resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const messages = [{ role: "user" as const, content: [{ text: "Summarize AWS in one line." }] }];
for (const modelId of ["amazon.nova-lite-v1:0", "meta.llama3-1-8b-instruct-v1:0"]) {
  const resp = await brt.send(new ConverseCommand({ modelId, messages, inferenceConfig: { maxTokens: 80 } }));
  console.log(modelId, "->", resp.output?.message?.content?.[0]?.text);
}

The call site is identical - only the modelId string changes.
This makes A/B testing and cross-family failover a matter of configuration.
Some features (tools, vision, documents) are supported only by certain families, so verify capability before relying on it.
Model IDs and inference-profile requirements are region/version-specific - list current options with the bedrock client and verify at build time.

Related: Model Selection: Claude, Llama, Nova & Titan Trade-offs.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Bedrock model IDs and inference profiles are region/version-specific - verify against the current Bedrock catalog at build time.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-bedrock-runtime @aws-sdk/client-bedrock (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK finds them automatically. Your identity needs bedrock:InvokeModel (and bedrock:ListFoundationModels for the control-plane example).
Model access must be enabled for the models you call, in the Bedrock console under Model access, for your region. A model you have not enabled returns an access error even with correct IAM.
A region where the model exists - examples assume us-east-1. Model IDs and inference-profile requirements are region/version-specific.

Basic Examples

1. Your First Converse Call

Send one user message to a model and print its reply.

# --- Python (boto3) ---
import boto3
 
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",  # representative id - verify per region
    messages=[{"role": "user", "content": [{"text": "Name three primary colors."}]}],
)
print(resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
 
const brt = new BedrockRuntimeClient({ region: "us-east-1" });
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0", // representative id - verify per region
  messages: [{ role: "user", content: [{ text: "Name three primary colors." }] }],
}));
console.log(resp.output?.message?.content?.[0]?.text);

The data-plane client is bedrock-runtime, distinct from the bedrock control-plane client.
A message has a role and a content array of blocks; a text block is {"text": ...}.
The reply lives at output.message.content[0].text for a simple text answer.
If this fails with an access error, enable model access for this id in your region.

Related: Bedrock's Unified Model-Invocation API - the mental model behind this call.

2. Add a System Prompt and Inference Config

Steer behavior with system, and cap length and randomness with inferenceConfig.

# --- Python (boto3) ---
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    system=[{"text": "You are a terse assistant. Answer in one sentence."}],
    messages=[{"role": "user", "content": [{"text": "Why is the sky blue?"}]}],
    inferenceConfig={"maxTokens": 200, "temperature": 0.2, "topP": 0.9},
)
print(resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  system: [{ text: "You are a terse assistant. Answer in one sentence." }],
  messages: [{ role: "user", content: [{ text: "Why is the sky blue?" }] }],
  inferenceConfig: { maxTokens: 200, temperature: 0.2, topP: 0.9 },
}));
console.log(resp.output?.message?.content?.[0]?.text);

system is a top-level list of instruction blocks, kept separate from the conversation turns.
inferenceConfig uses normalized names - maxTokens, temperature, topP, stopSequences - across all model families.
Lower temperature makes output more deterministic; higher values make it more varied.
maxTokens caps the reply length and your output-token cost, so always set it.

3. Hold a Multi-Turn Conversation

Keep context by appending the model's reply and the next question to the same list.

# --- Python (boto3) ---
messages = [{"role": "user", "content": [{"text": "My name is Ada."}]}]
first = brt.converse(modelId="amazon.nova-lite-v1:0", messages=messages)
 
messages.append(first["output"]["message"])            # the assistant turn
messages.append({"role": "user", "content": [{"text": "What is my name?"}]})
 
second = brt.converse(modelId="amazon.nova-lite-v1:0", messages=messages)
print(second["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const messages: any[] = [{ role: "user", content: [{ text: "My name is Ada." }] }];
const first = await brt.send(new ConverseCommand({ modelId: "amazon.nova-lite-v1:0", messages }));
 
messages.push(first.output!.message!);                 // the assistant turn
messages.push({ role: "user", content: [{ text: "What is my name?" }] });
 
const second = await brt.send(new ConverseCommand({ modelId: "amazon.nova-lite-v1:0", messages }));
console.log(second.output?.message?.content?.[0]?.text);

Bedrock is stateless per call - you resend the whole conversation each time.
Append the returned output.message verbatim so roles alternate correctly.
Longer histories cost more input tokens, so trim or summarize old turns when needed.
The same pattern carries tool-use turns, covered on the tool-use page.

4. Read Token Usage and Stop Reason

Every response reports what it cost and why it stopped.

# --- Python (boto3) ---
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Write a haiku about the sea."}]}],
    inferenceConfig={"maxTokens": 60},
)
u = resp["usage"]
print("stop:", resp["stopReason"])
print("tokens in/out/total:", u["inputTokens"], u["outputTokens"], u["totalTokens"])

// --- TypeScript (AWS SDK v3) ---
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Write a haiku about the sea." }] }],
  inferenceConfig: { maxTokens: 60 },
}));
const u = resp.usage!;
console.log("stop:", resp.stopReason);
console.log("tokens in/out/total:", u.inputTokens, u.outputTokens, u.totalTokens);

usage reports inputTokens, outputTokens, and totalTokens - the basis for on-demand billing.
stopReason is end_turn for a natural finish or max_tokens when the cap was hit.
A max_tokens stop means the reply was cut off; raise maxTokens if you need more.
resp["metrics"]["latencyMs"] reports server-side latency for the call.

Intermediate Examples

5. List Available Foundation Models

Use the control-plane client to see what you can call.

# --- Python (boto3) ---
import boto3
 
bedrock = boto3.client("bedrock", region_name="us-east-1")  # control plane
for m in bedrock.list_foundation_models()["modelSummaries"][:10]:
    print(m["modelId"], "-", m.get("modelName"))

// --- TypeScript (AWS SDK v3) ---
import { BedrockClient, ListFoundationModelsCommand } from "@aws-sdk/client-bedrock";
 
const bedrock = new BedrockClient({ region: "us-east-1" }); // control plane
const out = await bedrock.send(new ListFoundationModelsCommand({}));
for (const m of (out.modelSummaries ?? []).slice(0, 10)) console.log(m.modelId, "-", m.modelName);

The bedrock client (not bedrock-runtime) is the control plane for discovery and management.
ListFoundationModels returns current, region-specific model IDs - the authoritative source, never a hardcoded list.
ListInferenceProfiles shows the cross-region profile IDs some models require for on-demand access.
Filter results by provider or output modality to narrow the catalog.

6. Stream a Reply Token by Token

Use converse_stream when you want to show output as it is generated.

# --- Python (boto3) ---
resp = brt.converse_stream(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Count from 1 to 5."}]}],
)
for event in resp["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"]["text"], end="", flush=True)

// --- TypeScript (AWS SDK v3) ---
import { ConverseStreamCommand } from "@aws-sdk/client-bedrock-runtime";
 
const resp = await brt.send(new ConverseStreamCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Count from 1 to 5." }] }],
}));
for await (const event of resp.stream!) {
  if (event.contentBlockDelta) process.stdout.write(event.contentBlockDelta.delta?.text ?? "");
}

ConverseStream returns an event stream instead of a single response object.
Text arrives in contentBlockDelta events; assemble it as it comes.
The full streaming lifecycle and final usage event get their own page.
Streaming improves perceived latency but does not change token cost.

Related: Streaming Responses with ConverseStream - the complete streaming walkthrough.

7. Swap Model Families With One String

Because Converse is model-agnostic, changing families is a config change.

# --- Python (boto3) ---
messages = [{"role": "user", "content": [{"text": "Summarize AWS in one line."}]}]
for model_id in ["amazon.nova-lite-v1:0", "meta.llama3-1-8b-instruct-v1:0"]:
    resp = brt.converse(modelId=model_id, messages=messages,
                        inferenceConfig={"maxTokens": 80})
    print(model_id, "->", resp["output"]["message"]["content"][0]["text"])

// --- TypeScript (AWS SDK v3) ---
const messages = [{ role: "user" as const, content: [{ text: "Summarize AWS in one line." }] }];
for (const modelId of ["amazon.nova-lite-v1:0", "meta.llama3-1-8b-instruct-v1:0"]) {
  const resp = await brt.send(new ConverseCommand({ modelId, messages, inferenceConfig: { maxTokens: 80 } }));
  console.log(modelId, "->", resp.output?.message?.content?.[0]?.text);
}

The call site is identical - only the modelId string changes.
This makes A/B testing and cross-family failover a matter of configuration.
Some features (tools, vision, documents) are supported only by certain families, so verify capability before relying on it.
Model IDs and inference-profile requirements are region/version-specific - list current options with the bedrock client and verify at build time.

Related: Model Selection: Claude, Llama, Nova & Titan Trade-offs.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Bedrock model IDs and inference profiles are region/version-specific - verify against the current Bedrock catalog at build time.

Bedrock Basics

Search Documentation

Bedrock Basics