智能體身分（Agent Identity）：在Agent中安全訪問DingTalk

環境要求

本地測試環境需要安裝Python（版本≥ 3.10）以及pip包管理器。

使用者及許可權要求

1. 使用者要求：

   1. DingTalk開放平台管理員：用於管理DingTalk開放平台的應用

   2. 指令碼執行使用者（RAM使用者）：用於執行準備指令碼及本地應用測試。

2. RAM許可權要求：

   指令碼執行使用者需要具備以下許可權：

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "agentidentity:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "agentidentitydata:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "ram:CreateServiceLinkedRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "ram:ServiceName": ["agentidentity.aliyuncs.com"]
           }
         }
       },
       {
         "Effect": "Allow",
         "Action": [
           "ram:CreateApplication",
           "ram:CreateRole", 
           "ram:CreatePolicy",
           "ram:AttachPolicyToRole", 
           "ram:CreateAppSecret",
           "ram:DeleteApplication"
         ],
         "Resource": "*"
       }
     ]
   }

百鍊API密鑰

擷取具有百鍊模型調用許可權的DashScope API密鑰。如您還沒有建立百鍊API密鑰，請參考擷取API Key進行建立和配置。

建立DingTalk應用

按照DingTalkOAuth憑證供應商設定教程建立DingTalk應用，並將DingTalk配置為Agent Identity的OAuth2憑證供應商。

配置DingTalk應用許可權

1. 登入DingTalk開發人員後台。找到建立的DingTalk應用，進入應用詳情頁。

2. 在應用詳情頁的左側導覽列，單擊許可權管理。在許可權搜尋方塊中輸入Document.Document.Write，單擊返回結果操作列的立即開通。該許可權授予DingTalk應用以委託方式覆寫使用者本人的DingTalk文檔。

擷取並準備範例程式碼

1. 複製代碼倉庫。在本地開啟終端，執行以下命令複製範例程式碼。

   git clone https://github.com/aliyun/agent-identity-dev-kit.git
   cd agent-identity-dev-kit/agent_identity_python_samples/end-to-end_sample

2. 安裝依賴。建議建立並啟用一個 Python 虛擬環境，然後安裝專案所需的依賴。

   pip install -r requirements.txt

3. 配置環境變數。

   export AGENT_IDENTITY_REGION_ID=cn-beijing # 當前Agent Identity僅開放北京地區
   export DASHSCOPE_API_KEY=<your-api-key> # DashScope API

準備RAM使用者憑證

在本地使用使用者及許可權要求提到的指令碼執行使用者配置憑證。

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

執行準備指令碼

在本地專案根目錄下運行準備指令碼prepare.py來自動建立所需的雲資源：

python -m prepare

此指令碼執行以下操作：

1. 建立身份提供者

2. 建立阿里雲OAuth 2.1入站應用

3. 建立阿里雲MCP服務所需的OAuth 2.1 Native應用（在本教程中不會使用）

4. 建立工作負載身份和角色

5. 配置憑證提供者

指令碼會輸出建立的資源資訊到根目錄下的.config.json檔案中。

如果執行過程中出現異常失敗（如網路問題、資源超過quota等）需要清除建立的資源後再重新運行準備指令碼，清除建立的資源請運行：

python -m clear

在代碼中配置DingTalk憑證供應商

1. 在Agent Identity憑證供應商頁面，找到您在步驟一中建立的DingTalk憑證供應商，複製憑證供應商名稱。

2. 在專案下的deploy_starter/tools/ding_talk_tool.py檔案中，找到以下代碼：

   @requires_access_token(
       credential_provider_name="test-provider-for-dingtalk",
       scopes=["openid", "corpid"],
       auth_flow="USER_FEDERATION",
       on_auth_url= on_auth,
       # force_authentication=True,
       callback_url= f"{get_config_with_default('APP_REDIRECT_URI', 'http://localhost:8090')}/callback",
       inject_param_name="access_token",
   )

   將其替換為如下內容，其中credential_provider_name的值需要更新為您實際的DingTalk憑證供應商名稱：

   @requires_access_token(
       credential_provider_name="your-dingtalk-credential-provider-name",
       scopes=["openid", "corpid"],
       auth_flow="USER_FEDERATION",
       on_auth_url= on_auth,
       # force_authentication=True,
       callback_url= f"{get_config_with_default('APP_REDIRECT_URI', 'http://localhost:8090')}/callback",
       inject_param_name="access_token",
       custom_parameters={"prompt": "consent"},
   )