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.
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.
Before you start, make sure you have the following in place:
npm install -g aws-cdk
)aws configure
)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
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.
[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",
]
Install all dependencies with your usual workflow:
uv sync
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:
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
app = BedrockAgentCoreApp()
log = app.logger
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
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)
@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)}
if __name__ == "__main__":
app.run()
** 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
. 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": []
}
]
}
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.
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.
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.
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.
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..."}
Once local testing looks solid, deploy to AWS Bedrock AgentCore Runtime:
agentcore deploy
Under the hood, the CLI:
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
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.
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
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.
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.
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.