帮你快速理解、总结文档立即下载
文档中心>Agent Runtime>操作指南>网络>凭证注入（Credential Injection）

凭证注入（Credential Injection）

最近更新时间：2026-09-03 11:21:00
我的收藏

本页目录：

概述

Agent 沙箱内 Agent 发出的 HTTP 请求，平台自动注入所需的认证凭证到请求 Header 中，Agent 代码无需任何修改。
凭证注入让凭证永不进入沙箱，由平台在网络层透明注入，解决三个问题：
1. 凭证泄露风险：凭证不进沙箱，Prompt Injection 无法窃取。
2. 凭证管理复杂：平台自动获取、缓存、刷新凭证。
3. 审计不可控：每次注入在审计日志中记录。

端到端使用流程

以 Agent 调用外部 API 为例，完整演示从凭证托管到 Agent 使用的全链路。

Step 1：创建 CredentialProvider

创建一个 SecretMultiUser 类型的 Provider，用于按用户维度托管凭证：
// CreateCredentialProvider
{
  "Name": "my-api-secret",
  "Type": "SecretMultiUser",
  "Tags": [{"Key": "purpose", "Value": "api-auth"}]
}

// 返回
{
  "ProviderId": "agc-xxxx-001"
}

Step 2：写入 ManagedSecret

为具体用户写入需要注入的凭证：
// SetManagedSecret
{
  "CredentialProviderId": "agc-xxxx-001",
  "UserId": "u_12345",
  "Scope": "default",
  "Secret": "<需要注入的凭证值，如 API Token>",
  "OverwriteAllowed": false
}
说明：
SecretMultiUser 按 UserId + Scope 隔离存储。同一个 Provider 可以托管多个用户的凭证，每个用户通过不同的 UserId 区分。

Step 3：创建沙箱工具，配置 NetworkPolicy

在创建沙箱工具时，通过 NetworkPolicy 声明：
CredentialProviders：凭证从哪获取（引用 Step 1 的 ProviderId）。
Rules + Transform：哪些请求需要注入、注入什么。
{
  "ToolName": "my-agent",
  "ToolType": "custom",
  "NetworkPolicy": {
    "DefaultDecision": "deny",
    "CredentialProviders": [
      {
        "Type": "agentruntime",
        "Name": "managed_secret",
        "ProviderConfig": {
          "ProviderId": "agc-xxxx-001",
          "SecretMultiUserParameter": {
            "UserId": "${metadata.user_id}",
            "Scope": "${metadata.scope}"
          }
        }
      }
    ],
    "Rules": [
      {
        "Name": "inject-api-auth",
        "Resources": [
          {
            "Hosts": ["api.example.com"],
            "Ports": ["443"]
          }
        ],
        "Decision": "allow",
        "Transform": {
          "TransformConfigurations": [
            {
              "TransformType": "Header",
              "HeaderTransformConfigurations": [
                {
                  "Operation": "Remove",
                  "Header": {"Name": "Authorization"}
                },
                {
                  "Operation": "Set",
                  "Header": {"Name": "Authorization"},
                  "ValueExpression": "\\"Bearer \\" + credential.managed_secret"
                }
              ]
            }
          ]
        }
      },
      {
        "Name": "deny-all-other",
        "Resources": [{"Hosts": ["*"], "Ports": ["*"]}],
        "Decision": "deny"
      }
    ]
  }
}
配置含义：
CredentialProviders：声明一个名为 managed_secret 的凭证源，指向 Step 1 创建的 Provider。运行时通过 ${metadata.user_id} + ${metadata.scope} 选择对应用户的 Secret。
credential.managed_secret：CEL 表达式中直接引用 Provider Name，获取该用户存储的 Secret 值。系统自动推导依赖关系，无需显式声明 CredentialProviderRefs。
Rules[0]：匹配所有发往 api.example.com:443 的请求，先 Remove 已有 Authorization（防伪造），再 Set 平台注入的真实 Token。
Rules[1]：其他所有请求拒绝出站。

Step 4：创建沙箱实例

// StartSandboxInstance
{
  "ToolId": "tool-my-agent",
  "Timeout": "30m",
  "Metadata": [
    {"Name": "user_id", "Value": "u_12345"},
    {"Name": "scope", "Value": "default"}
  ]
}
Metadata 中的 user_id 和 scope 渲染到 SecretMultiUserParameter 的模板中，选择 Step 2 写入的 Secret。不同实例传入不同 user_id 即可使用不同用户的凭证。Metadata 格式为 Name/Value 数组。

Step 5：Agent 代码

import requests

# Agent 不需要知道凭证的存在
response = requests.get("https://api.example.com/v1/data")
# 实际发出的请求:
#   GET https://api.example.com/v1/data
#   Authorization: Bearer <Secret值>   ← 平台自动注入
#   Content-Type: application/json

关键机制说明

CEL 表达式

Transform 中的 ValueExpression 使用 CEL 表达式计算注入值：
变量
类型
说明
credential.<provider_name>
dynamic
从凭证服务获取的 Secret 值（SecretMultiUser 场景）
metadata["<key>"]
string
沙箱实例的 Metadata
CEL 表达式样例：
// 拼接 Bearer Token
"Bearer " + credential.managed_secret

// 引用 Metadata
metadata["user_id"]

// 静态值（注意 JSON 中需转义引号）
"network-policy-credential-injection"

// 条件选择（Metadata 优先，凭证服务兜底）
has(metadata.override_token) && metadata.override_token != ""
  ? metadata.override_token
  : credential.managed_secret

Header 操作类型

Operation
说明
ValueExpression
Set
设置 Header（覆盖已有值）
必填
Append
追加 Header 值
必填
Remove
删除 Header
不需要

Metadata 动态化

${metadata.xxx} 模板在策略下发时渲染（用于 CredentialProvider 配置中）。
metadata["xxx"] 在 CEL 表达式中引用（用于 ValueExpression）。
更新实例 Metadata 后，平台自动重新渲染并推送策略。
不同实例通过 Metadata 使用不同凭证（多租户隔离）。

全链路数据流

Agent 发起请求（无凭证）
       ↓
ZeroProxy Sidecar 拦截
       ↓ 匹配 Rule "inject-api-auth"，发现有 Transform
       ↓
转发到 ZeroProxy Gateway
       ↓
Gateway 解析 Transform → 根据 UserId+Scope 从凭证服务获取 Secret
       ↓
Gateway 按 HeaderTransformConfigurations 注入 Header
       ↓
Gateway 将请求转发到 api.example.com（已带凭证）
       ↓
API 返回响应 → 原路返回给 Agent

安全保障

特性
说明
凭证不进沙箱
获取和注入在 Gateway 完成。
Header 清洗
Remove + Set 防止 Agent 伪造。
Fail Closed
Gateway 不可用时拒绝请求。
工具级锁定
Transform 只能在工具级配置，实例无法修改。
审计记录
每次注入记录到审计日志。

实例级 NetworkPolicy 覆盖

实例创建时可以通过 NetworkPolicy 参数覆盖工具默认策略：
不传 NetworkPolicy：继承工具级 NetworkPolicy（包括 Transform）
传入 NetworkPolicy：整体覆盖工具默认值
实例级 Transform 规则：
场景
行为
工具有 Transform，实例不传 NetworkPolicy
继承工具的 Transform。
工具有 Transform，实例传入含 Transform 的 NetworkPolicy
允许，实例 Transform 覆盖工具的。
工具无 Transform，实例传入含 Transform 的 NetworkPolicy
拒绝，返回参数错误。
即：工具必须先声明 Transform 能力，实例才能覆盖或继承。

使用限制

需要 VPC 网络模式的沙箱工具。
当前对外支持 Header 注入（TransformType = "Header"）。
更新工具 NetworkPolicy 不自动更新已创建实例的策略。
工具未声明 Transform 时，实例级请求不能自行添加 CredentialProviders 或 Transform。
中国站