Bedrock AgentCore Python SDK：零基础设施部署AI代理的终极方案

Bedrock AgentCore SDK

Bedrock AgentCore SDK

将本地AI代理零基础设施部署到Bedrock AgentCore

<a href="https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/aws/bedrock-agentcore-sdk-python"/></a>
<a href="https://pypi.org/project/bedrock-agentcore"><img alt="PyPI version" src="https://img.shields.io/pypi/v/bedrock-agentcore"/></a>
<a href="https://python.org"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/bedrock-agentcore"/></a>

项目概述

Bedrock AgentCore Python SDK 是一个完整的AI代理开发框架，支持将本地开发的AI代理无缝部署到AWS Bedrock AgentCore服务，无需管理任何基础设施。该SDK提供了运行时框架、内存管理、身份验证和工具集成等核心功能。

功能特性

🚀 核心功能

• 零基础设施部署：将本地AI代理直接部署到Bedrock AgentCore服务
• 完整运行时框架：基于Starlette的Web服务器，包装用户函数为HTTP端点
• 智能内存管理：支持短期会话记忆和长期语义记忆
• 多策略记忆系统：语义记忆、摘要记忆、用户偏好记忆和自定义记忆策略

🔐 安全认证

• OAuth2身份验证：支持机器对机器(M2M)和用户联邦认证流程
• API密钥认证：灵活的API密钥管理装饰器
• AWS SigV4签名：所有API通信的安全认证
• TLS 1.2+强制：确保所有通信的安全性

🛠️ 工具集成

• 浏览器沙箱：使用Playwright进行安全的Web自动化
• 代码解释器：安全的代码执行沙箱环境
• 会话管理：完整的多用户、多会话对话管理
• 分支对话：支持创建和管理对话分支

📊 记忆能力

• 短期记忆(STM)：会话内的对话事件持久化
• 长期记忆(LTM)：跨会话的语义记忆和用户偏好
• 智能检索：基于相关性的记忆记录检索
• 多命名空间：灵活的记忆数据组织

安装指南

系统要求

• Python 3.8+
• AWS账户和凭证配置
• Bedrock AgentCore服务访问权限

安装步骤

# 基础安装
pip install bedrock-agentcore

# 包含Strands代理集成
pip install 'bedrock-agentcore[strands-agents]'

# 开发模式安装
git clone https://github.com/aws/bedrock-agentcore-sdk-python.git
cd bedrock-agentcore-sdk-python
uv sync
source .venv/bin/activate

环境配置

# 配置AWS凭证
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-west-2

# 可选：自定义端点（用于测试环境）
export BEDROCK_AGENTCORE_DP_ENDPOINT=your_data_plane_endpoint
export BEDROCK_AGENTCORE_CP_ENDPOINT=your_control_plane_endpoint

使用说明

基础使用示例

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.runtime import RequestContext

# 创建应用实例
app = BedrockAgentCoreApp()

@app.run()
async def my_agent_handler(context: RequestContext, input_text: str) -> str:
    """简单的AI代理处理器"""
    return f"处理后的响应: {input_text}"

# 启动应用
if __name__ == "__main__":
    app.start()

记忆会话管理

from bedrock_agentcore.memory import MemorySessionManager
from bedrock_agentcore.memory.constants import MessageRole

# 初始化会话管理器
manager = MemorySessionManager(
    memory_id="my-memory-123",
    region_name="us-east-1"
)

# 创建会话
session = manager.create_session(
    actor_id="user-123",
    session_id="conversation-456"
)

# 添加对话轮次
await session.add_turn(
    user_message="今天天气怎么样？",
    assistant_message="今天天气晴朗，温度适宜。"
)

# 检索相关记忆
records = await session.retrieve_memory_records(
    query="天气信息",
    top_k=5
)

身份验证集成

from bedrock_agentcore.auth import requires_access_token

@requires_access_token(
    provider_name="my-oauth-provider",
    scopes=["read:data", "write:data"],
    auth_flow="USER_FEDERATION"
)
async def protected_operation(access_token: str, data: dict) -> dict:
    """需要OAuth2访问令牌的保护操作"""
    # 使用access_token调用受保护的API
    return {"status": "success", "data": data}

浏览器自动化

from bedrock_agentcore.tools import browser_session

async def web_automation_example():
    """浏览器自动化示例"""
    async with browser_session(region="us-west-2") as browser:
        # 导航到网页
        await browser.goto("https://example.com")
        
        # 执行页面操作
        content = await browser.get_content()
        return f"页面内容: {content}"

核心代码解析

1. 运行时应用核心

"""BedrockAgentCore Runtime SDK - 构建和部署AI代理的Python SDK"""

from .runtime import BedrockAgentCoreApp, BedrockAgentCoreContext, RequestContext
from .runtime.models import PingStatus

__all__ = [
    "BedrockAgentCoreApp",
    "RequestContext", 
    "BedrockAgentCoreContext",
    "PingStatus",
]

代码说明：

• BedrockAgentCoreApp：主应用类，管理代理生命周期
• RequestContext：HTTP请求上下文，包含会话和请求元数据
• BedrockAgentCoreContext：代理身份上下文，管理访问令牌和请求头
• PingStatus：健康检查状态枚举，支持HEALTHY和HEALTHY_BUSY状态

2. 记忆客户端实现

"""AgentCore Memory SDK - 记忆操作的高级客户端"""

class MemoryClient:
    """Bedrock AgentCore Memory的高级客户端，提供基本操作"""
    
    # AgentCore Memory数据平面方法
    _ALLOWED_GMDP_METHODS = {
        "retrieve_memory_records",
        "get_memory_record", 
        "delete_memory_record",
        "list_memory_records",
        "create_event",
        "get_event",
        "delete_event", 
        "list_events",
    }
    
    # AgentCore Memory控制平面方法  
    _ALLOWED_GMCP_METHODS = {
        "create_memory",
        "get_memory",
        "list_memories",
        "update_memory",
        "delete_memory",
        "list_memory_strategies",
    }

    def __init__(self, region_name: Optional[str] = None):
        """初始化Memory客户端"""
        self.region_name = region_name or boto3.Session().region_name or "us-west-2"
        
        self.gmcp_client = boto3.client("bedrock-agentcore-control", region_name=self.region_name)
        self.gmdp_client = boto3.client("bedrock-agentcore", region_name=self.region_name)

代码说明：

• 支持数据平面和控制平面两种操作模式
• 自动处理AWS区域检测，默认回退到us-west-2
• 提供完整的记忆CRUD操作和策略管理

3. 身份验证装饰器

"""Bedrock AgentCore SDK的身份验证装饰器和工具"""

def requires_access_token(
    *,
    provider_name: str,
    into: str = "access_token", 
    scopes: List[str],
    on_auth_url: Optional[Callable[[str], Any]] = None,
    auth_flow: Literal["M2M", "USER_FEDERATION"],
    callback_url: Optional[str] = None,
    force_authentication: bool = False,
    token_poller: Optional[TokenPoller] = None,
) -> Callable:
    """在调用装饰函数之前获取OAuth2访问令牌的装饰器"""
    
    def decorator(func: Callable) -> Callable:
        client = IdentityClient(_get_region())

        async def _get_token() -> str:
            """通用的令牌获取逻辑"""
            return await client.get_token(
                provider_name=provider_name,
                agent_identity_token=await _get_workload_access_token(client),
                scopes=scopes,
                on_auth_url=on_auth_url,
                auth_flow=auth_flow,
                callback_url=callback_url,
                force_authentication=force_authentication
            )

代码说明：

• 支持OAuth2 M2M和用户联邦两种认证流程
• 自动处理令牌获取和刷新
• 提供灵活的回调URL和范围配置
• 支持自定义令牌轮询器实现

4. 会话管理器

"""包含AgentCore Memory交互的会话管理类"""

class MemorySessionManager:
    """管理AWS Bedrock AgentCore的会话和记忆操作"""
    
    def __init__(self, memory_id: str, region_name: str = "us-west-2"):
        """初始化MemorySessionManager"""
        self.memory_id = memory_id
        self.region_name = region_name
        self.client = MemoryClient(region_name=region_name)
        
    async def create_session(self, actor_id: str, session_id: str) -> "MemorySession":
        """为指定参与者和会话创建新的MemorySession"""
        return MemorySession(
            memory_id=self.memory_id,
            actor_id=actor_id,
            session_id=session_id,
            client=self.client
        )

代码说明：

• 简化多会话和多参与者的记忆管理
• 自动处理memory_id、actor_id和session_id参数
• 提供LLM集成的内置回调模式
• 支持对话分支和替代流程管理

5. 浏览器客户端

"""与浏览器沙箱服务交互的客户端"""

class BrowserClient:
    """与AWS浏览器沙箱服务交互的客户端"""
    
    def __init__(self, region: str) -> None:
        """为指定AWS区域初始化浏览器客户端"""
        self.region = region
        self.data_plane_service_name = "bedrock-agentcore"
        self.client = boto3.client(
            self.data_plane_service_name, 
            region_name=region, 
            endpoint_url=get_data_plane_endpoint(region)
        )
        self._identifier = None
        self._session_id = None

代码说明：

• 提供安全的浏览器自动化环境
• 基于Playwright的Web交互能力
• 支持实时视图和会话管理
• 自动处理凭证签名和安全性

Bedrock AgentCore Python SDK 为AI代理开发提供了完整的企业级解决方案，从本地开发到云端部署的全流程支持，让开发者能够专注于业务逻辑而不必担心基础设施复杂性。