Documentation

aws.BedrockClient

One model turn against the Amazon Bedrock Converse API (`POST /model/{modelId}/converse`).

Reference version

Signature

class aws.BedrockClient

One model turn against the Amazon Bedrock Converse API (POST /model/{modelId}/converse).

The wire format, the URL and the response parse are pure BAML (aws.internal, ns_internal/bedrock.baml); only the SigV4 signature is Rust, because the stdlib has no HMAC-SHA256 (aws.internal.sign_request, ns_internal/auth.baml).

Credentials and region are NEVER read at construction time. new() is pure, so declaring a client is always safe; the AWS provider chain (environment, shared config/credentials files, credential_process, SSO cache, container endpoint, EC2 IMDS) runs when a request is signed.

Source:<builtin>/aws/bedrock.bamlbytes 650–8713

Fields

model

string

A foundation-model id (anthropic.claude-3-5-haiku-20241022-v1:0), a cross-region inference-profile id (us.anthropic.claude-haiku-4-5-…), or a full model/inference-profile ARN. It is a URL path label, not a body field: / and : are percent-encoded so an ARN stays one path segment. There is no default — model availability is per-account and per-region, so there is no id that is right everywhere.

region

string | null

Explicit region. null resolves AWS_REGION, then AWS_DEFAULT_REGION, then the active profile's region; if none of those produce one, the request fails with a message naming all of them (unless endpoint_url is set, which needs no region for the URL — signing still scopes to the resolved region).

profile

string | null

Named profile in the shared config/credentials files. null uses AWS_PROFILE, else default.

access_key_id

string | null

Explicit static credentials. Both access_key_id and secret_access_key must be set to short-circuit the provider chain; a lone key id falls through rather than signing with half an identity.

secret_access_key

string | null

session_token

string | null

Session token for temporary (STS/SSO) credentials.

endpoint_url

ai.Credential | null

Replaces https://bedrock-runtime.<region>.amazonaws.com — a VPC endpoint, a LocalStack instance, or a test server. A trailing slash is tolerated. Setting it bypasses region resolution for the URL.

A literal string, or env.NAME (a late-bound baml.env.Ref read at request time) so a client Name = ... declaration — evaluated during $init, which cannot run io sysops — stays pure while a deployment still points the client somewhere else.

max_tokens

int | null

Maximum tokens to generate. Wire type is a 32-bit int.

temperature

float | null

top_p

float | null

stop_sequences

string[] | null

tool_choice

string | null

toolConfig.toolChoice: "auto", "any" (alias "required"), or a tool name to force. null omits the field, which is the API default and the only shape every Bedrock model family accepts.

NOTE on replayed tool results: toolResult.status ("success"/"error") is only supported by Amazon Nova and Anthropic Claude 3/4, so it is sent only when model names one of those families. Other families still get the result text, which carries the tool's error message.

cache_system_prompt

bool

Append a cachePoint after the system content, making the system prompt reusable across calls. Per-message checkpoints come from the cache_point key of ai.PromptMessage.metadata instead.

cache_tools

bool

Append a cachePoint after the tool list, making the tool definitions reusable across calls.

additional_model_request_fields

baml.json.json | null

additionalModelRequestFields: model-specific parameters Converse has no first-class field for, e.g. {"top_k": 50} or {"reasoning_config": {"type": "enabled", "budget_tokens": 1024}}. This is the engine's additional_model_request_fields option.

request_body

baml.json.json | null

Deep-merged into the serialized request as the last step before it is signed: maps merge recursively, a null value deletes that key, and everything else replaces. Use it to reach any Converse field the typed request does not model (guardrailConfig, promptVariables, …).

headers

map<string, string> | null

Extra request headers, applied BEFORE signing so they are covered by the signature. Names are lowercased; a name the client already sets is replaced, not duplicated.

query_params

map<string, string> | null

Extra query parameters, appended (and percent-encoded) BEFORE signing.

capture_wire

bool

Record request/response bodies on the LLMCall wire records delivered through on_event. Status, headers, and timing are always recorded; this flag only gates the bodies.

Static methods

function

new

(
model: string,
region: string | null = …,
profile: string | null = …,
access_key_id: string | null = …,
secret_access_key: string | null = …,
session_token: string | null = …,
endpoint_url: ai.Credential | null = …,
max_tokens: int | null = …,
temperature: float | null = …,
top_p: float | null = …,
stop_sequences: string[] | null = …,
tool_choice: string | null = …,
cache_system_prompt: bool = …,
cache_tools: bool = …,
additional_model_request_fields: baml.json.json | null = …,
request_body: baml.json.json | null = …,
headers: map<string, string> | null = …,
query_params: map<string, string> | null = …,
capture_wire: bool = …
) -> aws.BedrockClient

Creates a client. Construction reads no environment variable, so declaring one is always safe; credentials and endpoints resolve when a request is built.

Instance methods

function

resolved_endpoint_url

(self) -> string | null throws baml.errors.Io | baml.errors.ParseError

The request-time endpoint override: the explicit value (a literal, or the value of the variable an env.NAME ref points at), else null (build the regional host). Bedrock has no canonical endpoint variable.

Implementations

ai.Client for aws.BedrockClient

Instance methods

function

id

(self) -> string
function

invoke

(
self,
input: ai.ModelTurnInput
) -> ai.ModelTurn throws baml.errors.Timeout | baml.errors.UnknownError | reflect.errors.CompilationError | ai.errors.Failure
function

render

(
self,
input: ai.ModelTurnInput
) -> baml.http.Request throws baml.errors.Timeout | baml.errors.UnknownError | reflect.errors.CompilationError | ai.errors.Failure

This is deliberately the unsigned Converse request. Signing is an invocation concern and would read credentials during a snapshot.

Source:<builtin>/aws/bedrock.bamlbytes 7442–8167