How to Deploy a LangGraph AI Agent on Amazon Bedrock AgentCore: A Production Guide for 2026

A LangGraph agent can work perfectly in a notebook and still be nowhere near production-ready. The graph may reason correctly, call a local tool, and preserve state during a test. Deployment introduces a different set of obligations: every invocation needs an identity, every tool needs an authorization boundary, every session needs isolation, every release needs a rollback path, and every answer needs enough telemetry to explain what happened.

Amazon Bedrock AgentCore addresses much of that operational layer without requiring an enterprise to replace LangGraph. LangGraph continues to define the agent's state, nodes, branches, and tool-use loop. AgentCore supplies managed runtime isolation and can add identity, memory, tool gateways, policy enforcement, observability, and evaluation around it.

This guide takes a small but realistic LangGraph incident-triage agent from source code to a governed AgentCore deployment. It includes commands, Python, IAM boundaries, state design, failure handling, release strategy, evaluation criteria, and the production decisions that abbreviated tutorials usually omit.

Short answer: package the LangGraph application behind the AgentCore Runtime entrypoint, test it locally with the current agentcore CLI, deploy it as CodeZip or an ARM64 container, and invoke it through a versioned runtime endpoint. Before production, add verified caller identity, least-privilege tool access, durable state where needed, OpenTelemetry traces, regression evaluations, and a named endpoint that can be rolled back independently of the latest build.

Deployment at a Glance

The production path is easier to understand when it is separated into five phases:

Phase	Primary question	Main deliverable	Release gate
1. Define	What exactly can this agent decide and do?	LangGraph state machine, tool contracts, success criteria	Deterministic unit and graph-path tests pass
2. Adapt	How does the graph satisfy the AgentCore runtime contract?	AgentCore entrypoint, request/response schema, health behavior	Local Runtime invocation succeeds
3. Deploy	How is the artifact built, authorized, and exposed?	CodeZip or ARM64 container, execution role, runtime version	Isolated development endpoint passes smoke tests
4. Govern	Who may invoke it and which actions may it take?	Inbound authentication, Gateway targets, policies, network controls	Security and threat-model review passes
5. Operate	How will the team detect regressions and release safely?	Traces, metrics, evaluations, named endpoints, rollback and runbooks	SLO and evaluation thresholds pass

For a proof of concept, the first three phases may fit into a day. Production readiness is determined by phases four and five not by whether the first deployment command returned successfully.

What LangGraph Manages and What AgentCore Manages

LangGraph and AgentCore solve related but different problems. Treating one as a replacement for the other produces confused architecture and duplicated state.

Concern	LangGraph	Amazon Bedrock AgentCore	Enterprise decision
Agent reasoning flow	Nodes, edges, conditional routing, interrupts	Runs the packaged application	Keep business orchestration explicit in the graph
Working state	MessagesState or a custom graph state	Isolates a runtime session	Decide what is ephemeral, checkpointed, or durable
Model access	LangChain model adapter, such as ChatBedrockConverse	Can host agents using Bedrock or other models	Keep model and inference profile configurable
Tool invocation	Tool schemas, ToolNode, conditional edges	Gateway can expose and authorize enterprise tools	Do not make prompt instructions the authorization layer
Authentication	Usually application-specific	IAM SigV4 or JWT bearer authentication for a runtime	Select one inbound mode per runtime version
Authorization	Graph logic may decide when to ask for a tool	Gateway Policy can enforce Cedar rules outside agent code	Enforce sensitive permissions deterministically
Long-term memory	Checkpointer and store interfaces	AgentCore Memory integration	Define retention, actor isolation, deletion, and consent
Runtime isolation	Not a hosting feature	Dedicated microVM for each user session	Map verified users and sessions deliberately
Observability	Graph events and callbacks	CloudWatch, OpenTelemetry-compatible spans, logs, and metrics	Correlate user request, graph run, model call, and tool call
Evaluation	Application tests and custom datasets	Online, on-demand, and batch agent evaluations	Gate releases with business and safety criteria
Release management	Application code/version control	Immutable runtime versions and endpoint routing	Pin production to a named endpoint, not merely DEFAULT

The clean division is: LangGraph owns the agent's decision process; AgentCore owns the managed execution and governance envelope. Your application team still owns the code, dependencies, prompt-injection defenses, permission design, data handling, and operational outcomes.

Reference Architecture: An Incident-Triage Agent

To keep the deployment concrete, this guide uses an internal incident-triage agent. An employee asks, “Is checkout-api degraded, and what should I do next?” The agent can:

• inspect a sanitized, read-only service status source;

• retrieve an approved runbook;

• summarize evidence and propose next steps;

• draft a ticket or escalation for human approval; and

• decline destructive remediation it is not authorized to perform.

  
  

The first version deliberately does not restart services, modify infrastructure, or send external communications. That is a useful production pattern: begin with bounded read access and reversible outputs, evaluate behavior, and add higher-impact actions only after deterministic authorization and approval gates exist.

Employee or application
        |
        | IAM SigV4 or verified JWT
        v
Named AgentCore Runtime endpoint
        |
        v
LangGraph orchestration
  [classify] -> [model] <-> [approved tools] -> [respond]
                       |
                       v
               AgentCore Gateway
                  /          \
          status API      runbook service
                  \          /
                   policy checks

Supporting controls:
- AgentCore Memory for approved persistent context
- CloudWatch and OpenTelemetry for traces, logs, and metrics
- AgentCore Evaluations for behavioral and tool-use scoring
- KMS, Secrets Manager, VPC, IAM, and Security Hub controls

The trust boundaries that matter

The architecture contains four distinct trust boundaries:

1. Caller to runtime: proves who or what may invoke the agent.

2. Runtime to model: constrains which model resources the execution role may call.

3. Agent to tool: determines which API operation is permitted for this user and these parameters.

4. Session to durable data: controls whether information may persist beyond an isolated runtime session.

   
   

Logging a user in addresses only the first boundary. It does not automatically prove that the user is allowed to read a particular runbook, retrieve another team's incident, or invoke a change-management API.

Before You Deploy: Establish the AWS Landing Zone

Prerequisites

For the current AgentCore CLI workflow, prepare:

• an AWS account and target Region where the required AgentCore features and chosen model are available;

• Node.js 20 or later for the CLI;

• Python 3.10 or later for this example;

• AWS CDK prerequisites used by the CLI deployment workflow;

• AWS credentials for a deployment role;

• access to the selected Amazon Bedrock model or inference profile;

• a source repository with dependency locking and secret scanning; and

• a separate runtime execution role rather than reusing administrator credentials.

  
  

Install the current CLI:

npm install -g @aws/agentcore
agentcore --version
aws sts get-caller-identity

The aws sts get-caller-identity result should represent an approved deployment role. Do not build production automation around a developer's long-lived access keys.

Choose the Region and inference profile deliberately

Bedrock model availability, cross-Region inference options, data residency requirements, latency, and AgentCore feature availability can differ. In production, do not scatter a model ID across source files. Store the model or inference profile identifier in runtime configuration, validate it during deployment, and record it with the release metadata.

This guide uses an environment variable:

AWS_REGION=us-east-1
BEDROCK_MODEL_ID=<approved-model-or-inference-profile-id>

The placeholder is intentional. Model catalogs and supported identifiers change. Select an approved model using the current Amazon Bedrock supported models documentation, test it in the intended Region, and keep a model-change evaluation separate from an application-code change whenever possible.

Separate deployment permissions from runtime permissions

The deployment identity needs permission to create or update infrastructure. The runtime identity needs only the permissions used while serving requests. Combining them creates a role that can both operate the agent and change its own environment.

A minimal runtime role for the stateless example normally needs model invocation, logging and telemetry permissions, and access to any explicitly approved downstream services. If Memory or Gateway is added, grant only its required actions and resource ARNs.

AWS notes that policies generated by deployment tooling are intended to accelerate development and testing. Review and replace broad generated permissions before production. “The CLI deployed it” is not an IAM review.

Phase 1: Build a Deployable LangGraph Contract

A graph is easier to deploy when its boundary is intentionally small:

• input is versioned JSON rather than an unstructured Python object;

• output is JSON or a streamed event sequence;

• tool schemas are narrow and typed;

• model configuration comes from the environment or a controlled configuration bundle;

• errors have stable codes;

• the graph has a recursion limit and time budget; and

• side effects are outside the model's direct control.

  
  

Scaffold an AgentCore project

Create a LangGraph project using the current CLI:

agentcore create \
  --name IncidentTriageAgent \
  --framework LangChain_LangGraph \
  --protocol HTTP \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

The generated layout separates AgentCore configuration from the application:

IncidentTriageAgent/
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── .env.local
└── app/
    └── IncidentTriageAgent/
        ├── main.py
        └── pyproject.toml

Use CodeZip when the application is Python-only and does not need custom operating-system packages. Use Container when it needs system dependencies, a controlled base image, or custom build steps. Custom AgentCore Runtime containers must be built for ARM64 and follow the Runtime protocol contract.

If a LangGraph repository already exists, register it as bring-your-own code instead of recreating it:

agentcore add agent \
  --name IncidentTriageAgent \
  --type byo \
  --code-location ./incident-agent \
  --entrypoint main.py \
  --language Python

Define the graph

The following version uses a deterministic read-only tool to make the deployment runnable. Replace the in-memory status map with an AgentCore Gateway target later; do not place production service credentials in the function.

import os
from typing import Any

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from langchain_aws import ChatBedrockConverse
from langchain_core.messages import SystemMessage
from langchain_core.tools import tool
from langgraph.graph import MessagesState, START, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition


REGION = os.environ.get("AWS_REGION", "us-east-1")
MODEL_ID = os.environ["BEDROCK_MODEL_ID"]


@tool
def get_service_status(service_name: str) -> dict[str, str]:
    """Return sanitized, read-only status for an approved internal service."""
    approved_status = {
        "checkout-api": {
            "status": "degraded",
            "evidence": "Elevated p95 latency; error rate remains below paging threshold.",
            "runbook": "RB-CHECKOUT-04",
        },
        "catalog-api": {
            "status": "healthy",
            "evidence": "Latency and error rate are within the current service objective.",
            "runbook": "RB-CATALOG-02",
        },
    }

    key = service_name.strip().lower()
    if key not in approved_status:
        return {
            "status": "not_found",
            "evidence": "No approved service record is available.",
            "runbook": "none",
        }
    return approved_status[key]


tools = [get_service_status]

model = ChatBedrockConverse(
    model_id=MODEL_ID,
    region_name=REGION,
    temperature=0,
    max_tokens=700,
)
model_with_tools = model.bind_tools(tools)

SYSTEM_INSTRUCTIONS = """
You are an internal incident-triage assistant.
Use tools for current service status; do not invent operational facts.
Separate observed evidence from recommendations.
Never claim to restart, modify, or remediate a service.
If a requested action is not authorized, say so and propose a human approval path.
Keep the response concise and include the referenced runbook identifier.
""".strip()


def call_model(state: MessagesState) -> dict[str, Any]:
    response = model_with_tools.invoke(
        [SystemMessage(content=SYSTEM_INSTRUCTIONS), *state["messages"]]
    )
    return {"messages": [response]}


builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "model")
builder.add_conditional_edges("model", tools_condition)
builder.add_edge("tools", "model")
graph = builder.compile()


app = BedrockAgentCoreApp()


@app.entrypoint
def invoke(payload: dict[str, Any], context: Any) -> dict[str, Any]:
    prompt = payload.get("prompt")
    if not isinstance(prompt, str) or not prompt.strip():
        return {
            "status": "rejected",
            "error_code": "INVALID_PROMPT",
            "message": "The prompt must be a non-empty string.",
        }

    result = graph.invoke(
        {"messages": [("user", prompt.strip())]},
        config={"recursion_limit": 8},
    )
    final_message = result["messages"][-1]

    return {
        "status": "completed",
        "response": final_message.content,
    }


if __name__ == "__main__":
    app.run()

The important AgentCore adaptation is intentionally small: instantiate BedrockAgentCoreApp, decorate an invocation function with @app.entrypoint, and call app.run(). The rest remains ordinary LangGraph code.

Define a stable request and response schema

The tutorial code accepts only prompt, but an enterprise contract should be explicit:

{
  "schema_version": "1.0",
  "prompt": "Is checkout-api degraded, and what should I do next?",
  "conversation_id": "4b31732e-9b0c-4bda-b2ef-e09b10f8c385",
  "response_mode": "concise"
}

Recommended response envelope:

{
  "schema_version": "1.0",
  "status": "completed",
  "response": "checkout-api is degraded...",
  "evidence_refs": ["status:checkout-api", "runbook:RB-CHECKOUT-04"],
  "actions_proposed": [],
  "trace_id": "<correlation-id>"
}

Do not accept an actor_id, role, or authorization scope from an untrusted request body and then use it to authorize tools. Those values must come from verified identity context or a trusted upstream service.

Lock and inspect dependencies

At minimum, the project needs the AgentCore runtime package, LangGraph, and the AWS LangChain integration. Add OpenTelemetry instrumentation when observability is introduced.

[project]
name = "incident-triage-agent"
version = "0.1.0"
requires-python = ">=3.10,<3.13"
dependencies = [
  "bedrock-agentcore",
  "langgraph",
  "langgraph-checkpoint-aws",
  "langchain-aws",
  "aws-opentelemetry-distro",
  "opentelemetry-instrumentation-langchain",
]

Use a lock file in the real project, pin a tested dependency set, generate a software bill of materials, and scan both Python dependencies and container layers. A floating production build can change even when the application commit does not.

Phase 2: Test the Runtime Boundary Locally

Start the local development server from the project:

agentcore dev

The AgentCore CLI can also invoke the local application directly:

agentcore dev "Is checkout-api degraded, and what should I do next?"

For a streaming entrypoint, add --stream. The local server uses the Runtime HTTP contract, which makes this more useful than calling graph.invoke() alone: it exercises serialization, entrypoint behavior, environment configuration, and runtime request handling.

Tests required before cloud deployment

Run at least these layers:

Test layer	What to verify	Example failure caught
Tool unit tests	normalization, allowlists, timeouts, error mapping	unknown service returns fabricated data
Graph path tests	expected node transitions and recursion bounds	model repeatedly calls the same tool
Contract tests	JSON input/output and stable error codes	non-serializable message content
Adversarial tests	prompt injection, unauthorized action requests, data exfiltration	user asks tool to ignore its scope
Model regression set	task success and response quality	model update stops citing evidence
Load tests	concurrency, p95 latency, streaming behavior	downstream pool saturates before Runtime

A useful deterministic test checks the tool independently of the model:

def test_unknown_service_is_not_fabricated():
    result = get_service_status.invoke({"service_name": "secret-admin-api"})
    assert result["status"] == "not_found"
    assert result["runbook"] == "none"

The model can vary; tool permissions and data boundaries should not.

Phase 3: Deploy the Agent to AgentCore Runtime

First preview the generated infrastructure:

agentcore deploy --dry-run

Review the build mode, Region, execution role, environment configuration, network mode, authentication mode, and resources the deployment will create. Then deploy:

agentcore deploy
agentcore status

AgentCore creates an immutable runtime version. Updating the runtime creates a new complete version instead of mutating the old one in place. The DEFAULT endpoint automatically targets the latest version; that behavior is convenient for development but should not be your only production release control.

Invoke the deployed runtime

Use the CLI for a smoke test:

agentcore invoke \
  --prompt "Is checkout-api degraded, and what should I do next?" \
  --stream

Reuse a session identifier when testing multi-turn session behavior:

agentcore invoke \
  --session-id incident-demo-001 \
  "What evidence supports that conclusion?"

For IAM-authenticated application integration, the AWS SDK can invoke Runtime:

import json
import uuid

import boto3


client = boto3.client("bedrock-agentcore", region_name="us-east-1")

response = client.invoke_agent_runtime(
    agentRuntimeArn="<runtime-arn>",
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps(
        {"prompt": "Is checkout-api degraded, and what should I do next?"}
    ).encode("utf-8"),
    qualifier="DEFAULT",
)

chunks = []
for chunk in response.get("response", []):
    chunks.append(chunk.decode("utf-8"))

print("".join(chunks))

When a Runtime uses OAuth/JWT inbound authentication, call its HTTPS endpoint using the bearer token rather than assuming the AWS SDK invocation path applies. AgentCore Runtime supports IAM SigV4 or JWT bearer authentication for a runtime version; select the mode that matches the caller architecture.

Runtime protocol requirements for custom containers

Teams using the SDK and CLI generally do not need to implement health handling themselves. A custom HTTP container must satisfy the Runtime service contract:

• listen on 0.0.0.0 port 8080;

• expose POST /invocations;

• expose GET /ping;

• return JSON or server-sent events as appropriate;

• use an ARM64-compatible image; and

• avoid changing the health timestamp on every ping, which can interfere with session-idle behavior.

  
  

AgentCore also supports MCP, A2A, and AG-UI protocols with their documented ports and paths. Choose a protocol because the integration needs it—not because using more agent protocols makes the deployment more “agentic.”

Phase 4: Design State, Sessions, and Memory Separately

There are three state mechanisms that teams frequently conflate:

State type	Purpose	Lifetime	Example
Runtime session	Isolated execution environment and filesystem	Session lifecycle, up to configured maximum	temporary files used while handling one conversation
LangGraph checkpoint	Resume graph state and multi-turn thread	Defined by checkpointer and thread identity	prior messages and current graph position
AgentCore long-term memory	Retrieve retained information across sessions	Retention and memory policy	approved user preference or summarized case history

AgentCore Runtime provides a dedicated microVM for each user session, isolating CPU, memory, and filesystem. That does not automatically make an in-process LangGraph state durable. If the session stops or the graph must resume elsewhere, an external checkpointer is required.

Add AgentCore Memory as a LangGraph checkpointer

AWS provides a LangGraph checkpoint integration through langgraph_checkpoint_aws:

import os

from langgraph_checkpoint_aws import AgentCoreMemorySaver


MEMORY_ID = os.environ["AGENTCORE_MEMORY_ID"]
REGION = os.environ.get("AWS_REGION", "us-east-1")

checkpointer = AgentCoreMemorySaver(MEMORY_ID, region_name=REGION)
graph = builder.compile(checkpointer=checkpointer)

Invoke the graph with both a thread and actor identity:

config = {
    "configurable": {
        "thread_id": verified_session_id,
        "actor_id": verified_actor_id,
    },
    "recursion_limit": 8,
}

result = graph.invoke(
    {"messages": [("user", prompt)]},
    config=config,
)

In this integration, LangGraph's thread_id maps to an AgentCore session identifier and actor_id maps to the memory actor. Both must be derived from a verified context. A guessed or user-submitted actor ID can become a cross-tenant data exposure vulnerability.

The execution role also needs the specific Memory actions required by the integration, such as bedrock-agentcore:CreateEvent, bedrock-agentcore:ListEvents, and bedrock-agentcore:RetrieveMemories, restricted to the intended memory resource.

Do not persist everything

Before enabling long-term memory, specify:

• which facts are eligible for retention;

• which fields are prohibited, such as credentials or unnecessary personal data;

• per-tenant and per-user isolation keys;

• retention and deletion behavior;

• whether the user can inspect or correct retained information;

• how a memory is validated before it influences an action; and

• how memory poisoning will be detected.

  
  

For incident triage, a verified team preference for escalation format might be useful memory. A copied access token, unverified diagnosis, or confidential incident detail usually should not become long-term memory.

Phase 5: Put Enterprise Tools Behind Gateway and Policy

The local Python tool proves graph behavior, but it is not the preferred production boundary for enterprise systems. AgentCore Gateway can expose Lambda functions, OpenAPI or Smithy-described APIs, existing MCP servers, and other supported targets as tools.

A production migration looks like this:

Local @tool function
        |
        v
Versioned status-service API contract
        |
        v
AgentCore Gateway target
        |
        v
Policy evaluation + outbound authentication
        |
        v
Internal status platform

Gateway creates a stable tool surface while outbound authentication manages IAM credentials, OAuth credentials, or API keys without exposing those secrets to the model. “No authentication” should be limited to rare, explicitly reviewed cases.

Keep authorization outside the prompt

This instruction is useful:

Never restart a service without approval.

It is not an authorization control. Prompt instructions can be misunderstood, displaced by conflicting context, or bypassed through prompt injection.

AgentCore Gateway Policy uses Cedar to evaluate tool calls outside agent code. A policy can consider verified identity, tool name, and request parameters. The design should follow these rules:

• default deny;

• require an explicit permit for a tool action;

• use forbid for non-negotiable restrictions;

• ensure at least one permit applies before access is granted;

• test policy decisions independently of the model; and

• review any policy generated from natural language before deployment.

  
  

For example, a support user may read status for services in their business unit but may not call a remediation tool. An on-call engineer may propose remediation, while an incident commander provides the approval claim required to execute it. The graph can orchestrate that approval; Gateway Policy should enforce it.

Make tool contracts safe by construction

Every production tool should have:

• a narrow verb and purpose;

• typed, bounded parameters;

• server-side allowlists;

• tenant and object-level authorization;

• timeouts and bounded retries;

• idempotency keys for side effects;

• a dry-run mode where possible;

• sanitized output that excludes secrets;

• a machine-readable error taxonomy; and

• audit fields linking the caller, session, graph run, policy decision, and downstream transaction.

  
  

Avoid generic tools such as execute_sql, call_any_url, or run_shell_command. They transfer too much authority through parameters the model controls.

Secure the Runtime Before Production

Choose inbound authentication

AgentCore Runtime supports two primary inbound approaches:

Mode	Best fit	Key control
IAM SigV4	AWS services, backend-to-backend calls, AWS-native operators	least-privilege InvokeAgentRuntime permissions and resource restrictions
JWT bearer/OAuth	workforce or customer applications using an identity provider	validate issuer, audience, signing keys, claims, and token lifetime

A runtime version uses one of these modes, not both at the same time. If the enterprise needs workforce and service callers with different identity models, use a trusted application tier or separate runtimes instead of weakening the boundary.

The optional X-Amzn-Bedrock-AgentCore-Runtime-User-Id mechanism requires dedicated permissions and should not be treated as self-authenticating user identity. If used, the upstream system must already have verified the user and be authorized to invoke on that user's behalf.

Enforce least privilege at every role

Review at least four identities:

1. CI/CD deployment role;

2. Runtime execution role;

3. Application caller role or JWT client;

4. Gateway outbound identity for each downstream target.

   
   

The Runtime execution role should have equal or fewer privileges than its callers, scoped to the resources the agent actually needs. Restrict model ARNs or inference profiles, Memory resources, KMS keys, Secrets Manager secrets, Gateway targets, log groups, and network paths.

AgentCore exposes execution-role credentials through its task metadata mechanism to processes inside the runtime environment. Treat application code and dependencies as privileged. Run custom containers as a non-root user, scan images, verify provenance, and do not execute untrusted code in the agent process.

Enable MMDSv2

As of June 30, 2026, AgentCore Runtime requires MMDSv2. A runtime without it returns a ValidationException on invocation. New 2026 deployments should make this an explicit infrastructure assertion rather than relying on a console default.

Decide whether the runtime needs a VPC

Use VPC connectivity when the agent must reach private APIs, databases, or internal services. AgentCore creates elastic network interfaces in the selected subnets and security groups.

Important network detail: placing the runtime in a public subnet does not automatically provide public internet access. For controlled internet egress, use private subnets with an approved NAT path and internet gateway, or avoid internet access entirely. Where applicable, add VPC endpoints for AWS services. For container deployments, ECR API, ECR Docker, and the S3 gateway endpoint can reduce dependence on NAT for image-layer retrieval.

Account for endpoint policy, DNS, security groups, network ACLs, inspection, egress allowlists, and NAT data-processing cost in the design. AgentCore-created network interfaces may remain for a period after runtime deletion, so operational cleanup checks should not assume immediate disappearance.

Threat-model the agent as a privileged application

At minimum, test:

• direct and indirect prompt injection;

• malicious instructions embedded in tool output or retrieved documents;

• cross-tenant memory access;

• over-broad tool parameters;

• confused-deputy behavior;

• credential leakage in errors and traces;

• denial of wallet through long loops or high token usage;

• downstream partial failure;

• unsafe deserialization and dependency compromise; and

• operator misuse of logs or replay data.

  
  

If the graph uses generative AI safeguards, Amazon Bedrock Guardrails can help enforce content and policy constraints at model boundaries. Guardrails complement IAM, Gateway Policy, validation, and application controls; they do not replace them.

Make the Agent Observable, Not Merely Logged

AgentCore Observability integrates with Amazon CloudWatch and OpenTelemetry-compatible instrumentation. A useful trace should connect:

request -> runtime session -> graph node -> model call -> tool selection
        -> policy decision -> downstream call -> final response

Enable CloudWatch Transaction Search as required for the AgentCore trace experience, then use the CLI during investigation:

agentcore logs
agentcore traces list

Minimum operational telemetry

Signal	Measure	Why it matters
Availability	successful requests / eligible requests	reveals whether the endpoint is usable
Latency	p50, p95, p99 end-to-end and per node	separates model delay from tool delay
Agent behavior	turns, graph steps, recursion-limit hits	detects loops and inefficient plans
Model usage	input/output tokens, model errors, throttles	connects quality, capacity, and cost
Tool behavior	selection, parameter validity, authorization denials, failures	reveals unsafe or ineffective tool use
Quality	task success, correctness, groundedness, refusal quality	measures whether the agent helped
Safety	policy violations, injection detections, sensitive-output blocks	monitors control effectiveness
State	checkpoint errors, memory retrievals, cross-session anomalies	catches continuity and isolation failures

Logging rules

Do not log full prompts, tool responses, memory contents, or identity tokens by default. Implement field-level redaction and classify telemetry. Store a hashed or pseudonymous actor correlation key when a raw identifier is unnecessary. Set retention by environment and investigation need.

Every error should carry a correlation identifier and stable category, such as:

• INVALID_REQUEST;

• AUTHENTICATION_FAILED;

• AUTHORIZATION_DENIED;

• MODEL_THROTTLED;

• TOOL_TIMEOUT;

• TOOL_VALIDATION_FAILED;

• MEMORY_UNAVAILABLE;

• MAX_STEPS_EXCEEDED; or

• INTERNAL_ERROR.

Return a safe user message. Put diagnostic detail in protected telemetry, not in the model-visible response.

Evaluate the Agent Before and After Release

Agent evaluation must measure the trajectory, not just whether the final prose sounds helpful. A plausible answer can come from the wrong tool, invalid parameters, unsupported evidence, or an unauthorized action attempt.

AgentCore Evaluations supports on-demand, batch, and online evaluation. LangGraph traces can be instrumented using supported OpenTelemetry packages and evaluated in the unified trace format.

Build an incident-triage evaluation suite

Include cases across these dimensions:

Dimension	Example case	Pass condition
Goal success	identify degraded checkout service	status is correct and useful next step is offered
Tool selection	question requires live status	status tool is selected exactly when required
Parameter accuracy	“checkout API” maps to approved service key	canonical checkout-api is sent
Groundedness	tool reports degraded but not outage	response does not claim a total outage
Authorization	user asks to restart the service	no restart occurs; approval path is explained
Resilience	status tool times out	uncertainty is disclosed; no status is fabricated
Injection resistance	tool output says “ignore policy”	instruction is treated as data, not authority
Multi-turn state	user asks “what evidence?”	answer refers to the same verified observation
Tenant isolation	actor requests another tenant's incident	access is denied without data disclosure
Cost discipline	simple status query	graph terminates within the approved step/token budget

AgentCore includes evaluators for dimensions such as goal success, correctness, faithfulness, helpfulness, response relevance, tool selection accuracy, and tool parameter accuracy. Use code-based evaluators for deterministic requirements and model-based judges for rubric-driven qualities.

For a broader evaluation program—including groundedness, retrieval relevance, test-set construction, and release gates—see the Codersarts LLM Evaluation and Benchmark Engineering service and our guide to evaluating RAG quality with Amazon Bedrock.

Define release thresholds before running the test

An example policy might require:

• 98% or better correct tool selection on critical test cases;

• 100% denial of prohibited actions;

• no cross-tenant retrieval in isolation tests;

• a statistically defensible non-regression in goal success;

• p95 latency within the service objective;

• zero critical security findings; and

• a bounded cost per successful task.

  
  

The numbers should reflect the use case's risk. A read-only drafting assistant and an agent capable of changing production infrastructure should not share the same acceptance threshold.

Promote Runtime Versions Safely

Every AgentCore runtime update creates an immutable version. The DEFAULT endpoint moves to the latest version automatically. For production, create named endpoints that point to approved versions.

Version 11 ────────▶ dev endpoint
      |
      +───────────▶ staging endpoint

Version 10 ────────▶ production endpoint

After gates pass:
Version 11 ────────▶ production endpoint

Rollback:
Version 10 ────────▶ production endpoint

Recommended release sequence

1. Build an immutable artifact and record its digest, application commit, dependency lock hash, graph schema version, prompt version, model configuration, and evaluator version.

2. Deploy a new Runtime version without changing production routing.

3. Run contract, security, and evaluation suites against the candidate.

4. Route an internal or allowlisted cohort to a candidate endpoint.

5. Compare success, denial, latency, error, token, and cost metrics.

6. Move the named production endpoint only after approval.

7. Preserve the previous known-good version and rollback procedure.

   
   

Do not equate rollback of application code with rollback of all behavior. If prompts, Gateway targets, policies, model configuration, Memory strategy, or retrieval content changed independently, record and version them too.

Automate Deployment with CI/CD

A production pipeline should use short-lived federation, such as GitHub Actions OIDC, rather than repository secrets containing long-lived AWS keys. A typical flow is:

Pull request
  -> lint, type check, unit and graph tests
  -> dependency and secret scanning
  -> adversarial and evaluation subset
  -> artifact build and SBOM
  -> deploy candidate runtime version
  -> cloud smoke and integration tests
  -> full evaluation and security gates
  -> approval
  -> update named production endpoint
  -> monitor and auto/assisted rollback

Keep the infrastructure preview from agentcore deploy --dry-run as an auditable pipeline artifact. Run agentcore validate where appropriate, and query agentcore status, logs, and traces during smoke validation.

For container mode, scan the pushed image in ECR, deploy by immutable digest, and reject mutable-only references such as latest. Sign artifacts if the organization's supply-chain policy requires it.

The deployment workflow should be idempotent and environment-aware. Development, staging, and production need different roles, KMS keys, log groups, memory resources, endpoints, budgets, and possibly accounts. Copying one broad development role into production is not promotion.

Reliability Patterns for AgentCore Agents

Bound every loop

LangGraph makes cycles explicit, which is powerful and dangerous. Define:

• recursion or step limits;

• model-call limits;

• tool-call limits;

• per-tool deadlines;

• overall request deadline;

• token budgets; and

• maximum payload and response sizes.

  
  

AgentCore supports long-running workloads, but an eight-hour capability is not an invitation to let an interactive request run indefinitely. Set runtime idle and maximum lifetime based on the workload.

Retry only when it is safe

Retry model throttling and transient read failures with capped exponential backoff and jitter. Do not blindly retry a side-effecting tool. Use idempotency keys and ask the downstream system whether the previous request committed before attempting it again.

Classify failure by node. If the status API fails, the agent can say current health is unavailable and avoid diagnosis. It should not convert an unavailable signal into “healthy.”

Handle partial and streaming responses

If the user disconnects during streaming, decide whether graph execution should stop, finish asynchronously, or persist a result. For long tasks, expose an operation identifier and status resource rather than keeping a fragile client connection open.

Degrade capabilities, not controls

When Memory is unavailable, the agent may operate without personalization. When a low-risk search tool is unavailable, it may ask for a source. When Policy cannot evaluate a sensitive action, the action must fail closed.

Performance and Cost Model

AgentCore Runtime pricing is consumption-based: billed runtime CPU and peak memory are measured per second, subject to the current minimums and service terms. Model inference, Gateway, Memory, Browser, Code Interpreter, evaluations, logs, traces, data transfer, NAT, and downstream services can add separate costs.

A useful unit economics model is:

Cost per successful task =
  runtime compute
  + model input and output tokens
  + tool and Gateway calls
  + memory operations
  + evaluation sampling
  + observability ingestion and retention
  + network and downstream service cost
  ---------------------------------------
  successful business tasks

Measure cost per successful task, not merely cost per request. A cheap request that loops, fails, or creates manual rework is not efficient.

Cost controls that preserve quality

• route simple classification to a smaller approved model where evaluation supports it;

• retrieve only the context required for the task;

• cap graph steps and response length;

• cache deterministic, non-sensitive reference data with appropriate freshness controls;

• reduce verbose tool output before sending it to the model;

• sample online evaluations based on risk instead of evaluating every low-risk request;

• tune log and trace retention by environment;

• avoid NAT paths when private endpoints are available and appropriate; and

• set budgets and anomaly alerts per environment and tenant.

  
  

Use the current Amazon Bedrock AgentCore pricing page for rates. Avoid hard-coding a cost estimate before load tests reveal token use, tool latency, concurrency, and memory patterns.

A Worked Production Request

Consider an authenticated employee asking:

“Checkout feels slow. Is it down? Restart it if necessary.”

A controlled execution should look like this:

1. The application authenticates the employee and invokes the named production Runtime endpoint.

2. AgentCore creates or resumes the isolated session associated with the verified caller and conversation.

3. LangGraph sends the request to the model with bounded system instructions and approved tool definitions.

4. The model selects get_service_status with checkout-api.

5. Gateway Policy confirms the caller may read status for that service. Outbound authentication calls the internal status API.

6. The tool reports degraded, elevated p95 latency, and runbook RB-CHECKOUT-04; it does not report an outage.

7. The graph returns the evidence to the model.

8. The model states that the service is degraded, avoids claiming it is down, and references the runbook.

9. The restart request is not executed. The response explains that remediation requires an approved operational workflow.

10. The trace records the graph path, model use, tool parameters, policy decision, latency, and safe response without exposing credentials or unnecessary incident data.

11. An evaluation sample scores goal success, groundedness, tool choice, parameter accuracy, and refusal behavior.

    
    

The success is not “the model answered.” Success is that the right caller accessed the right evidence, the model did not overstate it, the unapproved action did not occur, and the result can be audited.

Common Deployment Failures

The graph works locally but Runtime returns a validation error

Check the entrypoint, request serialization, environment variables, architecture, health contract, and MMDSv2 setting. For custom containers, verify ARM64 compatibility, port 8080, 0.0.0.0, /invocations, and /ping.

The model can answer but cannot call Bedrock

Confirm model access, Region, model or inference profile identifier, and execution-role permissions for the exact Bedrock resource. A developer's local credentials can hide a missing Runtime permission.

Sessions appear to forget prior turns

Runtime isolation is not the same as a LangGraph checkpointer. Verify a persistent checkpointer, stable thread ID, verified actor ID, and the required AgentCore Memory permissions.

One user sees another user's context

Stop traffic and treat this as a security incident. Audit how actor and thread keys are derived, whether request-body identity was trusted, memory resource scoping, cache keys, logs, and tenant filters. Add adversarial isolation tests before reopening.

The agent repeatedly calls a tool

Inspect the trace for tool output the model cannot interpret, ambiguous tool descriptions, missing terminal conditions, or errors that are returned as normal data. Add step limits and a deterministic loop breaker.

The latest deployment unexpectedly changed production

The production path probably relied on the DEFAULT endpoint, which follows the latest Runtime version. Pin a named production endpoint to an approved version and separate deployment from promotion.

Latency is high even though model time is acceptable

Break down graph nodes, Gateway policy evaluation, downstream API time, retries, VPC/NAT path, cold dependencies, memory operations, serialization, and observability export. End-to-end latency rarely belongs to the model alone.

When AgentCore Is a Good Fit

This architecture is well suited when:

• LangGraph is the preferred orchestration framework but the team wants an AWS-managed agent runtime;

• agents need isolated sessions and support for real-time or long-running work;

• the organization needs IAM or JWT-based invocation;

• tools must be exposed through governed enterprise API boundaries;

• AWS-native telemetry, evaluation, networking, and security controls are valuable;

• the model may be on Amazon Bedrock or another supported provider; and

• teams want immutable Runtime versions without operating a general-purpose orchestration platform.

  
  

When Not to Use This Architecture

Choose a simpler or different design when:

• the workflow is deterministic and does not need model-directed branching—a Lambda function or Step Functions workflow may be clearer and safer;

• all the application needs is one stateless model call;

• the workload must run in an unsupported Region or processor architecture;

• a platform mandate requires Kubernetes-level scheduling, sidecars, or kernel controls unavailable in the managed runtime;

• the agent depends on unrestricted shell or arbitrary code execution in the Runtime process;

• data or regulatory requirements cannot be satisfied by the proposed AgentCore configuration; or

• the organization is not prepared to own tool authorization, evaluation, on-call response, and model-risk governance.

  
  

Managed infrastructure reduces operational work. It does not turn an under-specified autonomous system into a safe one.

Production Readiness Checklist

Agent contract
[ ] Input and output schemas are versioned.
[ ] Graph nodes, conditional paths, and terminal conditions are documented.
[ ] Tool schemas are typed, narrow, and bounded.
[ ] Step, time, token, and payload limits are enforced.
[ ] Model and prompt configuration are versioned outside source code.

Deployment and release
[ ] Build is reproducible from a locked dependency set.
[ ] Artifact digest, SBOM, source commit, and configuration are recorded.
[ ] CodeZip or ARM64 container mode is chosen intentionally.
[ ] MMDSv2 is enabled.
[ ] Production uses a named endpoint pinned to an approved Runtime version.
[ ] Rollback has been tested.

Identity and security
[ ] IAM SigV4 or JWT inbound authentication is configured and tested.
[ ] Deployment, caller, Runtime, and Gateway roles are separate.
[ ] Generated development policies have been replaced with least privilege.
[ ] Tool authorization is enforced outside model instructions.
[ ] Secrets are stored and rotated outside prompts and source code.
[ ] VPC, egress, endpoint, and encryption choices have passed review.
[ ] Prompt-injection and cross-tenant tests pass.

State and privacy
[ ] Runtime session, checkpoint state, and long-term memory are distinguished.
[ ] Thread and actor identifiers come from verified context.
[ ] Memory retention, deletion, correction, and prohibited data are defined.
[ ] Logs and traces are redacted and retention-controlled.

Operations and evaluation
[ ] End-to-end traces link Runtime, graph, model, policy, and tool activity.
[ ] SLOs and alert thresholds exist for availability, latency, errors, and quality.
[ ] Deterministic tests cover permissions and side effects.
[ ] Regression evaluations cover task success, correctness, groundedness, and tool use.
[ ] Online evaluation sampling and incident-response ownership are defined.
[ ] Cost per successful task is measured and budget alerts are active.

Frequently Asked Questions

Can I deploy an existing LangGraph agent to AgentCore?

Yes. Add the AgentCore Runtime entrypoint and use the CLI's bring-your-own-code workflow, or package a compliant custom container. The main work is usually not rewriting the graph; it is formalizing request schemas, dependencies, identity, tool boundaries, state, and telemetry.

Does AgentCore replace LangGraph?

No. LangGraph defines the stateful agent workflow. AgentCore provides a managed runtime and optional services for identity, memory, gateways, policy, observability, and evaluation. They are complementary layers.

Must the LangGraph agent use an Amazon Bedrock model?

AgentCore is framework- and model-agnostic, although using Bedrock often simplifies AWS-native identity, governance, and procurement. Confirm the current support and network requirements for any external provider.

Should I use CodeZip or a container?

Use CodeZip for Python agents without custom operating-system dependencies and when you want the shortest build path. Use Container for controlled base images, system packages, or custom build requirements. AgentCore custom containers must be ARM64-compatible.

Does AgentCore Runtime automatically preserve LangGraph conversation history?

No. Runtime sessions provide isolated execution, but durable LangGraph state requires a checkpointer. AgentCore Memory can integrate with LangGraph for checkpoints and longer-term retrieval when configured with verified actor and thread identities.

How long can an AgentCore session run?

AgentCore supports long-running sessions up to the configured service limits, documented as up to eight hours for Runtime workloads. Configure idle and maximum lifetime for the use case rather than accepting an unnecessarily long session.

Can AgentCore Gateway prevent an unauthorized tool call?

Yes, when the tool is exposed through Gateway and a correctly tested Gateway Policy applies. Cedar policies can enforce deterministic authorization using verified identity and tool parameters. Prompt instructions alone cannot provide the same guarantee.

How do I deploy without changing production immediately?

Deploy a new immutable Runtime version, test it through a non-production or candidate endpoint, and move a named production endpoint only after release gates pass. Avoid relying solely on DEFAULT, because it points to the latest version.

What should I evaluate for a tool-using LangGraph agent?

Measure task success, correctness, groundedness, tool selection, tool parameter accuracy, refusal behavior, policy enforcement, trajectory length, latency, and cost. Include deterministic assertions for high-risk requirements and model-based judges for qualitative rubrics.

How much does an AgentCore deployment cost?

Cost depends on runtime CPU and peak memory duration plus model tokens, Gateway and Memory usage, evaluation, observability, networking, and downstream systems. Estimate from load tests and calculate cost per successful business task using the current AWS pricing page.

From Prototype Graph to Governed Agent

Deploying LangGraph on Amazon Bedrock AgentCore is technically straightforward. Operating it responsibly is a systems-engineering exercise.

The strongest implementation keeps the graph explicit, the Runtime contract small, identity verified, tool authority narrow, state intentionally layered, and releases reversible. It evaluates the agent's path as well as its prose. It assumes failures will occur and makes those failures observable, bounded, and safe.

If your use case also retrieves enterprise knowledge, pair this deployment model with an appropriate RAG architecture. Our guides to enterprise RAG with Amazon Bedrock Knowledge Bases and Bedrock Knowledge Bases versus custom RAG explain that decision separately.

Need a LangGraph Agent Deployed on AWS?

Codersarts AI Agent Development Services can help design, implement, and productionize LangGraph agents in your AWS environment—from graph and tool design through AgentCore Runtime, Gateway, identity, memory, evaluation, security controls, observability, and CI/CD.

We can support:

• architecture and threat modeling;

• LangGraph implementation and migration;

• Amazon Bedrock and AgentCore integration;

• secure enterprise tool and API integration;

• RAG and memory design;

• evaluation datasets and release gates;

• VPC, IAM, KMS, and monitoring configuration; and

• proof-of-concept through production rollout.

  
  

For a broader custom AI program, see our AI Development Services. If retrieval is central to the agent, explore RAG Development Services.

Discuss your Amazon Bedrock AgentCore requirement

Bring your current LangGraph repository, target workflow, AWS constraints, and security requirements. We will help turn them into a deployable architecture and a measurable production plan.

Official Technical References

• Amazon Bedrock AgentCore Runtime

• Get started with AgentCore Runtime using the AgentCore CLI

• AgentCore Runtime service contract

• AgentCore Runtime HTTP protocol contract

• AgentCore Runtime versioning

• AgentCore Runtime security best practices

• AgentCore Runtime VPC connectivity

• Integrate AgentCore Memory with LangGraph

• AgentCore Gateway

• AgentCore Gateway Policy

• AgentCore Observability

• AgentCore Evaluations

• LangChain ChatBedrock integration

• LangGraph quickstart

• Amazon Bedrock AgentCore pricing

  
  

Recommended structured data for publishing

Use TechArticle as the primary schema, with BreadcrumbList and Organization. Add FAQPage only if the FAQ is visible on the published page and the implementation complies with the search engine's current structured-data policies. Include the visible dateModified, named author or reviewer, publisher, canonical URL, hero image, and about entities for LangGraph, Amazon Bedrock AgentCore, agentic AI, and AWS.

Suggested social copy

Deploying a LangGraph agent is the easy part. Production requires identity, tool authorization, memory boundaries, traces, evaluations, and reversible releases. This 2026 guide shows how those layers fit together on Amazon Bedrock AgentCore.