使用 LlamaIndex 将 Agent 部署到 Amazon Bedrock AgentCore Runtime 并接入沙箱浏览器、代码解释器与持久化记忆

使用 LlamaIndex 将 Agent 部署到 Amazon Bedrock AgentCore Runtime 并接入沙箱浏览器、代码解释器与持久化记忆【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本文围绕 LlamaIndex 官方集成的llama-index-tools-aws-bedrock-agentcore与llama-index-memory-bedrock-agentcore两个包展开讲解如何把基于FunctionAgent构建的 LlamaIndex Agent 以一行代码部署到 Amazon Bedrock AgentCore Runtime 托管平台并为其接入安全沙箱中的浏览器自动化导航、点击、提取内容、代码解释器执行 Python、Shell 命令、文件管理、最长 8 小时会话以及按用户隔离的持久化记忆短期聊天事件 长期语义记忆。读完本文你将掌握 Runtime 的部署方式与 SSE 事件协议、三大 ToolSpec 的完整工具清单与生命周期管理方法以及 Memory 组件在多租户场景下的配置要点并能在本地直接复现可运行示例。概览AgentCore 为 LlamaIndex Agent 提供什么Amazon Bedrock AgentCore 是 AWS 提供的托管 Agent 运行时基础设施负责生产级 AI Agent 的部署与运行。LlamaIndex 的集成在四个方面与之对接RuntimeAgentCoreRuntime适配器包装bedrock-agentcoreSDK 中的BedrockAgentCoreApp自动提供 AgentCore 要求的POST /invocations与GET /ping端点并内置 SSE 流式响应支持使任何 LlamaIndex Agent 都能被部署到 AgentCore Runtime。Browser ToolsAgentCoreBrowserToolSpec让 Agent 在 AWS 安全沙箱浏览器中导航网页、点击元素、提取文本与超链接。Code Interpreter ToolsAgentCoreCodeInterpreterToolSpec让 Agent 在沙箱中执行代码、运行命令、管理文件、安装包支持最长 8 小时的会话。MemoryAgentCoreMemory提供由 Bedrock AgentCore 支撑的持久化托管记忆支持基于事件的短期聊天历史与基于语义检索的长期记忆并通过actor_id实现按用户隔离适配多租户应用。安装与前置条件安装两个集成包pip install llama-index-tools-aws-bedrock-agentcore pip install llama-index-memory-bedrock-agentcore前置条件AWS 凭据已配置可通过环境变量、AWS CLI profile 或 IAM 角色三种方式之一提供IAM 权限需要bedrock-agentcore:*相关操作的权限详见 AgentCore 官方文档Python 3.9使用 Memory 前需要先在 AgentCore 控制台或通过 AWS SDK 创建 memory 资源以获得memory_id。从源码结构看两个包分别位于本仓库的 tools 集成目录 与 memory 集成目录入口导出见 工具包__init__.py它对外公开了AgentCoreBrowserToolSpec、AgentCoreCodeInterpreterToolSpec与AgentCoreRuntime三个核心类。Runtime把 Agent 部署到 AgentCore 托管平台一行代码启动AgentCoreRuntime负责把任意 LlamaIndex Agent 适配为 AgentCore Runtime 应用。最简单的用法如下它会直接启动 uvicorn 服务器并监听8080端口from llama_index.llms.bedrock_converse import BedrockConverse from llama_index.core.agent.workflow import FunctionAgent from llama_index.tools.aws_bedrock_agentcore import ( AgentCoreBrowserToolSpec, AgentCoreRuntime, ) tool_spec AgentCoreBrowserToolSpec(regionus-west-2) tools tool_spec.to_tool_list() llm BedrockConverse( modelus.anthropic.claude-sonnet-4-6-v1, region_nameus-west-2, ) agent FunctionAgent(toolstools, llmllm) # One-liner -- starts uvicorn on port 8080 AgentCoreRuntime.serve(agent)serve是类方法其实现就是创建 runtime 实例并调用run()先runtime cls(agentagent, **kwargs)再runtime.run()。run()内部调用self._app.run(portself._port, hostself._host, **kwargs)启动 uvicorn对应源码 runtime/base.py。更精细的配置如果需要更多控制可以显式构造AgentCoreRuntime实例并手动调用run()runtime AgentCoreRuntime( agentagent, streamTrue, # SSE streaming (default) port8080, # Required port for AgentCore deployment debugFalse, # Enable debug logging memorymemory, # Optional AgentCoreMemory instance ) runtime.run()各参数说明依据 Runtime 构造实现参数默认值说明agent必填要部署的 LlamaIndex Agent如FunctionAgentstreamTrue是否启用 SSE 流式响应False时走非流式 JSON 响应路径port8080uvicorn 监听端口AgentCore 部署要求使用 8080hostNone监听主机默认交给 uvicorn 处理debugFalse是否开启调试日志memoryNone可选的AgentCoreMemory实例用于跨请求持久化lifespan/middlewareNone透传给BedrockAgentCoreApp的 Starlette lifespan 与中间件请求负载与 Session ID 传播Runtime 在收到POST /invocations请求后会从 payload 中提取用户输入。_extract_prompt的实现runtime/base.py#L85-L99支持三种字段名prompt、message、input取值可以是字符串也可以是包含prompt键的字典若均缺失或不是字符串则抛出 400 错误。也就是说调用方只需保证请求体中包含prompt/message/input三者之一的字符串即可。当请求携带X-Amzn-Bedrock-AgentCore-Runtime-Session-Id头时该 Session ID 会自动传播给AgentCoreMemory_get_memory会基于当前 memory 做浅拷贝并把context.session_id替换为请求头中的值从而保证同一会话的对话历史被正确归位runtime/base.py#L101-L111。SSE 流式事件协议开启streamTrue时Runtime 遍历agent.run(...)的stream_events()把 LlamaIndex 的 Workflow 事件转换为 SSE 事件下发实现见 runtime/base.py#L123-L172。事件类型如下EventFieldsDescriptionagent_streamdelta,response,thinking_delta?Token-by-token LLM outputtool_calltool_name,tool_kwargsBefore tool executiontool_resulttool_name,tool_outputAfter tool executiondoneresponseFinal agent responseerrormessageError during streaming其中thinking_delta仅在模型返回思考增量时附带AgentStream、ToolCall、ToolCallResult、AgentOutput这些事件类型来自llama_index.core.agent.workflow.workflow_events。流结束前 Runtime 还会await handler一次以确保后台任务如 memory 写入完成。非流式模式下则直接返回{response: str(result)}的 JSON。Browser Tools沙箱浏览器自动化AgentCoreBrowserToolSpec让 Agent 能够在 AWS 托管的沙箱浏览器中完成网页交互。构造时region缺省时从环境变量获取get_aws_regionidentifier用于指定 VPC 场景下的自定义浏览器资源标识默认标识为aws.browser.v1源码常量见 browser/base.py。可用工具10 个navigate_browser、click_element、extract_text、extract_hyperlinks、get_elements、navigate_back、current_webpage、generate_live_view_url、take_control、release_control生命周期方法程序化调用list_browsers、create_browser、delete_browser、get_browser浏览器工具支持多线程会话隔离每个工具都接受thread_id参数默认defaultToolSpec 内部为每个线程维护独立的浏览器会话_browser_clients字典并发场景下互不干扰。navigate_browser会先校验 URL scheme 必须是http或https才执行跳转。generate_live_view_url用于生成可供人类实时观察浏览器会话的预签名 URL默认 300 秒过期便于人工监督take_control/release_control则分别用于禁用/恢复自动化流让人可以临时接管浏览器。import asyncio from llama_index.llms.bedrock_converse import BedrockConverse from llama_index.tools.aws_bedrock_agentcore import AgentCoreBrowserToolSpec from llama_index.core.agent.workflow import FunctionAgent async def main(): tool_spec AgentCoreBrowserToolSpec(regionus-west-2) tools tool_spec.to_tool_list() llm BedrockConverse( modelus.anthropic.claude-sonnet-4-6-v1, region_nameus-west-2, ) agent FunctionAgent(toolstools, llmllm) response await agent.run( Go to https://news.ycombinator.com/ and tell me the titles of the top 5 posts. ) print(str(response)) await tool_spec.cleanup() asyncio.run(main())注意示例结尾调用了tool_spec.cleanup()它会停止并清理全部浏览器会话也可传thread_id只清理指定线程避免残留远程会话。VPC 场景下传入自定义identifiertool_spec AgentCoreBrowserToolSpec( regionus-west-2, identifiermy-custom-browser-id, )此外生命周期方法支持创建自定义浏览器create_browser可指定name、execution_role_arn、network_modePUBLIC或VPCVPC 模式下还可传入subnet_ids与security_group_ids见 browser/base.py#L859-L907。Code Interpreter Tools沙箱代码执行AgentCoreCodeInterpreterToolSpec让 Agent 在远程沙箱中执行 Python 代码、运行 Shell 命令并管理文件支持最长 8 小时的会话。默认资源标识为aws.codeinterpreter.v1默认超时为 900 秒源码常量见 code_interpreter/base.py。可用工具15 个execute_code、execute_command、read_files、list_files、delete_files、write_files、start_command、get_task、stop_task、upload_file、upload_files、install_packages、download_file、download_files、clear_context生命周期方法程序化调用list_code_interpreters、create_code_interpreter、delete_code_interpreter、get_code_interpreter代码解释器同样是惰性初始化 按线程隔离第一次调用工具时才创建会话之后同一thread_id复用同一沙箱。execute_code支持language参数默认python与clear_context参数start_command/get_task/stop_task组合用于异步启动并跟踪长时间运行的命令install_packages支持带版本说明符的包名如pandas2.0下载文件时二进制内容会以 base64 编码返回。clear_context会重置 Python 执行上下文清空所有变量、导入与函数定义。import asyncio from llama_index.llms.bedrock_converse import BedrockConverse from llama_index.tools.aws_bedrock_agentcore import ( AgentCoreCodeInterpreterToolSpec, ) from llama_index.core.agent.workflow import FunctionAgent async def main(): tool_spec AgentCoreCodeInterpreterToolSpec(regionus-west-2) tools tool_spec.to_tool_list() llm BedrockConverse( modelus.anthropic.claude-sonnet-4-6-v1, region_nameus-west-2, ) agent FunctionAgent(toolstools, llmllm) response await agent.run( Write a Python function that calculates the factorial of a number and test it. ) print(str(response)) await tool_spec.cleanup() asyncio.run(main())同样支持 VPC 场景的自定义identifiertool_spec AgentCoreCodeInterpreterToolSpec( regionus-west-2, identifiermy-custom-interpreter-id, )从 code_interpreter/base.py 的extract_output_from_stream可以看出工具结果会从响应流中提取text类型内容并把resource类型如file://URI 指向的文件内容一并格式化返回给 Agent确保模型能直接读到生成文件的全文。Memory持久化托管记忆AgentCoreMemory提供由 Bedrock AgentCore 支撑的持久化记忆包含两条路径短期记忆通过 events 保存聊天历史create_event/list_events长期记忆通过list_memory_records/retrieve_memories对 memory records 做语义检索基于searchQuery的语义搜索并在注入 prompt 时使用。记忆通过actor_id按用户隔离天然适配多租户应用。注意必须先创建 memory 资源AgentCore 控制台或 AWS SDK获得memory_id才能使用本组件。import asyncio from llama_index.llms.bedrock_converse import BedrockConverse from llama_index.core.agent.workflow import FunctionAgent from llama_index.memory.bedrock_agentcore import ( AgentCoreMemory, AgentCoreMemoryContext, ) async def main(): memory AgentCoreMemory( contextAgentCoreMemoryContext( memory_idyour-memory-id, # from AgentCore console or API actor_iduser-123, session_idsession-456, namespace/, ), region_nameus-west-2, ) llm BedrockConverse( modelus.anthropic.claude-sonnet-4-6-v1, region_nameus-west-2, ) agent FunctionAgent(llmllm, tools[]) # Memory persists across agent runs response await agent.run(My name is Alice., memorymemory) print(str(response)) response await agent.run(What is my name?, memorymemory) print(str(response)) asyncio.run(main())AgentCoreMemoryContext 字段AgentCoreMemoryContext定义于 memory/base.py字段如下字段是否必填说明actor_id必填用户标识用于按用户隔离记忆memory_id必填AgentCore 中创建的 memory 资源 IDsession_id必填会话标识Runtime 部署时会用请求头X-Amzn-Bedrock-AgentCore-Runtime-Session-Id覆盖namespace默认/memory records 的命名空间memory_strategy_id可选长期记忆策略 ID配置后检索长期记忆时使用AgentCoreMemory 的检索与注入机制从 aget 实现 可以看到完整流程先读取该会话的 events 作为聊天历史把历史拼接为检索查询截断前 10000 字符调用retrieve_memories拿到长期记忆记录再通过insert_method决定注入方式InsertMethod.SYSTEM默认把记忆包装成 system message 注入格式为 Below are a set of relevant preferences retrieved from potentially several memory sources: ... This is the end of the retrieved preferences.见 utils.pyInsertMethod.USER把记忆合并进最新的 user message源码中有 TODO 注释当前默认走 SYSTEM 注入。底层通过 boto3 创建bedrock-agentcoreclient并在Config中设置了标准重试模式默认max_attempts10、连接/读取超时默认 60 秒以及x-client-framework:llama_index的用户代理标识见 memory/base.py#L528-L585。记忆写入事件时消息角色会被映射为 AgentCore 的USER/ASSISTANT/TOOL/OTHEROTHER对应 system 消息工具调用的 kwargs 以blob形式与conversational文本成对存储由于 AgentCore 不接受空文本 payload空的 assistant 文本会用PLACEHOLDER FOR EMPTY ASSISTANT占位并在读取时还原为空utils.py#L46-L77。另外BaseAgentCoreMemory还提供list_sessions、delete_events、delete_memory_records、batch_delete_memory_records默认批量 25 条、delete_all_memory_for_session等数据管理方法方便按会话清理历史。同步方法get/put/put_messages等内部通过asyncio_run包装异步实现便于在同步代码中使用。示例 Notebook本仓库提供了两个可直接运行的 Jupyter Notebook 示例Browser Tool NotebookCode Interpreter Tool Notebook对应测试用例也覆盖了浏览器、代码解释器与 Runtime 的同步/异步/端到端路径例如 test_browser.py、test_code_interpreter.py、test_runtime.py 以及 test_agentcore_memory.py可作为理解各组件行为与边界的参考。部署注意事项小结端口AgentCore 部署要求 Runtime 监听 8080 端口AgentCoreRuntime.serve(agent)默认即满足。Region 一致性ToolSpec、LLM 与 Memory 的region_name/region应保持一致示例统一使用us-west-2。凭证与权限确保运行环境已配置 AWS 凭据且 IAM 策略覆盖bedrock-agentcore:*相关操作。资源清理浏览器与代码解释器会话是远程托管的示例中通过tool_spec.cleanup()显式释放Memory 资源建议按业务需要调用delete_all_memory_for_session等管理方法清理。会话隔离多线程/多用户场景下浏览器与代码解释器工具都通过thread_id隔离会话Memory 通过actor_idsession_id隔离数据Runtime 部署时会自动把请求头的 Session ID 注入 memory。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考