AWS AgentCore + LangGraph
Multi-agent systems on AWS Bedrock AgentCore with LangGraph orchestration. Source: https://github.com/aws/bedrock-agentcore-starter-toolkit
Install
pip install bedrock-agentcore bedrock-agentcore-starter-toolkit langgraph
uv tool install bedrock-agentcore-starter-toolkit # installs agentcore CLI
Quick Start
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition # routing + tool execution
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from typing import Annotated
from typing_extensions import TypedDict
class State(TypedDict):
messages: Annotated[list, add_messages]
builder = StateGraph(State)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode(tools)) # prebuilt tool executor
builder.add_conditional_edges("agent", tools_condition) # routes to tools or END
builder.add_edge(START, "agent")
graph = builder.compile()
app = BedrockAgentCoreApp() # Wraps as HTTP service on port 8080 (/invocations, /ping)
@app.entrypoint
def invoke(payload, context):
result = graph.invoke({"messages": [("user", payload.get("prompt", ""))]})
return {"result": result["messages"][-1].content}
app.run()
CLI Commands
| Command |
Purpose |
agentcore configure -e agent.py --region us-east-1 |
Setup |
agentcore configure -e agent.py --region us-east-1 --name my_agent --non-interactive |
Scripted setup |
agentcore launch --deployment-type container |
Deploy (container mode) |
agentcore launch --disable-memory |
Deploy without memory subsystem |
agentcore dev |
Hot-reload local dev server |
agentcore invoke '{"prompt": "Hello"}' |
Test |
agentcore destroy |
Cleanup |
Core Patterns
Multi-Agent Orchestration
- Orchestrator delegates to specialists (customer service, e-commerce, healthcare, financial, etc.)
- Specialists: inline functions or separate deployed agents; all share
session_id for context
Memory (STM/LTM)
from bedrock_agentcore.memory import MemoryClient
memory = MemoryClient()
memory.create_event(session_id, actor_id, event_type, payload) # Store
events = memory.list_events(session_id) # Retrieve (returns list)
- STM: Turn-by-turn within session | LTM: Facts/decisions across sessions/agents
- ~10s eventual consistency after writes
Gateway Tools
python -m bedrock_agentcore.gateway.deploy --stack-name my-agents --region us-east-1
from bedrock_agentcore.gateway import GatewayToolClient
gateway = GatewayToolClient()
result = gateway.call("tool_name", param1=value1, param2=value2)
- Transport: Fallback Mock (local), Local MCP servers, Production Gateway (Lambda/REST/MCP)
- Auto-configures
BEDROCK_AGENTCORE_GATEWAY_URL after deploy
Decision Tree
Multiple agents coordinating? → Orchestrator + specialists pattern
Persistent cross-session memory? → AgentCore Memory (not LangGraph checkpoints)
External APIs/Lambda? → AgentCore Gateway
Single agent, simple? → Quick Start above
Complex multi-step logic? → StateGraph + tools_condition + ToolNode
Key Concepts
- AgentCore Runtime: HTTP service on port 8080 (handles
/invocations, /ping)
- AgentCore Memory: Managed cross-session/cross-agent memory
- LangGraph Routing:
tools_condition for agent→tool routing, ToolNode for execution
- AgentCore Gateway: Transforms APIs/Lambda into MCP tools with auth
Naming Rules
- Start with letter, only letters/numbers/underscores, 1-48 chars:
my_agent not my-agent
Troubleshooting
| Issue |
Fix |
on-demand throughput isn't supported |
Use us.anthropic.claude-* inference profiles |
Model use case details not submitted |
Fill Anthropic form in Bedrock Console |
Invalid agent name |
Use underscores not hyphens |
| Memory empty after write |
Wait ~10s (eventual consistency) |
| Container not reading .env |
Set ENV in Dockerfile, not .env |
| Memory not working after deploy |
Check logs for "Memory enabled/disabled" |
list_events returns empty |
Check actor_id/session_id match; event['payload'] is a list |
| Gateway "Unknown tool" |
Lambda must strip ___ prefix from bedrockAgentCoreToolName |
| Platform mismatch warning |
Normal - CodeBuild handles ARM64 cross-platform builds |
References
- agentcore-cli.md - CLI commands, deployment, lifecycle
- agentcore-runtime.md - Streaming, async, observability
- agentcore-memory.md - STM/LTM patterns, API reference
- agentcore-gateway.md - Tool integration, MCP, Lambda
- langgraph-patterns.md - StateGraph design, routing
- reference-architecture-advertising-agents-use-case.pdf - Example multi-agent architecture
1---2name: aws-agentcore-langgraph3description: Deploy production LangGraph agents on AWS Bedrock AgentCore. Use for (1) multi-agent systems with orchestrator and specialist agent patterns, (2) building stateful agents with persistent cross-session memory, (3) connecting external tools via AgentCore Gateway (MCP, Lambda, APIs), (4) managing shared context across distributed agents, or (5) deploying complex agent ecosystems via CLI with production observability and scaling.4---5
6# AWS AgentCore + LangGraph
7
8Multi-agent systems on AWS Bedrock AgentCore with LangGraph orchestration. Source: https://github.com/aws/bedrock-agentcore-starter-toolkit
9
10## Install
11```bash
12pip install bedrock-agentcore bedrock-agentcore-starter-toolkit langgraph
13uv tool install bedrock-agentcore-starter-toolkit # installs agentcore CLI
14```
15
16## Quick Start
17```python
18from langgraph.graph import StateGraph, START
19from langgraph.graph.message import add_messages
20from langgraph.prebuilt import ToolNode, tools_condition # routing + tool execution
21from bedrock_agentcore.runtime import BedrockAgentCoreApp
22from typing import Annotated
23from typing_extensions import TypedDict
24
25class State(TypedDict):
26 messages: Annotated[list, add_messages]
27
28builder = StateGraph(State)
29builder.add_node("agent", agent_node)
30builder.add_node("tools", ToolNode(tools)) # prebuilt tool executor
31builder.add_conditional_edges("agent", tools_condition) # routes to tools or END
32builder.add_edge(START, "agent")
33graph = builder.compile()
34
35app = BedrockAgentCoreApp() # Wraps as HTTP service on port 8080 (/invocations, /ping)
36@app.entrypoint
37def invoke(payload, context):
38 result = graph.invoke({"messages": [("user", payload.get("prompt", ""))]})
39 return {"result": result["messages"][-1].content}
40app.run()
41```
42
43## CLI Commands
44| Command | Purpose |
45|---------|---------|
46| `agentcore configure -e agent.py --region us-east-1` | Setup |
47| `agentcore configure -e agent.py --region us-east-1 --name my_agent --non-interactive` | Scripted setup |
48| `agentcore launch --deployment-type container` | Deploy (container mode) |
49| `agentcore launch --disable-memory` | Deploy without memory subsystem |
50| `agentcore dev` | Hot-reload local dev server |
51| `agentcore invoke '{"prompt": "Hello"}'` | Test |
52| `agentcore destroy` | Cleanup |
53
54## Core Patterns
55
56### Multi-Agent Orchestration
57- Orchestrator delegates to specialists (customer service, e-commerce, healthcare, financial, etc.)
58- Specialists: inline functions or separate deployed agents; all share `session_id` for context
59
60### Memory (STM/LTM)
61```python
62from bedrock_agentcore.memory import MemoryClient
63memory = MemoryClient()
64memory.create_event(session_id, actor_id, event_type, payload) # Store
65events = memory.list_events(session_id) # Retrieve (returns list)
66```
67- **STM**: Turn-by-turn within session | **LTM**: Facts/decisions across sessions/agents
68- ~10s eventual consistency after writes
69
70### Gateway Tools
71```bash
72python -m bedrock_agentcore.gateway.deploy --stack-name my-agents --region us-east-1
73```
74```python
75from bedrock_agentcore.gateway import GatewayToolClient
76gateway = GatewayToolClient()
77result = gateway.call("tool_name", param1=value1, param2=value2)
78```
79- Transport: Fallback Mock (local), Local MCP servers, Production Gateway (Lambda/REST/MCP)
80- Auto-configures `BEDROCK_AGENTCORE_GATEWAY_URL` after deploy
81
82## Decision Tree
83```
84Multiple agents coordinating? → Orchestrator + specialists pattern
85Persistent cross-session memory? → AgentCore Memory (not LangGraph checkpoints)
86External APIs/Lambda? → AgentCore Gateway
87Single agent, simple? → Quick Start above
88Complex multi-step logic? → StateGraph + tools_condition + ToolNode
89```
90
91## Key Concepts
92- **AgentCore Runtime**: HTTP service on port 8080 (handles `/invocations`, `/ping`)
93- **AgentCore Memory**: Managed cross-session/cross-agent memory
94- **LangGraph Routing**: `tools_condition` for agent→tool routing, `ToolNode` for execution
95- **AgentCore Gateway**: Transforms APIs/Lambda into MCP tools with auth
96
97## Naming Rules
98- Start with letter, only letters/numbers/underscores, 1-48 chars: `my_agent` not `my-agent`
99
100## Troubleshooting
101| Issue | Fix |
102|-------|-----|
103| `on-demand throughput isn't supported` | Use `us.anthropic.claude-*` inference profiles |
104| `Model use case details not submitted` | Fill Anthropic form in Bedrock Console |
105| `Invalid agent name` | Use underscores not hyphens |
106| Memory empty after write | Wait ~10s (eventual consistency) |
107| Container not reading .env | Set ENV in Dockerfile, not .env |
108| Memory not working after deploy | Check logs for "Memory enabled/disabled" |
109| `list_events` returns empty | Check actor_id/session_id match; `event['payload']` is a list |
110| Gateway "Unknown tool" | Lambda must strip `___` prefix from `bedrockAgentCoreToolName` |
111| Platform mismatch warning | Normal - CodeBuild handles ARM64 cross-platform builds |
112
113## References
114- [agentcore-cli.md](references/agentcore-cli.md) - CLI commands, deployment, lifecycle
115- [agentcore-runtime.md](references/agentcore-runtime.md) - Streaming, async, observability
116- [agentcore-memory.md](references/agentcore-memory.md) - STM/LTM patterns, API reference
117- [agentcore-gateway.md](references/agentcore-gateway.md) - Tool integration, MCP, Lambda
118- [langgraph-patterns.md](references/langgraph-patterns.md) - StateGraph design, routing
119- [reference-architecture-advertising-agents-use-case.pdf](references/reference-architecture-advertising-agents-use-case.pdf) - Example multi-agent architecture
modbender