mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 20:53:13 +00:00
60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
|
# AWS Bedrock
|
||
|
|
|
||
|
|
Conventions and gotchas for using AWS Bedrock — Agents, Knowledge Bases, and model invocations.
|
||
|
|
|
||
|
|
## Foundation Model IDs
|
||
|
|
|
||
|
|
For **Claude 4.x models on Bedrock Agents**, always use the cross-region inference profile ID, not the direct model ID.
|
||
|
|
|
||
|
|
| Use | Example |
|
||
|
|
|---|---|
|
||
|
|
| Direct invocation (`bedrock-runtime`) | `anthropic.claude-sonnet-4-5-20250929-v1:0` |
|
||
|
|
| Bedrock Agent `foundationModel` | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |
|
||
|
|
|
||
|
|
The direct model ID is only valid for `bedrock-runtime` invocations. Using it on `CfnAgent.foundationModel` makes the agent prepare successfully but throws `ResourceNotFoundException` at invocation time.
|
||
|
|
|
||
|
|
## IAM Permissions
|
||
|
|
|
||
|
|
Bedrock Agents need both the underlying foundation model and the cross-region inference profile in their IAM policy:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"Effect": "Allow",
|
||
|
|
"Action": "bedrock:InvokeModel",
|
||
|
|
"Resource": [
|
||
|
|
"arn:aws:bedrock:*::foundation-model/anthropic.claude-sonnet-4-5-20250929-v1:0",
|
||
|
|
"arn:aws:bedrock:us-east-1:<account>:inference-profile/us.anthropic.claude-sonnet-4-5-20250929-v1:0"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
The foundation model ARN uses the wildcard region (`*`) since cross-region inference can route to any of the profile's regions.
|
||
|
|
|
||
|
|
## Alias Version Pinning
|
||
|
|
|
||
|
|
When updating an agent's `foundationModel` or `instruction` via CDK or CloudFormation, the alias does **not** automatically re-point to the new version.
|
||
|
|
|
||
|
|
CloudFormation only updates the `DRAFT` version when `CfnAgent` changes. The alias stays pinned to the previous version unless the alias resource itself changes.
|
||
|
|
|
||
|
|
Force version rotation by bumping the alias `description` in the same change set:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
new bedrock.CfnAgentAlias(this, 'Alias', {
|
||
|
|
agentAliasName: 'live',
|
||
|
|
agentId: agent.attrAgentId,
|
||
|
|
description: `bumped 2026-05-14 — model update`, // change this to force a new version
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Knowledge Bases
|
||
|
|
|
||
|
|
The `@cdklabs/generative-ai-cdk-constructs` `VectorKnowledgeBase` L2 construct requires Docker Desktop on the deploying machine — it uses `Code.fromDockerBuild` for a custom resource Lambda. CI runners need Docker available.
|
||
|
|
|
||
|
|
For Knowledge Base S3 buckets, follow the standard tagging convention from [AWS Infrastructure](aws-infrastructure.md#s3): `Purpose` and `ManagedBy` tags.
|
||
|
|
|
||
|
|
## Action Groups
|
||
|
|
|
||
|
|
Action group Lambdas receive a Bedrock-specific event shape — they are not invoked as plain Lambda function URLs. The `apiPath` and `httpMethod` fields in the event identify which OpenAPI operation triggered the call. Validate them before dispatching.
|
||
|
|
|
||
|
|
Document the action group's OpenAPI schema in the same repo as the Lambda code; CloudFormation stores it inline.
|