本文介绍在生产环境中使用 AgentKit 智能体运行时(Runtime)时建议采用的安全实践。您可以将本文作为上线前检查清单,围绕会话隔离、网络、身份、权限、凭据、观测、安全围栏和命令执行等关键环节,降低 Agent 被越权调用、敏感数据泄露、工具误用或配置变更失控的风险。
AgentKit 智能体运行时(Runtime)为 Agent 提供框架与模型无关的托管式运行环境,支持基于业务流量自动扩缩容实例,并通过绑定的 IAM 角色控制 Runtime 对火山引擎云资源的访问权限。一个 Runtime 承载一个 Agent,是 Agent 从开发调试推进到生产运行的核心单元。
平台的会话持久化能力不等于“应当保存全部上下文”。对于一次性输入、临时授权码、用户隐私与低价值内容,应优先选择不写入或写入前脱敏。
Runtime 通过独立的托管实例承载 Agent,隔离边界由平台维护。用户身份、会话标识、短期上下文与长期记忆的隔离,仍需要您在 Agent 代码、请求头与业务存储中共同实现。请参照以下做法维护会话隔离与数据保护:
- 在客户端后端维护用户到会话的映射:调用 Runtime 时应通过 user_id 请求头标记发起请求的用户身份,通过 session_id 请求头标记当前会话。建议由您的后端维护用户与会话 ID 的绑定关系、生命周期与单用户最大会话数。默认取值 defaultUser 与 defaultSession 仅用于调试,不应用于生产。
- 从已验证的身份来源提取用户标识:如果 Runtime 使用 OAuth JWT 入站身份认证,用户标识应从已通过颁发方、受众、生效时间与过期时间校验的 JWT Claim 中提取,再映射为 Agent 内部使用的 user_id。请勿直接信任客户端在请求头中传入的任意用户 ID、租户 ID 或角色字段。
- 按用户、会话与租户维度隔离数据:会话资源(Session)、记忆库(Memory)与知识库(Knowledge)均支持按 app_name、user_id、session_id 等维度做数据隔离。多租户场景下应将租户标识显式绑定到 Session 资源、Memory 检索条件、Knowledge 检索条件、工具参数与业务数据库查询条件中,避免仅依赖 Prompt 约束模型。
- 分层管理数据生命周期:Session 用于承载当前会话的短期上下文,当前支持 RDS PostgreSQL 与 RDS MySQL 作为后端;Memory 用于沉淀跨会话的长期信息,当前支持 Viking 记忆库与 mem0 记忆库两种后端;Knowledge 用于承载外部知识检索结果。请依据数据周期、数据价值与合规要求,明确哪些字段可写入 Session、哪些可写入 Memory、哪些仅在当前请求内使用。
- 对高敏数据不写入长期上下文:长期有效的 Token、密钥、身份证号、银行卡号、未脱敏业务机密不应作为普通上下文写入 Session 或 Memory。记忆库抽取存在延迟,且抽取结果可能在后续对话中被再次注入 Prompt。
- 在链路两端做敏感数据识别与脱敏:在进入 Runtime 前对用户输入、文件内容与外部接口返回值做必要的敏感数据识别与脱敏;日志中避免输出完整请求体、完整响应体、凭据、用户隐私与业务机密。
不要把“能够调用成功”作为权限配置完成的标准。生产权限应能说明调用主体、可访问资源、可执行动作、审计方式与吊销方式。
Runtime 场景中的 IAM 治理涉及三类身份:管理 Runtime 的 IAM 身份、Runtime 承担的 IAM 角色、以及调用 Runtime 的入站凭据。三类应分别设计,避免同一凭据覆盖全部权限。请对与 Runtime 关联的所有 IAM 策略应用最小权限原则:
- 优先使用系统预置策略并按项目收敛:AgentKit 提供以下系统预置策略:
- 按需追加依赖服务权限:AgentKit 部分功能依赖其他云服务。若不使用相应能力,不应默认附加权限:
- 避免授予平台自用策略:AgentKitTosAccess(保障 Skills Sandbox 任务正常运行所需的 TOS 访问权限)、AgentKitToolAccess (AgentKit 工具相关平台自用策略)属于平台自用策略,不建议授予给 IAM 用户。
- 回顾发布链路的 IAM 身份:AgentKit CLI 与自动化流水线的执行身份也应遵循最小权限。避免将访问密钥(Access Key ID / Secret Access Key)暴露在命令历史、Shell 环境或 CI 日志中,建议使用凭据托管或 CI/CD 平台的密钥注入能力。
Runtime 访问火山引擎云资源时,依赖绑定的 IAM 角色进行鉴权。若信任策略或权限策略配置过于宽松,可能导致 Runtime 承担了超出业务需要的权限,甚至被跨服务代理调用。
请按照以下做法收敛信任关系与权限:
- 将信任关系限定为 Runtime 依赖的服务:Runtime 底层运行在函数服务(veFaaS)上,IAM 角色的信任策略应仅允许该服务承担该角色。示例:
"Action": ["sts:AssumeRole"],
- 若信任策略缺少 veFaaS 服务标识,Runtime 可能无法正常运行;若信任策略过度开放,可能被其他服务或身份意外承担。
- 按业务与环境拆分 IAM 角色:开发、测试与生产环境应使用独立 IAM 角色,不同业务线也应使用独立角色。避免让一个 IAM 角色被多个 Runtime 共享,导致权限边界模糊。
- 仅授予 Agent 运行所需的最小权限:IAM 角色可复用已有角色或按需创建。无论采用哪种方式,都应确保角色权限只覆盖 Agent 运行所必需的资源和动作。若角色缺少函数服务(veFaaS)相关权限,将直接导致 Runtime 不可用。
- 防止权限升级:Runtime 承担的 IAM 角色所拥有的权限,应等于或小于调用 Runtime 的委托人权限。避免出现"低权限用户通过调用 Runtime 获得高权限云资源访问"的路径。
- 将 IAM 角色变更纳入发布流程:IAM 角色权限调整属于安全变更,应通过发布记录、灰度发布与回退能力控制风险,并在测试环境完成验证。
- 优先使用完整 ARN 而非通配符:在权限策略中引用具体资源时,尽量使用完整的资源标识,避免使用宽泛通配符。
AgentKit 通过项目(Project)与标签(Tag)实现资源分组和访问控制。请合理利用这两种机制建立资源级边界:
- 通过项目与标签做资源分组:一个资源只能归属于一个项目。选定项目后,仅具备该项目权限的用户可访问对应 Runtime。标签可用于成本归属与检索聚合,但标签本身不构成强授权边界,不应作为唯一的隔离手段。
- 按业务与环境拆分 Runtime:开发、测试与生产环境应使用独立 Runtime。不同业务线、租户或数据敏感等级也建议拆分 Runtime,降低跨业务权限扩散和数据混用风险。
- 在创建时确定项目归属:一个资源只能归属于一个项目,创建后可按需变更。进入创建页面前,如已在顶部导航栏选择了具体项目,则新创建的 Runtime 只能绑定该项目。若需要绑定其他项目,请先将顶部导航栏切换到目标项目或"账号全部资源"。
- 明确项目变更的授权影响:变更资源所属项目会同步变更可访问该资源的用户范围。项目切换应作为一次授权变更纳入审计,避免在生产 Runtime 上意外扩大或收敛权限。
- 对关联组件保持一致的项目治理:Runtime 关联的会话资源、记忆库、知识库、沙箱工具与 MCP 工具集应与 Runtime 处于一致的项目与网络访问方式中,否则无法完成关联或调用。
- 使用标签管理成本与检索:标签由键-值对(Key-Value)构成,单个资源最多可绑定 50 个标签,单次操作最多绑定 20 个标签。标签仅用于分类、检索与成本归属,不建议作为访问控制的判断依据。
- 提前规划资源配额:生产上线前应确认下列平台限制,避免业务规模触及上限:
智能体网关(Gateway)是 Agent 访问外部系统与服务的统一入口,负责连接、路由、调用治理与出入站鉴权。将存量 REST/OpenAPI 服务通过 Gateway 转换为 MCP 服务、或通过 Gateway 部署与导入 MCP 服务,可以在 Agent 环境之外集中应用控制:
认证通过只表示调用方身份可信,不表示调用方可以执行所有业务动作。业务侧仍应根据用户、租户、角色和资源关系进行授权校验。
- 对齐 Runtime 与网关的认证配置:Runtime 与网关的认证配置应分别审查。仅保护 Runtime 而忽略网关暴露的 MCP 服务入口,会形成绕过路径。
- 对齐网络访问方式:Runtime 关联网关下的 MCP 工具集时,关联组件的网络访问方式需与 Runtime 网络访问方式一致,否则无法完成关联或调用。
- 入站身份认证:网关下的 MCP 服务和 MCP 工具集支持 API Key 与 OAuth JWT 两种入站身份认证,且两者互斥。单个 MCP 服务或 MCP 工具集最多可配置 5 个 API Key 入站身份认证,OAuth JWT 最多可绑定 5 个客户端。请为生产环境中的 MCP 服务与 MCP 工具集强制启用入站认证,避免未受保护的接口被直接访问。
- 出站凭据集中托管:网关支持通过智能体身份与权限管理平台托管出站凭据。当 MCP 服务入站认证为 OAuth JWT 类型时,支持配置用户委托(USER_FEDERATION)类型的出站凭据,用于 OAuth 2.0 3-Legged Authorization 流程;API Key 出站凭据也支持选择由 Identity 托管,将凭据以非明文形式存储在密钥管理服务(KMS)内。
- 合理选择后端服务类型:网关支持将容器服务、云服务器与其他后端作为 MCP 服务的后端。开启私网访问的 MCP 服务可选择同 VPC 内的容器服务与云服务器,避免流量绕行公网。
- 收敛出向访问面:MCP 工具集支持切换调用模式(全量返回、语义检索、标签检索),生产使用应根据 Agent 能力需要决定暴露的工具范围,避免默认全量暴露高危工具。
- 审查工具调用参数:工具调用参数应在 Agent 代码中做白名单校验,避免由模型直接拼接高风险命令、SQL、URL 或文件路径。
Runtime 入站身份认证支持 API Key 与 OAuth JWT 两种方式,二选一。创建 Runtime 时选定后,不支持更换。因此,生产环境在选型前应先明确调用主体、身份来源、授权模型与凭据轮换方式。请遵循以下做法:
认证配置一经创建不可修改。若需切换认证方式,需重新创建 Runtime 并完成客户端迁移。请在生产上线前充分评估。
- 完整校验 JWT:采用 OAuth JWT 时,应校验发现地址、颁发方(Issuer)、受众(Audience)、允许的客户端、允许的 Scope 与所需的自定义 Claim。不要仅依据"能拿到 Token"就完成鉴权。
- 不要在生产代码中硬编码令牌:请通过环境变量、受控配置中心或凭据托管能力注入 API Key 与 OAuth 凭据。硬编码在源代码或已构建镜像中的令牌,将随交付物一起扩散。
- 对 API Key 建立轮换与吊销流程:采用 API Key 时,生产使用中不要将 Key 写入前端页面、移动端包、浏览器脚本、公开仓库、Prompt、日志或报错信息。建议通过安全配置中心或凭据托管能力注入运行环境,并建立轮换、吊销与调用审计机制。
- 确认在线测试链路一致:基于 OAuth JWT 入站身份认证创建的 Runtime,仅支持 M2M 类型客户端进行在线测试。如需使用控制台在线测试功能进行调试,请在用户池创建 M2M 类型客户端,避免测试链路与生产链路的身份模型不一致。
- 优先仅在公网访问下使用在线测试:控制台在线测试功能仅在网络访问方式为公网访问时可用,私网访问 Runtime 需要在受控网络内自行发起调用。
- 不要直接信任 X-user-id 类请求头:如需在业务层表达用户身份,应从 JWT Claim 或经过身份验证的委托人上下文中派生 user_id,而不是取用调用方任意传入的值。
Runtime 场景中常见凭据包括 Runtime 入站 API Key、OAuth 客户端凭据、访问密钥(Access Key ID / Secret Access Key)、数据库账号密码、第三方 API Key、网关出站凭据与工具调用所需凭据。凭据管理的核心目标是避免密钥散落在代码、Prompt、镜像、日志、命令历史与个人终端中:
如果同一密钥同时用于本地调试、测试环境与生产 Runtime,后续审计、轮换与泄露处置都将变得困难。生产凭据应独立创建、独立授权、独立轮换。
- 区分入站与出站凭据:调用 Runtime 的 API Key 或 OAuth JWT,不应与 Runtime 访问第三方系统的凭据混用。二者的授权模型、轮换周期、可见范围不同,应分别治理。
- 使用凭据托管能力管理出站凭据:通过智能体身份与权限管理平台的凭据托管能力(API Key 凭据、OAuth Client 凭据)托管出站凭据,并通过环境变量或受控配置方式供 Runtime 使用。托管凭据会以非明文形式存储在密钥管理服务(KMS)中。
- 优先托管网关出站凭据:通过网关配置的 API Key 出站凭据可选择由 Identity 托管。生产环境应优先通过托管方式管理出站凭据,避免在 Agent 代码、镜像或环境变量中长期保存明文密钥。
- 收敛托管凭据的可见范围:托管凭据资源本身也应纳入 IAM 与项目权限治理,只有需要管理或使用凭据的人员、Runtime、网关或工具可以访问对应凭据。
- 禁止明文写入密钥,防止在运行链路扩散:请勿在 Agent 代码、Prompt、Dockerfile、示例请求、WebShell 命令或环境变量中明文写入密钥;即便凭据在静态存储层有加密保护,一旦被写入日志、Trace 或错误堆栈,即等同于以明文形式扩散。请在业务侧做好脱敏与日志内容审查。
- 对环境变量做审查:Runtime 支持通过表单或 JSON 格式配置环境变量。生产 Runtime 应对每次环境变量变更做发布前审查,确认是否包含明文密钥、临时调试开关或过期字段。
- 按环境与调用方拆分凭据:为开发、测试、生产环境使用不同凭据;为不同调用方或下游系统使用不同凭据。禁止在本地调试、测试环境与生产 Runtime 之间复用同一份密钥。
- 建立轮换与吊销流程:人员离职、系统下线、调用方迁移、疑似泄露或权限收敛时,应及时轮换或吊销凭据。定期做凭据盘点,剔除长期未使用的凭据。
- 控制凭据可见范围:只有需要管理或使用凭据的人员、Runtime、网关或工具可以访问对应凭据。凭据托管资源本身也应纳入 IAM 与项目权限治理。
- 收敛部署链路的凭据面:AgentKit CLI 与自动化流水线部署 Runtime 时,应避免将访问密钥暴露在命令历史或日志中。建议通过环境变量、受控配置中心或 CI/CD 平台的密钥注入能力管理凭据,并限制流水线执行身份的 IAM 权限,避免部署链路成为新的密钥泄露面。
Runtime 支持 公网访问 与 私网访问 两种网络访问方式。请依据调用方位置、下游资源位置与合规要求做出选择:
网络访问方式一旦确定即影响关联组件的可选范围。切换网络访问方式属于高风险操作,应在测试环境完成完整回归后再进行。
请按以下做法收敛网络访问面:
- 提前规划 VPC 拓扑:采用私网访问的场景,需要提前开通私有网络,并在待部署地域准备好 VPC 与子网。每个可用区仅支持选择一个子网,因此建议在投入生产前先完成网络拓扑规划,确认调用方、Runtime、Session、Memory、Knowledge、Gateway 后端服务与其他下游服务之间的连通性。
- 对齐关联组件的网络访问方式:Runtime 关联会话资源、记忆库、知识库、沙箱工具或 MCP 工具集时,关联组件的网络访问方式需与 Runtime 网络访问方式一致,否则无法完成关联或调用。
- 明确共享公网端口的语义:共享公网端口仅改变私网访问场景下 Runtime 访问公网的出向路径,不等同于放宽入站身份认证。无论是否开启共享公网端口,都应继续使用 API Key 或 OAuth JWT 保护调用入口。
- 在测试环境验证网络配置:生产环境建议先在测试环境验证私网连通性、域名解析、出向访问与发布流程,再迁移到生产 Runtime。
- 收敛调用来源:对面向公网的 Runtime,可结合业务侧的调用方 IP 白名单、来源校验、限流与异常告警,避免开放接口被暴力扫描或滥用。
创建 AgentKit 资源时,平台默认开启观测服务,并同时开通 APMPlus 与 TLS,由 APMPlus 负责写入日志,形成指标、链路、日志一体化的观测能力。
观测的目标不是保留尽可能多的数据,而是在发生异常调用、越权访问、提示词攻击、敏感数据泄露或发布故障时,能够快速定位影响范围与处置路径。
请依据以下做法建立可用于审计与排障的观测基线:
- 基础监控:用于观察 Runtime 与实例的资源变化,重点关注请求次数、请求分布、平均延迟、出向响应带宽、CPU 使用率、内存使用率与实例数量等指标。查询窗口最小 1 小时、最大 15 天,仅保留最近 30 天数据,采集频率 30 秒。
- 应用观测:于定位模型、Runtime、网关、工具、Session 或 Memory 相关问题,重点关注运行时总览、会话分析、Trace 分析、模型监控、日志分析、工具分析、洞察大盘与告警模板等能力是否形成闭环。
- 日志治理:Runtime 日志会自动投递至 AgentKit 专用日志项目 apmplus-server 下的日志主题 apmplus-server-log。日志中应记录调用人、时间、目标 Runtime、请求 ID、错误码与调用链追踪(Trace)标识;避免记录明文凭据、完整 Token、用户隐私与业务机密。
- 调用链追踪(Trace):通过 Trace 数据可以将一次业务请求串联到 Runtime、工具调用、Session、Memory、Knowledge 与外部系统调用,用于问题定位与影响面分析。生产环境建议将 Trace 数据接入评测集,形成"线上真实数据 → 评测验证"的闭环。
- 安全围栏观测:安全概览用于观察请求次数、防护次数、执行动作分布与整体攻击分布;攻击日志用于回溯送检类型、命中规则、检测分类、执行动作与时间。日常运维应将安全概览与攻击日志纳入巡检,重点关注提示词攻击激增、敏感数据命中激增、拦截比例异常、同一调用方重复触发攻击规则等现象。
- 发布记录与灰度:Runtime 支持全量发布与灰度发布,新版本流量比例可在 10%~100% 之间调整。为每次变更预先定义观察指标、异常阈值与回退条件,并保留可追溯的版本记录。灰度期间持续监控错误率、延迟、鉴权失败与安全拦截等指标,出现异常及时终止放量并回退。
- 建立异常告警:建议为下列指标建立告警阈值:请求量、平均延迟、错误率、实例数量、CPU 与内存使用率、API Key 或 OAuth JWT 鉴权失败次数、安全围栏命中次数、Session/Memory/Knowledge 调用错误率、WebShell 与高风险变更事件。
- 权限治理:日志下载与日志查询权限、Trace 查询权限、观测大盘权限应纳入 IAM 与项目权限治理,避免观测数据被越权访问。
Runtime 支持通过 WebShell 直接在实例中执行命令行操作,适用于文件查看、任务创建与深度排障。命令执行能力本质上属于高风险运维入口,请仅开放给受信任的运维或研发人员,并纳入审计、审批与最小权限控制。
WebShell 中执行的命令直接作用于线上实例状态。请将 WebShell 视为例外排障手段,而非日常变更入口。
请按以下做法收敛 WebShell 使用:
- 限制可进入 WebShell 的 IAM 身份:仅授予具备排障职责的人员进入 Runtime 实例执行命令的权限。查询 Runtime 实例 WebShell 连接地址的接口(GetRuntimeWebshellEndpoint)应通过 IAM 策略明确限制。
- 对命令执行做审计:命令执行操作应记录调用人、时间、目标 Runtime、目标实例、命令内容、执行结果与失败原因,并将审计日志与业务日志关联。
- 不要在 WebShell 中读写高敏凭据:不要在 WebShell 中输出、复制或长期保存 API Key、OAuth 凭据、访问密钥、数据库密码与用户隐私。避免通过 env、cat 等命令批量导出环境变量。
- 不要用 WebShell 绕过发布流程:涉及镜像、环境变量、模型配置、IAM 角色权限、关联组件与观测服务的变更,应通过 Runtime 配置与发布流程完成,并保留版本记录。
- 控制长耗时任务:长耗时任务不应依赖同步请求链路,需结合 Runtime 同步请求执行超时 30 分钟的限制进行任务拆分或异步化设计。
- 执行前先在测试环境验证:涉及删除文件、修改配置、安装依赖、发起外部请求或访问敏感目录等操作前,请确认影响范围,并优先在测试环境验证。
- 排障后清理临时资产:排障完成后,应清理临时文件、临时凭据与临时调试脚本,避免长期驻留在实例中。
平台负责提供安全能力和运行底座,您负责在业务上下文中正确配置、集成与验证这些能力。
AgentKit 提供 Runtime 托管运行、基础隔离、自动扩缩容、IAM 角色集成、智能体网关、会话管理、记忆库、知识库、智能体身份与权限管理平台、观测、评测、安全围栏、日志与发布管理等平台能力。平台能力为生产运行提供安全底座,但不会自动替代您的业务安全责任。
生产上线前,建议至少完成以下检查:
- 调用入口已启用合适的入站认证(API Key 或 OAuth JWT)。
- Runtime 管理权限符合最小权限原则,IAM 角色的信任关系与权限范围已收敛。
- 公网或私网访问方式符合业务需要,关联组件的网络访问方式一致。
- 若启用安全围栏服务,已在 Agent 代码中完成集成并重新发布 Runtime。