在AgentRun中使用Agent Identity

环境要求

• Python：版本 ≥ 3.10

• pip：包管理器

RAM用户及权限要求

您需要准备一个RAM用户用于执行Agent Identity CLI命令，以创建工作负载身份和关联的RAM角色，并为RAM角色自动配置所需权限。执行CLI命令的RAM用户至少需要具备以下权限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "agentidentity:CreateWorkloadIdentity",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateRole",
        "ram:AttachPolicyToRole",
        "ram:CreatePolicy"
      ],
      "Resource": "*"
    }
  ]
}

OAuth2身份提供商

您需要准备一个支持OIDC/OAuth2协议的身份提供商（IdP）用于验证终端用户身份，并颁发JWT令牌（又称ID Token）。在调用Agent时，JWT令牌将被一同传入用以完成AgentRun以及Agent Identity的入站认证。本教程以阿里云身份提供商为例。

创建大语言模型服务

AgentRun通过统一模型代理网关管理模型调用，需要创建大模型服务供Agent调用。

1. 登录函数计算FC控制台。

2. 在左侧导航栏选择函数智能 > 智能体AgentRun，进入AgentRun控制台。

3. 在顶部导航栏选择模型管理，单击添加模型。

4. 保持默认选择的API模型选项，然后选择模型服务提供商（如阿里云），配置具体模型。

   在弹窗中，名称会自动生成，API端点默认填写为 https://dashscope.aliyuncs.com/compatible-mode/v1（留空则使用默认端点）。

5. 在凭证配置部分，选择API密钥。输入您从模型提供商处获得的API密钥（如百炼API Key）。

   在访问密钥字段旁，可单击获取百炼API KEY链接跳转获取密钥。页面提示：API 密钥仅用于当前模型，不会保存到凭证管理中。

6. 单击创建模型，完成模型创建。复制模型服务名称并保存，以备后用。

   模型服务名称（例如 model-BTAtkv）显示在模型卡片上方，可单击旁边的复制图标进行复制。

创建AgentRun入站访问凭证

入站凭证用于验证调用方身份。AgentRun支持多种认证方式，本教程使用JWT认证。

1. 在AgentRun控制台顶部导航栏选择其他 > 凭证管理。

2. 保持默认选择的访问AgentRun凭证页签，单击创建访问凭证。

3. 在创建访问凭证页面，完成如下配置：

   • 凭证名称：用于标识凭证的名称，例如输入aliyun。

   • 认证类型：选择认证类型为JWT（JSON Web Token）。

   • JWKS配置方式：选择JWKS URL获取方式：

   • JWKS端点URL：输入阿里云的JWKS端点地址https://oauth.aliyun.com/v1/keys。

   超时时间(秒)：输入 30（取值范围 1-30 秒）。缓存时间(秒)：输入 3600（取值范围 300-7200 秒）。勾选创建后立即启用，然后单击创建凭证。

4. 其余设置均保持默认。单击创建凭证，完成访问凭证创建。

   凭证管理列表中显示名为 aliyun 的 JWT 类型凭证，状态为启用，绑定资源数量为 1。

安装Agent Identity CLI

在本地环境中安装Agent Identity CLI（全局安装）。

pip install agent-identity-cli

准备RAM用户凭证

在本地使用RAM用户及权限要求中提到的RAM用户配置凭证。

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

创建工作负载身份

执行以下命令创建工作负载身份及关联的RAM角色：

agent-identity-cli create-workload-identity --workload-identity-name <your-workload-identity-name>

CLI将自动创建以下资源：

配置阿里云为Agent Identity入站身份提供商

创建的工作负载身份，需要关联到身份提供商，才可以完成Agent Identity处的入站身份认证。

1. 登录Agent Identity控制台。

2. 参考教程配置阿里云为Agent Identity的身份提供商创建入站身份提供商，将回调地址设置为http://localhost:8090。完成后，复制应用ID保存以备后用。

3. 在左侧导航栏选择工作负载身份，找到上一步中创建的工作负载身份。

4. 单击关联身份提供商，选择创建的入站身份提供商。

5. 单击确定，完成入站身份提供商配置。

获取示例代码

示例代码基于LangChain框架，集成了Agent Identity SDK实现安全的第三方服务访问。在本地打开终端，执行以下命令克隆示例代码。

git clone https://github.com/aliyun/agent-identity-dev-kit
cd agent_identity_python_samples/agentrun-langchain_sample

zip -r agentrun-langchain_sample.zip .

创建并配置钉钉应用

如您还没有创建并配置钉钉应用，请参照在Agent中安全访问钉钉教程中的步骤一完成创建和配置，并将钉钉配置为Agent Identity的OAuth2凭证提供商。

注意：钉钉凭证提供商的名称必须设置为test-provider-for-dingtalk，以与Agent示例项目中的配置（位于agentrun-langchain_sample/ding_talk_tool.py中）匹配。

配置工作负载身份的应用回调地址

为了让Agent Identity为您的Agent从钉钉处获取OAuth访问令牌，需要为创建的工作负载身份配置应用回调地址。

1. 登录Agent Identity控制台。

2. 进入工作负载身份详情页的认证流程区域，单击设置应用回调地址。

3. 在设置应用回调地址弹窗中，输入地址http://localhost:8090/callback。

4. 单击确定。

配置Web前后端应用示例

1. 在项目根目录下（agent-identity-dev-kit），执行以下命令切换到端到端示例目录：

   cd agent_identity_python_samples/end-to-end_sample

2. 安装端到端示例所需的依赖（建议在Python虚拟环境中操作）：

   pip install -r requirements.txt

3. 将配置阿里云为Agent Identity入站身份提供商步骤中保存应用ID，以及创建并配置Agent步骤中保存的Agent公网访问端点更新至项目下的application/app.yml文件中：

   INBOUND_APP_ID: "<replace-with-your-oauth-app-id>"
   AGENT_ENDPOINT: "https://<replace-with-your-agent-access-endpoint>/openai/v1/chat/completions"

启动前后端应用

在目录end-to-end_sample下执行以下命令：

python -m application.backend.app

访问应用并与代理交互

1. 等待代理及前后端应用启动完毕后，在浏览器中输入应用访问地址http://localhost:8090。

2. 完成阿里云登录及用户授权。之后，您可在应用对话窗口中与模型进行对话，例如输入：“将以下内容写入我的钉钉文档：{钉钉文档链接或文档ID} {需要写入的内容}”。

   输入上述内容后，对话界面将返回一条包含 OAuth 授权链接的提示，提示文本为 Please click the link to authorize Write to DingTalk document，用户需点击该授权链接完成钉钉文档写入授权后，Agent 方可执行写入操作。

   说明

   您需要提前获取钉钉文档的链接，本示例应用无法新建钉钉文档并写入。

3. 单击返回结果中的OAuth授权地址并使用钉钉文档持有者账户完成登录和授权。

4. 完成授权后，如果一切正常，Agent将提示文档已经写入成功。类似如下：

   在 Agent 对话界面中，用户提供钉钉文档链接并下达写入指令，Agent 通过 Agent Identity 服务生成 OAuth 授权链接并提示用户点击完成授权，授权通过后 Agent 确认内容已成功写入目标文档。

5. 此时检查钉钉文档，会发现文档已成功写入内容。