Agent connections

Create an Agent connection

Compute Nest Agents support connections to the following tools. Click a link in the table below to view the instructions for a specific connection type.

Bind to an Agent

You can bind an Agent to multiple types of connections simultaneously, such as a sandbox and session management. Each connection type injects a different set of environment variables. However, you can typically bind an Agent to only one connection of a given type. For example, you cannot bind an Agent to multiple session management connections at the same time.

Bind during Agent creation

On the Agent creation page, go to the Tool Configuration section and select the desired Agent connection under Application Connections. After the Agent is created, the system automatically binds the connection.

Bind to an existing Agent

1. Go to Application > Agent Management, select the desired Agent, and click Bind. In the dialog box that appears, select the connection that you want to bind.

   

2. Go to Release Management and publish the latest deployment artifact. To apply connection changes, you must restart the application.

Activation after binding

Compute Nest injects the connection information into the Agent's deployment environment (an ECS instance or a cluster) as environment variables. Your application can then access tools like the sandbox or session management by reading these variables, which eliminates the need to hardcode endpoints in your code. The guide for each tool details the specific environment variable names and their meanings.

Sandbox

AGENTRUN_TEMPLATE_ID: Template name
ALIBABA_CLOUD_ACCESS_KEY_ID: Access Key
ALIBABA_CLOUD_ACCESS_KEY_SECRET: Access Secret
AGENTRUN_ACCOUNT_ID: Your Alibaba Cloud account UID
AGENTRUN_REGION: The region where the AgentRun template is located

import os
account_id = os.getenv("AGENTRUN_ACCOUNT_ID")

Create a Redis instance

1. Log on to the Redis console to create a Redis instance.

2. After you create the Redis instance, add 0.0.0.0/0 to the whitelist and enable password-free access.

Create a session connection

1. Go to Agent Deployment > Session Management and click Create Session Connection. In the dialog box that appears, click Next.

2. Select the Redis Region and Redis Instance ID, and then click Create.

Environment variables

Creating a session connection sets the following environment variable on your machine:

SESSION_REDIS_URL: The private connection URL for the session management Redis instance, in the format redis://r-bp1b7cexxxxxxxx.redis.rds.aliyuncs.com:6379

You can read this value from the environment variable in your code to connect to session management. The following code provides a Python example:

import os
session_redis_url = os.getenv("SESSION_REDIS_URL")

Notes

Redis supports only private communication within a VPC. The server that runs the Agent must be in the same VPC as the Redis instance. Otherwise, the session connection cannot be established.

Create a knowledge base connection

1. Go to Agent Deployment > Memory and click Create Knowledge Base Connection. In the dialog box that appears, click Next.

2. On the edit page, enter a Connection Name, select the Model Studio Workspace ID and Model Studio Knowledge Base ID, and enter an AccessKey and AccessKey Secret. You can specify a custom connection name. You can obtain an AccessKey and AccessKey Secret in one of the following ways:

   1. Go to this link: https://ram.console.aliyun.com/profile/access-keys. Obtain the AccessKey ID and AccessKey Secret for your account, which grant full permissions to your account.

   2. Log on to the RAM console, create a user, and grant the AliyunAgentRunFullAccess permission to the user. You can then create an AccessKey pair for the user. For more information, see Create a RAM user and Manage the permissions of a RAM user.

Environment variables

BAILIAN_WORKSPACE_ID: Model Studio workspace ID
BAILIAN_INDEX_ID:  Model Studio knowledge base ID
BAILIAN_ALIBABA_CLOUD_ACCESS_KEY_ID: Alibaba Cloud AccessKey
BAILIAN_ALIBABA_CLOUD_ACCESS_KEY_SECRET: Alibaba Cloud AccessKey Secret
BAILIAN_REGION_ID:  The region of the Model Studio workspace

You can read these values from the environment variables in your code to connect to the knowledge base. The following code provides a Python example:

import os
bailian_workspace_id = os.getenv("BAILIAN_WORKSPACE_ID")
bailian_region_id = os.getenv("BAILIAN_REGION_ID")

Create a memory library connection

1. Go to Agent Deployment > Memory and click Create Memory Connection. In the dialog box that appears, click Next.

2. On the page that appears, specify the Memory Library ID and Memory Rule ID, and then click Create. If you leave these fields empty, a connection is created with the default memory library.

Environment variables

Creating a memory connection sets the following environment variables on your machine:

BAILIAN_MEMORY_LIBRARY_ID: The ID of the Model Studio memory library. If this is not configured, the default memory library is used. If configured, read and write operations are performed on the specified memory library.
BAILIAN_MEMORY_PROJECT_ID: The ID of the Model Studio memory rule. If this is not configured, the memory rules bound in the console are not enabled. If configured, memory is stored and retrieved based on the rules of this project.

You can read these values from the environment variables in your code to connect to the memory library. The following code provides a Python example:

import os
bailian_library_id = os.getenv("BAILIAN_MEMORY_LIBRARY_ID")
bailian_project_id = os.getenv("BAILIAN_MEMORY_PROJECT_ID")

MCP during Agent creation

1. On the creation page, go to the Tool Configuration section, turn on the Enable MCP switch, and select the desired MCP. If the MCP is not enabled, the page prompts you to enable it.

2. After you enable the service and confirm that the switch is on, proceed with creating the Agent as usual.

MCP for existing Agents

1. Go to Application > Agent Management > MCP and click Change MCP Configuration.

2. The change page is similar to the creation page. Select the desired MCP and click Change Configuration.

JSON file

The MCP configuration is ultimately stored as a JSON file in a specified path. The format of the JSON file is as follows:

{
  "mcpServers": {
    "market-cmapi011033": {
      "type": "streamableHttp",
      "baseUrl": "https://dashscope.aliyuncs.com/api/v1/mcps/market-cmapi011033/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    },
    "amap-maps": {
      "type": "sse",
      "baseUrl": "https://dashscope.aliyuncs.com/api/v1/mcps/amap-maps/sse",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

1. ECS deployment: If you deploy the Agent on an ECS instance, the content of this JSON file overwrites the file in the specified directory.

2. Cluster deployment: If you deploy the Agent in a cluster, the content of this JSON file is stored as an environment variable in the app-config configuration item. The key is MCP_JSON and the value is the content of the JSON file.