How to Deploy a LangGraph Agent on AWS Bedrock AgentCore

You’ve built a LangGraph agent that works fine on your laptop. The next challenge is getting it running in a scalable, serverless production infrastructure without having to redesign the whole thing.

That’s where AWS Bedrock AgentCore comes in. In this guide, I’ll show you how to put a wrapper for your existing agent to make it run on AgentCore, set up an AgentCore project, test it locally, deploy it to AWS, and invoke it after deployment.

---

What Is AWS Bedrock AgentCore?

AgentCore is a serverless hosting platform designed by AWS to deploy, scale, and operate your AI agents securely without you managing the infrastructure. It works with any open-source framework like LangGraph, Strands, CrewAI, or LlamaIndex and supports Large Language Models like OpenAI's GPT, Google's Gemini, or Anthropic's Claude. So you don’t have to rewrite the agent logic. It also provides session isolation, persistent memory, observability and identity management.

The deployment is managed through the AgentCore CLI, a Node.js tool that scaffolds projects, runs a local dev server, and deploys to AWS using CDK under the hood.

---

Prerequisites

Before you start, make sure you have the following in place:

• Python 3.12+
• uv or pip for Python dependency management
• Node.js 20+ — the AgentCore CLI is an npm package
• AWS CDK installed globally (npm install -g aws-cdk)
• An AWS account with credentials configured locally (aws configure)
• Your existing LangGraph agent code that creates a compiled StateGraph object

---

Step 1 — Install the AgentCore CLI

The AgentCore workflow starts with a single command-line tool. You’ll use it to create the project, run the app locally, and deploy it to AWS cloud.

Install the CLI:

npm install -g @aws/agentcore

Verify it after the installation:

agentcore --help

---

Step 2 — Add Additional Dependencies

Add the following packages to your agent's dependencies:
- bedrock-agentcore - the Python SDK that provides the BedrockAgentCoreApp wrapper class.
- aws-opentelemetry-distro - AWS-supported distribution of the OpenTelemetry Python Instrumentation package.

# pyproject.toml
[project]
name = "my-agent"
version = "0.1.0"
requires-python = ">=3.12"

dependencies = [
    "aws-opentelemetry-distro==0.17.0",
    "bedrock-agentcore>=1.6.3",
    "boto3>=1.42.0",
    "langgraph>=1.1.0",
    "langchain-core>=1.2.0",
    # ... your other existing dependencies
]

Install all dependencies with your usual workflow:

uv sync
# or: pip install -e .

---

Step 3 — Write the AgentCore Entrypoint (main.py)

AgentCore expects a single Python file as the entrypoint with a BedrockAgentCoreApp instance and a function decorated with @app.entrypoint. The important part is that your LangGraph logic does not need to change much; you’re just wrapping it in a small runtime entrypoint.

Here is the basic structure:

# main.py

from langchain_core.messages import HumanMessage
from bedrock_agentcore.runtime import BedrockAgentCoreApp

from graphs.my_agent_graph import build_my_agent  # your existing graph builder

# 1. Instantiate the AgentCore app and logger
app = BedrockAgentCoreApp()
log = app.logger

# 2. Build your graph at module load time (startup)
#    AgentCore initialises the module once, then handles concurrent invocations.
#    Any failure here will prevent a broken agent from going live.
def create_agent():
    log.info("Initialising agent...")
    graph = build_my_agent()   # returns your compiled LangGraph StateGraph
    log.info("Agent ready")
    return graph

try:
    graph = create_agent()
except Exception as e:
    log.error(f"Critical failure during agent initialisation: {e}")
    raise  # fail fast — don't let a broken agent start serving requests

# 3. Async helper that drives the LangGraph streaming loop
async def run_agent(user_input: str, session_id: str = "default-session") -> str:
    responses = []
    config = {"configurable": {"thread_id": session_id}}

    async for chunk in graph.astream(
        {"messages": [HumanMessage(content=user_input)]},
        config=config,
        stream_mode="values",
    ):
        messages = chunk.get("messages", [])
        if messages:
            last = messages[-1]
            if getattr(last, "type", None) == "ai":
                responses.append(last)

    if not responses:
        return "No response"

    content = getattr(responses[-1], "content", "")
    return content if isinstance(content, str) else str(content)

# 4. The entrypoint — this is what AgentCore calls on every invocation
@app.entrypoint
async def invoke(payload, context):
    try:
        log.info("Invoke received")
        user_input = payload.get("prompt", "")
        session_id = payload.get("session_id", "default-session")

        if not user_input.strip():
            return {"error": "Prompt cannot be empty"}

        response = await run_agent(user_input, session_id)
        return {"response": response}

    except Exception as e:
        log.error(f"Error: {e}")
        return {"error": str(e)}

# 5. Run the app (only executed when running locally using agentcore dev)
if __name__ == "__main__":
    app.run()

A few things that matter

BedrockAgentCoreApp() gives you the AgentCore runtime wrapper. It sets up the HTTP server, health check endpoints, and structured logging for you.

Module-level graph initialisation — the graph is created once when the module loads, not on every request. That catches startup failures early, which is good because it prevents a broken app from going live.

@app.entrypoint — this decorator registers the function as the handler for incoming invocations. It receives payload (the parsed JSON body) and context (AgentCore request context). It should return a plain JSON-serializable dictionary, not a raw string or a custom object.

session_id → thread_id — The session_id is passed into LangGraph as thread_id, which enables per-session memory with MemorySaver.

---

Step 4 — Create an AgentCore Project

Next, we need to generate our project layout. Run the initialization wizard inside a clean root folder and let it create the basic project layout for you.

agentcore create

The setup wizard will ask a few simple questions, like the project name, language, Python version, entrypoint file, etc. The important part is that the entrypoint and the Python version matches your app.

After the project is created, you’ll get an agentcore.json file (in agentcore folder) that tells AgentCore where your code lives and how to run it.

{
  "name": "MyAgentOnAgentcore",
    "runtimes": [
    {
      "name": "my-agent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/my-agent/",
      "runtimeVersion": "PYTHON_3_12",
      "networkMode": "PUBLIC",
      "protocol": "HTTP",
      "envVars": []
    }
  ]
}

---

Step 5 — Put Your Source Code to the Code Location

Copy or move your agent source into the directory specified by codeLocation in agentcore.json. This part is easy to get wrong, and when it’s wrong, deployment becomes unnecessarily frustrating. I struggled for a while after accidentally putting it in the agentcore folder.

A typical layout should look like this:

MyAgentOnAgentcore/
├──agentcore
    └── agentcore.json
├──app/
    └──my-agent/                       ← codeLocation 
        ├── main.py                  ← entrypoint (matches agentcore.json)
        ├── pyproject.toml           ← or requirements.txt
        ├── src/
        │   └── my_agent_graph.py    ← your LangGraph graph builder
        │   └── tools.py             ← your tools, utilities, etc.
        └── .env                   ← your configuration variables

Make sure main.py sits at the top level of codeLocation and matches the entrypoint in agentcore.json exactly.

Environment variables

AgentCore can pass environment variables into the runtime container. For local testing, a .env file is usually the easiest option.

For production, you can put values in agentcore.json under envVars (.env file also works). But secrets like passwords and API keys are better stored in AWS Secrets Manager and loaded at runtime. If you do that, the AgentCore execution role needs permission to read those secrets.

Note: envVars should be an array of JSON objects with name and value fields.

---

Step 6 — Validate the Project

Before you try to run anything, use AgentCore CLI to validate the project configuration:

agentcore validate

This catches the common mistakes early, like a missing entrypoint file or a bad path in the config.

---

Step 7 — Run and Test Locally

Start the local runtime to test the agent locally:

agentcore dev

This spins up a local HTTP server that closely mirrors the production environment for testing. If everything is wired up properly, you should see that the app is ready and listening on a local port.

Test on Local Server

You can test an invocation using either the AgentCore CLI or curl:

agentcore invoke "Summarise last month sales"

Or

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise last month sales", "session_id": "test-001"}'

A successful response should come back as JSON with the agent’s answer in it.

{"response": "Last month, total sales were $1.2M across 3 regions..."}

---

Step 8 — Deploy to AWS

Once local testing looks solid, deploy to AWS Bedrock AgentCore Runtime:

agentcore deploy

Under the hood, the CLI:

1. Packages your code
2. Provisions an S3 bucket for direct code deploy
3. Creates an IAM execution role
4. Deploys the AgentCore Runtime via CDK

The first deploy takes a few minutes. Subsequent deploys tend to be faster.

When it’s successfully completed, check the runtime status. It will display the runtime ARN and HTTP URL to invoke the deployed agent.

agentcore status

---

Step 9 — Invoke the Deployed Agent

The easiest way to test the deployed version is with the CLI:

agentcore invoke --prompt "Who are the top 5 customers by revenue?" --session-id "session-id-with-length-greater-than-or-equal-33"

If you want to call it using HTTP, you’ll need to sign the request with AWS SigV4.

curl -X POST "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn-of-MyAgentOnAgentcore-xxxx/invocations" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-east-1:bedrock-agentcore" \
  -H "Content-Type: application/json" \
  -H "x-amzn-bedrock-agentcore-runtime-session-id: session-id-with-length-greater-than-or-equal-33" \
  -d '{"prompt": "Who are the top 5 customers by revenue?"}'

Use the HTTP URL displayed by agentcore status.

When integrating your agent with other Python applications, using the SDK is usually the cleanest approach. You can keep the runtime ARN in an environment variable, send the prompt, and pass the same session ID back on follow-up requests.

# invoke_agent.py
import json
import boto3
import os
from dotenv import load_dotenv

load_dotenv()

client = boto3.client("bedrock-agentcore", region_name="us-east-1")
runtime_arn = os.getenv("AGENTCORE_RUNTIME_ARN")

def invoke(prompt: str, session_id: str) -> str:
    payload = json.dumps({"prompt": prompt, "session_id": session_id})

    response = client.invoke_agent_runtime(
        agentRuntimeArn=runtime_arn,
        payload=payload,
        contentType="application/json"
    )

    body = json.loads(response["response"].read().decode())
    return body["response"]

if __name__ == "__main__":
    session_id = ""
    print("Ready. Type 'exit' to quit.")

    while True:
        prompt = input("Your question: ").strip()
        if prompt == "exit":
            break
        if not prompt:
            continue

        params = {
            "agentRuntimeArn": runtime_arn,
            "payload": json.dumps({"prompt": prompt}),
            "contentType": "application/json"
        }
        if session_id:
            params["runtimeSessionId"] = session_id

        try:
            response = client.invoke_agent_runtime(**params)
            body = json.loads(response["response"].read().decode())
            session_id = response.get("runtimeSessionId", session_id)
            print(f"Agent: {body['response']}\n")
        except Exception as e:
            print(f"Error: {e}")

Set AGENTCORE_RUNTIME_ARN in your .env file:

AGENTCORE_RUNTIME_ARN=arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/MyAgentOnAgentcore-xxxx

Maintaining session state across invocations

Notice runtimeSessionId in the boto3 example. AgentCore returns a runtimeSessionId in every response. Passing it back in the next request tells AgentCore to route subsequent calls to the same session context — which, combined with LangGraph's MemorySaver, gives the agent full conversation memory across multiple HTTP calls.

---

Common Gotchas

Startup failures are intentional. If create_agent() raises at module load, AgentCore will refuse to start the runtime. This is a feature, not a bug — it prevents an incorrectly configured agent (missing credentials, wrong DB URL) from going live silently.

The execution role AgentCore creates needs explicit permissions for any AWS service your agent touches, including Secrets Manager and S3. Add those permissions after the first deploy.

The Python version in pyproject.toml should match the runtime version in agentcore.json.

The entrypoint should return a JSON-serialisable dictionary. If it returns a plain string or a custom object, the runtime boundary will reject it.

---

Conclusion

The transition from a local LangGraph agent to an AgentCore deployment really comes down to a few practical changes: add the right dependencies, wrap the graph in BedrockAgentCoreApp, scaffold the project, test locally, then deploy and invoke it.

Everything else — the graph, the tools, the model calls, and the memory setup — stays mostly the same. AgentCore handles the runtime side, and LangGraph handles the agent logic.

A full working example is available at github.com/thedataengr/data-agent-on-aws-agentcore.