ProcessAWS Bedrock & AgentCore

From notebook to AgentCore Runtime: deploying a LangGraph or CrewAI agent

A LangGraph or CrewAI agent that works in a notebook still needs a runtime contract, authentication, governed tools, memory, tracing and rehearsed failure handling before anyone depends on it. This process walks through deploying such an agent to Amazon Bedrock AgentCore Runtime in nine steps, using a hypothetical research assistant, and flags what usually breaks on the way.

Reviewed 6 min read

On this page
  1. One authenticated request through the deployed agent
  2. Nine steps from notebook to production runtime
  3. Choosing between IAM and JWT inbound authorization
  4. A hypothetical research assistant leaves the notebook
  5. What usually breaks between notebook and production
  6. Questions and answers
  7. Sources

One authenticated request through the deployed agent

Request + JWTValidated, new sessionLoad session eventsMCP tool callAllowed call + tokenResultTool resultStore new eventsStreamed responseAnswer01Clientapplication02AgentCoreRuntime03Agent code(LangGraph)04AgentCore Memory05Gateway withPolicy06Enterprise API
  1. Client application

    The user-facing app that signs the user in and calls the agent with a bearer token.

  2. AgentCore Runtime

    Validates the token, starts or resumes an isolated session and passes the request to your code.

  3. Agent code (LangGraph)

    Your graph or crew, wrapped in the AgentCore entrypoint, deciding which steps and tools to run.

  4. AgentCore Memory

    Holds session events and long-term records the agent reads and writes.

  5. Gateway with Policy

    Checks each tool call against policy and injects the right outbound credential.

  6. Enterprise API

    The internal or third-party system behind the tool.

  1. Client application to AgentCore RuntimeRequest + JWT
  2. AgentCore Runtime to Agent code (LangGraph)Validated, new session
  3. Agent code (LangGraph) to AgentCore MemoryLoad session events
  4. Agent code (LangGraph) to Gateway with PolicyMCP tool call
  5. Gateway with Policy to Enterprise APIAllowed call + token
  6. Enterprise API to Gateway with PolicyResult
  7. Gateway with Policy to Agent code (LangGraph)Tool result
  8. Agent code (LangGraph) to AgentCore MemoryStore new events
  9. Agent code (LangGraph) to AgentCore RuntimeStreamed response
  10. AgentCore Runtime to Client applicationAnswer
Conceptual message sequence for one request. Real runs repeat the tool and memory steps, and every hop emits trace data.

Nine steps from notebook to production runtime

  1. Write the runtime contract

    Document what the agent accepts and returns, every tool it calls and whether each reads or writes, what state must survive between turns, the longest acceptable run and who may call it. Every later step, and every reviewer, works from this document.

    Output
    Runtime contract
    Owner
    Agent developer with product owner

  2. Package the agent for Runtime

    Wrap the graph or crew with the AgentCore SDK's BedrockAgentCoreApp entrypoint and build an ARM64 container image pushed to Amazon ECR, or let the AgentCore CLI scaffold and deploy it9. Under the HTTP contract the container serves requests on port 8080 at the invocations path1.

    Output
    Container image and runtime definition
    Owner
    Agent developer

  3. Configure inbound authentication

    Choose IAM SigV4 for service-to-service callers, or a JWT authorizer with your identity provider's discovery URL and allowed audiences, clients and scopes for user-facing apps. A runtime supports one of the two, not both2.

    Output
    Authorizer configuration
    Owner
    Platform security

  4. Set up outbound credentials

    Create a credential provider in AgentCore Identity for each third-party system, decide whether each call acts for the user or for the agent, and let the token vault hold OAuth tokens and API keys instead of environment variables2.

    Output
    Credential provider list
    Owner
    Platform security

  5. Register tools through Gateway

    Expose APIs, Lambda functions and existing MCP servers as MCP tools behind one gateway endpoint, using OpenAPI, Smithy or Lambda definitions as inputs3. Point the agent's tool client at the gateway rather than at each system.

    Output
    Gateway with registered targets
    Owner
    Agent developer

  6. Add memory deliberately

    Use short-term memory for turn-by-turn context within a session, and long-term memory only for facts worth keeping across sessions4. Scope records per user and write down what must never be stored.

    Output
    Memory design
    Owner
    Agent developer with data owner

  7. Turn on tracing and dashboards

    AgentCore emits built-in metrics; add OpenTelemetry spans in your code for graph nodes, decisions and tool calls so that traces in CloudWatch explain a failure rather than merely record it5.

    Output
    Dashboards and alerts
    Owner
    Operations

  8. Enforce tool boundaries with Policy

    Associate a policy engine with the gateway and write Cedar rules, or natural-language drafts validated into Cedar, stating which principals may call which tools with which arguments6. Then restrict the runtime so that callers cannot bypass the gateway.

    Output
    Policy set
    Owner
    Platform security with process owner

  9. Rehearse failure, evaluate and release

    Set idle timeout and maximum lifetime, test cancellation and recovery in the middle of a tool call, and run an on-demand evaluation set from the pipeline8. Release a version to a named endpoint so that rollback is a pointer change.

    Output
    Release record and runbook
    Owner
    Operations with agent developer

Choosing between IAM and JWT inbound authorization

CriterionIAM SigV4JWT bearer token
Typical callerAnother AWS service or a backend holding IAM credentialsA user-facing application whose users sign in with your identity provider
Proof of the end userNone by default; a user-ID header can be passed but is not checked against a sign-inIssuer, signature, expiry, audience, client and scopes are validated
User-delegated outbound tokensPossible through the user-ID header, whose permission must be tightly restrictedA natural fit: the validated token is exchanged for a workload access token bound to that user
Setup effortThe default, with no extra configurationAn authorizer with a discovery URL and allowed audiences or clients
Fronting with GatewayRestrict invocation to the gateway's execution role with a resource-based policyRestrict invocation with the authorizer's allowed-workload setting

AWS recommends JWT authorization for production deployments where an identity provider is configured2.

A hypothetical research assistant leaves the notebook

What usually breaks between notebook and production

State held in process memory

Early signalAnswers lose context when a new session starts or a microVM is replaced.

MitigationKeep conversation state in AgentCore Memory or a persistent filesystem, never in module-level variables.

Tool calls that outlive the session

Early signalLong reports or slow APIs end in timeouts and half-finished side effects.

MitigationMake writes idempotent, move long work to asynchronous patterns and size lifetime settings from measured runs.

Secrets baked into the container

Early signalAPI keys turn up in environment variables, image layers or logs.

MitigationFetch credentials through Identity at call time and scan images before every release.

Framework internals invisible in traces

Early signalA trace shows one long span for the whole graph run.

MitigationAdd a span per node and per tool call, redacting inputs where needed.

Direct invocations that skip Policy

Early signalSome clients call the runtime endpoint instead of going through the gateway.

MitigationLock runtime invocation to the gateway and alert on any direct call.

Questions and answers

Can I test an AgentCore agent locally before deploying it?

Yes. Runtime hosts a container that implements a documented HTTP contract, so you can run the same image locally and send requests to its invocations path before deploying1. The AgentCore CLI also scaffolds projects and invokes deployed agents. Local runs will not reproduce gateway policies or identity flows, so keep a cloud test environment for those.

How does a Runtime-hosted agent reach systems inside our VPC?

Runtime supports VPC networking, so sessions can reach private endpoints such as internal APIs or databases9. Agree subnets, security groups, VPC endpoints for AWS services and DNS with your platform team before deployment, and keep tool traffic going through Gateway wherever Policy should apply.

What if a task runs longer than an AgentCore session allows?

On the default microVM compute a session can run for up to eight hours, and the Instances compute type supports sessions of up to fourteen days on AWS-managed EC2 capacity7. For work that is merely slow, an asynchronous pattern that returns a job reference and stores progress is usually cleaner than holding a session open.

Does a CrewAI agent need anything different from a LangGraph agent?

Not from Runtime's point of view: both are framework code behind the same entrypoint, and AWS lists both as supported7. The differences are inside the agent: where each framework keeps state, how it calls tools and where you add tracing spans. Map those three points explicitly when moving either framework onto AgentCore Memory, Gateway and Observability.

Sources

  1. Understand the AgentCore Runtime service contract — Amazon Web Services · checked 10 October 2026
  2. Authenticate and authorize with Inbound Auth and Outbound Auth — Amazon Web Services · checked 10 October 2026
  3. Amazon Bedrock AgentCore Gateway — Amazon Web Services · checked 10 October 2026
  4. Add memory to your Amazon Bedrock AgentCore agent — Amazon Web Services · checked 10 October 2026
  5. Observe your agent applications on Amazon Bedrock AgentCore Observability — Amazon Web Services · checked 10 October 2026
  6. Policy in Amazon Bedrock AgentCore: Control Agent Interactions — Amazon Web Services · checked 10 October 2026
  7. Host agent or tools with Amazon Bedrock AgentCore Runtime — Amazon Web Services · checked 10 October 2026
  8. Amazon Bedrock AgentCore Evaluations is now generally available — Amazon Web Services · checked 10 October 2026
  9. AgentCore harness vs. Runtime — Amazon Web Services · checked 10 October 2026

More in AWS Bedrock & AgentCore

Back to AWS Bedrock & AgentCore

Next step

Move your agent prototype onto AgentCore with us

Share the framework, the tools the agent calls and how users will reach it. We will reply with an outline runtime contract and the deployment steps that need the most attention in your account.

Plan an AgentCore deployment