bedrock

Specialist guidance for Amazon Bedrock. Covers model selection, agent design, knowledge bases, guardrails, prompt engineering, batch inference, and cost optimization.

Process

1. Understand the workload: what is being built, who consumes it, and what quality bar is required
2. Use the awsknowledge MCP tools (mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend) to verify current Bedrock model availability, pricing, and features (these change frequently)
3. Select the right model(s) based on task complexity, latency, and cost
4. Design the architecture: direct invocation, RAG, agent, or multi-agent
5. Configure guardrails for user-facing surfaces
6. Estimate costs using the references/cost-modeling.md template
7. Recommend monitoring and cost controls

Model Selection

The model choice is the single biggest cost and quality decision. Get this right first.

Note: Model availability and pricing change frequently. Verify current options via awsknowledge MCP tools (mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend) before making final recommendations.

Model Selection Principles

• Start with the smallest model that could work. Upgrade only when evidence shows it falls short.
• Benchmark on real data, not generic benchmarks. A smaller well-prompted model often beats a larger general one.
• Use Bedrock's intelligent prompt routing to auto-route requests to the right model tier.
• Evaluate the Nova family before defaulting to third-party models — Nova Pro offers comparable quality to Claude Sonnet for many tasks at significantly lower cost per token, and Nova Lite/Micro provide sub-100ms latency for classification and routing tasks where you don't need full reasoning capability. Nova models also have no cross-provider data transfer fees and deeper native Bedrock integration (Guardrails, Knowledge Bases, Flows).

Bedrock Agents

Design Principles

• One agent, one job. If the agent description contains "and", consider splitting.
• Fewer tools = fewer reasoning steps = faster + cheaper. 3-5 tools is the sweet spot.
• Use direct InvokeModel for simple tasks. Not everything needs an agent.

Architecture Patterns

Router + Specialists: A lightweight classifier (Nova Micro) routes to specialized agents. Each specialist has a focused tool set and optimized prompt. This beats one mega-agent with 20 tools.

Knowledge Base + Guardrails: For customer-facing Q&A — KB for retrieval, guardrails for safety, single model call for generation. No agent orchestration needed; use RetrieveAndGenerate API directly.

Agent with Session Memory: For multi-turn conversations — use AgentCore sessions with memory. Let the agent maintain context across turns instead of stuffing history into the prompt each time.

Action Groups

• Use Lambda-backed action groups for complex logic
• Use Return Control for client-side tool execution (keeps agent stateless, avoids Lambda cost)
• Define OpenAPI schemas tightly — vague schemas cause the model to guess (and guess wrong)

Knowledge Bases

Chunking Strategy

• Fixed-size chunking (default): Good starting point. 300-500 tokens with 10-20% overlap.
• Semantic chunking: Better quality, higher embedding cost. Use for high-value, heterogeneous documents.
• Hierarchical chunking: Best for long documents with clear structure (manuals, legal docs).
• Curate the data source — garbage in, garbage out applies doubly to RAG.

Vector Store Selection

• OpenSearch Serverless: Default choice. Managed, scales, integrates natively. See references/cost-modeling.md for minimum costs.
• Aurora PostgreSQL (pgvector): Good if already running Aurora — consolidates infrastructure.
• Pinecone / Redis: If existing investments in these stores.
• For PoCs, share a single OpenSearch Serverless collection across multiple KBs to minimize cost.

Retrieval Tuning

• Start with hybrid search (semantic + keyword) — outperforms pure semantic for most workloads
• Tune retrieved chunk count (default 5). More chunks = more context = more input tokens. Find the minimum that gives good answers.
• Use metadata filtering to scope retrieval — avoid searching everything when the document category is known.

Prompt Engineering on Bedrock

Prompt Caching

• Bedrock caches repeated system prompts automatically for supported models
• Structure prompts: long, stable system prompt + short, variable user prompt
• Cached input tokens are up to 90% cheaper — structure prompts to maximize cache hits

Prompt Management

• Use Bedrock's Prompt Management to version and manage prompts
• Treat prompts like code — version them, test them, review changes
• Use prompt variables for dynamic content instead of string concatenation

Structured Output

• Request JSON with explicit schemas to reduce output token waste
• Use the Converse API with tool use for structured extraction — more reliable than asking for JSON in the prompt

Batch Inference

• 50% cheaper than on-demand for supported models
• Use for: document processing, bulk classification, dataset enrichment, eval runs
• Not for: real-time user-facing requests (latency is minutes to hours)
• Submit jobs via S3 input/output — fits naturally into data pipelines

Guardrails

• Apply to user-facing inputs and outputs. Skip for internal agent reasoning steps.
• Content filters are cheaper than denied topic policies — use filters for broad categories, denied topics for specific restrictions.
• Contextual grounding checks catch hallucination at inference time — useful for RAG apps.
• PII detection/redaction is built in — use it instead of building custom regex.

Diagnostic CLI Commands

Resource creation belongs in IaC. Use the iac-scaffold skill for templates.

# List available models in the region
aws bedrock list-foundation-models \
  --query 'modelSummaries[].{id:modelId,name:modelName,provider:providerName}' --output table

# Quick model test (Converse API — preferred over invoke-model)
aws bedrock-runtime converse \
  --model-id amazon.nova-micro-v1:0 \
  --messages '[{"role":"user","content":[{"text":"Hello"}]}]'

# List agents
aws bedrock-agent list-agents --output table

# List knowledge bases
aws bedrock-agent list-knowledge-bases --output table

# List guardrails
aws bedrock list-guardrails --output table

# Check model invocation logging status
aws bedrock get-model-invocation-logging-configuration

Anti-Patterns

• Defaulting to the biggest model "just to be safe" — start small, upgrade with evidence
• Building an agent when a single InvokeModel call would do — agents compound cost per turn
• Stuffing entire documents into prompts instead of using Knowledge Bases — RAG is cheaper and more maintainable
• Ignoring prompt caching — it is automatic for supported models, just structure prompts correctly
• Using on-demand for bulk processing that could be batch — 50% savings left on the table
• One massive Knowledge Base instead of scoped, curated collections — hurts retrieval quality and costs more
• Skipping guardrails on user-facing apps — "we'll add them later" becomes a security incident
• Not monitoring token usage — costs sneak up fast during iteration, especially with agents

Additional Resources

Reference Files

For detailed cost modeling and estimation, consult:

• references/cost-modeling.md — Pricing model breakdown, cost modeling template, optimization strategies, monitoring setup, and cost estimation output format

Related Skills

• cost-check — Broader AWS cost analysis beyond Bedrock
• iac-scaffold — IaC templates for Bedrock resource creation
• security-review — Security audit for Bedrock configurations and guardrail policies

Output Format

When advising on a Bedrock solution:

Include cost profile and watch-out-for items specific to the use case.