AWS Bedrock

Hankweave can run models hosted on AWS Bedrock under your own AWS credentials and billing, for both codons (sealed agent tasks in a sequence) and sentinels (parallel observers). This page is the lookup reference for that support: how to spell Bedrock model ids, which harness each spelling lands on, where codons and sentinels get AWS credentials, what your AWS account needs, and how Bedrock failures are classified. Each section ends with pointers to the broader pages it depends on, so you can start anywhere and follow the links outward.

When to run on Bedrock#

Bedrock is a fit when consolidated billing, private networking, or AWS compliance controls matter, because requests stay inside your AWS account and its guardrails. When those constraints do not apply, a direct provider API is simpler to set up and debug; see authentication and models. Bedrock support is [since 0.9.0].

Spelling Bedrock models#

Every place Hankweave accepts a model also accepts a Bedrock spelling: amazon-bedrock/<model-id-or-inference-profile-id>. That covers a codon's model, a sentinel's model, and global overrides such as HANKWEAVE_RUNTIME_MODEL. The provider id amazon-bedrock comes from the models.dev registry, and the override is a free-form string validated at runtime by Hankweave's model registry (LLMRegistry).

Anthropic-family ids use anthropic.claude-… for on-demand models and <geo>.anthropic.claude-… for cross-region inference profiles. The supported geography prefixes are us., eu., jp., au., global., and us-gov.. The prefix matters in practice: AWS rejects a bare on-demand id for newer Anthropic models when on-demand throughput is unsupported, so use the serving geography or a global. profile where available.

The catalog is embedded in the compiled binary at build time. The pinned release snapshot contains 119 Amazon Bedrock models out of 6,472 total and has no separate browsing surface, so re-check pinned ids against the amazon-bedrock provider's model list for each release; the CLI's --validate mode can then run its model self-tests.

The two fragments below are valid one-line codon model settings in a hank (a run configuration). The first uses a cross-region inference profile for an Anthropic model; the second uses a non-Anthropic Bedrock model. Their enclosing codon shape is defined by hank.schema.json, the configuration schema.

{"model": "amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"}

{"model": "amazon-bedrock/deepseek.v3.2"}

See model resolution for the broader spelling and resolution rules.

Which harness a Bedrock model lands on#

The routing predicate sends a model to the Claude Agent SDK harness when its provider is anthropic or when it is an Anthropic-family id on amazon-bedrock. Non-Anthropic Bedrock models use the embedded Pi harness. The table summarizes the three spellings:

The pi/ prefix is the explicit override. [changed 0.10.0] Selection is late-bound at dispatch from the model's real identity. "Claude Code (Bedrock mode)" is an allowed alias for the Claude Agent SDK harness; the canonical name is Claude Agent SDK harness. For example, pi/amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0 selects the embedded Pi harness even though the underlying model is Anthropic-family.

On the Claude Agent SDK route, the runtime sets CLAUDE_CODE_USE_BEDROCK=1 and passes an enumerated AWS environment-variable list to the Agent SDK subprocess. The list below is the complete set the subprocess receives; a non-Bedrock codon receives a byte-identical environment to the one it received before Bedrock support.

const BEDROCK_AWS_ENV_VARS = [
  "AWS_REGION",
  "AWS_DEFAULT_REGION",
  "AWS_BEARER_TOKEN_BEDROCK",
  "AWS_ACCESS_KEY_ID",
  "AWS_SECRET_ACCESS_KEY",
  "AWS_SESSION_TOKEN",
  "AWS_PROFILE",
  "AWS_SHARED_CREDENTIALS_FILE",
  "AWS_CONFIG_FILE",
  "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
  "AWS_CONTAINER_CREDENTIALS_FULL_URI",
  // EKS Pod Identity (and any token-protected full-URI endpoint) needs the
  // authorization token alongside the URI, or the subprocess can't fetch creds.
  "AWS_CONTAINER_AUTHORIZATION_TOKEN",
  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
  "AWS_WEB_IDENTITY_TOKEN_FILE",
  "AWS_ROLE_ARN",
  "AWS_ROLE_SESSION_NAME",
  "AWS_EC2_METADATA_DISABLED",
  // Custom/IPv6 IMDS endpoints: the child's SDK chain must target the same
  // metadata endpoint the preflight probe resolved.
  "AWS_EC2_METADATA_SERVICE_ENDPOINT",
  "AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE",
  "AWS_CA_BUNDLE",
] as const;

See model resolution and runtime architecture for routing and harness boundaries.

Where codons get AWS credentials#

Codons use the ambient AWS credential chain: sources visible to the Hankweave process, not credentials stored in a hank. On the Claude Agent SDK route, the quickest source is AWS_BEARER_TOKEN_BEDROCK. Other sources are AWS_ACCESS_KEY_ID plus AWS_SECRET_ACCESS_KEY and optional AWS_SESSION_TOKEN, AWS_PROFILE with single sign-on (SSO), ECS container credentials including EKS Pod Identity authorization tokens, IRSA web identity, and EC2 instance roles through the Instance Metadata Service (IMDS). A minimal bearer-token setup looks like this:

export AWS_BEARER_TOKEN_BEDROCK="..."
export AWS_REGION="us-east-1"

Before a run starts, Bedrock preflight checks these sources in order: gateway-managed authentication through CLAUDE_CODE_SKIP_BEDROCK_AUTH, ambient source detection, Claude settings helpers (awsAuthRefresh and awsCredentialExport), and then an IMDS probe. The probe requests an IMDSv2 token and requires a non-empty iam/security-credentials/ listing within 500 ms. It honors AWS_EC2_METADATA_SERVICE_ENDPOINT and AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE, and is skipped when AWS_EC2_METADATA_DISABLED=true.

Two interactions in that chain are easy to trip over. With AWS_PROFILE set, an environment key pair does not satisfy preflight because the AWS SDK skips its environment-key provider; the selected profile must provide usable credentials, and profile sections are inspected for actual credential keys, not merely for the section's presence. And EC2/IMDS instance roles authenticate only the Claude Agent SDK route: the embedded Pi route does not probe on-disk config files or IMDS, so Pi-routed Bedrock models need an explicit environment credential source.

Region resolution follows the same ambient rule. AWS_REGION or AWS_DEFAULT_REGION wins. If neither is set and AWS_PROFILE or the default profile defines a region, the Agent SDK CLI resolves it from that profile while the runtime leaves the variable unset. Otherwise the runtime uses us-east-1 and emits a startup warning naming the setting.

Short-term Bedrock API keys expire. An expired or invalid bearer token is a permanent failure, so the request is not retried; generate a long-term key in AWS Console → Bedrock → API keys.

See environment variables for process variable names and scopes.

Why sentinel credentials are narrower#

Sentinels do not share the codon credential chain. A Bedrock-modeled sentinel accepts explicit environment credentials only: AWS_BEARER_TOKEN_BEDROCK, or AWS_ACCESS_KEY_ID plus AWS_SECRET_ACCESS_KEY with optional AWS_SESSION_TOKEN. The sentinel-scoped HANKWEAVE_SENTINEL_AWS_BEARER_TOKEN_BEDROCK override is checked before the process-wide bearer token.

Profile/SSO, container credentials, IRSA, and IMDS are not sentinel sources. The sentinel provider signs requests through its built-in aws4fetch path instead of the ambient chain; including the omitted credential-provider package would add a transitive tree of about 6 MB to the binary.

The practical consequence: without an explicit source, the amazon-bedrock sentinel provider is marked not-configured with an error naming the accepted sources. Bedrock-modeled sentinels are skipped, while Bedrock codons on the same machine can run normally.

The sentinel health check follows the configured region's geographic profile for the Anthropic Haiku model: us-gov. for GovCloud, us., eu., jp., or au. where served, and global. otherwise. A geographic profile routes only within its own geography.

A sentinel configuration selects its model with the same amazon-bedrock/… spelling used for codons:

{
  "model": "amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"
}

See sentinel configuration.

Setting up the AWS account#

On the AWS side, three enablement rules apply. Serverless foundation models auto-enable on first invoke. Anthropic models require a one-time use-case form for first-time use. Marketplace-served models require one first invoke by a Marketplace-permissioned user; AWS has retired the console's "Model access" page.

For permissions, the least-privilege action set is bedrock:InvokeModel plus bedrock:InvokeModelWithResponseStream. A cross-region us.* inference profile needs permission on both the profile ARN and its underlying foundation-model ARNs. The runtime's AccessDenied remedy recommends Resource: "*" for an invoke-only principal, so the restriction is expressed by the two allowed actions rather than by a resource ARN.

Once the account is enabled and permissioned, the following AWS-side command verifies a Converse request for the selected model before you point Hankweave at it.

aws bedrock-runtime converse \
  --region us-east-1 \
  --model-id us.anthropic.claude-haiku-4-5-20251001-v1:0 \
  --messages '[{"role":"user","content":[{"text":"Say OK"}]}]'

An invoke-only policy can use these actions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    }
  ]
}

These are AWS-side procedures; verify the command and policy against the target account and region before relying on them. See authentication and models for the provider setup boundary.

How Bedrock failures classify#

Bedrock authentication and access failures are permanent (retriable: false) and carry a remediation hint. They do not enter the retry path because the surfaced text has no HTTP status; the default would otherwise retry a failure that only the operator can fix.

Ten Bedrock matchers run in declaration order, and the first matching row wins. The table below is the Bedrock slice of the classifier, rendered sorted by id for lookup; use matchOrder, not row order, to follow declaration precedence. matchOrder preserves each matcher's position in the complete classifier, so this slice starts at 3 rather than being renumbered. In the pattern column, AND and OR describe compound conditions, and /…/ marks the regular expression used for the on-demand-throughput pattern.

Reading the rows in precedence order explains the remedies. The role-assumption matcher precedes generic AccessDeniedException, so a role denial gets the role remedy: check the role ARN, trust policy, and external-id or MFA requirements. Generic access denials point to IAM/SCP restrictions, cross-region permissions, first-time Anthropic access, or Marketplace first invoke. Invalid credentials point to the bearer token or key pair; expired short-term keys need a long-term key. Signature failures point to the access-key secret, expired or invalid SSO sessions to refreshed profile credentials, and missing credentials to an explicit bearer token, key pair, or profile plus region. The Pi-not-configured row requires an explicit environment source; the on-demand-throughput row requires a geography prefix or available global. profile. Signature matching runs before the timeout branch because AWS signature-error dumps contain x-stainless-timeout header lines; otherwise a broken credential chain could become retriable.

One failure looks like a model problem but is a region problem: a wrong-region model appears as ResourceNotFoundException or Pi's "The provided model identifier is invalid." Both are permanent; set AWS_REGION to a serving region or use the global. inference profile id. The complete failure taxonomy and exit-code contract live in errors and exit codes; this page embeds only the Bedrock slice.

When Bedrock features are unavailable#

Two route constraints limit which models and credential sources work:

• A codon model must accept tool definitions in Converse requests. A model that rejects them cannot drive codons; DeepSeek-R1 surfaces "This model doesn't support tool use" as a permanent invalid request, while the shipped catalog carries deepseek.v3.2 as the working alternative.
• EC2 instance roles through IMDS authenticate only the Claude Agent SDK route. The embedded Pi route does not probe on-disk config files or IMDS; its checkAuth covers only Pi's credential store and ambient environment markers. Pi-routed Bedrock models, and all sentinels, need an explicit environment credential source.

Where to continue from Bedrock#

• Authentication and models – provider credentials and model-selection planes.
• Model resolution – model spellings, identity, and harness routing.
• Runtime architecture – harness feature sets and runtime boundaries.
• Sentinel configuration – sentinel model and credential settings.
• Environment variables – process environment names and scopes.
• Errors and exit codes – the complete failure taxonomy and exit contract.