AWS图代理

基于AWS Bedrock AgentCore与LangGraph编排的多代理系统。通过StateGraph状态图定义代理工作流,AgentCore Runtime封装为HTTP服务,Memory管理持久记忆,Gateway集成外部工具。

安装

pip install bedrock-agentcore bedrock-agentcore-starter-toolkit langgraph
uv tool install bedrock-agentcore-starter-toolkit  # 安装agentcore CLI

预检清单(差异化,部署前必读)

部署前逐项确认,避免常见失败:

快速开始

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.add_node("agent", agent_node)
builder.add_node("tools", ToolNode(tools))  # 预置工具执行器
builder.add_conditional_edges("agent", tools_condition)  # 路由到tools或END
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命令速查

多代理模式库(差异化)

模式1:编排器+专家

编排器代理 ──委派──→ 客服专家
         ──委派──→ 电商专家
         ──委派──→ 医疗专家
         ──委派──→ 金融专家

• 编排器根据意图路由到专家
• 专家可以是内联函数或独立部署的代理
• 所有代理共享 session_id 保持上下文

模式2:单一代理+工具

用户输入 → 代理节点 → tools_condition → ToolNode → 回到代理
                    → END(无需工具)

• 最简模式,适合简单场景
• tools_condition 自动路由
• ToolNode 预置工具执行

模式3:复杂多步逻辑

builder = StateGraph(State)
builder.add_node("planner", plan_node)
builder.add_node("executor", execute_node)
builder.add_node("reviewer", review_node)
builder.add_conditional_edges("reviewer", lambda s: "executor" if s["needs_revision"] else END)
builder.add_edge(START, "planner")
builder.add_edge("planner", "executor")
builder.add_edge("executor", "reviewer")

记忆系统(STM/LTM)

from bedrock_agentcore.memory import MemoryClient
memory = MemoryClient()
memory.create_event(session_id, actor_id, event_type, payload)  # 存储
events = memory.list_events(session_id)  # 检索(返回列表)

记忆类型

一致性处理模式(差异化)

记忆写入后约10秒最终一致。应对策略:

import time

def write_and_verify(memory, session_id, actor_id, event_type, payload):
    """写入记忆并验证一致性"""
    memory.create_event(session_id, actor_id, event_type, payload)

    # 等待最终一致性(~10s)
    time.sleep(10)

    # 验证写入
    events = memory.list_events(session_id)
    if not events:
        # 重试逻辑
        memory.create_event(session_id, actor_id, event_type, payload)
        time.sleep(5)

    return memory.list_events(session_id)

注意事项:
- list_events 返回空时,先等待10秒再重试
- event['payload'] 是列表类型
- 确认 actor_id 和 session_id 匹配
- 检查日志中"Memory enabled/disabled"确认记忆已启用

网关工具

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)

传输模式

部署后自动配置 BEDROCK_AGENTCORE_GATEWAY_URL。

Gateway工具注意事项

• Lambda必须从 bedrockAgentCoreToolName 中去除 ___ 前缀
• 否则返回"Unknown tool"错误

决策树(快速路由)

多代理协调? → 编排器+专家模式
跨会话持久记忆? → AgentCore Memory(非LangGraph checkpoints)
外部API/Lambda? → AgentCore Gateway
单一代理,简单? → 快速开始模板
复杂多步逻辑? → StateGraph + tools_condition + ToolNode

关键概念

命名规则

• 字母开头,仅字母/数字/下划线,1-48字符
• 正确: my_agent
• 错误: my-agent(连字符不允许)

成本优化策略(差异化)

常见问题FAQ

Q: 部署后记忆为空怎么办?
A: 记忆写入后有约10秒最终一致性延迟。等待10秒后用 list_events 重新查询。如仍为空,检查日志中是否显示"Memory enabled",确认部署时未使用 --disable-memory。

Q: 容器无法读取.env文件怎么办?
A: 容器模式下.env文件不会被自动读取。在Dockerfile中使用ENV指令设置环境变量,而非依赖.env文件。

Q: 收到"on-demand throughput isn't supported"错误?
A: 使用 us.anthropic.claude-* 推理配置文件替代按需吞吐量。这是区域和模型组合的限制。

Q: 代理名称无效?
A: 代理名称必须字母开头,仅含字母/数字/下划线,1-48字符。将连字符改为下划线(如 my-agent → my_agent)。

Q: Gateway返回"Unknown tool"?
A: Lambda函数必须从 bedrockAgentCoreToolName 参数中去除 ___ 前缀。检查Lambda代码中的工具名处理逻辑。

Q: 平台不匹配警告需要处理吗?
A: 不需要。这是正常的,CodeBuild会处理ARM64跨平台构建。

故障排查

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux
• Python: 3.9+
• AWS账户: 需要AWS账户和Bedrock访问权限

第三方依赖

API Key 配置

• 需要AWS访问密钥(AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY)
• 需要AWS区域配置(AWS_REGION)
• 需要在Bedrock Console完成模型使用审批

可用性分类

• 分类: MD+EXEC(纯Markdown指令,需要命令行执行能力进行部署与管理)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent在AWS Bedrock AgentCore上部署与编排多代理系统。需要Python环境和AWS账户。