AgentCore + Codex 构建生产级 Agent 的原理与实践

阿里巴巴中间件 · 2026-11-04 22:07 · 22 阅读

原创寒斜 2026-11-04 22:07 浙江

本文章演示 AgentCore^[^1]的自定义代码/镜像能力，目的是展示如何基于自定义的 Harness 框架（Codex）结合 AgentCore 提供的身份、模型、工具、技能、凭证、观测评估等能力实现一个端到端的 Agent 应用，内容包含两个部分，技术方案和实践教程，文末附相关源码和本次的测试数据，可以根据需要自行查阅。

一、技术方案

1、整体架构

2、AgentCore-Runloop 的内部执行架构

注：

agentcore-chat 是可交互的智能应用前端。
agentcore-runloop 是连接 agentcore 基础设施和自定义harness （当前是codex）的运行时框架。

3、模型

harness 对模型的注册消费架构如下，基本就是在 AgentCore 上配置好对应的模型连接，通过环境变量注入到运行时，然后通过 sdk 查询到模型连接地址和凭证然后交给 codex 进行挂载使用。

4、工具

AgentCore 提供资源元数据和数据面凭证，Harness 将资源编译成一个会话级 MCP Tool Registry；Codex 只连接 Runloop MCP Aggregator，通过标准 tools/list/tools/call 使用能力，实际鉴权、HITL、路由和执行全部由 Harness 完成。

5、技能

AgentCore 提供 Skill 元数据与受控下载入口，Harness 负责签名下载、安装到工作区并向 Codex 注入技能索引；Codex 仅在任务匹配时渐进读取 SKILL.md 及附件，由现有工具和沙箱执行其中的操作，Skill 本身不作为普通 MCP Tool。

这里有一个有意思的实现，Skill 包可按版本持久化在 NAS/AgenticFS 的隔离目录中，Harness 在每次运行时将其只读映射为统一的 .agents/skills/ 逻辑路径；Codex 始终使用相对路径访问技能，从而解耦物理存储、执行环境和 Skill 内部引用，并降低路径冲突与越权访问风险。

6、存储

Agent 在执行任务过程中会持续产生和消费文件，包括用户上传的附件、代码仓库、中间结果以及最终产物，因此需要同时考虑文件持久化、访问性能和多租户隔离。AgentCore 提供 OSS 和 NAS（AgenticFS）两类存储方案：

NAS（AgenticFS）提供 POSIX 文件系统语义，支持目录结构、随机读写、文件编辑、原子改名以及大量小文件操作，适合作为 Agent 的持久化会话工作盘。代码检出、Git 操作、依赖解压、文件编辑和中间结果都可以直接保存在工作盘中，并在同一会话的多轮执行之间持续复用。
OSS 适合存储大对象和生命周期相对独立的文件，可用于用户上传附件、只读输入、模型数据、最终 Artifact 以及跨系统文件交付。由于 OSS 本质上是对象存储，随机修改、目录操作和 rename 等文件系统行为并不是它的优势，因此默认不将 OSS FUSE 作为 Agent 的工作目录。

这里推荐采用“OSS 对象交换层 + AgenticFS 会话工作盘”的分层方式，简单来说就是 AgenticFS负责过程产生数据及持久化，Oss 负责拿到结果展示给用户看。

当前 Harness 已经进行了用户粒度的内部文件隔离所以无需担心文件混用，未来也会支持更严格的基于执行沙箱的隔离方案。

7、身份与安全

Agent 身份是当前构建 Agent 被低估了的一项能力，随着 Agent 进入生产以及进行商业化，可信性变为一种刚需，AgentCore 背后的身份是基于阿里云Agentidentity 实现，在平台上构建的每一个 Agent 都具备一个 Agentidentity 的工作负载身份这个身份可以关联可信的身份提供商，绑定阿里云的资源管理角色，作用是能够让 Agent 更安全的管理云资源，同时能够让你的 Agent 由阿里云来承担信任背书。

基本概念

Agent 身份是一组执行上下文，包括：

业务身份：uid、租户和云账号，表示任务代表谁。
执行身份：conversationId 和 runId，用于会话隔离与审计。
资源身份：本次允许访问的工具、Skill、Sandbox 和子 Agent。

用户身份和资源归属由可信网关校验。uid 只用于隔离和追踪，本身不是认证凭证。

临时凭证

Agent 访问云资源时使用短期、最小权限的 STS 凭证。凭证由可信服务按请求签发，绑定账号、地域、资源范围、操作权限和有效期。

凭证只保留在 Runloop 控制面，由 Runloop 代模型完成请求签名；模型、Codex 和执行 Worker 均不能读取密钥。凭证不写入提示词、事件历史、日志或工作盘，过期后由上游重新签发，不回退使用永久 AK。

当前 AgentCore runloop 框架中内置了基于工作负载的凭证颁发服务，体现在通过客户端对 Agent 生成的文件进行访问的时候，通过该服务获取最小的 OSS 访问权限，来达到查看目的。

8、观测与评估

AgentCore 的 Runloop 框架可以通过环境变量配置来快速完成对 Agentloop 的观测接入，背后实现是通过自定义 OpenTelemetry 埋点完成接入。应用只需配置 AgentLoop 上报参数，无需在业务代码中逐个创建 span。

9、多模态

当前 AgentCore Runloop 的多模态能力采用“文件驱动”的实现方式：文本通过 AG-UI 直接传递，图片、文档等非文本内容先被物化为 Agent 工作区内的文件，再由 Agent 使用受控工具读取；PPT、图片、文档等生成结果则以文件产物的形式发布并在前端预览。

实现原理

多模态输入不会直接以内嵌二进制或 Base64 的方式进入模型上下文，而是经过以下链路：

1. 用户在前端选择文件，或者直接粘贴剪贴板中的图片。

2. 前端向 /api/uploads 申请短期上传地址，并将文件直接上传至 OSS。

3. 服务端确认文件大小、类型和 ETag，并校验附件是否属于当前用户和会话。

4. 调用 Agent 前，部署适配层将附件下载到当前隔离工作区，例如：

/workspace/uploads/<uploadId>/file.png

5. Runloop 将附件转换成 user.attachment 事件，并把文件路径写入 Agent 上下文。

6. Agent 根据文件类型调用 view_image、文件读取或文档处理工具完成理解。

这种方式使 Runloop 与具体存储解耦。Runloop 不访问 OSS、不签发上传凭证，也不持有存储密钥，只消费已经物化且可以在执行环境中访问的文件路径。

能力边界

当前实现本质上是“工具增强的文件多模态”，而不是把图片直接作为模型原生多模态 Content Block 发送：

Runloop 将附件压缩为文件路径引用。
图片理解依赖 view_image。
文档理解依赖文件读取及对应解析工具。
输出文件依赖 publish_artifact 完成交付。
AG-UI 通道只返回文本、工具事件和受控文件引用，不返回文件二进制。

这种方案不依赖特定模型的原生图片协议，能够在不同 Agent CLI 和模型之间保持一致的文件处理、安全隔离和产物交付能力。

二、实践教程

1、前置资源准备

云产品开通：

AgentCore
AgentLoop
Sls
CMS
Agentidentity
Acr (需创建企业实例)
RAM
Fc
Oss
Nas (需申请加白 Agenticfs，然后在 Nas 控制台创建)

2、构建与部署

构建

拉取镜像

agentcore-app-registry.cn-hangzhou.cr.aliyuncs.com/template-images/agentcore-runloop:v0.1.0

或者基于 agentcore-runloop源码构建镜像，推送到 acree。

打开 AgentCore 配置好需要的基础资源，模型连接、Skill、Mcp、凭证、记忆、知识库

记录创建好的模型连接、MCP、Skill 的相关名称和版本。（知识库和记忆也是基于 MCP 的因此需要记录对应的 MCP 名称）

配置模型

配置 Skill

配置凭证（用来完成 Agent 的识图和生图）

这里展示通过凭证配置百炼的生图识图秘钥，满足 Agent 多模态需求，AgentCore-Runloop 内部的图片识别和生成使用独立的模型服务，图片识别默认使用的是 qwen-vl-max，图片生成则使用 qwen-image-plus。

可以通过 AGENTCORE_IMAGE_VISION_MODEL 和 AGENTCORE_IMAGE_GENERATION_MODEL 调整。

多模态使用的凭证 KEY 是 DASHBOARD_API_KEY，可以在 AgentCore 凭证中配置。

对应的值可以在百炼进行最小粒度的约束，比如只支持 qwen-vl-max 和 qwen-image-plus 防止该凭证越权滥用。

配置知识库

知识库使用百炼知识库，这里需要你提前准备好，并且给予相关的权限才能在 Agent 正常消费。

执行角色的部分需要重点关注一下，这里有个双向授权。

1. 当前选中的角色要具备 AliyunBailianDataFullAccess 来访问百炼。

2. 百炼的页面上要给这个角色授予当角色的数据操作权限。

配置记忆

同理记忆在 Agent 的注册消费也是通过 MCP 的方式完成，AgentCore 的记忆构建如下：

创建后需要开启 MCP 服务。

搭建 Agent 服务

Agent 基础配置

当前面准备就绪后可以快速搭建对应的 Agent 了，选择高代码找到对应已经上传好的 agentcore-runloop 镜像。

配置指令，执行角色。

agentcore-runloop 的启动指令如下：

node /app/agentcore-runloop/scripts/start.mjs

配置环境变量：

变量名	值示例	说明
AGENTCORE_MODEL_CONNECTION	hx-model-connection	模型连接名
AGENTCORE_MODEL_NAME	qwen3.8-max	模型名
AGENTCORE_SKILLS	pptx@0.0.3,remotion-best-practices	Skill
AGENTCORE_SYSTEM_PROMPT	你是小红，一个有用的助手	系统提示词
AGENTCORE_MCP_SERVERS	tool-mcp,bailian-tool-9lhdp,hx-memory	MCP服务
AGENTCORE_WORKDIR	/mnt/agenticfs/shared/users	agent 持久化工作路径，对应agentic fs
AGENTCORE_ARTIFACT_ROOT	/mnt/oss/data/users	agent 对外可公开产物地址，对应oss

Agent 访问协议配置

配置 AGUI 协议

Agent 存储配置

配置 OSS

配置 NAS

保存后我先使用控制台的调试进行简单测试，确认 ok，再继续进行下面的操作。

Agent 可观测

镜像已经准备把观测上报的基本能力准备好了，接下来只需要在 Agentloop 配置然后注入环境变量即可。

以下是 Agent 可观测部分的环境变量配置及说明：

变量名	说明
`RUNLOOP_AGENTLOOP_CONFIG_SOURCE`	配置来源，可选 `env` 或 `agentcore`。
`RUNLOOP_AGENTLOOP_ENDPOINT`	AgentLoop OTLP Trace 上报地址，必须使用 HTTPS。
`RUNLOOP_AGENTLOOP_LICENSE_KEY`	AgentLoop 数据上报凭证。
`RUNLOOP_AGENTLOOP_PROJECT`	AgentLoop Project 名称。
`RUNLOOP_AGENTLOOP_WORKSPACE`	AgentLoop Workspace 名称。
`RUNLOOP_AGENTLOOP_SERVICE_NAME`	Trace 中展示的服务名称。
`RUNLOOP_AGENTLOOP_SERVICE_VERSION`	服务版本，建议使用镜像 Tag 或 Git SHA。
`RUNLOOP_AGENTLOOP_ENVIRONMENT`	部署环境标识，例如 `staging`、`production`。
`RUNLOOP_AGENTLOOP_CAPTURE_CONTENT`	是否采集 Prompt、模型回复、工具参数和工具结果。
`RUNLOOP_AGENTLOOP_CREDENTIAL_NAME`	AgentCore 模式下保存 AgentLoop 配置的命名凭证名称。

如何获取上述变量值？

进入 Agentloop 接入中心。

打开上述页面。
选择「手动埋点」→「Node.js」。
在「参数配置」中填写应用名、版本号和部署环境，点击「LicenseKey → 点击获取」。
滚动到「初始化 OpenTelemetry SDK 和 Exporter」，从生成的代码中复制对应字段。

变量名	获取方式
`RUNLOOP_AGENTLOOP_ENDPOINT`	选择「阿里云内网方式」或「公网方式」，复制 `OTLPTraceExporter` 中的 `url`
`RUNLOOP_AGENTLOOP_LICENSE_KEY`	点击「LicenseKey → 点击获取」，复制 `headers["x-arms-license-key"]`，应存入 Secret
`RUNLOOP_AGENTLOOP_PROJECT`	复制 `headers["x-arms-project"]`
`RUNLOOP_AGENTLOOP_WORKSPACE`	复制 `headers["x-cms-workspace"]` 或 `resource["acs.cms.workspace"]`
`RUNLOOP_AGENTLOOP_SERVICE_NAME`	来自参数配置中的「应用名」，对应 `resource["service.name"]`
`RUNLOOP_AGENTLOOP_SERVICE_VERSION`	来自「版本号」，对应 `resource["service.version"]`
`RUNLOOP_AGENTLOOP_ENVIRONMENT`	来自「部署环境」，对应 `resource["deployment.environment"]`
`RUNLOOP_AGENTLOOP_CAPTURE_CONTENT`	Runloop 自有开关，不从控制台获取；是否采集模型输入输出内容
`RUNLOOP_AGENTLOOP_CONFIG_SOURCE`	Runloop 自有配置；填写 `env` 或 `agentcore`
`RUNLOOP_AGENTLOOP_CREDENTIAL_NAME`	使用 `agentcore` 配置源时，填写保存 AgentLoop 配置的 AgentCore 凭据名称