Amazon Bedrock Agents: Production Deployment Guide
Running agents in production on Amazon Bedrock AgentCore: deployment targets and CI/CD with the AgentCore CLI, versions and endpoints, inbound and outbound identity, memory, observability, evaluations, least-privilege IAM and cost. A short section covers Agents Classic.
Verified against: AgentCore CLI (
@aws/agentcore) 1.0.2,bedrock-agentcore1.26.0 andboto31.44.2 (checked 2026-11-19). CLI commands were run against a generated project (create,add,export) or checked against--help(deploy,invoke,logs,traces,eval). boto3 calls were validated against the service models.
This page is about AgentCore: code-defined agents on Runtime and managed harnesses. Writing the agent is covered in the Strands Agents guide and the AgentCore guide. Existing Agents Classic deployments are covered briefly at the end.
Deployment options
Section titled “Deployment options”| Route | What it does | Use it when |
|---|---|---|
AgentCore CLI (agentcore deploy) | Synthesises and deploys a CDK app from agentcore/agentcore.json: runtimes, harnesses, endpoints, memories, gateways, credentials, evaluators | The default. Your project, IAM roles and resources live in one config file |
CDK constructs (@aws/agentcore-cdk) | The constructs the CLI generates, used in your own CDK app | AgentCore is part of a larger CDK estate |
boto3 / CloudFormation (create_agent_runtime, AWS::BedrockAgentCore::Runtime) | Individual resources | You already manage infrastructure another way |
A code runtime is built either as a CodeZip (the default: your source and dependencies zipped and run on a managed PYTHON_3_x or NODE_22 runtime) or as a container (the CLI builds your Dockerfile; Runtime runs ARM64 images). Add a Dockerfile to the runtime’s folder to switch. Choose a container when you need system packages or a custom base image.
Environments and CI/CD
Section titled “Environments and CI/CD”Deployment targets (account and Region) live in agentcore/aws-targets.json. The first agentcore deploy creates a target called default from your current credentials and Region; add more entries for environments:
[ { "name": "staging", "account": "111122223333", "region": "us-west-2" }, { "name": "prod", "account": "444455556666", "region": "us-west-2" }]agentcore build builds the deployable artifacts without touching AWS, which is the right pre-deploy check in a pull request. agentcore deploy --target staging deploys, and agentcore status --target staging shows what exists. In CI, pass flags and the commands run without prompts. --json makes output machine-readable, and --region overrides the Region. (In CLI 1.0, --yes on deploy only confirms removing a target’s stack when the project declares nothing to deploy.) A GitHub Actions workflow using OIDC role assumption:
name: deploy-agenton: push: branches: [main]
permissions: id-token: write contents: read
jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - uses: actions/setup-python@v5 with: python-version: "3.13" - run: npm install -g @aws/agentcore && pip install uv
- run: agentcore build
- uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::111122223333:role/agent-deploy-staging aws-region: us-west-2 - run: agentcore deploy --target staging --json - name: Smoke test run: agentcore invoke --runtime SalesAnalyst --target staging --payload '{"prompt":"Reply with the word OK."}' --json | tee smoke.json
- uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::444455556666:role/agent-deploy-prod aws-region: us-west-2 - run: agentcore deploy --target prod --jsonPin the CLI version in CI (npm install -g @aws/agentcore@1.0.2) so a new release cannot change a pipeline. Put an approval gate (a GitHub environment with required reviewers) on the production step, and run your unit tests for tools and entrypoint logic before any deploy. Those tests need no AWS access, because the entrypoint is a plain function.
Deploy-role permissions. The CLI deploys through CloudFormation and creates IAM roles, S3 objects, ECR repositories and CodeBuild projects. AWS’s CLI policy is intended for development; for CI, pre-bootstrap CDK in the target account and scope the deploy role to the project’s stack (AgentCore-<project>-<target>) and the resources it declares. agentcore deploy also tries to enable CloudWatch Transaction Search and skips that step if the role lacks the X-Ray, CloudWatch Logs and Application Signals permissions it needs (AWS lists them on the page above).
A smoke test that actually checks something
Section titled “A smoke test that actually checks something”agentcore invoke in CI fails on transport errors, but it does not tell you whether the agent behaved. A small boto3 check that fails the build on a bad answer:
import jsonimport sysimport uuid
import boto3
def smoke_test(runtime_arn: str, qualifier: str = "DEFAULT") -> None: client = boto3.client("bedrock-agentcore") response = client.invoke_agent_runtime( agentRuntimeArn=runtime_arn, qualifier=qualifier, runtimeSessionId=f"smoke-{uuid.uuid4()}", # at least 33 characters payload=json.dumps({"prompt": "Reply with exactly the word OK."}), ) if response["statusCode"] != 200: sys.exit(f"runtime returned HTTP {response['statusCode']}") body = response["response"].read().decode() if "OK" not in body: sys.exit(f"unexpected answer: {body[:200]}") print("smoke test passed")
if __name__ == "__main__": smoke_test(sys.argv[1], *sys.argv[2:3])For behavioural checks beyond “it answers”, use evaluations.
Versions and endpoints
Section titled “Versions and endpoints”Every deploy that changes a runtime creates a new immutable version. The DEFAULT endpoint follows the latest version. Named endpoints pin a version, so callers that use qualifier="prod" only move when you move the endpoint.
With the CLI, the endpoint is part of the project config:
agentcore add runtime-endpoint --runtime SalesAnalyst --name prod --version 3agentcore deploy --target prod# promote later: change "endpoints": {"prod": {"version": 4}} in agentcore.json and deploy againWith boto3, the same blue/green move:
import boto3
control = boto3.client("bedrock-agentcore-control")RUNTIME_ID = "SalesAnalyst-abc123"
control.create_agent_runtime_endpoint(agentRuntimeId=RUNTIME_ID, name="canary", agentRuntimeVersion="4")# ... run the smoke test and evaluations with qualifier="canary" ...control.update_agent_runtime_endpoint(agentRuntimeId=RUNTIME_ID, endpointName="prod", agentRuntimeVersion="4")# roll back by pointing "prod" at "3" againFor a gradual rollout between two variants, the CLI has A/B tests over configuration bundles or gateway targets (agentcore eval ab-test config-based run and agentcore eval ab-test target-based run, with get, pause, resume and stop to manage them). Harnesses have the same model: agentcore harness version list and agentcore harness endpoint create|update pin and move versions.
Sessions, limits and scaling
Section titled “Sessions, limits and scaling”- Sessions. A
runtimeSessionIdmaps to one microVM with its own memory and filesystem. Reuse the ID for a conversation and use a new one per user conversation. Never share a session between users. - Lifecycle.
idleRuntimeSessionTimeout(default 900 seconds) andmaxLifetime(default 28,800 seconds) bound how long a session lives and bills. The API accepts 60 to 1,209,600 seconds for each. Set them with--lifecycle-configurationonagentcore add runtimeor inlifecycleConfigurationoncreate_agent_runtime. Long background work should reportHealthyBusythrough@app.async_task(see Resource management). - Quotas. Concurrent sessions, invocation rates and payload sizes are per account and Region; check AgentCore quotas and request increases before a launch rather than load-testing into them. Bedrock model quotas (tokens per minute) are usually the first limit an agent hits.
- Agent state. Build the agent once per session, not per request, and keep anything that must survive a session ending in Memory or your own store, not in process memory.
Identity
Section titled “Identity”Inbound. IAM (SigV4) suits service-to-service callers. For end users, configure a JWT authorizer on the runtime (authorizerConfiguration.customJWTAuthorizer, shown in the AgentCore guide). JWT callers invoke over HTTPS with a bearer token instead of the SigV4 SDK call:
import jsonimport urllib.parseimport urllib.requestimport uuid
def invoke_with_jwt(region: str, runtime_arn: str, token: str, prompt: str, qualifier: str = "DEFAULT") -> str: url = ( f"https://bedrock-agentcore.{region}.amazonaws.com/runtimes/" f"{urllib.parse.quote(runtime_arn, safe='')}/invocations?qualifier={qualifier}" ) request = urllib.request.Request( url, data=json.dumps({"prompt": prompt}).encode(), method="POST", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": str(uuid.uuid4()), }, ) with urllib.request.urlopen(request) as response: return response.read().decode()From the CLI, agentcore invoke --runtime SalesAnalyst --bearer-token "$TOKEN" --payload '{"prompt": "..."}' does the same. Test both a valid token and an expired or wrong-audience token before launch. The second must fail with 401/403, not reach your code.
Outbound. Tools that call third-party APIs should get credentials from AgentCore Identity (@requires_access_token, @requires_api_key, or agentcore add credentials), not from environment variables baked into the image. With JWT inbound auth, user-federated OAuth tokens are scoped to the calling user. AWS recommends that production execution roles deny bedrock-agentcore:GetWorkloadAccessTokenForUserId, which issues tokens for a caller-supplied user ID without verifying a token, and allow only GetWorkloadAccessTokenForJWT.
Payload trust. Runtime passes the payload to your entrypoint unchanged. Validate that prompt is a string, and strip toolUse blocks from any message lists before they reach the agent. Take user and tenant IDs from the verified token or context, not from the payload.
Memory
Section titled “Memory”Add memory to the project rather than creating it by hand, so it is versioned with the agent:
agentcore add memory --name SalesMemory --strategies SEMANTIC,SUMMARIZATION --event-expiry-duration 30- Scope every read and write by actor ID (the end user) and session ID, both taken from the verified identity. Namespace templates such as
/users/{actorId}/factskeep users’ long-term records apart. - Each long-term strategy runs extraction on new events, which costs model tokens. Enable only the strategies you query.
- Set the event expiry to your retention policy, and use a customer-managed KMS key (
encryptionKeyArn) where your data classification requires it. - With Strands,
AgentCoreMemorySessionManagerwrites and reads memory for you (see the Strands guide).
Observability
Section titled “Observability”- CloudWatch Transaction Search must be enabled once per account and Region so spans are stored and appear in the GenAI Observability dashboards.
agentcore deployenables it for you; opt out withagentcore config transactionSearch falseif your organisation manages it centrally. - CLI-generated Python projects already depend on
aws-opentelemetry-distro. For hand-built containers, see instrumenting an agent. - Use the CLI to look at a deployed agent:
agentcore status --target prodagentcore logs runtime --name SalesAnalyst --since 1h --level erroragentcore traces runtime list --name SalesAnalyst --since 30magentcore traces runtime get <traceId> # writes <traceId>.jsonagentcore logs runtime --tail follows new records, and agentcore logs harness and agentcore traces harness do the same for harnesses. Alarm on Runtime errors and latency, on Bedrock throttling for the models you use, and on any business metric your tools publish.
Evaluations
Section titled “Evaluations”AgentCore Evaluations scores agent traces with built-in or custom evaluators (LLM-as-a-judge or a Lambda function). The built-in evaluators include Builtin.Correctness, Builtin.Helpfulness, Builtin.Faithfulness, Builtin.GoalSuccessRate, Builtin.ToolSelectionAccuracy, Builtin.ToolParameterAccuracy, Builtin.Coherence, Builtin.Conciseness, Builtin.InstructionFollowing, Builtin.ResponseRelevance, Builtin.Refusal, Builtin.Harmfulness and Builtin.Stereotyping, plus trajectory matchers for tool-call order. There are two ways to run them.
Continuous (online) evaluation samples live traffic. Declare it in the project so it is deployed with the agent:
agentcore add online-eval --name SalesQuality --agent SalesAnalyst \ --evaluators Builtin.Helpfulness Builtin.Correctness --sampling-rate 10agentcore deploy --target prod--sampling-rate is a percentage of sessions (0.01 to 100). Evaluation is enabled when the config deploys; pass --enable-on-create false to add it paused. agentcore eval online-eval pause|resume|list|get|logs manages it afterwards.
On-demand evaluation scores sessions that already exist, for example the last day of traffic, or one session against a known answer:
agentcore eval ondemand evaluate --agent <runtime-id> \ --evaluators Builtin.GoalSuccessRate --lookback-days 1
agentcore eval ondemand evaluate --agent <runtime-id> \ --evaluators Builtin.Correctness --session-ids <session-id> \ --ground-truth '[{"context":{"spanContext":{"sessionId":"<session-id>","traceId":"<trace-id>"}},"expectedResponse":{"text":"Q4 revenue rose 12%"}}]'From Python, EvaluationClient in the SDK reads the session’s spans from CloudWatch and calls the evaluation API. Use it in tests or notebooks:
from datetime import timedelta
from bedrock_agentcore.evaluation import EvaluationClient
client = EvaluationClient(region_name="us-west-2")
results = client.run( evaluator_ids=["Builtin.Helpfulness", "Builtin.Correctness"], session_id="SESSION_ID", agent_id="SalesAnalyst-abc123", # the runtime ID; its log group is derived from it look_back_time=timedelta(days=2),)
for result in results: print(result["evaluatorId"], result.get("value"), result.get("explanation"))agentcore add evaluator llm-as-a-judge defines a custom judge (with --level SESSION|TRACE|TOOL_CALL, instructions and a rating scale such as pass-fail or 1-5-quality), and add evaluator code-based uses a Lambda function. For a pre-promotion gate, replay a stored dataset against the canary endpoint with agentcore eval ondemand simulate (or eval batch-evaluation simulate for a service-side batch), and move prod only if the scores hold. agentcore eval dataset creates and versions the datasets.
Prompt recommendations (preview)
Section titled “Prompt recommendations (preview)”RecommendationClient asks the service to propose an improved system prompt from traces that have already been evaluated. It is marked as preview in the SDK, so expect the request shape to change. start_recommendation_and_wait starts the job and polls until it completes, which usually takes several minutes, so give it a longer max_wait than the five-minute default for large trace sets.
from bedrock_agentcore.evaluation import RecommendationClient, WaitConfig
client = RecommendationClient(region_name="us-west-2")
recommendation = client.start_recommendation_and_wait( wait_config=WaitConfig(max_wait=1800, poll_interval=30), name="support-prompt-rec", type="SYSTEM_PROMPT_RECOMMENDATION", recommendationConfig={"systemPromptRecommendationConfig": { "systemPrompt": {"text": "You are a support assistant."}, "agentTraces": {"batchEvaluation": {"batchEvaluationArn": BATCH_EVALUATION_ARN}}, "evaluationConfig": {"evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}, ]}, }},)print(recommendation["recommendationResult"])Read the output from recommendationResult; recommendationConfig in the response only echoes your input. The client also forwards get_recommendation, list_recommendations and delete_recommendation. Treat the result as a suggestion: run it through the same evaluations against the canary endpoint before you promote it.
IAM least privilege
Section titled “IAM least privilege”Three kinds of principal need permissions. Keep them separate:
| Principal | Needs | Scope to |
|---|---|---|
| Deploy role (CI) | CloudFormation, IAM role creation for *BedrockAgentCore* roles, S3/ECR/CodeBuild for bedrock-agentcore-* | One account per environment |
| Execution role (assumed by Runtime) | Logs, X-Ray, cloudwatch:PutMetricData (namespace bedrock-agentcore), workload-identity tokens, bedrock:InvokeModel* on the models used, and the Memory, Gateway, Lambda or S3 resources the agent’s tools reach | The specific inference profiles and foundation models, and the runtime’s own log group |
| Callers | bedrock-agentcore:InvokeAgentRuntime (plus InvokeHarness for a harness) | The runtime or harness ARN, and endpoint |
The trust policy on the execution role should allow only bedrock-agentcore.amazonaws.com, conditioned on your account (aws:SourceAccount) and AgentCore resources (aws:SourceArn). The IAM examples page has the full policies. The CLI generates execution roles for you. Review them before production, because the defaults favour getting started over least privilege.
AgentCore bills by consumption: Runtime by active CPU and memory per session-second, Memory by events and extracted records, Gateway by calls and indexed tools, Code Interpreter and Browser by session time. There is no separate harness orchestration charge. Model tokens are billed by Bedrock as usual. See AgentCore pricing and filter Cost Explorer on the AgentCore service.
- Short idle timeouts stop idle sessions accruing Runtime charges.
- Use a small model (Haiku class) for routing and extraction steps, and prompt caching (
CacheConfigon StrandsBedrockModel) for long, stable system prompts and tool lists. - Enable only the memory strategies you read.
- Always stop Code Interpreter and Browser sessions (the
code_session/browser_sessioncontext managers do this). - Set
maxIterations,maxTokensandtimeoutSecondson a harness, and timeouts and node limits on Strands multi-agent runs, so a looping agent fails cheaply.
Production checklist
Section titled “Production checklist”- Entrypoint validates the payload; identity comes from the token or
context, not the payload - Tools and entrypoint covered by unit tests; smoke test and evaluations run against a staging or canary endpoint
-
prodendpoint pinned to a tested version; rollback is “move the endpoint back” - Execution role scoped to specific models and resources; trust policy conditioned on account and source ARN
- Inbound auth chosen and tested with bad tokens;
GetWorkloadAccessTokenForUserIddenied where JWTs are available - Lifecycle timeouts and harness or multi-agent limits set
- Transaction Search enabled; alarms on errors, latency and throttling
- Memory expiry, strategies and KMS reviewed; actor and session IDs scoped per user
- Quotas checked for expected peak concurrency
Agents Classic in production
Section titled “Agents Classic in production”For existing Agents Classic deployments (maintenance mode since 30 July 2026):
- Versions and aliases. Test against
DRAFT(withTSTALIASID), then create an alias, which snapshots a numbered version. Roll forward or back by pointing the alias at another version withupdate_agent_alias(agentId=..., agentAliasId=..., agentAliasName=..., routingConfiguration=[{"agentVersion": "N"}]). Callers always use an alias ID, neverDRAFT. - Smoke test. After each change, invoke the alias and check the answer, as below.
- Monitoring.
AWS/Bedrock/AgentsCloudWatch metrics andenableTrace=Truetraces; see the observability page. - IAM. A service role trusted by
bedrock.amazonaws.comfor your account’s agents, plusbedrock:InvokeAgenton the alias ARN for callers; see the IAM examples. - Plan the move. No new models will reach Classic. See Migrating from Bedrock Agents Classic.
import uuid
import boto3
def classic_smoke_test(agent_id: str, alias_id: str) -> None: runtime = boto3.client("bedrock-agent-runtime") response = runtime.invoke_agent( agentId=agent_id, agentAliasId=alias_id, sessionId=str(uuid.uuid4()), inputText="Reply with exactly the word OK.", ) answer = "".join(e["chunk"]["bytes"].decode() for e in response["completion"] if "chunk" in e) if "OK" not in answer: raise SystemExit(f"unexpected answer: {answer[:200]}")