1. 引言agntcy-identity-sdk 是 Agntcy 生态中用于身份管理与认证授权的 Python SDK为智能体Agent应用提供统一的身份标识、令牌签发、权限校验与密钥管理能力。它面向需要多智能体协作、服务间安全通信以及细粒度访问控制的场景帮助开发者把身份层从业务代码中解耦出来。本文将从功能特性、安装方式、核心语法与参数、9 个实际应用案例以及常见错误与注意事项五个方面系统介绍 agntcy-identity-sdk 的使用方法。2. 功能概述agntcy-identity-sdk 的核心功能可以归纳为以下几类身份标识管理为智能体、服务或用户创建全局唯一身份标识Agent ID支持元数据绑定与生命周期管理。令牌签发与验证基于 JWT 标准签发访问令牌支持自定义声明Claims、过期时间与签名算法配置。权限策略控制提供基于角色的访问控制RBAC与基于属性的访问控制ABAC两种策略模型。密钥管理封装对称与非对称密钥的生成、存储、轮换与吊销支持与外部 KMS 集成。多智能体信任链支持智能体之间的委托授权与信任传递适用于多智能体协作场景。审计与追踪记录身份操作日志便于安全审计与合规追溯。3. 安装与环境要求3.1 环境要求agntcy-identity-sdk 要求 Python 3.9 及以上版本支持 Linux、macOS 和 Windows 主流操作系统。建议在虚拟环境中安装避免依赖冲突。3.2 安装命令使用 pip 安装最新稳定版本pip install agntcy-identity-sdk如需安装指定版本pip install agntcy-identity-sdk0.4.2如需包含可选的 KMS 集成依赖pip install agntcy-identity-sdk[kms]3.3 验证安装import agntcy_identity_sdk print(agntcy_identity_sdk.__version__)4. 核心语法与参数4.1 初始化客户端所有操作都从创建 IdentityClient 实例开始。初始化参数包括endpoint身份服务地址默认为本地 127.0.0.1:8080。api_key调用身份服务所需的 API 密钥。timeout请求超时时间单位秒默认 30。verify_ssl是否校验 SSL 证书默认 True。from agntcy_identity_sdk import IdentityClient client IdentityClient( endpointhttps://identity.example.com, api_keyyour-api-key, timeout30, verify_sslTrue, )4.2 创建身份create_identity 方法用于创建新的智能体身份主要参数name身份名称必填。agent_type智能体类型如 assistant、worker、coordinator。metadata附加元数据字典可选。ttl身份有效期单位秒默认 86400。identity client.create_identity( nameorder-assistant, agent_typeassistant, metadata{team: commerce, env: prod}, ttl86400, ) print(identity.id)4.3 签发令牌issue_token 方法用于为身份签发访问令牌主要参数identity_id身份 ID必填。claims自定义声明字典可选。expires_in令牌有效期单位秒默认 3600。audience令牌受众可选。token client.issue_token( identity_ididentity.id, claims{role: order:read, scope: orders}, expires_in3600, audienceorder-service, ) print(token.access_token)4.4 验证令牌verify_token 方法用于校验令牌有效性返回解析后的声明信息claims client.verify_token(token.access_token) print(claims)4.5 权限检查check_permission 方法用于判断身份是否具备某项操作权限allowed client.check_permission( identity_ididentity.id, actionorder:read, resourceorders/12345, ) print(allowed)5. 实际应用案例5.1 案例一为智能体创建身份并签发令牌这是最基础的用法适用于需要为每个智能体分配独立身份并获取访问令牌的场景。from agntcy_identity_sdk import IdentityClient client IdentityClient(endpointhttp://localhost:8080, api_keydemo-key) 创建智能体身份 agent client.create_identity( namedata-analyzer, agent_typeworker, metadata{purpose: data-analysis}, ) 签发访问令牌 token client.issue_token( identity_idagent.id, claims{scope: dataset:read}, expires_in7200, ) print(fAgent ID: {agent.id}) print(fAccess Token: {token.access_token})5.2 案例二服务间安全通信两个微服务之间通过令牌进行身份认证确保请求来源可信。# 服务 A签发令牌 client_a IdentityClient(endpointhttp://localhost:8080, api_keyservice-a-key) service_a_identity client_a.create_identity(nameservice-a, agent_typeservice) token client_a.issue_token(identity_idservice_a_identity.id, audienceservice-b) 服务 B验证令牌 client_b IdentityClient(endpointhttp://localhost:8080, api_keyservice-b-key) claims client_b.verify_token(token.access_token) if claims.get(aud) service-b: print(服务 B 验证通过允许访问) else: print(令牌受众不匹配拒绝访问)5.3 案例三基于角色的权限控制为不同角色分配不同权限实现细粒度的访问控制。# 创建管理员身份 admin client.create_identity(nameadmin-user, agent_typeuser) client.assign_role(identity_idadmin.id, roleadmin) 创建普通用户身份 user client.create_identity(nameregular-user, agent_typeuser) client.assign_role(identity_iduser.id, roleviewer) 检查权限 admin_can_delete client.check_permission(identity_idadmin.id, actionorder:delete, resourceorders/1) user_can_delete client.check_permission(identity_iduser.id, actionorder:delete, resourceorders/1) print(f管理员可删除订单: {admin_can_delete}) print(f普通用户可删除订单: {user_can_delete})5.4 案例四多智能体委托授权主智能体将部分权限委托给子智能体实现任务分发与协作。# 创建主智能体 coordinator client.create_identity(namecoordinator, agent_typecoordinator) 创建子智能体 worker client.create_identity(nameworker-1, agent_typeworker) 主智能体委托权限给子智能体 client.delegate_permission( from_identity_idcoordinator.id, to_identity_idworker.id, actions[task:execute], resourcetasks/*, expires_in3600, ) 子智能体执行任务前检查权限 allowed client.check_permission( identity_idworker.id, actiontask:execute, resourcetasks/42, ) print(f子智能体可执行任务: {allowed})5.5 案例五令牌过期与刷新处理令牌过期场景通过刷新令牌获取新的访问令牌。# 签发短时令牌 token client.issue_token(identity_idagent.id, expires_in60) 模拟令牌过期 import time time.sleep(61) try: claims client.verify_token(token.access_token) except Exception as e: print(f令牌已过期: {e}) # 使用刷新令牌重新获取 refresh_token client.refresh_token(refresh_tokentoken.refresh_token) print(f新令牌: {refresh_token.access_token})5.6 案例六密钥轮换定期轮换密钥提升系统安全性。# 生成新密钥 new_key client.create_key( namesigning-key-v2, key_typeRSA, key_size2048, ) 将新密钥设为当前签名密钥 client.activate_key(key_idnew_key.id) 吊销旧密钥 client.revoke_key(key_idsigning-key-v1) print(f新密钥已激活: {new_key.id})5.7 案例七审计日志查询查询身份操作日志用于安全审计。logs client.list_audit_logs( identity_idagent.id, start_time2026-09-01T00:00:00Z, end_time2026-09-23T23:59:59Z, limit50, ) for log in logs: print(f{log.timestamp} - {log.action} - {log.result})5.8 案例八与 FastAPI 集成在 FastAPI 应用中集成身份验证中间件保护 API 端点。from fastapi import FastAPI, Depends, HTTPException from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials from agntcy_identity_sdk import IdentityClient app FastAPI() security HTTPBearer() client IdentityClient(endpointhttp://localhost:8080, api_keyapi-key) def verify_auth(credentials: HTTPAuthorizationCredentials Depends(security)): try: claims client.verify_token(credentials.credentials) return claims except Exception: raise HTTPException(status_code401, detail无效令牌) app.get(/orders) def get_orders(claims: dict Depends(verify_auth)): return {message: 订单数据, user: claims.get(sub)}5.9 案例九批量创建身份在初始化阶段批量创建多个智能体身份提高效率。agents [] for i in range(10): agent client.create_identity( namefworker-{i}, agent_typeworker, metadata{batch: 2026-09, index: i}, ) agents.append(agent) print(f成功创建 {len(agents)} 个智能体身份) for agent in agents: print(f - {agent.name}: {agent.id})6. 常见错误与使用注意事项6.1 常见错误错误类型错误信息原因与解决方案连接错误ConnectionError: Failed to connect to identity service身份服务未启动或地址配置错误。检查 endpoint 参数和服务状态。认证失败AuthenticationError: Invalid API keyAPI 密钥错误或已过期。核对 api_key 参数。令牌过期TokenExpiredError: Token has expired令牌超过有效期。使用 refresh_token 刷新或重新签发。权限不足PermissionDeniedError: Insufficient permissions身份缺少目标操作权限。检查角色分配和权限策略。身份不存在IdentityNotFoundError: Identity not foundidentity_id 无效或身份已被删除。确认身份 ID 正确。参数校验错误ValidationError: name is required缺少必填参数。按文档补齐参数。6.2 使用注意事项密钥安全api_key 和私钥不要硬编码在代码中建议使用环境变量或密钥管理服务保存。令牌有效期合理设置 expires_in过短会导致频繁刷新过长会增大安全风险。时区处理审计日志查询的时间参数建议使用 UTC 时间避免时区偏差。异常处理所有 SDK 调用都应包裹在 try-except 中针对不同异常类型做差异化处理。版本兼容升级 SDK 前阅读 changelog确认接口变更避免破坏性更新影响线上服务。并发安全IdentityClient 实例是线程安全的可在多线程环境中共享无需重复创建。资源清理不再使用的身份和密钥应及时吊销减少安全暴露面。7. 总结agntcy-identity-sdk 为 Python 智能体应用提供了完整的身份管理解决方案覆盖身份创建、令牌签发、权限控制、密钥管理和审计追踪等核心能力。通过本文的 9 个实际案例开发者可以快速掌握其基本用法并将其集成到真实业务系统中。在实际使用中务必重视密钥安全、令牌有效期管理和异常处理以构建安全可靠的多智能体应用。《AI提示工程必知必会》主要内容包括各类提示词的应用如问答式、指令式、状态类、建议式、安全类和感谢类提示词以及如何通过实战演练掌握提示词的使用技巧使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务以及在数据挖掘、程序开发等领域的应用AI在绘画创作上的应用百度文心一言和阿里通义大模型这两大智能平台的特性与功能以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》读者可掌握如何有效利用AI提示工程提升工作效率创新工作流程并在职场中脱颖而出。