智能體身分（Agent Identity）：在百鍊高代碼中使用Agent Identity

環境要求

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

RAM使用者及許可權要求

1. RAM使用者要求：

   您需要準備兩個RAM使用者，分別用於不同目的。

   1. 管理員：用於登入百鍊、Function Compute（FC）、Agent Identity及RAM控制台進行應用管理及許可權配置。

   2. 指令碼執行使用者：用於執行準備指令碼、本地應用測試以及將應用部署至百鍊高代碼平台。

2. RAM許可權要求：

   管理使用者至少需要具備以下許可權：

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "fc:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "ram:PassRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "acs:Service": [
               "fc.aliyuncs.com"
             ]
           }
         }
       },
       {
         "Effect": "Allow",
         "Action": "bailiancontrol:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "ram:ListUserBasicInfos",
           "ram:*Application*"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "ram:CreateRole",
           "ram:GetRole",
           "ram:ListRoles",
           "ram:AttachPolicyToRole",
           "ram:ListPolicyAttachments",
           "ram:ListPolicies",
           "ram:GetPolicy",
           "ram:ListUsers"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "openapiexplorer:*Mcp*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "agentidentity:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "log:Get*",
           "log:List*"
         ],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "log:Query*",
           "log:CallAiTools"
         ],
         "Resource": "*"
       }
     ]
   }

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

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "bailiandata:*",
           "sfm:*"
         ],
         "Resource": "*"
       },
       {
         "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",
           "ram:ListUserBasicInfos",
           "ram:ListRoles"
         ],
         "Resource": "*"
       }
     ]
   }

   上述許可權需要通過自訂權限原則授予對應的RAM使用者，操作步驟如下：

   1. 建立自訂權限原則。登入RAM控制台，在左側導覽列選擇許可權管理 > 權限原則，單擊建立權限原則，在指令碼編輯頁簽中將上述JSON內容填入策略文檔，然後單擊確定並輸入策略名稱稱完成建立。管理員和指令碼執行使用者要求的權限不同，需要分別建立兩個自訂權限原則。具體操作請參見建立自訂權限原則。

   2. 建立RAM使用者。在RAM控制台的左側導覽列選擇身份管理 > 使用者，分別建立管理員和指令碼執行使用者。在訪問方式地區，管理員選中控制台訪問，用於登入各控制台完成配置；指令碼執行使用者選中使用永久AccessKey訪問，用於配置阿里雲CLI及部署應用。具體操作請參見建立RAM使用者。

      說明

      AccessKey Secret僅在建立時顯示，請及時儲存指令碼執行使用者的AccessKey ID和AccessKey Secret。

   3. 為RAM使用者授權。在使用者頁面找到目標RAM使用者，單擊操作列的新增授權。在新增授權面板中，將資源範圍設定為帳號層級，選擇自訂策略並勾選上一步建立的權限原則，然後單擊確認新增授權。具體操作請參見管理RAM使用者的許可權。

3. 百鍊業務空間許可權要求：

   指令碼執行使用者需要先被添加為百鍊使用者，再為其授予部署要求的權限。操作步驟如下：

   1. 使用管理員使用者登入百鍊帳號管理頁面。

   2. 單擊新增使用者，選擇前文建立的指令碼執行使用者，完成添加。

   3. 在使用者列表中找到該使用者，單擊編輯許可權。本文樣本使用預設業務空間。

   4. 在編輯許可權彈窗中，進入頁面許可權步驟，至少勾選以下許可權，然後儲存配置。

      • API-KEY：用於擷取和管理業務空間的API Key。

      • 智能體-操作：用於部署和管理高代碼應用。

服務開通與授權

1. 確保您的阿里雲帳號已開通以下服務：

   • 大模型服務平台百鍊

   • Function Compute（FC）

2. 在百鍊控制台完成雲端服務授權。前往阿里雲百鍊-應用管理，點擊高代碼類型，並對相關雲端服務使用進行一鍵授權。

   確保Function ComputeFC、Object Storage Service、API Gateway三個服務在“已授權”狀態。

百鍊API密鑰

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

擷取並準備範例程式碼

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 # 本教程以華北2（北京）為樣本
   export DASHSCOPE_API_KEY=<YOUR-API-KEY> # DashScope API
   export MODELSTUDIO_WORKSPACE_ID=<YOUR-WORKSPACE-ID> # 可選，替換為百鍊的業務空間ID，該空間將部署高代碼應用，不設定將使用預設業務空間

準備RAM使用者憑證

在本地使用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檔案中。其中包含mcp_app_name，需要在後續使用到。

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

python -m clear

配置OpenAPI MCP服務

1. 導航到阿里雲OpenAPI 自訂MCP服務頁面，完成登入。

2. 在搜尋方塊中輸入"resourcecenter"，單擊搜尋結果中的"resourcecenter"系統服務。

3. 在OAuth配置地區，單擊修改。

4. 在彈出的修改OAuth配置對話方塊中，選擇自訂OAuth。單擊下拉式功能表，選擇準備指令碼所建立的MCP應用程式名稱。具體應用程式名稱應與專案根目錄下的.config.json檔案中的mcp_app_name欄位值匹配。單擊確認修改。

5. 在配置資訊地區，複製Streamable HTTP Endpoint地址，將其更新至專案deploy_starter/config.yml檔案中的MCP_SERVER欄位。

測試應用

1. 啟動Agent代理服務。在根目錄下執行以下命令：

   python -m deploy_starter.main

2. 啟動前後端應用。在根目錄下執行以下命令：

   python -m application.backend.app

3. 訪問應用並與代理互動：

   1. 等待代理及前後端應用啟動完畢後，在瀏覽器中輸入應用訪問地址http://localhost:8090。

   2. 完成阿里雲登入及使用者授權。之後，您可在應用交談視窗中與模型進行對話，例如輸入：“查詢我阿里雲帳號下的VPC配置資訊”。

   3. 單擊返回結果中的OAuth授權地址並完成授權。

      系統返回提示資訊，說明首次對話需要授權擷取MCP工具列表，並顯示阿里雲MCP服務的OAuth授權連結。

   4. 完成授權後，如果一切正常，將返回查詢結果。查詢結果顯示共有6個VPC執行個體分布在三個地區。以杭州地區（cn-hangzhou）為例，每個VPC條目包含VPC名稱、資源ID、資源群組ID、建立時間等欄位，部分條目還包含標籤資訊。

   說明

   更多與Agent互動的樣本，請參考代碼倉庫的README文檔。

打包本地代碼

1. 安裝打包及部署代碼所需依賴。在專案根目錄執行以下命令：

   pip install rich
   pip install alibabacloud-bailian20231229

2. 配置指令碼執行使用者的AccessKey。打包與部署命令通過AccessKey調用百鍊及Function Compute的API，請在執行打包和部署命令的終端中配置以下環境變數：

   export ALIBABA_CLOUD_ACCESS_KEY_ID=<YOUR-ACCESS-KEY-ID>
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<YOUR-ACCESS-KEY-SECRET>

   說明

   請使用RAM使用者及許可權要求中建立的指令碼執行使用者的AccessKey。

3. 打包Agent。在專案根目錄執行下面命令進行打包：

   python setup.py bdist_wheel

   打包成功後，將產生.whl檔案並儲存至專案下的dist目錄中。

部署Agent至百鍊

1. 在專案根目錄下執行以下命令，將打包出來的whl檔案部署到百鍊：

   runtime-fc-deploy --deploy-name agent-identity-sample  --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable

   執行結果類似如下：

   (.venv) xxx agentscope-sample % runtime-fc-deploy --deploy-name agent-identity-sample --whl-path ./dist/agentdev_starter_5ca90297-0.1.0-py3-none-any.whl --telemetry enable
     Built wheel at    /Users/xxx                          agentscope-sample/dist/agentdev_starter_5ca90297-0.1.0-py3-none-any.whl
     Resource Name     agent-identity-sample
                       Deploy Result
   Console URL: https://bailian.console.alibabacloud.com/?tab=app#/app-center
   Deploy ID: bf96fd32xxxxxxxxxxxxxxxxxxxxxxxx

   說明

   如您在部署過程中遇到了許可權相關報錯，請檢查RAM使用者及許可權要求中提到的RAM許可權及百鍊空間許可權是否有被授予指令碼執行使用者。

2. 部署成功後，稍等片刻，您可在阿里雲百鍊-應用管理中找到部署的Agent應用（狀態為發行）。

   在應用管理頁面選擇高代碼分類標籤，即可看到名為 agent-identity-sample 的應用，狀態顯示為綠點發行。

在Function Compute中修改函數啟動命令

高代碼應用部署到Function Compute後，需要將函數的啟動命令修改為範例程式碼的入口模組，否則函數無法正常啟動。

1. 在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用，進入應用詳情頁。

2. 在高代碼應用詳情頁，單擊基礎配置地區右側的查看詳情，進入高代碼應用所在的Function Compute函數詳情頁。

3. 在函數詳情頁，單擊配置頁簽，然後單擊基礎配置地區右側的編輯。

4. 將啟動命令修改為'python3 -m deploy_starter.main'，然後單擊部署。

在Function Compute中配置執行個體RAM角色

1. 登入RAM控制台，建立一個用於關聯到Function Compute執行個體的RAM角色，雲端服務主體選擇“Function Compute”。具體步驟請參見建立可信實體為阿里雲服務的RAM角色。

2. 在RAM控制台中為建立的RAM角色授予AliyunAgentIdentityDataFullAccess系統策略。

3. 在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用。在高代碼應用詳情頁，單擊基礎配置地區右側的查看詳情，進入高代碼應用所在Function Compute執行個體詳情頁。

4. 在Function Compute詳情頁，單擊配置頁簽。在配置頁簽下，單擊進階配置地區右側的編輯按鈕。

5. 在進階配置編輯頁，單擊許可權。在函數角色輸入框中搜尋並選擇剛建立的RAM角色。

6. 單擊部署。

在百鍊中配置環境變數

1. 在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用，進入應用詳情頁。

2. 在高代碼應用詳情頁，單擊環境變數地區右側的編輯按鈕。

3. 在末尾添加配置如下兩個環境變數，完成後單擊確定。

   • AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME：設定為專案根目錄.config.json中的workload_identity_name欄位值。

   • DASHSCOPE_API_KEY：設定為百鍊當前業務空間中的API Key。

4. 在彈出的儲存環境變數確認框中，單擊確認。

驗證部署情況

完成上述配置後，在高代碼應用詳情頁的調試地區，可以通過以下兩種方式驗證應用是否部署成功。

• API測試：選擇API測試頁簽，將Path設定為/health，然後單擊運行。返回成功響應說明應用已正常啟動。

• 文本對話體驗：選擇文本對話體驗頁簽，單擊立即體驗，與Agent進行對話，驗證應用能否正常響應。

在本地代碼中配置公網訪問地址和鑒權Token

1. 在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用。在高代碼應用詳情頁，複製觸發器地區下的公網訪問地址和鑒權token。

2. 將公網訪問地址和鑒權Token更新至專案下的application/app.yml檔案中（在代碼倉庫中的完整路徑為agent_identity_python_samples/end-to-end_sample/application/app.yml）：

   AGENT_BEARER_TOKEN: "<鑒權Token>"
   AGENT_ENDPOINT: "<公網地址>/process"

日誌查詢（可選）

您可在高代碼應用所在的Function Compute執行個體上查看請求日誌，以瞭解調用歷史及Agent的輸出資訊。

在函數詳情頁選擇日誌頁簽，通過調用請求列表可查看每次調用的請求 ID、調用狀態（如調用成功 200）、記憶體用量及執行時間。日誌本文中包含 MCP 工具註冊記錄（如 Registered 5 tool functions from ResourceCenter-20221201-SearchResources）以及 Agent 的 tool_use 調用詳情，展示 Agent 通過 ResourceCenter API 搜尋 OSS Bucket 資源的完整過程。