AWS AgentCore + LangGraph
Multi-agent systems on AWS Bedrock AgentCore with LangGraph orchestration. Source: https://github.com/aws/bedrock-agentcore-starter-toolkit
Install
CODEBLOCK0
Quick Start
CODEBLOCK1
CLI Commands
| Command | Purpose |
|---|
| INLINECODE0 | Setup |
| INLINECODE1 |
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
CODEBLOCK5
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 INLINECODE14
Troubleshooting
| Issue | Fix |
|---|
| INLINECODE15 | Use us.anthropic.claude-* inference profiles |
| INLINECODE17 |
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/sessionid 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
AWS AgentCore + LangGraph
基于LangGraph编排的AWS Bedrock AgentCore多智能体系统。来源：https://github.com/aws/bedrock-agentcore-starter-toolkit
安装
bash
pip install bedrock-agentcore bedrock-agentcore-starter-toolkit langgraph
uv tool install bedrock-agentcore-starter-toolkit # 安装agentcore CLI
快速开始
python
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition # 路由 + 工具执行
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.addnode(agent, agentnode)
builder.add_node(tools, ToolNode(tools)) # 预构建的工具执行器
builder.addconditionaledges(agent, tools_condition) # 路由到工具或结束
builder.add_edge(START, agent)
graph = builder.compile()
app = BedrockAgentCoreApp() # 封装为端口8080上的HTTP服务（/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命令
| 命令 | 用途 |
|---|
| agentcore configure -e agent.py --region us-east-1 | 配置 |
| agentcore configure -e agent.py --region us-east-1 --name my_agent --non-interactive |
脚本化配置 |
| agentcore launch --deployment-type container | 部署（容器模式） |
| agentcore launch --disable-memory | 无内存子系统部署 |
| agentcore dev | 热重载本地开发服务器 |
| agentcore invoke {prompt: Hello} | 测试 |
| agentcore destroy | 清理 |
核心模式
多智能体编排
- - 编排器将任务委派给专业智能体（客户服务、电子商务、医疗、金融等）
- 专业智能体：内联函数或独立部署的智能体；所有智能体共享session_id以保持上下文
内存（STM/LTM）
python
from bedrock_agentcore.memory import MemoryClient
memory = MemoryClient()
memory.create
event(sessionid, actor
id, eventtype, payload) # 存储
events = memory.list
events(sessionid) # 检索（返回列表）
- - STM：会话内的逐轮记忆 | LTM：跨会话/跨智能体的事实/决策记忆
- 写入后约10秒最终一致性
网关工具
bash
python -m bedrock_agentcore.gateway.deploy --stack-name my-agents --region us-east-1
python
from bedrock_agentcore.gateway import GatewayToolClient
gateway = GatewayToolClient()
result = gateway.call(tool_name, param1=value1, param2=value2)
- - 传输方式：回退模拟（本地）、本地MCP服务器、生产网关（Lambda/REST/MCP）
- 部署后自动配置BEDROCKAGENTCOREGATEWAY_URL
决策树
多个智能体协同？ → 编排器 + 专业智能体模式
需要持久化跨会话记忆？ → AgentCore内存（非LangGraph检查点）
外部API/Lambda？ → AgentCore网关
单一智能体、简单场景？ → 上述快速开始
复杂多步骤逻辑？ → StateGraph + tools_condition + ToolNode
关键概念
- - AgentCore运行时：端口8080上的HTTP服务（处理/invocations、/ping）
- AgentCore内存：托管式跨会话/跨智能体内存
- LangGraph路由：tools_condition用于智能体→工具路由，ToolNode用于执行
- AgentCore网关：将API/Lambda转换为带认证的MCP工具
命名规则
- - 以字母开头，仅包含字母/数字/下划线，1-48个字符：my_agent而非my-agent
故障排除
| 问题 | 修复 |
|---|
| on-demand throughput isnt supported | 使用us.anthropic.claude-*推理配置文件 |
| Model use case details not submitted |
在Bedrock控制台填写Anthropic表单 |
| Invalid agent name | 使用下划线而非连字符 |
| 写入后内存为空 | 等待约10秒（最终一致性） |
| 容器未读取.env | 在Dockerfile中设置ENV，而非.env |
| 部署后内存不工作 | 检查日志中Memory enabled/disabled |
| list
events返回空 | 检查actorid/session_id是否匹配；event[payload]是一个列表 |
| 网关Unknown tool | Lambda必须从bedrockAgentCoreToolName中去除
_前缀 |
| 平台不匹配警告 | 正常 - CodeBuild处理ARM64跨平台构建 |
参考文档
