Skip to content

docs(ai-sessions): bedrock/vertex blocks apply on record-based launches #443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pllesperance-lc merged 1 commit into from
Sep 22, 2026
Merged

docs(ai-sessions): bedrock/vertex blocks apply on record-based launches #443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 8 additions & 14 deletions docs/9-ai-sessions/alternative-providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ This page is about running **Claude** through your cloud agreement. To run user

There are two ways to point a session at Bedrock or Vertex:

1. **Structured provider blocks** — a top-level `bedrock:` or `vertex:` block. On a direct `SessionRequest` (the org-scoped API), the block is validated and applied: the runner translates it into the correct environment variables for the Claude subprocess.
2. **Manual environment variables** — set `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` and the corresponding cloud-provider variables under the profile's `environment:` map. This is the original mechanism, and it is the one to use on `ai_agent` Hive records today.
1. **Structured provider blocks** — a top-level `bedrock:` or `vertex:` block. The block is validated and applied on every launch path: a direct `SessionRequest` (the org-scoped API), and sessions launched from an `ai_agent` Hive record (D&R rules, UI actions, `ai start-session --definition`). The runner translates it into the correct environment variables for the Claude subprocess. **This is the recommended form.**
2. **Manual environment variables** — set `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` and the corresponding cloud-provider variables under the profile's `environment:` map. This is the original mechanism and still works, but the structured blocks above supersede it.

!!! warning "Availability on `ai_agent` Hive records"
`bedrock:` and `vertex:` blocks on `ai_agent` Hive records are accepted and validated by the schema, but sessions launched **from a Hive record** (D&R rules, UI actions, `ai start-session --definition`) do not apply them yet. For those launches, use the manual environment-variable mode described below, which requires `anthropic_secret` to be set (a placeholder for Bedrock). The structured blocks work today on direct `SessionRequest` API calls.
Pick exactly one credential source per session: `anthropic_secret`, the `bedrock:` block, or the `vertex:` block. They are mutually exclusive — a session cannot mix providers, and the schema rejects a record that sets more than one.

Pick exactly one credential source per session: `anthropic_secret`, the `bedrock:` block, or the `vertex:` block. They are mutually exclusive — a session cannot mix providers.
!!! warning "Records created before the mutual-exclusion rule"
Older `ai_agent` records could be saved with `anthropic_secret` **and** a `bedrock:` or `vertex:` block at the same time. On those records `anthropic_secret` takes precedence and the session runs against Anthropic's API — with no error to tell you it happened. The precedence is deliberate: it keeps an existing record from silently changing provider. If you have records predating the rule that are meant to run on Bedrock or Vertex, remove `anthropic_secret` from any record that also carries a provider block.

## Amazon Bedrock

Expand Down Expand Up @@ -65,9 +65,6 @@ The general format is `<region-prefix>.anthropic.<model-name>-v<version>:<minor>

The `bedrock` block lives at the top of an `ai_agent` Hive record, alongside `prompt`. All credential fields end with `_secret` and accept either a literal value or a `hive://secret/<name>` reference.

!!! warning
Records with a `bedrock:` block validate and store, but launches from Hive records do not apply the block yet — use the [manual environment-variable mode](#configuration-via-environment-variables-manual-mode) for record-based launches today. The equivalent [direct `SessionRequest` form](#direct-sessionrequest-api-and-integrations) works now.

```yaml
ai_agent:
bedrock-investigator:
Expand Down Expand Up @@ -127,7 +124,7 @@ Validation enforces exactly one of `anthropic_key`, `bedrock`, or `vertex` per r

The original mechanism — setting AWS variables under the profile's `environment:` map — still works. The runner forwards every entry of `environment:` to the Claude subprocess as-is, so the cloud-provider variables get picked up there.

This is the mode to use for sessions launched from `ai_agent` Hive records today (D&R rules, UI actions, `ai start-session --definition`).
Prefer the structured `bedrock:` block above, including on `ai_agent` Hive records. Reach for this mode only for existing configurations that already depend on it.

```yaml
ai_agent:
Expand Down Expand Up @@ -176,9 +173,6 @@ The region you set must be one that Anthropic publishes models to (commonly `glo

### Configuration via the `vertex:` block

!!! warning
Records with a `vertex:` block validate and store, but launches from Hive records do not apply the block yet. Because the manual environment-variable mode cannot carry the service-account JSON (see below), Claude-on-Vertex is currently only usable through the direct `SessionRequest` form, not from `ai_agent` Hive records.

```yaml
ai_agent:
vertex-investigator:
Expand Down Expand Up @@ -227,7 +221,7 @@ The runner writes the resolved service-account JSON to a per-session temporary f

### Configuration via environment variables (manual mode)

If you must configure Vertex through the profile `environment:` map instead of the structured `vertex:` block, set the variables the runner would otherwise set on your behalf. Note that you cannot inline the service-account JSON as an environment variable — you have to mount it as a file at a known path inside the runner image and point `GOOGLE_APPLICATION_CREDENTIALS` at that path. Most users do not have a way to do that, which is why the structured `vertex:` block on a direct `SessionRequest` is the supported path.
If you must configure Vertex through the profile `environment:` map instead of the structured `vertex:` block, set the variables the runner would otherwise set on your behalf. Note that you cannot inline the service-account JSON as an environment variable — you have to mount it as a file at a known path inside the runner image and point `GOOGLE_APPLICATION_CREDENTIALS` at that path. Most users do not have a way to do that, which is why the structured `vertex:` block is the supported path — on `ai_agent` Hive records as well as on a direct `SessionRequest`.

| Variable | Description |
|---|---|
Expand All @@ -244,7 +238,7 @@ The endpoint resolves `hive://secret/<name>` references just before sending the

## Notes

- On a direct `SessionRequest` with a `bedrock` or `vertex` block, you do **not** supply `anthropic_key`. The `ai_agent` schema likewise accepts a record with `bedrock:` or `vertex:` and no `anthropic_secret`, but since record-based launches do not apply the blocks yet, record-based Bedrock launches use the manual environment-variable mode, which requires a placeholder `anthropic_secret`.
- With a `bedrock` or `vertex` block you do **not** supply `anthropic_key` (direct `SessionRequest`) or `anthropic_secret` (`ai_agent` record) — the block is the credential source. A placeholder `anthropic_secret` is needed only for the manual environment-variable mode.
- Claude model availability varies by AWS region and Vertex region. Check the [Bedrock model availability page](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) and [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) before picking a region.
- Billing for Claude usage goes through your AWS or GCP account when using these providers, not through Anthropic directly.
- The provider you choose only affects the Claude API path. LimaCharlie data, MCP servers, the LC CLI, tool execution, and session storage are unaffected.
8 changes: 4 additions & 4 deletions docs/9-ai-sessions/dr-sessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ respond:
| Parameter | Description |
|-----------|-------------|
| `prompt` | The instructions for Claude. Supports [template strings](../4-data-queries/template-transforms.md) to include event data. |
| `anthropic_secret` | Your Anthropic API key. Use `hive://secret/<name>` to reference a [Hive Secret](../7-administration/config-hive/secrets.md). To route Claude through AWS Bedrock instead, use the manual environment-variable mode — see [Alternative AI Providers](alternative-providers.md). |
| `anthropic_secret` | Your Anthropic API key. Use `hive://secret/<name>` to reference a [Hive Secret](../7-administration/config-hive/secrets.md). To route Claude through AWS Bedrock or Google Cloud Vertex AI instead, use a `bedrock:` or `vertex:` block in place of this field — see [Alternative AI Providers](alternative-providers.md). |

#### Optional Parameters (Inline Mode)

Expand Down Expand Up @@ -486,9 +486,9 @@ This approach keeps D&R rules clean and lets you update the agent's behavior (pr
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | Yes | Instructions for Claude. |
| `anthropic_secret` | string | Yes | Anthropic API key or `hive://secret/` reference. To route Claude through AWS Bedrock, keep a placeholder `anthropic_secret` and set the Bedrock variables under `environment:` — see [Alternative AI Providers](alternative-providers.md). |
| `bedrock` | object | No | AWS Bedrock provider block (`region`, `access_key_id_secret`, `secret_access_key_secret`, `session_token_secret`, `bearer_token_secret`). Accepted and validated, but not applied to record-based launches yet — see [Alternative AI Providers](alternative-providers.md#amazon-bedrock). |
| `vertex` | object | No | Google Cloud Vertex AI provider block (`project_id`, `region`, `service_account_json_secret`). Accepted and validated, but not applied to record-based launches yet — see [Alternative AI Providers](alternative-providers.md#google-cloud-vertex-ai). |
| `anthropic_secret` | string | No | Anthropic API key or `hive://secret/` reference. Set exactly one credential source: `anthropic_secret`, `bedrock`, or `vertex`. |
| `bedrock` | object | No | AWS Bedrock provider block (`region`, `access_key_id_secret`, `secret_access_key_secret`, `session_token_secret`, `bearer_token_secret`). Applied on record-based launches — see [Alternative AI Providers](alternative-providers.md#amazon-bedrock). |
| `vertex` | object | No | Google Cloud Vertex AI provider block (`project_id`, `region`, `service_account_json_secret`). Applied on record-based launches — see [Alternative AI Providers](alternative-providers.md#google-cloud-vertex-ai). |
| `lc_api_key_secret` | string | No | LimaCharlie API key or `hive://secret/` reference. |
| `lc_uid_secret` | string | No | LimaCharlie User ID or `hive://secret/` reference. Required when `lc_api_key_secret` is a user API key. |
| `name` | string | No | Session name. Supports template strings. |
Expand Down
Loading