refactor(bb-agent): model presets (#16)

Author: pjkroker

.changeset/refactor-bb-agent-model-presets.md

@@ -0,0 +1,14 @@
+---
+"@aws-blocks/bb-agent": minor
+---
+
+refactor(bb-agent): capability-based model presets with global inference profiles
+
+New presets:
+- `BALANCED` (Claude Sonnet 4.6): recommended default for most workloads
+- `SMART` (Claude Opus 4.8): highest capability for hardest tasks
+- `FAST` (Claude Haiku 4.5): lowest latency
+
+All presets use `global.` inference profiles for region-agnostic deployment.
+
+Deprecated (non-removing): `DEFAULT` resolves to `BALANCED`, `BUDGET` and `MICRO` resolve to `FAST`. Note this changes the underlying model for existing callers — `DEFAULT` moves from Opus to Sonnet, and `BUDGET`/`MICRO` move from Amazon Nova Pro/Lite to Claude Haiku, so cost and latency profiles differ. The symbols still resolve (no type break), but migrate to `BALANCED`/`FAST` (or a region-scoped profile) explicitly to pin the model you want.

packages/bb-agent/API.md

@@ -102,25 +102,29 @@ export type AgentTool<TContext = DefaultToolContext> = ToolDefinition<TContext,
 
 // @public
 export const BedrockModels: {
-    readonly DEFAULT: {
+    readonly BALANCED: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-opus-4-8-20250610-v1:0";
+        readonly modelId: "global.anthropic.claude-sonnet-4-6";
     };
-    readonly BALANCED: {
+    readonly SMART: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-sonnet-4-20250514-v1:0";
+        readonly modelId: "global.anthropic.claude-opus-4-8";
     };
     readonly FAST: {
         readonly provider: "bedrock";
-        readonly modelId: "us.anthropic.claude-haiku-4-5-20251001-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
+    };
+    readonly DEFAULT: {
+        readonly provider: "bedrock";
+        readonly modelId: "global.anthropic.claude-sonnet-4-6";
     };
     readonly BUDGET: {
         readonly provider: "bedrock";
-        readonly modelId: "us.amazon.nova-pro-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
     };
     readonly MICRO: {
         readonly provider: "bedrock";
-        readonly modelId: "us.amazon.nova-lite-v1:0";
+        readonly modelId: "global.anthropic.claude-haiku-4-5-20251001-v1:0";
     };
 };
 

packages/bb-agent/README.md

@@ -17,7 +17,7 @@ import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 const scope = new Scope('my-app');
 
 const agent = new Agent(scope, 'support-agent', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You are a helpful support agent.',
 });
 
@@ -192,30 +192,30 @@ model: {
 
 #### Bedrock Presets
 
-Pre-configured model presets for quick setup. Names are capability-based so the underlying model can be upgraded without breaking your code. These use cross-region inference profiles — work across all AWS regions:
+Pre-configured model presets for quick setup. Names are capability-based so the underlying model can be upgraded without breaking your code. These use [global inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) — requests may be routed to any supported AWS region for optimal throughput. If your workload has data residency requirements, specify a region-scoped inference profile explicitly instead of using a preset.
 
 ```typescript
 import { Agent, BedrockModels} from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'agent', {
   model: {
-    deployed: BedrockModels.DEFAULT,
+    deployed: BedrockModels.BALANCED,
   },
   systemPrompt: '...',
 });
 ```
 
 | Preset | Current Model | Notes |
 |--------|---------------|-------|
-| `BedrockModels.DEFAULT` | `us.anthropic.claude-opus-4-8-20250610-v1:0` | Highest capability. Recommended default. |
-| `BedrockModels.BALANCED` | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Strong quality/cost balance. |
-| `BedrockModels.FAST` | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | Fastest, lowest latency. |
-| `BedrockModels.BUDGET` | `us.amazon.nova-pro-v1:0` | Low cost per token with acceptable quality. |
-| `BedrockModels.MICRO` | `us.amazon.nova-lite-v1:0` | Ultra-cheap for simple tasks. |
+| `BedrockModels.BALANCED` | `global.anthropic.claude-sonnet-4-6` | Great tool use, balanced cost. Recommended default for most workloads. |
+| `BedrockModels.SMART` | `global.anthropic.claude-opus-4-8` | Highest capability for the hardest tasks. |
+| `BedrockModels.FAST` | `global.anthropic.claude-haiku-4-5-20251001-v1:0` | Lowest latency, still strong capabilities. |
+
+> **Migrating?** `DEFAULT` → `BALANCED` (or `SMART` for highest capability). `BUDGET`/`MICRO` → `FAST`. The old presets are still available but deprecated. Please consider upgrading!
 
 Override inference settings with spread:
 ```typescript
-model: { deployed: { ...BedrockModels.DEFAULT, inferenceConfig: { temperature: 0.9, maxTokens: 8192 } } }
+model: { deployed: { ...BedrockModels.BALANCED, inferenceConfig: { temperature: 0.9, maxTokens: 8192 } } }
 ```
 
 #### Ollama Presets
@@ -227,7 +227,7 @@ import { Agent, BedrockModels, OllamaModels} from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'agent', {
   model: {
-    deployed: BedrockModels.DEFAULT, 
+    deployed: BedrockModels.BALANCED, 
     local: OllamaModels.SMALL,
   },
   systemPrompt: '...',
@@ -264,7 +264,7 @@ To see detailed health check logs, pass a logger with `info` level:
 import { Logger } from '@aws-blocks/bb-logger';
 
 const agent = new Agent(scope, 'agent', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: '...',
   logger: new Logger(scope, 'agent-log', { level: 'info' }),
 });
@@ -543,7 +543,7 @@ The Agent BB works without a frontend — for scripts, background jobs, or serve
 import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'summarizer', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'Summarize the input concisely.',
 });
 
@@ -562,7 +562,7 @@ import { Agent, BedrockModels, InterruptError } from '@aws-blocks/bb-agent';
 import { z } from 'zod';
 
 const refundBot = new Agent(scope, 'refunds', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You process customer refund requests.',
   tools: (tool) => ({
     issueRefund: tool({
@@ -689,7 +689,7 @@ import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 const scope = new Scope('my-app');
 
 const agent = new Agent(scope, 'chat', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You are a helpful assistant.',
 });
 
@@ -753,7 +753,7 @@ const scope = new Scope('my-app');
 const kb = new KnowledgeBase(scope, 'docs', { source: './knowledge' });
 
 const agent = new Agent(scope, 'support', {
-  model: { deployed: BedrockModels.DEFAULT },
+  model: { deployed: BedrockModels.BALANCED },
   systemPrompt: 'You are a customer support agent. Look up orders and search documentation to help the user.',
   toolContextSchema: z.object({ userId: z.string() }),
   tools: (tool) => ({

packages/bb-agent/src/index.test.ts

@@ -1004,9 +1004,9 @@ describe('checkModelHealth', () => {
 // ── Model Presets ─────────────────────────────────────────────────────────────
 
 describe('BedrockModels presets', () => {
-	test('DEFAULT resolves to a bedrock provider', async () => {
-		assert.strictEqual(BedrockModels.DEFAULT.provider, 'bedrock');
-		assert.ok(BedrockModels.DEFAULT.modelId);
+	test('BALANCED resolves to a bedrock provider', async () => {
+		assert.strictEqual(BedrockModels.BALANCED.provider, 'bedrock');
+		assert.ok(BedrockModels.BALANCED.modelId);
 	});
 
 	test('all presets have provider bedrock and a modelId', () => {
@@ -1016,8 +1016,8 @@ describe('BedrockModels presets', () => {
 		}
 	});
 
-	test('DEFAULT flows through createStrandsModel to BedrockModel', async () => {
-		const model = await createStrandsModel(BedrockModels.DEFAULT);
+	test('BALANCED flows through createStrandsModel to BedrockModel', async () => {
+		const model = await createStrandsModel(BedrockModels.BALANCED);
 		assert.ok(model, 'should create a model instance');
 	});
 });

packages/bb-agent/src/models.ts

@@ -3,35 +3,50 @@
 
 import type { ModelConfig } from './types.js';
 
+const BALANCED_MODEL_ID = 'global.anthropic.claude-sonnet-4-6';
+const SMART_MODEL_ID = 'global.anthropic.claude-opus-4-8';
+const FAST_MODEL_ID = 'global.anthropic.claude-haiku-4-5-20251001-v1:0';
+
 /**
- * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Pre-configured Bedrock model presets using global inference profiles.
  * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ *
+ * **Note:** Global inference profiles route requests to any supported AWS region for
+ * optimal throughput. If your workload has data residency requirements, specify a
+ * region-scoped inference profile explicitly.
+ * @see https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
  */
 export const BedrockModels = {
-	/** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
-	DEFAULT: {
+	/** Great tool use, balanced cost — good middle tier for most workloads. Currently: Claude Sonnet 4.6. */
+	BALANCED: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-opus-4-8-20250610-v1:0',
+		modelId: BALANCED_MODEL_ID,
 	},
-	/** Strong quality/cost balance. Currently: Claude Sonnet 4. */
-	BALANCED: {
+	/** Highest capability for the hardest tasks. Currently: Claude Opus 4.8. */
+	SMART: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+		modelId: SMART_MODEL_ID,
 	},
-	/** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+	/** Lowest latency, still strong capabilities. Currently: Claude Haiku 4.5. */
 	FAST: {
 		provider: 'bedrock',
-		modelId: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+		modelId: FAST_MODEL_ID,
+	},
+
+	/** @deprecated Use `BedrockModels.BALANCED` instead. */
+	DEFAULT: {
+		provider: 'bedrock',
+		modelId: BALANCED_MODEL_ID,
 	},
-	/** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+	/** @deprecated Use `BedrockModels.FAST` instead. */
 	BUDGET: {
 		provider: 'bedrock',
-		modelId: 'us.amazon.nova-pro-v1:0',
+		modelId: FAST_MODEL_ID,
 	},
-	/** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+	/** @deprecated Use `BedrockModels.FAST` instead. */
 	MICRO: {
 		provider: 'bedrock',
-		modelId: 'us.amazon.nova-lite-v1:0',
+		modelId: FAST_MODEL_ID,
 	},
 } as const satisfies Record<string, ModelConfig>;
 
@@ -65,6 +80,7 @@ export const OllamaModels = {
 		apiKey: 'ollama',
 	},
 	/** Strong reasoning at moderate size. Currently: DeepSeek R1 14B (~9 GB, needs 16 GB VRAM). */
+	// TODO: DeepSeek R1 is strong at reasoning but weak at tool calling — swap to a more tool-capable model.
 	MEDIUM: {
 		provider: 'openai-api',
 		modelId: 'deepseek-r1:14b',

test-apps/comprehensive/aws-blocks/index.ts

@@ -266,7 +266,7 @@ const validatedJob = new AsyncJob(scope, 'validated-job', {
 });
 
 // Agent BB - AI agent with tools and conversation persistence
-import { Agent } from '@aws-blocks/bb-agent';
+import { Agent, BedrockModels } from '@aws-blocks/bb-agent';
 
 const agent = new Agent(scope, 'agent', {
   removalPolicy: 'destroy',
@@ -378,6 +378,23 @@ const cannedAgent = new Agent(scope, 'canned', {
 });
 
 
+// Preset agents — one per live BedrockModels preset, used to verify presets work e2e.
+// Skip the deprecated aliases (DEFAULT/BUDGET/MICRO) so we don't provision dead
+// agents that the suite never exercises.
+const LIVE_PRESETS = ['BALANCED', 'SMART', 'FAST'] as const;
+
+const presetAgents = Object.fromEntries(
+	LIVE_PRESETS.map((name) => [
+		name,
+		new Agent(scope, `preset-${name.toLowerCase()}`, {
+			removalPolicy: 'destroy',
+			inferenceOnly: true,
+			model: { deployed: BedrockModels[name], local: { provider: 'canned' } },
+			systemPrompt: 'Reply with exactly one word.',
+		}),
+	]),
+);
+
 // Agent with model fallback — first candidate is unreachable, should fall through to canned
 const fallbackAgent = new Agent(scope, 'fallback', {
   removalPolicy: 'destroy',
@@ -1663,6 +1680,14 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
     return { channelId, channel: await fallbackAgent.getChannel(channelId) };
   },
 
+  async agentPresetStream(presetName: string, message: string) {
+    const presetAgent = presetAgents[presetName];
+    if (!presetAgent) throw new Error(`Unknown preset: ${presetName}. Available: ${Object.keys(presetAgents).join(', ')}`);
+    const result = await presetAgent.stream(message);
+    const done = await result.complete();
+    return { text: done.text ?? '' };
+  },
+
   async agentTestApiKeyResolver() {
     // Tests the AppSetting → apiKey resolver pattern used for secure API key storage.
     // Puts a test value into the secret setting, then resolves it via the same

test-apps/comprehensive/test/agent.test.ts

@@ -321,6 +321,16 @@ export function agentTests(getApi: () => typeof apiType) {
       });
     });
 
+    describe('Bedrock Model Presets', () => {
+      for (const presetName of ['BALANCED', 'SMART', 'FAST']) {
+        test(`preset ${presetName} returns a response`, { timeout: 30_000 }, async () => {
+          const api = getApi();
+          const { text } = await api.agentPresetStream(presetName, 'hi');
+          assert.ok(text && text.length > 0, `${presetName} should return a non-empty response`);
+        });
+      }
+    });
+
     describe('HITL — Tool Approval (deterministic)', () => {
       test('interrupt chunk arrives for tool with approval: always', { timeout: 15_000 }, async () => {
         const api = getApi();