首先完成“将 API 设计为 Agent 工具并使用”即可解锁本课程。转到上一课

为什么代理需要认证

当 AI 代理调用外部服务——数据库、第三方 API、云函数时,必须证明自己的身份。这一证明通常有两种形式:静态 API 密钥(服务仅向你发放一次的长随机字符串)或通过 OAuth 2.0 颁发的短期令牌(代理用凭证换取时效访问令牌的协议)。两者的作用相同:远程服务器检查凭据,然后决定是否执行请求。

危险并非凭据本身——而是凭据泄露时会发生的事。聊天日志、错误追踪或发送给大型语言模型的提示中被泄露的 API 密钥可能在数分钟内被抓取并滥用。将秘密当作生产数据库密码那样严格对待,是基本的期望值。

两种身份验证流程对比图:静态 API 密钥附加在每个请求中,以及通过握手获取 OAuth 令牌后在临时期间使用

存放秘密的位置

切勿在源代码中硬编码凭据。切勿将它们粘贴到提示模板中。常用模式是在运行时从环境变量中加载它们,使秘密存在于部署环境中,而非代码库中。

python
import os
import requests
api_key = os.environ["WEATHER_API_KEY"]
response = requests.get(
"https://api.weather.example.com/v1/current",
headers={"Authorization": f"Bearer {api_key}"}
)

在这个片段中,密钥从环境中读取,作为 Bearer 令牌附加在 HTTP 头中,且永不写入磁盘或被日志记录。如果环境变量缺失,代理应快速失败并给出明确的启动错误——而不是悄悄回退到掩盖配置错误的占位符。

对于本地开发,一个 .env 文件(纯文本,key=value 对,且通过 .gitignore 排除在版本控制之外)效果很好。生产环境中,由编排工具或秘密管理器注入值。无论哪种情况,规则相同:秘密应位于代码之外。

OAuth 令牌与刷新流程

静态密钥简单但不灵活。OAuth 令牌在代理代表用户执行操作时更合适——例如读取他们的日历或在他们的帐户上发帖。流程如下:

bash
# Step 1: agent receives an authorization code after user consent
# Step 2: exchange code for access token + refresh token
curl -X POST https://auth.example.com/oauth/token \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "client_id=AGENT_ID" \
-d "client_secret=AGENT_SECRET"
# Step 3: use the access token until it expires, then refresh

代理应仅在内存中存储访问令牌,将刷新令牌存储在安全的存储中。当访问令牌过期(通常由 401 响应表示)时,代理使用刷新令牌静默地换入一个新的访问令牌——用户无需再次授予同意。将刷新逻辑塞进一个小型辅助函数可使调用代码保持整洁。

避免提示和日志中的泄露

在代理系统中最常见的凭据泄露是意外回显:代理在发送给大型语言模型(LLM)的提示中包含秘密,或日志记录器打印出包含头部信息的完整请求。只要知道如何查看,这两者都很容易防止。

python
def build_prompt(user_query: str, context: dict) -> str:
# Never inject credentials into the prompt
safe_context = {k: v for k, v in context.items() if not k.startswith("secret_")}
return f"Context: {safe_context}\nUser: {user_query}"
def safe_log_request(method, url, headers):
# Strip Authorization header before logging
redacted = {k: ("***" if k.lower() == "authorization" else v) for k, v in headers.items()}
print(f"{method} {url} headers={redacted}")

第一个函数过滤掉名称中含有秘密信号的任何上下文字段。第二个在打印前对 Authorization 头进行红acting。将同样的清理应用到追踪日志、错误报告以及任何面向用户的错误信息——若堆栈跟踪中包含令牌,则说明你已经丢失了。

总结

大多数暴露面涵盖的三条规则。第一,从环境变量加载凭据,而不是从代码或提示中加载。第二,只要服务支持 OAuth,优先使用短期令牌而非长期密钥,并自动刷新。第三,将每一条日志、错误信息和提示都视为潜在的泄露向量——在写入前进行裁剪。遵循这三条规则并不能让系统百战百胜,但它确实关闭了攻击者实际会走的门。

课后练习

课程检查点

巩固所学知识,获取作业反馈。

0/1
已回答 · 0/1