Agent工作流中API密钥的安全管理实践

随便打开一个带有 AI Agent 的代码仓库，十有八九会看到同样的东西：一个 .env 文件，里面躺着一个 OpenAI key、一个 GitHub token，可能还有一个数据库 URL，全是长期有效的、全作用域的、以明文形式躺在磁盘上的。

在演示环境里这没问题。但这恰恰是那种会把一次文件泄露、被污染的依赖、或者一次被注入 prompt 的工具调用，升级为账户完全接管的操作模式——因为 Agent 持有的凭证不会过期、不知道自己是为哪个任务而存在，通常能干的事远超任务实际需要的。

解决方案不是"更好的密钥管理"，而是压根不要把 Agent 当成持有凭证的东西来对待。下面是目前在 MCP、Auth0、WorkOS 等少数几家真正做对了这件事的地方正在收敛的模式，外加一个你可以直接抄过去的最小化实现。

为什么你现在的做法本身就是问题，而不是差一个变通方法就能解决的

一个静态 API key 只回答一个问题：持证人是否被允许做这类事，永久有效，直到有人想起来去轮换它。这对一个 Agent 来说是极差的形态，因为 Agent 不是一个行为者做一个工作。同一个 Agent 进程可能在此时此刻为一个用户读取客户记录，三十秒后又用同一份凭证去修改另一个用户的部署配置。

一旦把这份凭证的权限范围设得很大，这些截然不同的操作现在全靠同一份笼统授权来支撑。如果 Agent 被操纵去做了不该做的事——prompt 注入、恶意工具调用、幻觉出来的计划——凭证不会察觉任何区别。它压根就没有被限制在具体任务范围内过。

解决方案是不要再给 Agent 凭证，而是给它一种方式，让它在需要的那一刻去"要"一份凭证，而且范围恰好精确到那一步操作。

动手写代码之前，先搞清楚你的 Agent 到底是哪一种，因为这会改变整个流程：

Agent 是否代表某个已登录用户行事？
├── 是 → 授权码 + PKCE
│         （Agent 继承窄范围、用户同意过的权限）
│
└── 否 → 这是一个后台任务 / 守护进程 / 流水线，没有用户参与？
          ├── 是 → 客户端凭据授权（Client Credentials Grant）
          │         （Agent 以自身身份认证，拿一份短期 token）
          │
          └── 不确定 → 任务中途是否会触碰某个特定用户的数据？
                    ├── 是 → 按用户委托处理，用 token 交换
                    └── 否 → 客户端凭据，用你能定义的最窄范围

大多数 Agent 架构实际上在不同阶段两者都需要——Agent 自身的后台身份用客户端凭据，每次需要代表特定用户执行某个调用时用 token 交换。

模式一：客户端凭据，正确做法

这是一个没有用户参与的全自主 Agent 的基准方案。Agent 以自身身份认证，拿一份快速过期的 token。

import time
import httpx

class AgentTokenClient:
    def __init__(self, token_url, client_id, client_secret):
        self.token_url = token_url
        self.client_id = client_id
        self.client_secret = client_secret
        self._cached = None  # (token, expires_at, scope)

    def get_token(self, scope: str) -> str:
        if self._cached and self._cached[2] == scope and self._cached[1] > time.time() + 5:
            return self._cached[0]

        resp = httpx.post(self.token_url, data={
            "grant_type": "client_credentials",
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "scope": scope,
        })
        resp.raise_for_status()
        data = resp.json()
        expires_at = time.time() + data["expires_in"]
        self._cached = (data["access_token"], expires_at, scope)
        return data["access_token"]

有两件事值得做但大家经常忽略：请求能覆盖你即将发起的这次调用的最窄 scope 字符串（不是 "crm:*"，而是 "crm:read:invoices"），以及把 TTL 设为你工作流能接受的最低值。敏感操作五到十五分钟，只读操作最多一小时。这个流程里故意没有 refresh token——如果 token 过期了，Agent 重新认证就行。这是特性，不是摩擦。

模式二：Token 交换——"代表这个特定用户、此时此刻执行"

这个模式是大多数 Agent 代码仓库完全跳过的，但一旦你的 Agent 会代表不同用户行事，它恰恰就是最关键的那个。

思路来自 RFC 8693：你的 Agent 持有一份基础 token，证明 Agent 是谁，然后用它换一份更窄的、受众受限的 token，这份新 token 证明的是：这个特定调用在这个特定用户上被允许做什么，而且只在此时此刻有效。

def exchange_for_scoped_token(base_token: str, target_resource: str, action: str) -> str:
    resp = httpx.post(TOKEN_EXCHANGE_URL, data={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": base_token,
        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
        "resource": target_resource,
        "scope": action,          # 例如 "invoices:refund"
    })
    resp.raise_for_status()
    return resp.json()["access_token"]

收益：如果这份窄 token 泄露了，爆炸半径是一个操作、一个资源、窗口期以分钟计——而不是 Agent 对所有曾接触过的东西的全部常设权限。

模式三：Vault Broker——让 Agent 永远接触不到原始密钥

最干净的版本是让 Agent 完全退出凭证处理业务。Agent 不是直接向认证服务器请求 token，而是向一个 broker 请求执行某个操作的许可，broker 在真正发往目标 API 调用的路上把凭证注入进去。

class CredentialBroker:
    def __init__(self, vault_client):
        self.vault = vault_client

    def authorized_call(self, agent_identity: str, action: str, api_call):
        # 1. 策略检查——这个 Agent 此时此刻被允许做这件事吗？
        if not self.policy_allows(agent_identity, action):
            raise PermissionError(f"{agent_identity} not authorized for {action}")

        # 2. 为这步操作生成一份受限的、短生命周期的 token
        token = self.vault.issue_token(scope=action, ttl_seconds=300)

        # 3. 发起调用，在这里注入凭证，绝不把凭证交给 Agent
        try:
            return api_call(token)
        finally:
            self.vault.revoke(token)  # 双重保险

Agent 的代码只需要调用 broker.authorized_call("refund-agent", "invoices:refund", do_refund)，全程不接触任何凭证。如果 Agent 的进程被攻陷了——prompt 注入、恶意工具输出、任何情况——没有东西可偷，因为压根就没有任何长期有效的东西存在过。

MCP 在这里已经做对了什么

如果你基于 Model Context Protocol 构建，有些设计已经帮你处理好了这部分。MCP 的授权 spec 有意把 MCP server 当作 OAuth 资源服务器，而不是授权服务器——也就是说，处理你工具调用的那个服务器，并不是决定谁可以调用它们的那个。这个职责属于专门的 identity provider，MCP server 的唯一职责是验证它拿到的那份 token。

这个分离比听起来更重要。它意味着你可以换掉或升级认证 provider，而无需碰你运行的每一个 MCP server，也意味着工具级别的授权决策只存在于一个地方，而不是在你构建的每一个集成里不一致地重复实现。

如果你不用 MCP、自己实现 Agent 到工具的协议，这一点值得直接抄过来：把"这个 token 能不能做这个"和"这个工具是干什么的"彻底分开。

仍然会出问题的地方

对短板诚实一些，因为这个模式还不是一个已经完成的解决方案：

多租户隔离。 如果你的 Agent 同时服务多个组织，每个 token 都需要把租户 ID 写死进去并在每一跳都检查——来自 Org A 的 Agent 拿着恰好也能访问 Org B 数据的 token，这是一个真实的、反复出现的故障模式。

撤销延迟。 短 TTL 有帮助，但如果你在任务中途撤销了 Agent 的常设权限，它已经拿到的短期 token 在自己过期之前仍然有效。

"谁批准了这个 scope"的治理。 上述机制干净地处理了发放问题，但完全没有涉及：是谁决定这个 Agent 可以请求 invoices:refund 的，以及这个决定在六个月后会不会被 review。这是策略工作，不是代码，而大多数团队跳过了它，因为这部分很无聊。

SDK 摩擦。 很多 LLM provider 的 SDK 仍然假设在初始化时用一份静态 key，中途换凭证没有干净的钩子。你最终会发现自己包装客户端的次数比你想要的要多。

Agent 既不是用户，也不是静态的服务账号——它是一种全新的行为者，需要自己的身份、自己窄范围受限的凭证、以及以分钟而不是月来计算的凭证生命周期。如果你的 Agent 的 .env 文件里有任何不会自己过期的东西，这周就去改它，别让它出现在下个月的故障报告里。