Identidade do Agente (Agent Identity):Use Agent Identity in Model Studio (Bailian) high-code

Requisitos de ambiente

O ambiente de teste local requer Python (versão 3.10 ou posterior) e o gerenciador de pacotes pip.

Requisitos de usuários e permissões do RAM

1. Requisitos de usuários RAM:

   São necessários dois usuários RAM para finalidades diferentes.

   1. Administrador: faz login nos consoles do Model Studio (Bailian), Function Compute (FC), Agent Identity e RAM para gerenciar aplicativos e configurar permissões.

   2. Usuário de execução de script: executa scripts de preparação, testa o aplicativo localmente e implanta o aplicativo na plataforma Model Studio (Bailian) high-code.

2. Requisitos de permissões RAM:

   O administrador precisa ter, no mínimo, as seguintes permissões:

   {
     "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": "*"
       }
     ]
   }

   O usuário de execução de script requer as seguintes permissões:

   {
     "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": "*"
       }
     ]
   }

3. Requisitos de permissão do workspace do Model Studio (Bailian):

   Conceda a permissão Component Management_Agent_Operation ao usuário de execução de script para o workspace de destino na Página de gerenciamento de contas do Model Studio (Bailian).

   Na caixa de diálogo Edit Permissions, acesse a etapa Page Permissions, selecione a aba Application e escolha a permissão desejada.

Ativação e autorização de services

1. Verifique se os seguintes services estão ativados para sua conta Alibaba Cloud:

   • Model Studio (Bailian)

   • Function Compute (FC)

2. Autorize os services de nuvem no console do Model Studio (Bailian). Acesse Alibaba Cloud Model Studio (Bailian) - App Management, clique em no tipo high-code e conceda autorização com um clique para os services de nuvem relacionados.

   Certifique-se de que o Function Compute (FC), o Object Storage Service (OSS) e o API Gateway estejam com o status Authorized.

Chave de API do DashScope

Obtenha uma chave de API do DashScope com permissão para chamar modelos do Model Studio (Bailian). Caso ainda não possua uma, consulte Obter chave de API para criá-la.

Obter e preparar o código de exemplo

1. Clone o repositório de código. Abra um terminal na máquina local e execute os comandos a seguir.

   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. Instale as dependências. Recomendamos criar e ativar um ambiente virtual Python antes de instalar as dependências.

   pip install -r requirements.txt

3. Configure as variáveis de ambiente.

   export AGENT_IDENTITY_REGION_ID=cn-beijing # Agent Identity is currently available only in the China (Beijing) region.
   export DASHSCOPE_API_KEY=<your-api-key> # DashScope API
   export MODELSTUDIO_WORKSPACE_ID=<your-workspace-id> # Optional. Replace with the Model Studio (Bailian) workspace ID where the high-code application will be deployed. If not set, the default workspace is used.

Preparar credenciais de usuário RAM

Configure as credenciais locais usando o usuário de execução de script definido em Requisitos de usuários e permissões do RAM.

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

Executar o script de preparação

No diretório raiz do projeto, execute o script prepare.py para criar os recursos de nuvem necessários:

python -m prepare

Este script executa as seguintes ações:

1. Cria um provedor de identidade

2. Cria um aplicativo de entrada OAuth 2.1 da Alibaba Cloud

3. Cria um aplicativo nativo OAuth 2.1 necessário pelo service MCP da Alibaba Cloud

4. Cria uma identidade de carga de trabalho e uma função

5. Configura um provedor de credenciais

O script salva os detalhes dos recursos criados no arquivo .config.json no diretório raiz, incluindo o campo mcp_app_name necessário em uma etapa posterior.

Se o script falhar devido a problemas de rede ou cota de recursos excedida, limpe os recursos criados antes de tentar novamente:

python -m clear

Configurar o service OpenAPI MCP

1. Acesse a página Alibaba Cloud OpenAPI Custom MCP Service e faça login.

2. Na caixa de pesquisa, insira "resourcecenter" e clique em no service de sistema "resourcecenter" nos resultados da busca.

3. Na área OAuth Configuration, clique em Modify.

4. Na caixa de diálogo Modify OAuth Configuration, selecione Custom OAuth. No menu suspenso, selecione o nome do aplicativo MCP criado pelo script de preparação. O nome do aplicativo deve corresponder ao valor do campo mcp_app_name no arquivo .config.json localizado no diretório raiz do projeto. Clique em Confirm Change.

5. Na área Configuration Information, copie o endereço Streamable HTTP Endpoint e atualize o campo MCP_SERVER no arquivo deploy_starter/config.yml.

Testar o aplicativo

1. Inicie o service de proxy do agente. Execute o seguinte comando no diretório raiz:

   python -m deploy_starter.main

2. Inicie os aplicativos de frontend e backend. Execute o seguinte comando no diretório raiz:

   python -m application.backend.app

3. Acesse o aplicativo e interaja com o agente:

   1. Após iniciar o proxy do agente e os aplicativos, abra http://localhost:8090 no navegador.

   2. Conclua o login na Alibaba Cloud e a autorização do usuário. Em seguida, interaja com o modelo na janela de chat do aplicativo. Por exemplo, insira: "Consultar minhas informações de configuração de VPC na minha conta Alibaba Cloud."

   3. Clique em na URL de autorização OAuth na resposta e conclua a autorização.

      O sistema retorna uma mensagem indicando que a primeira conversa requer autorização para obter a lista de ferramentas MCP e fornece um link de autorização OAuth para o Alibaba Cloud MCP Service.

   4. Após a autorização, a consulta retorna uma lista de seis instâncias de Virtual Private Cloud (VPC) distribuídas em três regiões. Por exemplo, na região China (Hangzhou) (cn-hangzhou), cada entrada de VPC inclui campos como VPC Name, Resource ID, Resource Group ID e Creation Time. Algumas entradas também incluem informações de tag.

   Nota

   Para mais exemplos de interação com o agente, consulte o documento README no repositório de código.

Empacotar o código local

1. Instale as dependências para empacotamento e implantação. Execute os seguintes comandos no diretório raiz do projeto:

   pip install rich
   pip install alibabacloud-bailian20231229

2. Empacote o agente. Execute o seguinte comando no diretório raiz do projeto:

   python setup.py bdist_wheel

   Após o empacotamento bem-sucedido, um arquivo .whl será gerado no diretório dist do projeto.

Implantar o agente no Model Studio (Bailian)

1. Execute o seguinte comando no diretório raiz do projeto para implantar o arquivo .whl empacotado no Model Studio (Bailian):

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

   A saída deve ser semelhante à seguinte:

   (.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

   Nota

   Se ocorrerem erros relacionados a permissões durante a implantação, verifique se o usuário de execução de script possui as permissões RAM e as permissões de workspace do Model Studio (Bailian) necessárias, conforme descrito em Requisitos de usuários e permissões do RAM.

2. Após uma implantação bem-sucedida, aguarde alguns instantes. O aplicativo de agente implantado aparecerá com o status Published em Alibaba Cloud Model Studio (Bailian) - App Management.

   Na página App Management, selecione a aba da categoria high-code. Um aplicativo chamado agent-identity-sample aparecerá com um ponto verde indicando o status Published.

Configurar variáveis de ambiente no Model Studio (Bailian)

1. Em Alibaba Cloud Model Studio (Bailian) - App Management, localize e clique em no aplicativo de agente implantado para abrir sua página de detalhes.

2. Na página de detalhes do aplicativo high-code, clique em no botão de edição à direita da área Environment Variables.

3. Adicione as duas variáveis de ambiente a seguir e clique em OK.

   • AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME: defina este valor como o conteúdo do campo workload_identity_name encontrado no arquivo .config.json no diretório raiz do projeto.

   • DASHSCOPE_API_KEY: defina este valor como a chave de API do DashScope do workspace atual no Model Studio (Bailian).

4. Na caixa de diálogo de confirmação Save Environment Variables, clique em Confirm.

Configurar a função RAM da instância no Function Compute

1. Faça login no console do RAM e crie uma função RAM para associar à instância do Function Compute. Como entidade de service de nuvem, selecione Function Compute. Para etapas detalhadas, consulte Criar uma função RAM para um service confiável da Alibaba Cloud.

2. No console do RAM, conceda a política de sistema AliyunAgentIdentityDataFullAccess à função RAM recém-criada.

3. Em Alibaba Cloud Model Studio (Bailian) - App Management, localize e clique em no aplicativo de agente implantado. Na página de detalhes do aplicativo high-code, clique em View Details à direita da área Basic Configurations para visualizar os detalhes da instância do Function Compute que hospeda o aplicativo.

4. Na página de detalhes do Function Compute, clique em na aba Configuration. Em seguida, clique em Configuration no lado direito da seção Edit.

5. Na página de edição de configurações avançadas, clique em Advanced Configurations. Na caixa de entrada Permissions, pesquise e selecione a função RAM criada anteriormente.

6. Clique em function role.

Configurar o endpoint público e o token de autenticação no código local

1. Em Alibaba Cloud Model Studio (Bailian) - App Management, localize e clique em no aplicativo de agente implantado. Na página de detalhes do aplicativo high-code, copie o endpoint público e o token de autenticação da área Deploy.

2. Atualize o arquivo deploy_starter/config.yml com o endpoint público e o token de autenticação:

   AGENT_BEARER_TOKEN: "<authentication-token>"
   AGENT_ENDPOINT: "<public-endpoint>/process"

Consultar logs (opcional)

Visualize os logs de solicitação na instância do Function Compute para revisar o histórico de chamadas e a saída do agente.

Na página de detalhes da função, selecione a aba Logs. A lista Invocation Requests mostra o ID da solicitação, o status da invocação (por exemplo, 200 para sucesso), o uso de memória e o tempo de execução. As entradas de log incluem registros de registro de ferramentas MCP, como Registered 5 tool functions from ResourceCenter-20221201-SearchResources, e detalhes de chamada tool_use mostrando consultas de recursos do agente por meio da API ResourceCenter.