Use Agent Identity in AgentRun

Environment requirements

• Python: Version 3.10 or later

• pip: The package manager for Python

RAM user and permissions

You need a RAM user to run Agent Identity CLI commands to create a workload identity and its associated RAM role, and to automatically configure the required permissions. The RAM user who runs the CLI commands must have at least the following permissions:

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

OAuth 2.0 identity provider

You need an identity provider (IdP) that supports the OIDC/OAuth2 protocol to authenticate end users and issue a JWT token (also known as an ID Token). When you call the agent, pass the JWT token to complete inbound authentication for both AgentRun and Agent Identity. This tutorial uses Alibaba Cloud as the identity provider.

Create a large language model service

AgentRun manages model calls through a unified model proxy gateway. You need to create a large language model service for the agent to use.

1. Log on to the Function Compute console.

2. In the left-side navigation pane, choose Function Intelligence > AgentRun to go to the AgentRun console.

3. In the top navigation bar, choose Model Management, and then click Add Model.

4. Keep the default API Model option selected, and then select a model Service Provider (such as Alibaba Cloud) to configure a specific model.

   In the pop-up window, a Name is automatically generated. The API Endpoint defaults to https://dashscope.aliyuncs.com/compatible-mode/v1. If you leave it blank, the default endpoint is used.

5. In the Credential Configuration section, select API key. Enter the API key that you obtained from the model provider, such as a Model Studio API key.

   Next to the access key field, you can click the Get Model Studio API key link to get a key. The page indicates that the API key is used only for the current model and is not saved to Credential Management.

6. Click Create Model to finish. After the model is created, copy the model service name and save it for later use.

   The model service name (for example, model-BTAtkv) is displayed above the model card. You can click the copy icon next to it to copy the name.

Create an AgentRun inbound access credential

Use inbound credentials to verify the caller's identity. AgentRun supports multiple authentication methods. This tutorial uses JWT authentication.

1. On the AgentRun console, choose Others > Credential Management from the top navigation bar.

2. Keep the default Access AgentRun Credentials tab selected and click Create Access Credential.

3. On the Create Access Credential page, configure the following settings:

   • Credential Name: Enter a name to identify the credential, for example, aliyun.

   • Authentication Type: Select JWT (JSON Web Token).

   • JWKS Configuration Method: Select how to obtain the JWKS URL.

   • JWKS Endpoint URL: Enter the Alibaba Cloud JWKS endpoint URL https://oauth.aliyun.com/v1/keys.

   Timeout (seconds): Enter 30 (valid range: 1–30). Cache Time (seconds): Enter 3600 (valid range: 300–7,200). Select Enable after creation, and then click Create Credential.

4. Keep the other settings at their default values. Click Create Credential to create the access credential.

   In the credential management list, a JWT-type credential named aliyun appears, with its status as Enabled and 1 bound resource.

Install Agent Identity CLI

Install the Agent Identity CLI in your local environment (global installation).

pip install agent-identity-cli

Prepare RAM user credentials

In your local environment, configure credentials using the RAM user mentioned in the RAM user and permissions section.

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

Create a workload identity

Run the following command to create a workload identity and its associated RAM role:

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

The CLI automatically creates the following resources:

Configure Alibaba Cloud as the inbound IdP

You must associate the workload identity you created with an identity provider to complete inbound authentication with Agent Identity.

1. Log on to the Agent Identity console.

2. Follow the tutorial Configure Alibaba Cloud as an identity provider for Agent Identity to create an inbound identity provider. Set the callback URL to http://localhost:8090. After you finish, copy the Application ID and save it for later use.

3. In the left-side navigation pane, choose Workload Identity and find the workload identity that you created in the previous step.

4. Click Associate Identity Provider and select the inbound identity provider that you created.

5. Click OK to complete the configuration.

Get sample code

The sample code is based on the LangChain framework and integrates the Agent Identity SDK to enable secure access to third-party services. Open a terminal on your local machine and run the following command to clone the sample code.

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

zip -r agentrun-langchain_sample.zip .

Create and configure a DingTalk application

If you have not created and configured a DingTalk application, follow Step 1 in the Securely access DingTalk from an agent tutorial to create and configure it, and then set DingTalk as an OAuth 2.0 credential provider for Agent Identity.

Important: You must set the name of the DingTalk credential provider to test-provider-for-dingtalk to match the configuration in the agent sample project (located in agentrun-langchain_sample/ding_talk_tool.py).

Configure workload identity callback URL

To allow Agent Identity to obtain an OAuth access token from DingTalk for your agent, you need to configure an Application Callback URL for the workload identity you created.

1. Log on to the Agent Identity console.

2. Go to the authentication flow section of the Workload Identity details page and click Set Application Callback URL.

3. In the Set Application Callback URL dialog box, enter the URL http://localhost:8090/callback.

4. Click OK.

Configure the sample web application

1. In the project's root directory (agent-identity-dev-kit), run the following command to switch to the end-to-end sample directory:

   cd agent_identity_python_samples/end-to-end_sample

2. Install the dependencies required for the end-to-end sample (we recommend doing this in a Python virtual environment):

   pip install -r requirements.txt

3. Update the application/app.yml file in your project with the Application ID that you saved in the Configure Alibaba Cloud as the inbound identity provider for Agent Identity step, and the Agent public endpoint that you saved in the Create and configure an agent step:

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

Start the front-end and back-end applications

In the end-to-end_sample directory, run the following command:

python -m application.backend.app

Interact with the agent

1. After the agent and the front-end/back-end applications have started, enter the application URL http://localhost:8090 in your browser.

2. Complete the Alibaba Cloud login and user authorization. You can then interact with the model in the application's chat window. For example, enter: "Write the following content into my DingTalk document: {DingTalk document link or document ID} {content to write}".

   After you enter this prompt, the chat interface displays a message with an OAuth authorization link: Please click the link to authorize Write to DingTalk document. Click this link to grant the agent permission to write to the document.

   Note

   You need to obtain the link to the DingTalk document in advance. This sample application cannot create a new DingTalk document and write to it.

3. Click the OAuth authorization URL in the returned result and log in with the DingTalk document owner's account to grant authorization.

4. After authorization, if everything is configured correctly, the agent confirms that the document has been successfully written. Example:

   In the agent chat UI, the user provides a DingTalk document link and asks the agent to write content. The agent uses Agent Identity to generate an OAuth authorization link and prompts the user to click it. After authorization succeeds, the agent confirms that the content has been written to the target document.

5. Verify that the content has been written to the document.