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

通過百鍊高代碼平台，可以快速地開發、部署高度自訂的 AI Agent。通過將Agent Identity與百鍊高代碼平台整合，可以使使用者安全可控地訪問Agent，同時令Agent安全可控地訪問資源。本教程示範如何在百鍊高代碼應用中整合Agent Identity，實現智能體（Agent）在執行敏感操作（如訪問雲資源）前，必須先獲得使用者即時授權，從而安全、可控地訪問雲端服務。

架構

diagram_agentidentity_bailian1

準備工作

環境要求

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

RAM使用者及許可權要求

RAM使用者要求：
您需要準備兩個RAM使用者，分別用於不同目的。
1. 管理員：用於登入百鍊、Function Compute（FC）、Agent Identity及RAM控制台進行應用管理及許可權配置。
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": "*"
    }
  ]
}

百鍊業務空間許可權要求：
為指令碼執行使用者在百鍊帳號管理頁面添加特定業務空間的組件管理_智能體_操作許可權。
在編輯許可權彈窗中，進入頁面許可權步驟，選擇應用頁簽，勾選目標許可權即可。

服務開通與授權

確保您的阿里雲帳號已開通以下服務：
- 大模型服務平台百鍊
- Function Compute（FC）
在百鍊控制台完成雲端服務授權。前往阿里雲百鍊-應用管理，點擊高代碼類型，並對相關雲端服務使用進行一鍵授權。
確保Function ComputeFC、Object Storage Service、API Gateway三個服務在“已授權”狀態。

百鍊API密鑰

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

步驟一：本地安裝與測試應用

擷取並準備範例程式碼

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

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

安裝依賴。建議建立並啟用一個 Python 虛擬環境，然後安裝專案所需的依賴。
```
pip install -r requirements.txt
```

配置環境變數。

export AGENT_IDENTITY_REGION_ID=cn-beijing # 當前Agent Identity僅開放北京地區
export DASHSCOPE_API_KEY=<your-api-key> # DashScope API
export MODELSTUDIO_WORKSPACE_ID=<your-workspace-id> # 可選，替換為百鍊的業務空間ID，該空間將部署高代碼應用，不設定將使用預設業務空間

準備RAM使用者憑證

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

使用阿里雲CLI

安裝阿里雲CLI（如已安裝，可跳過）。具體請參考快速使用 CLI。
登入阿里雲CLI。具體請參考為阿里雲CLI配置OAuth認證。

檢查憑證配置。執行命令aliyun configure list檢查憑證配置是否存在且有效。輸出類似如下：

Profile        | Credential          | Valid   | Region           | Language
---------      | ------------------  | ------- | ---------------- | --------
OAuthProfile * | OAuth:xQcliVOdYA@CN | Valid   | cn-hangzhou      | zh

使用Access Key（不推薦）

為指令碼執行使用者建立存取金鑰（Access Key）並配置到本地環境變數中。

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

此指令碼執行以下操作：

建立身份提供者
建立阿里雲OAuth 2.1入站應用
建立阿里雲MCP服務所需的OAuth 2.1 Native應用
建立工作負載身份和角色
配置憑證提供者

指令碼會輸出建立的資源資訊到根目錄下的.config.json檔案中。其中包含mcp_app_name，需要在後續使用到。

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

python -m clear

說明

為避免對帳號下的RAM資源造成影響，清理邏輯不會刪除角色/自訂策略，需要手動刪除。

配置OpenAPI MCP服務

導航到阿里雲OpenAPI 自訂MCP服務頁面，完成登入。
在搜尋方塊中輸入"resourcecenter"，單擊搜尋結果中的"resourcecenter"系統服務。
在OAuth配置地區，單擊修改。
在彈出的修改OAuth配置對話方塊中，選擇自訂OAuth。單擊下拉式功能表，選擇準備指令碼所建立的MCP應用程式名稱。具體應用程式名稱應與專案根目錄下的.config.json檔案中的mcp_app_name欄位值匹配。單擊確認修改。
在配置資訊地區，複製Streamable HTTP Endpoint地址，將其更新至專案deploy_starter/config.yml檔案中的MCP_SERVER欄位。

測試應用

啟動Agent代理服務。在根目錄下執行以下命令：
```
python -m deploy_starter.main
```
啟動前後端應用。在根目錄下執行以下命令：
```
python -m application.backend.app
```
訪問應用並與代理互動：
1. 等待代理及前後端應用啟動完畢後，在瀏覽器中輸入應用訪問地址http://localhost:8090。
2. 完成阿里雲登入及使用者授權。之後，您可在應用交談視窗中與模型進行對話，例如輸入：“查詢我阿里雲帳號下的VPC配置資訊”。
3. 單擊返回結果中的OAuth授權地址並完成授權。
  系統返回提示資訊，說明首次對話需要授權擷取MCP工具列表，並顯示阿里雲MCP服務的OAuth授權連結。
4. 完成授權後，如果一切正常，將返回查詢結果。查詢結果顯示共有6個VPC執行個體分布在三個地區。以杭州地區（cn-hangzhou）為例，每個VPC條目包含VPC名稱、資源ID、資源群組ID、建立時間等欄位，部分條目還包含標籤資訊。
說明
更多與Agent互動的樣本，請參考代碼倉庫的README文檔。

步驟二：打包並部署Agent至百鍊高代碼

打包本地代碼

安裝打包及部署代碼所需依賴。在專案根目錄執行以下命令：
```
pip install rich
pip install alibabacloud-bailian20231229
```
打包Agent。在專案根目錄執行下面命令進行打包：
```
python setup.py bdist_wheel
```
打包成功後，將產生.whl檔案並儲存至專案下的dist目錄中。

部署Agent至百鍊

在專案根目錄下執行以下命令，將打包出來的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://modelstudio.console.alibabacloud.com/?tab=app#/app-center
Deploy ID: bf96fd3202e24e64989442f7aaae57b1

說明

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

部署成功後，稍等片刻，您可在阿里雲百鍊-應用管理中找到部署的Agent應用（狀態為發行）。
在應用管理頁面選擇高代碼分類標籤，即可看到名為 agent-identity-sample 的應用，狀態顯示為綠點發行。

步驟三：配置百鍊高代碼應用

在百鍊中配置環境變數

在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用，進入應用詳情頁。
在高代碼應用詳情頁，單擊環境變數地區右側的編輯按鈕。
在末尾添加配置如下兩個環境變數，完成後單擊確定。
- AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME：設定為專案根目錄.config.json中的workload_identity_name欄位值。
- DASHSCOPE_API_KEY：設定為百鍊當前業務空間中的API Key。
在彈出的儲存環境變數確認框中，單擊確認。

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

登入RAM控制台，建立一個用於關聯到Function Compute執行個體的RAM角色，雲端服務主體選擇“Function Compute”。具體步驟請參見建立可信實體為阿里雲服務的RAM角色。
在RAM控制台中為建立的RAM角色授予AliyunAgentIdentityDataFullAccess系統策略。
在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用。在高代碼應用詳情頁，單擊基礎配置地區右側的查看詳情，進入高代碼應用所在Function Compute執行個體詳情頁。
在Function Compute詳情頁，單擊配置頁簽。在配置頁簽下，單擊進階配置地區右側的編輯按鈕。
在進階配置編輯頁，單擊許可權。在函數角色輸入框中搜尋並選擇剛建立的RAM角色。
單擊部署。

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

在阿里雲百鍊-應用管理中找到並單擊部署的Agent應用。在高代碼應用詳情頁，複製觸發器地區下的公網訪問地址和鑒權token。
將公網訪問地址和鑒權Token更新至專案下的deploy_starter/config.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 資源的完整過程。

注意事項

如您希望再次執行準備指令碼prepare.py，請先在專案根目錄下執行清理指令碼以清理資源：
```
python -m clear
```
專案準備指令碼prepare.py下的常量配置資訊不可更改，否則會導致應用無法正常工作。
如果您希望將前後端應用部署至阿里雲（如ECS樣本），需要為後端應用所在的環境關聯執行個體RAM角色（如ECS執行個體角色、Function Compute執行個體角色），並授予AliyunAgentIdentityDataCompleteAuthAccess系統策略。否則Agent將無法獲得OAuth Access Token。