Amazon Bedrock Agents: setup and production patterns.
How to build agents on Amazon Bedrock: what an agent is, action groups and schemas, the orchestration loop, Knowledge Bases, memory, return-of-control, the trace, versions and aliases, cost, the production gotchas, and when to use AgentCore, Flows or your own code instead.
- An Amazon Bedrock Agent is a managed wrapper around a foundation model that completes multi-step tasks. It reasons about a request, calls the tools (Lambda functions or your APIs) and knowledge bases you give it, reads the results, and loops until done. Bedrock runs that loop, so you configure the agent instead of coding the control flow.
- You define an agent with a model and instructions, one or more action groups (actions described by an OpenAPI or function schema and run by Lambda or handed back to your app), and optional Knowledge Bases. You test with the trace, publish a version, point an alias at it and call InvokeAgent.
- If you want to write the agent in your own framework (LangGraph, CrewAI, Strands and others) and have AWS run it, look at Amazon Bedrock AgentCore instead. Agent cost is mostly model tokens, because every step re-sends the prompt. A vetted AWS partner can file POC or IW funding for the build when it qualifies and AWS approves.
IWhat Amazon Bedrock Agents are
A plain model call returns text. An agent takes a goal, decides which steps and tools it needs, runs them against real systems, and returns a result, with Bedrock managing the loop.
An Amazon Bedrock Agent pairs a foundation model (Claude, Amazon Nova, Llama and others) with tools and knowledge sources, plus an orchestration engine that lets the model use them. Ask it to "refund order 4471 and email the customer" and it works out the sequence: look up the order, check the refund policy in a knowledge base, call the refund API, then the email API, reading each result before the next move.
The agent is not following a fixed script. At each turn it decides what to do next from what it has seen so far. That suits tasks where the path depends on intermediate results.
Bedrock writes the loop for you: it prompts the model, parses the tool call, invokes the function, feeds the result back and re-prompts. This plan, act, observe cycle is often called a ReAct loop. You declare the pieces (model, instructions, tools, knowledge) and Bedrock runs it. See the Bedrock Agents user guide.
IIThe parts: instructions, action groups, schemas, orchestration, prompts
An agent has a few well-defined parts. Knowing what each one does is most of what you need to build agents that behave predictably.
Base model and instructions
Every agent has one foundation model and a block of instructions: its role, what it may and may not do, tone and business rules ("escalate any refund above the policy limit"). This is the agent's system prompt and the highest-leverage thing you write. Stronger reasoning models follow multi-step plans and tool schemas more reliably; smaller models cut latency and cost for simple agents.
Action groups: the agent's tools
An action group is a set of related actions. It has a schema that describes the actions and parameters, and an executor that runs them, usually a Lambda function. When the model picks an action, Bedrock calls your Lambda with the parameters and feeds the result back into the loop. An agent can have several action groups (orders, shipping, notifications) and picks across all of them.
With return-of-control (section III), Bedrock hands the chosen action back to your application to run instead. That helps when the logic lives outside AWS or needs a human approval.
OpenAPI or function schemas
The model knows an action exists, and how to call it, only from its schema: an OpenAPI description or a simpler function definition. The model reads those descriptions to choose an action and its parameters. Thin descriptions are a leading cause of wrong tool calls and invented parameters, so precise descriptions matter as much as the instructions.
The orchestration loop
When you invoke the agent, Bedrock sends the model the input, instructions, tools and session context. The model reasons and either answers or asks to call a tool or query a knowledge base (act). Bedrock runs it, captures the result (observe), adds it to the context and re-prompts. This repeats until the model gives a final answer. You control what the model can see and do at each step, not the loop itself.
Prompt templates
Bedrock uses a prompt template for each stage: pre-processing, orchestration, knowledge-base response generation and post-processing. The defaults work. You can override any of them to constrain reasoning, add domain context or turn a stage off. Most teams start with the defaults and override the orchestration or pre-processing template only when a specific behavior needs fixing.
| Component | What it is | You provide | Bedrock manages | Main reliability lever |
|---|---|---|---|---|
| Model + instructions | Reasoning engine and system prompt | Model choice, instruction text | Hosting and invocation | Clear, specific instructions |
| Action group | Callable actions (tools) | Lambda or return-of-control | Routing calls, feeding back results | Narrowly scoped actions |
| OpenAPI / function schema | Contract for each action | Schema with good descriptions | Showing tools to the model | Precise descriptions |
| Knowledge Base | Managed RAG source | Data source and vector store | Chunking, embedding, retrieval | Good chunking, relevant corpus |
| Orchestration loop | Plan, act, observe engine | Nothing | The whole loop | Controlled through the rows above |
| Prompt templates | Per-stage prompt scaffolding | Optional overrides | Defaults per stage | Targeted overrides |
| Guardrail | Safety and policy filter | A guardrail config | Applying it to input and output | Tuned filters, denied topics |
IIIKnowledge Bases, memory and return-of-control
Three features turn a basic agent into a useful one: retrieval from your data, memory across turns and sessions, and a hand-off so your app can run sensitive actions itself.
Knowledge Base integration
You can associate Knowledge Bases with an agent. A Knowledge Base chunks your documents (often in S3), embeds them, stores the vectors (OpenSearch Serverless, Aurora with pgvector and other options) and serves retrieval. The loop can query it at any step, so the agent answers from your actual policy instead of guessing. Action groups are for doing; knowledge bases are for knowing. Most agents use both.
Memory and session state
You invoke the agent with a session ID, and Bedrock keeps the turn-by-turn context for that session. You can also pass session attributes, such as a signed-in customer ID.
Agents also support memory across sessions, so a returning user does not start from scratch. Memory stores and re-sends user context, which has privacy and cost effects, so turn it on deliberately.
Return-of-control
Instead of calling a Lambda, Bedrock can return the chosen action and its parameters to your application in the InvokeAgent response. Your code runs it and sends the result back so the loop continues. Planning stays in Bedrock; execution, credentials and approvals stay with you. Use it for high-impact actions and logic outside AWS.
IVBuild, test with the trace, version, alias, deploy
You iterate on a draft, debug with the trace, publish a version, and route traffic through an alias. Shipping a new agent is a pointer change, not a redeploy.
Building
Create the agent in the console, through the API, or with infrastructure as code (CloudFormation, CDK or Terraform for production). Pick the model, write the instructions, add action groups, associate knowledge bases, attach a guardrail and configure memory. Then prepare it, which compiles the config into a DRAFT you can test right away.
Testing with the trace
The trace is a step-by-step record of each invocation: the model's reasoning at each step, the action it chose and its parameters, what the Lambda or knowledge base returned, and how that shaped the next step. When an agent calls the wrong tool, loops, or answers without retrieving, the trace shows where and why. Iterate in the console, then script test cases against the API for regression coverage.
Versions, aliases and invoking
A version is an immutable snapshot of the whole agent config. An alias (prod, staging) points at one version, and your app always calls the alias. To ship, cut version N+1, test it behind staging, then repoint prod. To roll back, repoint it again. In production your app calls InvokeAgent with the agent ID, alias ID, session ID and input; the response streams back. There is no server to manage.
| Stage | What you do | Artifact | Used for |
|---|---|---|---|
| Build + prepare | Configure model, instructions, tools, KBs | DRAFT | Testing and iteration |
| Test | Invoke with trace on | Trace output | Debugging |
| Version | Snapshot the working config | Immutable version N | Reproducible config |
| Alias | Point a named alias at a version | Alias (e.g. prod) | What your app calls |
| Deploy / roll back | Repoint the alias | Updated alias target | Release with no code change |
VObservability and cost in production
Once an agent is live, you need to see what it does and know what it costs.
Observability
Bedrock sends metrics (invocations, latency, errors) to CloudWatch and supports model invocation logging to CloudWatch Logs or S3. Every action call is a Lambda invocation, so you also get Lambda logs, metrics and X-Ray tracing for the tool side. A common setup: turn on invocation logging, capture the trace on errors or a sample, alarm on Lambda errors and latency, and track token use as a cost signal.
Cost: no agent fee, but agents use many tokens
There is no separate per-agent fee. You pay for (1) model tokens on every step of the loop, usually the largest cost; (2) Lambda for each action; (3) Knowledge Base costs (embedding, vector store, retrieval); and (4) Guardrails on the text evaluated. One request can trigger several model calls, each re-sending instructions, schemas and context, so a multi-step task can cost many times a single chat call.
The levers: use the smallest model that does the job, keep instructions and schemas tight, use prompt caching for the fixed prefix (instructions and tool definitions), cap orchestration steps, and keep retrieval scoped.
VIProduction gotchas: latency, errors, guardrails
Agents that demo well can struggle in production for predictable reasons.
- Latency stacks up across the loop: Every step is a model round trip, and tool steps add Lambda time. Use a faster model, fewer steps, parallel tool calls where possible, and stream the final answer. For fixed, latency-bound paths, a Flow or direct calls may fit better.
- Tool errors need handling: Return structured, descriptive errors from your Lambda ("order not found, ask the user to re-check the ID") so the model can react. Set timeouts and make actions idempotent so a retried refund does not pay twice.
- Schema descriptions do a lot of work: Most "wrong tool" and "invented parameter" bugs trace back to thin descriptions. Precise action names, parameter descriptions and required flags fix more than prompt tweaks.
- Non-determinism and looping: Two identical requests can take different paths, and a confused agent can loop. Constrain it with explicit instructions, tight tool scopes and step limits where available, and test with the trace to catch loops.
- Attach a Guardrail: Screen both input and output for prompt attacks, denied topics and PII. For anything customer-facing this is required, not optional. See the Guardrails page.
- Prompt injection through tools and documents: Agents read tool output and retrieved text that may contain hostile instructions. Treat that content as untrusted, keep high-impact actions behind return-of-control or approval, and give each action Lambda a least-privilege IAM role.
- Cost surprises from chatty loops: A few extra steps per request add up at production volume. Track tokens as a first-class metric, cache the fixed prefix and right-size the model.
VIIBedrock Agents vs Amazon Bedrock AgentCore
AgentCore is the other agent option on AWS. Bedrock Agents is configure-not-code. AgentCore runs and operates agents you build with any framework and any model.
AWS describes Amazon Bedrock AgentCore as a platform to build, deploy and operate agents using any framework (CrewAI, LangGraph, LlamaIndex, Strands Agents and others) and any foundation model, in or outside Bedrock. Its services work together or on their own: Runtime (serverless hosting with session isolation), Memory (short- and long-term), Gateway (turns APIs and Lambda functions into MCP tools), Identity, Code Interpreter, Browser, Observability (OpenTelemetry traces), Evaluations and Policy. Harness is a managed agent loop you define with a model, system prompt and tools in one API call. Pricing is consumption-based with no minimum.
Choose Bedrock Agents when you want a managed agent you configure (instructions, action groups, knowledge bases) and do not want to write or host agent code. Choose AgentCore when your team already writes agents in a framework, needs models outside Bedrock, wants MCP or agent-to-agent protocols, or needs per-session isolation and deeper observability at scale. You can also mix: AgentCore Gateway can expose existing Lambda tools to any agent.
VIIIWhen to use Agents, Flows or custom orchestration
The deciding question is how much of the path you know in advance.
Use Bedrock Agents when the task is multi-step, the path depends on intermediate results, and the agent must choose among tools. Support agents, operations copilots and triage assistants are typical fits.
Use Bedrock Flows when the workflow is fixed and you could draw it on a whiteboard. You get predictability, lower latency and lower cost because nothing re-plans each step. See the Bedrock Flows page.
Use custom orchestration (the Converse API with tool use plus your own code, or AgentCore to host it) when you need full control over the loop or framework-specific behavior. You own the plumbing. Many stacks mix all three.
IXWho can fund a Bedrock agent build
Model inference, Lambda, Knowledge Bases and Guardrails all draw down AWS credits automatically. The question is how you get the funding.
Partner-filed funding: a vetted AWS partner can file POC (proof of concept) funding to test the agent, or incremental workload (IW) funding if you already run on AWS and the agent is new work. For startups this is typically $50K to $150K. Depends on the workload; AWS approves.
AWS Activate: you apply yourself. Activate Founders gives self-funded startups $1,000 to start, up to $5,000. Activate Portfolio gives up to $200,000 with the Org ID from your VC, accelerator or angel group, if it is an Activate Provider. A consulting partner cannot file Activate for you.
CloudRoute matches you with one vetted AWS partner who can build the agent and check which funding fits. Startups pay CloudRoute nothing. Partners pay CloudRoute a monthly membership plus 10% of AWS-approved funding.
| Funding | Who files it | Amount | When it fits |
|---|---|---|---|
| Migration Acceleration Program (MAP) | Your matched AWS partner | $50K to $150K for startups. Depends on the workload; AWS approves. | You are not on AWS yet and want to migrate. |
| Proof of concept (POC) funding | Your matched AWS partner | $50K to $150K for startups. Depends on the workload; AWS approves. | You want to test something, whether or not you are on AWS today. |
| Incremental workload (IW) funding | Your matched AWS partner | $50K to $150K for startups. Depends on the workload; AWS approves. | You are already on AWS and are launching new work: a new AI feature, a new customer or a new contract. |
| AWS Activate Founders | Founder applies | $1,000 to start, up to $5,000 | Self-funded startups with no investor or accelerator behind them. |
| AWS Activate Portfolio | Founder applies | up to $200,000 | Startups backed by a VC firm, accelerator or angel investor that is an AWS Activate Provider. |
| AWS Credits for AI Startups | Invite only (AWS account manager) | $200,000 or more, by invitation | AI startups ready to scale after Activate Portfolio, invited by AWS. |
Bedrock Agents vs AgentCore vs Flows vs custom code
The main ways to run multi-step generative-AI work on AWS. The choice depends on how fixed the path is and how much of the plumbing you want to own.
| Dimension | Bedrock Agents | AgentCore | Bedrock Flows | Custom code |
|---|---|---|---|---|
| Best for | Open-ended tasks, configured not coded | Framework-built agents run at scale | Fixed, known workflows | Bespoke control |
| Path decided by | The model at run time | Your agent code (or Harness) | You, at design time | Your code |
| Who runs it | Bedrock | AgentCore Runtime | Bedrock | You |
| Models | Bedrock models | Any model, in or outside Bedrock | Bedrock models | Any |
| Predictability | Lower | Depends on your code | High | Whatever you build |
| Build effort | Low | Medium | Low to medium | High |
How a match works (example)
- You tell us about the work
You fill in a short form: what you run today, what you want to move, test or build, your stage and your region.
- We pick one partner
We read your answers and pick one vetted AWS consulting partner that fits the work, the stack and the region. We reply within 24 hours; your matched partner reaches out within 5 business days.
- The partner checks POC funding
Your matched partner scopes the test with you. Then it checks whether the test qualifies for POC (proof of concept) funding. A POC can fit whether or not you run on AWS today.
- The partner files, AWS decides
If the work qualifies, the partner files the funding request with AWS. AWS reviews it and decides. The amount depends on the workload.
- You pay nothing
CloudRoute is free for startups. Partners pay CloudRoute a monthly membership plus 10% of AWS-approved funding.
AWS Activate credits are separate, and you apply for them yourself. Use Activate Founders if no investor backs you. Use Activate Portfolio with the Org ID or invite from your VC, accelerator, incubator or angel group if it is an Activate Provider. A consulting partner cannot apply for Activate on your behalf.
Common questions
What are Amazon Bedrock Agents?
How do Bedrock Agents call my APIs or functions?
What is the difference between Bedrock Agents and AgentCore?
What is the agent trace?
How do versions and aliases work for Bedrock Agents?
Can I put a Guardrail on a Bedrock Agent?
How much do Bedrock Agents cost?
Can AWS funding cover building a Bedrock agent?
Get the agent built by a partner who can file the funding
A vetted AWS partner can build the agent (action groups, knowledge bases, guardrails, versioning) and check whether it qualifies for POC or IW funding: typically $50K to $150K for startups. Depends on the workload; AWS approves. CloudRoute is free for startups.