npmAI / MLupdated 05 Nov 2026

@aws-sdk/client-bedrock-runtime review

Converse gives supported Bedrock models a common message format, but model features still determine which requests will work. @aws-sdk/client-bedrock-runtime is the AWS JavaScript v3 client for calling Bedrock inference APIs. You construct a BedrockRuntimeClient and send a command with a model or inference-profile identifier. This guide concentrates on ConverseCommand: text messages, conversation history, image input, tool requests, and guardrail configuration. A shared request shape does not make every model accept images, tools, or the same inference settings. The separate @aws-sdk/client-bedrock package handles model management.

@aws-sdk/client-bedrock-runtime · v3.1163.0 · aws/aws-sdk-js-v3 · docs · reviewed by Keyoor

Verdict

Choose @aws-sdk/client-bedrock-runtime for typed Bedrock inference when your application can own message history, tool execution, and model-specific checks. Begin with one text request against your chosen resource before adding images, tools, or guardrails.

Answers from our run

@aws-sdk/client-bedrock-runtime or @aws-sdk/client-bedrock: which should you use?

@aws-sdk/client-bedrock: Choose it for creating, managing, tuning, or evaluating Bedrock models. It serves a management task rather than replacing these inference examples. Choose @aws-sdk/client-bedrock-runtime for typed Bedrock inference when your application can own message history, tool execution, and model-specific checks.

When should you not use @aws-sdk/client-bedrock-runtime?

You need local or offline inference. These examples send requests to the Bedrock service.

API stability4/5The version-tagged Converse command exposes a typed request and response behind client.send(command), with a common interface for models that support messages. The registry includes both JavaScript entry points and bundled declarations. That earns 4 on the stated documentation rubric. Model-specific feature support and managed-prompt field restrictions prevent treating one valid request shape as a guarantee across models.

Docs3/5The version-tagged command documents permissions, managed-prompt restrictions, input unions, response fields, and modeled errors. Its generated example also lists alternatives inside the same union block, so copying that entire object would violate its own one-key rule. A 3 reflects useful reference coverage that still asks you to assemble a minimal request and check the chosen model separately.

Maintenance4/5The pinned changelog records 3.1163.0 on 2026-11-05 and 3.1162.0 on 2026-11-04, both as version-only bumps for this package. Together with the published version metadata, that supports a 4 for an actively released client. It does not show a new Bedrock feature, service reliability, issue-resolution speed, or successful execution of the examples here.

Ecosystem3/5The package metadata lists AWS credential-provider and Smithy dependencies, while the two verified companion packages offer model management and a Claude-specific Bedrock interface. That is useful surrounding support and earns 3 on this documentation rubric. Download volume and model coverage have not been used as quality evidence, and the examples do not establish compatibility with every Bedrock model.

Use it if

Your JavaScript service calls Bedrock models and needs typed AWS command inputs and outputs.
You want a common message format across Bedrock models that support Converse, and can check feature support for each selected model.
Your application will own conversation history and the execution of permitted tools requested by a model.
You need to attach an existing Bedrock guardrail to inference requests.

Skip it if

You need local or offline inference. These examples send requests to the Bedrock service.
Your application cannot meet the Node.js 20 minimum for this package version.
You only need model creation, management, tuning, or evaluation. Start with @aws-sdk/client-bedrock instead.
You want an assistant that executes tools and manages conversation state for you. These command examples leave that work in your application.
You expect every Bedrock model to accept images, tools, and identical inference parameters just because the request type contains those fields.

Setup reality

Install the reviewed version with npm install @aws-sdk/client-bedrock-runtime@3.1163.0. Its package metadata requires Node.js 20 or newer and supplies TypeScript declarations plus CommonJS and ESM entry points. The examples below use JavaScript ES modules with top-level await. They are documentation-based, unexecuted illustrations checked against the version-tagged command and model definitions. We did not install the package or make a live Bedrock request, so this guide makes no latency, cost, or successful-inference claim.

Before running them, configure AWS credentials outside the source file, replace YOUR_MODEL_OR_PROFILE_ID with a resource available to your account, and choose its AWS region. A package install cannot grant service access. Converse requires bedrock:InvokeModel permission. A model ID and an inference-profile ID are different resource choices even though both go in modelId. Check the selected resource and model's requirements before copying an example. Credentials, permissions, and regional availability are deployment work you still own.

Each snippet starts a separate example. The placeholder region us-east-1 is illustrative, not a claim that your chosen model is available there. For a follow-up, build messages with the earlier user messages and the complete assistant message returned in output.message. Keep that history in your application and decide how much to send on the next request. Reading just content[0].text is too narrow for an application that also receives tool requests or other content blocks. The examples select text blocks for display and leave the original message available for history.

Converse responses include stopReason and token usage alongside the output. Inspect the stop reason before treating a reply as complete. A response stopped by max_tokens needs different handling from one that ended its turn or requested a tool. A tool specification only describes a tool to the model. Your application must validate the requested operation, perform permitted work, and send a toolResult with the matching toolUseId. Do not turn a model-provided tool name into unrestricted code execution.

Prompt management adds another trap. When modelId names a managed prompt version, you cannot include additionalModelRequestFields, inferenceConfig, system, or toolConfig in the request. Define those fields in the managed prompt instead. The examples here use a model or inference profile, not a managed prompt ARN. Guardrail examples also require an existing identifier and version. Passing the configuration is not evidence that your application's safety requirements have been met.

The 3.1163.0 changelog entry is a version bump only. It does not announce a new Converse capability. Ratings below use a documentation-based five-point rubric: 1 means substantial documented constraints, 3 means useful support with material conditions, and 5 means unusually complete evidence for that dimension. Intermediate scores sit between those anchors. These are editorial judgments, not benchmarks or adoption measurements. For object storage operations, see the separate S3 client guide.

Patterns

Send a text message and read text blocks send-text

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const response = await client.send(new ConverseCommand({
  modelId,
  messages: [{ role: 'user', content: [{ text: 'Explain a DNS TTL.' }] }],
}));
const text = (response.output?.message?.content ?? [])
  .filter(block => typeof block.text === 'string')
  .map(block => block.text)
  .join('');
console.log({ text, stopReason: response.stopReason, usage: response.usage });

Replace the model placeholder and configure credentials first. Text extraction is for display only. Preserve the complete output.message if you will send a follow-up.

Put task instructions in the system field set-system-instructions

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const response = await client.send(new ConverseCommand({
  modelId,
  system: [{ text: 'Explain networking terms to a new developer. Expand abbreviations.' }],
  messages: [{ role: 'user', content: [{ text: 'What is DNS?' }] }],
}));
console.log(response.output?.message);

Use a model that supports the requested system instructions. If modelId is a managed prompt version, system must be configured in that prompt instead.

Set a token cap and a stop sequence limit-generation

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const response = await client.send(new ConverseCommand({
  modelId,
  messages: [{ role: 'user', content: [{ text: 'Give a brief DNS glossary.' }] }],
  inferenceConfig: {
    maxTokens: 128,
    stopSequences: ['END_GLOSSARY'],
  },
}));
console.log(response.stopReason, response.usage, response.output?.message);

128 is an example output cap, not a cost or response-length measurement. Confirm the selected model supports these settings. A max_tokens stop is a reason to inspect for a cut-off answer.

Send the previous assistant message with a follow-up continue-conversation

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const messages = [{ role: 'user', content: [{ text: 'Explain DNS caching.' }] }];
const first = await client.send(new ConverseCommand({ modelId, messages }));
const assistant = first.output?.message;
if (!assistant || first.stopReason !== 'end_turn') {
  throw new Error('Handle the initial response before continuing.');
}
const second = await client.send(new ConverseCommand({
  modelId,
  messages: [
    ...messages,
    assistant,
    { role: 'user', content: [{ text: 'How does a TTL affect that cache?' }] },
  ],
}));
console.log(second.output?.message);

This example only continues a completed turn. Tool requests and other stop reasons need their own handling. Keep the whole assistant message rather than rebuilding it from displayed text.

Include local image bytes in a user message send-image

import { readFile } from 'node:fs/promises';
import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const imageBytes = await readFile('./diagram.png');
const response = await client.send(new ConverseCommand({
  modelId,
  messages: [{
    role: 'user',
    content: [
      { text: 'Describe the connections in this diagram.' },
      { image: { format: 'png', source: { bytes: imageBytes } } },
    ],
  }],
}));
console.log(response.output?.message);

This Node example needs a real PNG file and a model that accepts images. Send bytes directly in the image source. Do not combine text and image keys in one content block.

Describe a tool and inspect requests for it describe-tool

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const response = await client.send(new ConverseCommand({
  modelId,
  messages: [{ role: 'user', content: [{ text: 'Add 12 and 7 using add_numbers.' }] }],
  toolConfig: {
    tools: [{ toolSpec: {
      name: 'add_numbers',
      description: 'Add two finite numbers.',
      inputSchema: { json: {
        type: 'object',
        properties: { a: { type: 'number' }, b: { type: 'number' } },
        required: ['a', 'b'],
        additionalProperties: false,
      } },
    } }],
  },
}));
for (const block of response.output?.message?.content ?? []) {
  if (block.toolUse) console.log(block.toolUse);
}
console.log(response.stopReason);

Choose a model with tool support. Asking for the tool does not guarantee a tool request. This example only inspects requests, and performs no tool work. Validate inputs before acting on a real request.

Match a tool result to its request identifier return-tool-result

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

// A fabricated transcript illustrates the wire shape, not a recorded model reply.
const toolSpec = {
  name: 'add_numbers',
  description: 'Add two finite numbers.',
  inputSchema: { json: {
    type: 'object',
    properties: { a: { type: 'number' }, b: { type: 'number' } },
    required: ['a', 'b'],
    additionalProperties: false,
  } },
};
const response = await client.send(new ConverseCommand({
  modelId,
  toolConfig: { tools: [{ toolSpec }] },
  messages: [
    { role: 'user', content: [{ text: 'Add 12 and 7.' }] },
    { role: 'assistant', content: [{ toolUse: {
      toolUseId: 'example-call', name: 'add_numbers', input: { a: 12, b: 7 },
    } }] },
    { role: 'user', content: [{ toolResult: {
      toolUseId: 'example-call', content: [{ json: { sum: 19 } }],
    } }] },
  ],
}));
console.log(response.output?.message);

The transcript and arithmetic result are illustrative. In an application, use the actual toolUseId and preserve the complete assistant message that requested the tool. Return the result only after validating and performing the permitted operation.

Apply an existing guardrail to a request attach-guardrail

import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';

const client = new BedrockRuntimeClient({ region: 'us-east-1' });
const modelId = 'YOUR_MODEL_OR_PROFILE_ID';

const response = await client.send(new ConverseCommand({
  modelId,
  messages: [{ role: 'user', content: [{ text: 'Explain a DNS TTL.' }] }],
  guardrailConfig: {
    guardrailIdentifier: 'YOUR_GUARDRAIL_ID',
    guardrailVersion: 'YOUR_GUARDRAIL_VERSION',
    trace: 'enabled',
  },
}));
console.log(response.stopReason);
// Inspect response.trace in a controlled diagnostic environment.

Replace both guardrail placeholders with an existing configuration. With no guardContent blocks, the guardrail applies to all messages in the request and any included prompt resource. Review trace handling before storing it in application logs.

Alternatives

Package	Registry	Pick it when
@aws-sdk/client-bedrock	npm	Choose it for creating, managing, tuning, or evaluating Bedrock models. It serves a management task rather than replacing these inference examples.
@anthropic-ai/bedrock-sdk	npm	Choose it when you specifically want the Claude API through AWS Bedrock. Its documented interface uses AnthropicBedrock and messages.create rather than the Converse message schema.

More ai / ml guides

@modelcontextprotocol/sdk · openai · mcp · huggingface-hub · @anthropic-ai/sdk · openai · the whole shelf →

How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.