@x12i/bedrock-runtime

TypeScript runtime for AWS Bedrock Converse / ConverseStream, local function tools, and normalized responses.

Install

npm install @x12i/bedrock-runtime

Usage

import { createBedrockRuntime } from "@x12i/bedrock-runtime";

const runtime = createBedrockRuntime({
  region: process.env.AWS_REGION ?? "us-east-1",
  defaultModel: "anthropic.claude-sonnet-4-20250514-v1:0"
  // credentials optional — uses the AWS default credential chain when omitted
});

const response = await runtime.run({
  messages: [{ role: "user", content: "Hello" }]
});

console.log(response.text);

Streaming

for await (const event of runtime.executeStreamingChat({ prompt: "Hello" })) {
  if (event.type === "stream.text.delta") {
    process.stdout.write(String((event.data as { text: string }).text));
  }
}

Compile without sending

import { compileRuntimeRequest } from "@x12i/bedrock-runtime";

const compiled = compileRuntimeRequest(
  { prompt: "Hello", maxTokens: 64 },
  {},
  { defaultModel: "anthropic.claude-3-haiku-20240307-v1:0" }
);
// compiled.input is a ConverseCommand input shape

Agent id and metadata

agentId and metadata are optional. String, number, and boolean values are stored as one record on Converse requestMetadata: m.0, m.1, and so on. Read it back with decodeProviderMetadata. Objects and arrays are not stored in the record. The record must fit in 16 pieces of 256 characters. Those pieces use the invocation-log character set, so the original strings, including JSON, come back from the log through decodeProviderMetadata.

await runtime.run({
  prompt: "Hello",
  agentId: "agent-42",
  metadata: { sessionId: "s-1" }
});

Auth

• Prefer IAM role / instance profile / AWS_PROFILE
• Or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / optional AWS_SESSION_TOKEN
• Or pass credentials / injectable client in options

Region: options.region or AWS_REGION / AWS_DEFAULT_REGION.

Logging

Set BEDROCK_RUNTIME_LOGS=true or pass logger on options.

Scope (v1)

• Converse + ConverseStream
• Messages / prompt / system
• Local function tools + tool loop on run()
• Normalized RuntimeResponse / RuntimeStreamEvent

Not included: InvokeModel raw paths, OpenRouter-style server tools, citations/patches/images.