项目概览 在这一顶点课程中,你将构建一个完整的 AI 智能体,代表经过身份验证的用户执行四个现实世界的任务:通过身份验证验证身份、对数据库进行读写记录、调用外部 API 以获取或发送数据、并实施基于角色的访问控制(RBAC),以确保用户只看到其被允许看到的内容。这里是课程中所有前置概念相互连接的集成点。
你构建的智能体遵循请求-响应模式:用户发送请求,智能体校验用户身份,决定用户的权限,然后要么查询数据库、要么调用 API,或两者兼有,并返回结果。我们将使用 Python 处理智能体逻辑,使用 SQL 数据库进行持久化,使用一个模拟外部 API 进行外部数据交互,并使用简单的 JWT(JSON Web Token)机制进行身份验证。
体系结构与设置 在编写代码之前,我们先勾画四个运行中的部分及其连接方式。用户携带一个 JWT 令牌发送请求。智能体验证令牌,提取用户 ID 和角色,然后根据用户意图将请求路由到数据库处理程序或 API 调用程序。数据库处理程序使用参数化的 SQL 查询以防止注入攻击。API 调用程序在出站请求中附加相同的 JWT,以便外部服务能够独立验证调用方。
python 复制
from dataclasses import dataclass
@dataclass
class UserContext :
user_id : int
role : str
token : str
该 UserContext 对象随每次内部调用一起传递。请求进入智能体后,上下文被标记在其上,所有下游函数接收相同的上下文,因此在每个步骤进行授权检查,而不仅仅在入口点进行。
实现认证 认证意味着证明用户的身份。我们将使用一个简单的 JWT 风格令牌:一个包含用户 ID、角色和到期时间戳的 base64 编码字符串,通过共享密钥签名。在生产环境中,你会使用像 PyJWT 这样的库,但这里保持最小化,以便你看到机制。
python 复制
import base64 , json , hmac , hashlib , time
SECRET = "change-me-in-production"
def create_token ( user_id : int , role : str ) - > str :
payload = { "uid" : user_id , "role" : role , "exp" : int ( time . time ( ) ) + 3600 }
body = base64 . urlsafe_b64encode ( json . dumps ( payload ) . encode ( ) ) . decode ( )
sig = hmac . new ( SECRET . encode ( ) , body . encode ( ) , hashlib . sha256 ) . hexdigest ( )
return f" { body } . { sig } "
def verify_token ( token : str ) - > UserContext :
body , sig = token . split ( "." )
expected = hmac . new ( SECRET . encode ( ) , body . encode ( ) , hashlib . sha256 ) . hexdigest ( )
if not hmac . compare_digest ( sig , expected ) :
raise PermissionError ( "Invalid token signature" )
payload = json . loads ( base64 . urlsafe_b64decode ( body ) )
if payload [ "exp" ] < int ( time . time ( ) ) :
raise PermissionError ( "Token expired" )
return UserContext ( user_id = payload [ "uid" ] , role = payload [ "role" ] , token = token )
verify_token 函数是门卫。每个受保护的端点都会先调用它。如果令牌被篡改、过期或缺失,请在执行任何数据库或 API 代码之前拒绝请求。
安全查询数据库 完成身份验证后,下一步是让代理读取用户记录。此处的关键规则是:永远不要通过字符串拼接来构建 SQL。始终使用参数化查询,以使用户输入被视为数据,而非可执行的 SQL。
python 复制
import sqlite3
def get_user_orders ( ctx : UserContext , target_user_id : int ) - > list :
conn = sqlite3 . connect ( "app.db" )
cur = conn . cursor ( )
cur . execute ( "SELECT id, product, total FROM orders WHERE user_id = ?" , ( target_user_id , ) )
rows = cur . fetchall ( )
conn . close ( )
return rows
请注意用户 ID 作为元组参数传递,而不是被插入到字符串中。这一单一习惯阻止了 SQL 注入,这是最常见的数据库攻击。
调用外部 API 许多代理任务需要数据库中没有的数据,例如来自快递公司的运输状态或某条送货路线的天气信息。代理调用外部 HTTP API,传递同一 JWT,以便外部服务能够验证调用方。
python 复制
import urllib . request
def get_shipping_status ( ctx : UserContext , order_id : int ) - > dict :
req = urllib . request . Request (
f"https://api.courier.example/orders/ { order_id } " ,
headers = { "Authorization" : f"Bearer { ctx . token } " }
)
with urllib . request . urlopen ( req ) as resp :
return json . loads ( resp . read ( ) )
令牌被转发,而不是生成一个新的令牌。这允许快递服务记录谁提出了请求,并对每个用户应用其自己的速率限制。
强制执行基于角色的访问控制 身份验证告诉你是谁。授权(RBAC)告诉你他们被允许做什么。最干净的执行地点是在每个入口点调用的一个小策略函数。
python 复制
def require_role ( ctx : UserContext , allowed : list [ str ] ) :
if ctx . role not in allowed :
raise PermissionError ( f"Role ' { ctx . role } ' not permitted" )
python 复制
def list_all_orders ( ctx : UserContext ) - > list :
require_role ( ctx , [ "admin" ] )
conn = sqlite3 . connect ( "app.db" )
cur = conn . cursor ( )
cur . execute ( "SELECT id, user_id, product, total FROM orders" )
rows = cur . fetchall ( )
conn . close ( )
return rows
普通用户调用 list_all_orders 会被拒绝。管理员调用它则可看到整张表。策略检查只有一行,但它是系统安全与数据泄露之间的分界线。
把它们串联起来 主代理函数将身份验证、数据库访问、API 调用和 RBAC 组合成一个流程。
python 复制
def handle_request ( token : str , intent : str , params : dict ) :
ctx = verify_token ( token )
if intent == "my_orders" :
return get_user_orders ( ctx , params [ "user_id" ] )
elif intent == "all_orders" :
return list_all_orders ( ctx )
elif intent == "shipping" :
return get_shipping_status ( ctx , params [ "order_id" ] )
else :
raise ValueError ( "Unknown intent" )
每条路径都以 verify_token 开始。接触敏感数据的每条路径都调用 require_role。每个数据库查询都采用参数化。每次对外部 API 的调用都携带用户的令牌。这四个习惯,无处不在地重复,是让代理达到生产就绪状态的原因。
摘要 现在你拥有一个端到端可用的智能代理。身份验证通过签名令牌来证明身份。参数化的 SQL 查询进行读写数据,避免注入风险。对外部 API 的调用复用同一令牌,便于外部服务按用户进行审计和限流。基于角色的访问控制贯穿于每一个入口点,而不仅仅是前门,因此特权提升需要绕过多重检查。当你构建真正的代理时,模式是相同的:先验证身份,再在每个环节授权,总是参数化,并在每次调用中传递上下文。