AgentCore Quick Start
AgentCoresupports unified access to multiple model providers and runs Agents in a managed manner. Multiple Agents can form a Team, in which the Leader organizes the division of work and Workers perform specific tasks. This topic describes the complete workflow from model connection to confirming that Agents are online in a Team conversation, including creating a model connection, creating two Agents, creating a user, enabling the collaboration control plane, creating a Team, and sending the first message.
Workflow overview
Step | Operation | Output |
Preparation | Activate and authorize AgentCore and create a Workspace | A Workspace in the Running state |
Step 1 | Create and debug a model connection | An available model connection and its models |
Step 2 | Create two Agents | One Agent as the Leader and one Agent as the Worker |
Step 3 | Create a user | A local account user for signing in to the collaboration client |
Step 4 | Enable the collaboration control plane | The Collaboration Client (WEB) and Collaboration Client (API) endpoints are both Running |
Step 5 | Create a Team | An Agent team with a Leader and a Worker |
Step 6 | Send a message in the Team group chat to confirm that the Agents are online | Both Agents reply |
After completion | Clean up resources | No residual resources that incur ongoing charges |
Enabling the collaboration control plane is an asynchronous process. To reduce the waiting time, submit the enable request in Step 4 after you complete Step 1, then return to Step 2 and Step 3 to continue the configuration, and finally confirm that the endpoints are ready before you create the Team.
Prerequisites
You have registered an Alibaba Cloud account and completed real-name verification.
You have activated AgentCore and the required products.
To use AgentCore, you must activate other Alibaba Cloud products as dependencies. These products are billed independently based on their own billing rules. For more information, seeAgentCore Overview.
You have completed account authorization.
Authorization requires different handling for the primary account and sub-accounts. Primary account users can follow the console authorization instructions, while sub-account users need an administrator to adjust RAM permissions. For more information, seeAuthorize a sub-account to use the AgentCore console through RAM.
You have created a Workspace: Click the drop-down list in the upper-left corner of the page, click Create Workspace in the menu that appears, configure the Workspace name, select whether to bind a VPC as needed, select a storage mode in the storage configuration section, and click Create.
Parameter | Description |
Bind VPC | Whether to configure private network resources for the Workspace. When the switch is off, the following parameters are not displayed. When the switch is on, you must complete the VPC and vSwitch configuration. |
VPC | Required. Select the VPC to use for the Workspace. |
vSwitch | Required. Available after you select a VPC. Select at least two vSwitches and make sure that they cover at least two different zones. |
Storage Mode | Platform Storage (default; uses an OSS bucket under the AgentCore platform account) or Private Storage (uses an OSS bucket under the current Alibaba Cloud account). In both modes, the storage space and its contents are created and managed automatically by AgentCore. |
AgentLoop | (Optional) Associate an AgentSpace from AgentLoop. After an AgentSpace is created, you can bind it to a CloudMonitor 2.0 workspace. You can create one automatically or select an existing one. |
After the Workspace is created, confirm that you are in the target Workspace and that the Workspace status is Running. The model connections, Agents, users, and Teams created later belong to this Workspace.
You have obtained the API Key of the model provider. For example, for Alibaba Cloud Model Studio, create and save an API Key on the API Key management page of the Model Studio console.
Do not modify or delete the files in the bucket that is created automatically for the Workspace storage configuration, and we recommend that you do not change the bucket configuration. Otherwise, the Workspace and related features may not work properly.
Step 1: Create and debug a model connection
Agents depend on model configurations to run. A model connection connects to a model provider and centrally maintains its credentials and model list. You can create multiple connections for the same provider by business or environment, and use, manage, and monitor them separately. A connection can include multiple models.
Log on to the AgentCore console and go to the target Workspace.
In the left-side navigation pane, under the Asset Management group, click Model Connections. The page title is Model Management, and the page has two tabs at the top: Model List and Model Connections. The number after each tab is the number of objects on that tab.
On the Model Connections tab, click Add Model in the upper-right corner to go to the Add Model Connection page.
In the Basic Information section, configure the following parameters.
Parameter
Description
Model Provider
Required. Select a preset model provider (such as Alibaba Cloud Model Studio) or a custom model provider. If you use Alibaba Cloud Coding Plan, switch to a custom model provider, select OpenAI-compatible, and then enter the corresponding model service configuration.
Model Connection Name
Required. Enter a name for the model connection.
API Endpoint
Required. Enter an API endpoint that complies with the OpenAI specification.
Access Credentials
Required. Select Enter API Key Manually and enter the key. The key is stored in encrypted form. Click Add Credential to add multiple credentials for rotation. If you use Alibaba Cloud Model Studio, click Get Model Studio API Key to go to the Model Studio console and create an API Key.
Description
(Optional) A description of the model connection's purpose. Maximum length: 255 characters.
In the Model Configuration section, select the models to connect. This topic uses qwen3.8-flash as an example. The list shows the large language models available in the provider catalog. Each row shows the model name, context length, and capability tags (such as tool calling, multi-tool calling, streaming tool calling, vision, video, and reasoning). You can filter by model name in the search box. The table header shows the number of selected models.
Click OK in the upper-right corner to create the model connection.
Verify that the connection is available: Return to the Model Connections tab, move the pointer over the target connection card, click Debug, enter some test content, and send it. A normal status and a model reply indicate that the connection and credentials are configured correctly.
Expected result: The connection card appears on the Model Connections tab with the status Available. The card shows the provider, creation time, API endpoint, connected models, and description. These models are visible on the Model List tab. When you hover over the connection card, three actions are available: Details, Debug, and Delete.
API Keys are access credentials. Store them securely. Do not paste them into Agent conversations, shared documents, or code repositories.
Step 2: Create two Agents
This topic creates two Agents: one acts as the Team Leader, organizing the division of work and aggregating results; the other acts as a Worker, performing specific work. Both Agents are created in managed Harness mode.
Agents created from custom code or images do not support joining a Team for now. If you need to form a Team later, create the Agents in managed Harness mode.
In the left-side navigation pane, click Agent.
Click Create Agent.
Select a creation method: Managed Harness.
Configure the basic information.
Parameter
Description
Harness
Required. Select a managed Harness from the drop-down list. Each option includes a capability description, for example, Qwen Paw (a general-purpose AI assistant that excels at knowledge Q&A, document processing, and scheduled reports).
Agent Template
Specify whether to use a template to configure the Agent. By default, no template is used (you configure the Agent manually). If you do not use a template, you only need to enter a system prompt and do not need to prepare SOUL.md or AGENTS.md.
Agent Name
Required. Enter an Agent name.
Model Connection
Required. Select the model connection created in Step 1. The drop-down list shows “Connection name (provider)”. You can click the plus sign on the right to create a model connection.
Model
Required. Select a model connected under this connection. This topic uses qwen3.8-flash as an example.
Reasoning Effort
Select the reasoning effort of the model from the drop-down list. Default value: default.
Token Quota
Turn on the Enable Token Quota switch. After the switch is turned on, enter the quota limit and select a metering period (day, week, or month).
Description
(Optional) A description of the Agent's purpose. Maximum length: 255 characters.
In File Configuration, enter the system prompt of the Agent to describe its role, responsibilities, and working method.
The Leader's system prompt must describe the business responsibilities, members and division of work, mapping between requirements and tasks, assignment approach, and delivery requirements.
The Worker's system prompt only needs to define the business processing capabilities. Do not repeat built-in collaboration rules such as team scheduling, status feedback, and result submission.
System prompts support prompt variables. Click Prompt Variables (N) in the upper-right corner of the system prompt to open the dialog box, click Add Variable, and enter the variable name, description, and default value. Reference the variable in the body as
{variable_name}. A variable name must start with a letter or underscore and contain only letters, digits, and underscores.
This topic does not configure Skills or bind other assets. The create page provides six types of assets as tabs: Skill, SubAgent, Tool, Knowledge Base, Memory, and Credential. You can add them as needed after you complete this workflow.
Configure the Resource Configuration settings.
Parameter
Description
Specification
Required. Select the CPU and memory specifications for the instance.
Maximum Sessions per Instance
Required. Set the maximum number of Sessions that a single instance can host. Valid values: 1–20.
Session TTL (seconds)
Required. Set the lifetime of platform Sessions. Valid values: 60–86400. This is not the timeout for a single model generation.
Minimum Instances
Required. Valid values: 0–100.
Maximum Instances
Required. Valid values: 0–100.
Configure the Network Configuration settings.
Parameter
Description
Allow Internet Access Through the Default ENI
Turn on as needed when the Agent needs to access public model services or other public endpoints.
Allow VPC Access
Turn on as needed when the Agent needs to access VPC resources of the Workspace. After the switch is turned on, the VPC configuration of the current Workspace is used. If the Workspace is not bound to a VPC, the page prompts you to bind a VPC first.
Click Create Now.
Repeat steps 1–9 to create the second Agent in the same way. This Agent acts as a Worker in the Team.
Expected result: Both Agents in the Agent list have the status Normal. Click Details to view Agent information, or Edit Configuration to modify the configuration.
Step 3: Create a user
A user is a sign-in identity in the collaboration client and is different from an Alibaba Cloud account. The Team Admin and team members of a Team must be created users.
In the left-side navigation pane, under the Identity and Permissions group, click User Management.
Click Create User.
Configure the following parameters.
Parameter
Description
Username
Enter the user name to identify and distinguish users.
Display Name
The user name that is displayed externally.
Email
The email address of the user.
Authentication Method
Only local accounts are supported.
Password
You can generate a password automatically or set a custom password. For a custom password, follow the on-page requirements: 8–32 characters; the password must contain lowercase letters, uppercase letters, digits, and special characters and cannot contain the user name.
Click Create Now.
Expected result: The user appears in the User Management list. The authentication method is Local Account, and the status is Active.
Set and securely store the sign-in password yourself. You do not need to tell the Agent in the conversation.
Step 4: Enable the collaboration control plane
Team collaboration depends on a collaboration control plane instance. If the collaboration control plane is not enabled, the Team Collaboration page shows that collaboration is not enabled.
In the left-side navigation pane, under the Agent Collaboration group, click Team Collaboration.
If the page shows that collaboration is not enabled, click Enable Now, and then click Enable in the confirmation dialog box that appears.
Configure the network access mode of the collaboration service.
Parameter
Description
Public Access
Turn on or off with the switch. After it is turned on, the collaboration client can be accessed through a public endpoint.
VPC Access
Turn on or off with the switch. After it is turned on, the collaboration client can be accessed through a VPC internal endpoint. After you turn it on, select a VPC and vSwitches. Select vSwitches in at least two different zones to ensure high availability of the collaboration service.
Enable at least one of Public Access and VPC Access. If the Workspace is not bound to a valid VPC, you must enable Public Access.
Click Enable. The system redirects you to the purchase page. Create a collaboration control plane instance as prompted. Collaboration control plane instances are billed at the pricing of the corresponding product.
Wait for the process to complete. The page shows that the collaboration control plane is being created, which takes about 3–5 minutes. The process runs asynchronously in the background. You can continue with Step 2 and Step 3 in the meantime. Do not submit the request again.
Go back to Team Collaboration → Access Management → Connection Points and confirm that Collaboration Client (WEB) and Collaboration Client (API) are both in the Running state.
Expected result: The Connection Points page shows the public and private endpoints of Collaboration Client (WEB) (a web console endpoint that provides a visual interface) and Collaboration Client (API) (an API access endpoint that provides programmatic access), and the status is Running.
Step 5: Create a Team
Confirm that Step 4 is complete and that the Collaboration Client (WEB) connection point is Running.
In the left-side navigation pane, under the Agent Collaboration group, click Team Collaboration, and then switch to Team Management.
Click Create Agent Team.
In the 1. Basic Information section, configure the following parameters, and then click Next.
Parameter
Description
Team Name
The name of the Agent team.
Team Admin
The administrator of the Agent team (a human user). Select the user created in Step 3. The Team Admin can maintain team information, add or remove team members and team Agents, and change the Team Leader.
Team Members
(Optional) Add members (human users) to the Agent team.
Description
(Optional) A description of the Agent team's purpose.
In the 2. Team Leader Configuration section, configure the following parameters, and then click Next.
Parameter
Description
Leader Source
Valid values: Select Existing Agent or Create Leader Agent.
Agent
Select the Agent to act as the Leader, that is, the first Agent created in Step 2. The selected Agent is responsible for task breakdown and assignment and does not appear again as a team member.
In the 3. Team Agent Configuration section, select the Agent to add to the Team from Available Agents (that is, the second Agent created in Step 2). After you select it, the Agent is displayed in Added Agents. The Leader does not need to be added again in this step.
Click Create Now.
Expected result: The team appears in the team list with the status Normal, the Agent count is 2, and the Team Admin and Leader Agent match the configuration. Click Details to view team information, Edit to modify it, or Delete to delete the team.
The following Agents cannot join a team. The console displays a message on the corresponding Agent. Click View Details to learn the reason:
Agents created from custom code or images do not support joining a team for now.
Agents that are already the Leader of another team.
Agents that already belong to another team. The console also displays the name of the team they belong to.
If a message indicates that the Agent's team ownership cannot be determined at the moment, refresh the page and select the Agent again.
Step 6: Send a message in a team conversation
In the left-side navigation pane, under the Agent Collaboration group, click Team Collaboration, and then go to Connection Points in Access Management.
Find Collaboration Client (WEB), confirm that its status is Running, and click Open to enter AgentCore App.
On the sign-in page, click Continue with password, enter the username and password of the user created in Step 3, and click Sign in.
When an authorization request appears on the first sign-in, verify that the application corresponds to the current Workspace, confirm the OpenID Connect authentication request, and click Allow to return to the client.
Go to Chat and select the target conversation.
Conversation
Description
Team: <team name>Team group chat. All Agents in the team are included. This conversation is suitable for organizing a multi-Agent discussion around the same deliverable.
Leader DM: <team name>Direct message with the Leader. This conversation is suitable for discussing requirements and clarifying goals first, and then letting the Leader organize execution.
Select the
Team: <team name>group chat and send a message to confirm that both Agents are online. Click @ below the input box, select the two Agents from the member list in sequence, enter the requirement in the input box (for example, “Reply with one sentence each to confirm that you are online.”), and click Send.
Expected result: Replies from both Agents appear in the conversation, which indicates that the Team is created and both Agents can respond properly. If an Agent does not reply for a long time, return to the console and confirm that the Agent status is Normal and the model connection status is Available.
Clean up resources
The Team, Agents, collaboration control plane, and Workspace created in this topic incur ongoing charges. If you no longer use them, release them in the following order: save the required deliverable files → delete the Team → delete the two Agents → disable collaboration → delete the models and model connection → delete the user → delete the Workspace.
Closing the browser or leaving the chat does not complete the cleanup. You must perform the operations in the console.
CMS (CloudMonitor), PrivateLink, and SchedulerX3, which are enabled together with the service, continue to incur charges after the Workspace is deleted. If you no longer use them, handle them separately in the console of each product.
Next steps
Goal | You can continue with |
Assign a clear work goal to the team and review the results | |
Work with a clear goal that a single Agent can complete | Use a single Worker in a Team |
Learn how Leaders and Workers collaborate and how to write instructions | |
Team work triggered automatically on a schedule | |
Extend an Agent with external tool capabilities | |
Let an Agent consult its own business materials | Connect an Alibaba Cloud Model Studio Knowledge Base in AgentCore |
Chat with an Agent in IM applications such as DingTalk and Lark | |
Call an Agent from the business application server | AgentCore SDK Overview and Session mechanisms and session isolation |
Stop billing when the resources are no longer used | Delete the Team → delete the Agent → disable collaboration → delete the models and model connection → delete the user → delete the Workspace |