为什么代理需要认证
当 AI 代理调用外部服务——数据库、第三方 API、云函数时,必须证明自己的身份。这一证明通常有两种形式:静态 API 密钥(服务仅向你发放一次的长随机字符串)或通过 OAuth 2.0 颁发的短期令牌(代理用凭证换取时效访问令牌的协议)。两者的作用相同:远程服务器检查凭据,然后决定是否执行请求。
危险并非凭据本身——而是凭据泄露时会发生的事。聊天日志、错误追踪或发送给大型语言模型的提示中被泄露的 API 密钥可能在数分钟内被抓取并滥用。将秘密当作生产数据库密码那样严格对待,是基本的期望值。
存放秘密的位置
切勿在源代码中硬编码凭据。切勿将它们粘贴到提示模板中。常用模式是在运行时从环境变量中加载它们,使秘密存在于部署环境中,而非代码库中。
在这个片段中,密钥从环境中读取,作为 Bearer 令牌附加在 HTTP 头中,且永不写入磁盘或被日志记录。如果环境变量缺失,代理应快速失败并给出明确的启动错误——而不是悄悄回退到掩盖配置错误的占位符。
对于本地开发,一个 .env 文件(纯文本,key=value 对,且通过 .gitignore 排除在版本控制之外)效果很好。生产环境中,由编排工具或秘密管理器注入值。无论哪种情况,规则相同:秘密应位于代码之外。
OAuth 令牌与刷新流程
静态密钥简单但不灵活。OAuth 令牌在代理代表用户执行操作时更合适——例如读取他们的日历或在他们的帐户上发帖。流程如下:
代理应仅在内存中存储访问令牌,将刷新令牌存储在安全的存储中。当访问令牌过期(通常由 401 响应表示)时,代理使用刷新令牌静默地换入一个新的访问令牌——用户无需再次授予同意。将刷新逻辑塞进一个小型辅助函数可使调用代码保持整洁。
避免提示和日志中的泄露
在代理系统中最常见的凭据泄露是意外回显:代理在发送给大型语言模型(LLM)的提示中包含秘密,或日志记录器打印出包含头部信息的完整请求。只要知道如何查看,这两者都很容易防止。
第一个函数过滤掉名称中含有秘密信号的任何上下文字段。第二个在打印前对 Authorization 头进行红acting。将同样的清理应用到追踪日志、错误报告以及任何面向用户的错误信息——若堆栈跟踪中包含令牌,则说明你已经丢失了。
总结
大多数暴露面涵盖的三条规则。第一,从环境变量加载凭据,而不是从代码或提示中加载。第二,只要服务支持 OAuth,优先使用短期令牌而非长期密钥,并自动刷新。第三,将每一条日志、错误信息和提示都视为潜在的泄露向量——在写入前进行裁剪。遵循这三条规则并不能让系统百战百胜,但它确实关闭了攻击者实际会走的门。
课程检查点
巩固所学知识,获取作业反馈。