# 委托介绍
委托是华为云统一身份认证服务（IAM）提供的一种信任关系机制。如果您在华为云购买了多种云资源，其中一种云资源希望让更专业、高效的公司、账号或者云服务来代运维，您可以通过IAM的委托功能，与代运维公司、账号或者云服务创建委托关系，实现安全高效的资源代运维工作。被委托的账号、公司或云服务可以根据权限代替您进行资源运维工作。
表1委托类型 
| 类型  | 说明                                                                                      |
|:---|:---|
| 普通账号委托 | 通过委托信任功能，将自己的资源操作权限委托给其他华为云账号，被委托的账号可以根据权限代替您进行资源运维工作。                                    |
| 云服务委托 | 由于华为云各服务之间存在业务交互关系，一些云服务需要与其他云服务协同工作，需要您创建云服务委托，将操作权限委托给该服务，让该服务以您的身份使用其他云服务，代替您进行一些资源运维工作。 |
   
**功能优势**
- **灵活管理**：支持向账号和云服务委托权限，满足不同场景下的资源管理需求。企业可以根据业务需要，将部分业务委托给更专业的其他企业来完成。
- **安全可靠**：创建委托并授权后，被委托方只能按照权限使用资源，保障了账号、数据和资源的安全。委托方可以随时通过简单操作建立、修改或取消委托关系。
更多关于委托的详细介绍，请参考[委托概述](https://support.huaweicloud.com/usermanual-iam/iam_01_0661.html)。
AgentArts运行时涉及两个委托，分别用于不同的场景：
- AgentArtsRuntimeDeploymentAgency（服务部署委托）
- 用户运行时委托（智能体身份委托）
#### AgentArtsRuntimeDeploymentAgency（服务部署委托）
| 属性   | 说明                                       |
|:---|:---|
| 委托名称   | AgentArtsRuntimeDeploymentAgency（固定名称）   |
| 对应策略 | AgentArtsRuntimeDeploymentAgencyPolicy   |
| 用途  | 委托给沙箱服务，用于下载用户镜像、挂载SFS Turbo共享文件存储      |
| 是否必须 | 必须。该委托由服务内部使用，是AgentArts运行时正常工作的前提条件，不可删除 |
| 用户感知 | 对用户不感知，由服务内部自动使用                          |
   
AgentArtsRuntimeDeploymentAgencyPolicy包含以下权限：
| 权限 Action                       | 权限级别 | 说明                          |
|:---|:---|:---|
| swr::createAuthorizationToken | 写入     | 授予共享版仓库生成新的临时登录指令的权限       |
| swr:repo:download                | 读取     | 授予共享版仓库下载镜像的权限             |
| sts::createServiceBearerToken | 写入    | 授予权限获取一个绑定至某服务的 Bearer Token |
| sfsturbo:shares:getShare     | 读取     | 授予查询弹性文件系统的权限              |
   
各Action详细说明：
swr::createAuthorizationToken
- 功能：生成SWR（容器镜像服务）共享版仓库的临时访问凭证
- 使用场景：AgentArts沙箱服务在拉取用户镜像前，需要先获取SWR的临时登录指令
swr:repo:download
- 功能：从SWR共享版仓库下载容器镜像
- 使用场景：沙箱服务通过该权限下载用户上传的智能体运行时镜像
sts::createServiceBearerToken
- 功能：获取绑定至特定服务的 Bearer Token
- 使用场景：沙箱服务通过STS获取服务级令牌，用于跨服务认证
sfsturbo:shares:getShare
- 功能：查询SFS Turbo弹性文件系统信息
- 使用场景：沙箱服务在挂载SFS Turbo共享存储前，需要查询文件系统的状态和配置信息
#### 用户运行时委托（智能体身份委托）
| 属性     | 说明                                                                                                         |
|:---|:---|
| 委托名称   | 用户自定义（服务开通时自动创建默认委托 DefaultAgentArtsRuntimeAgency）                                                      |
| 推荐策略 | AgentArtsCoreRunRuntimeIdentityAgencyPolicy + AgentArtsCoreRunRuntimeOpsAgencyPolicy                      |
| 用途     | 在智能体运行时内部代表用户身份与其他华为云云服务交互                                                                              |
| 是否必须    | 推荐配置。使用默认委托可开箱即用；如需自定义，可在创建运行时时手动创建                                                                        |
| 创建方式    | 服务开通时自动创建 DefaultAgentArtsRuntimeAgency；也可在创建运行时时手动创建，信任主体类型选择"云服务"，云服务搜索 service.WorkloadSandboxMetadata |
   
关于运行时委托的创建和配置，请参考[通过控制台部署智能体运行时](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html)。
**策略一：AgentArtsCoreRunRuntimeIdentityAgencyPolicy**
该策略用于获取智能体运行时出站认证凭据的相关权限。
| 权限 Action                            | 权限级别 | 说明                                    |
|:---|:---|:---|
| agentIdentity::getResourceApiKey      | 读取    | 授予获取与API密钥凭证提供者关联的API密钥的权限             |
| agentIdentity::getResourceOauth2Token | 读取   | 授予通过OAuth2 两方/三方授权流程获取访问令牌，以访问外部资源的权限 |
| agentIdentity::getResourceStsToken      | 读取   | 授予从STS凭证提供者获取IAM临时凭证的权限               |
| csms:secret:getVersion               | 读取   | 授予查询指定凭据版本的信息和其明文凭据值的权限               |
| kms:cmk:decryptDataKey              | 写入   | 授予解密数据密钥的权限                           |
   
各 Action 详细说明：
- agentIdentity::getResourceApiKey：从Agent Identity服务获取API Key，用于以API Key认证方式访问外部云服务
- agentIdentity::getResourceOauth2Token：通过OAuth2流程（M2M或USER_FEDERATION）获取访问令牌，用于访问支持OAuth2认证的外部资源
- agentIdentity::getResourceStsToken：从STS凭证提供者获取IAM临时凭证（AK/SK/SecurityToken），用于以华为云用户身份访问其他云服务
- csms:secret:getVersion：查询凭据管理服务中存储的凭据明文值，用于获取预先配置的密钥和证书
- kms:cmk:decryptDataKey：解密凭据管理服务中加密存储的数据密钥，配合CSMS凭据读取使用
**策略二：AgentArtsCoreRunRuntimeOpsAgencyPolicy**
该策略用于智能体运行时可观测性服务相关权限。
| 权限 Action           | 权限级别 | 说明                       |
|:---|:---|:---|
| apm:application:get | 读取   | 授予获取应用信息数据的权限           |
| aom:metric:list     | 列举  | 授予权限以查询指标项              |
| aom:icmgr:get      | 读取 | 授予权限以获取采集组件（ICAgent）版本信息 |
   
各Action详细说明：
- apm:application:get：从APM（应用性能管理服务）获取应用信息数据，用于智能体运行时的性能监控
- aom:metric:list：从 AOM（应用运维管理服务）查询监控指标项，用于采集和上报运行时指标
- aom:icmgr:get：获取 ICAgent 采集组件版本信息，用于运行时可观测性管理
#### 如何使用两个委托
**AgentArtsRuntimeDeploymentAgency**
该委托由AgentArts服务内部直接使用，对用户完全透明。用户无需进行任何额外配置或代码编写。
服务会在以下场景中自动使用该委托：
- 下载用户镜像：当用户创建或更新智能体运行时时，沙箱服务使用该委托从SWR下载用户指定的容器镜像
- 挂载SFS Turbo：当用户配置了SFS Turbo存储时，沙箱服务使用该委托查询并挂载弹性文件系统
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
该委托是AgentArts运行时正常工作的前提条件，请勿删除。如果该委托被删除，将导致运行时创建失败或镜像下载异常。
**用户运行时委托（智能体身份委托）**
该委托用于在智能体运行时内部代表用户身份访问其他华为云云服务。AgentArts运行时SDK提供了 MetadataProvider来自动获取该委托对应的临时凭据，用户可以使用该凭据来访问其他云服务。
工作原理
```
智能体运行时  →  MetadataProvider  →  元数据服务  →  获取AK/SK/SecurityToken  →  使用凭据访问其他云服务
```
MetadataProvider是AgentArts SDK凭证提供链中的一环。当智能体运行在AgentArts运行时环境中时，SDK会自动通过元数据服务获取委托对应的临时凭据（AK/SK/SecurityToken），无需用户手动配置AK/SK。
SDK凭证获取优先级
AgentArts SDK的凭证提供链（CredentialProviderChain）按以下顺序尝试获取凭证：
1. EnvCredentialProvider：从环境变量读取（HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK）
2. ProfileCredentialProvider：从配置文件读取
3. MetadataProvider：从 AgentArts 运行时元数据服务获取（仅在运行时环境中可用）
**代码示例**
**示例 1：直接使用MetadataProvider获取凭据**
```
from agentarts.sdk.utils.metadata import create_credential
# 自动按优先级获取凭证：环境变量 → 配置文件 → 元数据服务
# 在 AgentArts 运行时环境中，会自动通过 MetadataProvider 获取委托凭据
credentials = create_credential()
# 使用获取到的凭据访问其他华为云服务
# credentials 包含 AK、SK 和 SecurityToken
print(f"AK: {credentials.ak}")
print(f"SK: ***（已隐藏）")
print(f"Security Token: {credentials.security_token}")
```
**示例 2：使用 @require_sts_token 装饰器获取 STS 临时凭据**
```
from agentarts.sdk import require_sts_token
# 通过装饰器自动获取 STS 凭证并注入到函数参数中
@require_sts_token(
    provider_name="huaweicloud-iam",       # 凭证提供者名称
    agency_session_name="my-agent-session" # 会话名称
)
def access_cloud_resource(sts_credentials=None):
    """使用 STS 凭证访问华为云服务"""
    print(f"Access Key ID: {sts_credentials.access_key_id}")
    print(f"Secret Access Key: ***（已隐藏）")
    print(f"Security Token: {sts_credentials.security_token}")
    print(f"Expiration: {sts_credentials.expiration}")
    # 在此处使用 sts_credentials 访问其他华为云服务
    # 例如：访问 OBS、RDS、ECS 等
# 调用函数，STS 凭证会自动注入
access_cloud_resource()
```
**示例 3：使用 @require_api_key 装饰器获取 API Key**
```
from agentarts.sdk import require_api_key
@require_api_key(
    provider_name="my-api-key-provider"  # 凭证提供者名称
)
def call_external_api(api_key=None):
    """使用 API Key 调用外部服务"""
    print(f"API Key: {api_key}")
    # 在此处使用 api_key 访问外部 API
    headers = {"Authorization": f"Bearer {api_key}"}
    # response = requests.get("https://api.example.com/data", headers=headers)
call_external_api()
```
**示例 4：使用 @require_access_token 装饰器获取 OAuth2 令牌**
```
from agentarts.sdk import require_access_token
@require_access_token(
    provider_name="my-oauth2-provider",
    auth_flow="M2M",  # 机器对机器流程，也可使用 "USER_FEDERATION"
    scopes=["read", "write"]
)
def access_oauth_resource(access_token=None):
    """使用 OAuth2 令牌访问受保护的资源"""
    print(f"Access Token: {access_token}")
    # 在此处使用 access_token 访问受 OAuth2 保护的资源
    headers = {"Authorization": f"Bearer {access_token}"}
    # response = requests.get("https://api.example.com/protected", headers=headers)
access_oauth_resource()
```
**示例 5：在智能体代码中集成使用**
```
from agentarts.sdk import AgentArtsRuntimeApp, RequestContext
from agentarts.sdk import require_sts_token
app = AgentArtsRuntimeApp()
@app.route("/invoke")
@require_sts_token(
    provider_name="huaweicloud-iam",
    agency_session_name="runtime-agent"
)
async def handle_invoke(request, sts_credentials=None):
    """智能体入口函数，自动获取 STS 凭证访问其他云服务"""
    # 使用 sts_credentials 访问用户的其他华为云资源
    # 例如：读取 OBS 中的数据、查询 RDS 数据库等
    ak = sts_credentials.access_key_id
    sk = sts_credentials.secret_access_key
    token = sts_credentials.security_token
    # 示例：使用凭证访问 OBS
    # from obs import ObsClient
    # obs_client = ObsClient(
    #     access_key_id=ak,
    #     secret_access_key=sk,
    #     security_token=token,
    #     server="obs.cn-southwest-2.myhuaweicloud.com"
    # )
    # obs_client.getObject("my-bucket", "my-object")
    return {"status": "success", "message": "资源访问成功"}
if __name__ == "__main__":
    app.run()
```
关键说明
1. 元数据服务地址：MetadataProvider通过元数据服务的 v1/metadata/securitykey接口获取凭据，该服务仅在AgentArts运行时环境内可访问
2. 凭据有效期：通过元数据服务获取的临时凭据具有有效期（expires_at），SDK会自动处理凭据的刷新
3. 本地开发：在本地开发环境中（非运行时环境），MetadataProvider将无法获取凭据，SDK会提示配置环境变量HUAWEICLOUD_SDK_AK 和 HUAWEICLOUD_SDK_SK
4. 默认委托：如果未自定义委托，服务开通时自动创建的DefaultAgentArtsRuntimeAgency已包含推荐的两个策略，可直接开箱使用