# Agent applications

> Alibaba Cloud Model Studio agent applications let you connect an LLM to external tools and knowledge bases without code, extending the model's capabilities beyond its built-in limits.

<Tip>
  - <strong>Console access restrictions:</strong> Only users who created Alibaba Cloud Model Studio applications <strong>in the Singapore region</strong> before <strong>April 21, 2025</strong> can access the <strong>Application Development</strong> tab.

    > This tab contains the following features: Applications ([agent application](/help/en/model-studio/single-agent-application) and [workflow application](/help/en/model-studio/workflow-application)), Components ([prompt engineering](/help/en/model-studio/prompt-template) and [plug-in](/help/en/model-studio/plug-in-overview)), and Data ([knowledge base](/help/en/model-studio/rag-knowledge-base) and [application data](/help/en/model-studio/data-import-instructions)). <strong>These are all preview features. Use them with caution in production environments.</strong>
  - <strong>API call restrictions:</strong> Only users who created Alibaba Cloud Model Studio applications <strong>in the Singapore region</strong> before <strong>April 21, 2025</strong> can call the [application data, knowledge base, and prompt engineering APIs](/help/en/model-studio/api-bailian-2023-12-29-dir).
</Tip>

## How it works <span id="2aef17cb98aje" /> <span id="d6b49fdf3frog" />

An agent uses prompts to orchestrate external tools and complete complex tasks. When the agent receives a request, the LLM identifies the user's intent, plans the tasks, calls the necessary external tools, and integrates the results to generate a final response.

Use an agent when you want the model to autonomously decide which tools to use for a task, rather than following a manually designed workflow.

Model Studio agents support the following core capabilities:

1. <strong>Knowledge base (RAG)</strong>: Connects the agent to an external knowledge base to answer questions based on your private data. This is useful for Q\&A scenarios in specialized domains not covered by the model's training data.
2. <strong>Plugin</strong>: Calls pre-built platform tools for tasks such as code execution, image generation, or weather queries. This is useful when the agent must perform actions rather than just converse.

## Quick start <span id="a9de1b3f7enzm" /> <span id="c0a3d115e446a" />

### Create a basic agent <span id="940d18fab91ap" /> <span id="fb6c6e0fed98n" />

1. Go to the [Application Management](https://modelstudio.console.alibabacloud.com/?tab=app#/app-center) page on the Alibaba Cloud Model Studio console. Click <strong>+ Create Application</strong>. On the <strong>Agent Application</strong> tab, click <strong><strong>Create Now</strong></strong>.
2. On the application configuration page, select a model from the model drop-down list, such as `Qwen-Plus`. You can keep the default settings for other parameters.
3. After the application is created, enter `Hello` in the conversation box on the left to test it.

## Agent capabilities <span id="58ca895ad5lsf" /> <span id="c20cc2dff3v07" />

You can extend an agent's capabilities by selecting a model, optimizing the system prompt, adding a knowledge base (RAG), and calling plugins.

### Model <span id="0b8fedab13lc0" /> <span id="952dc466855od" />

The model is the core component that drives an agent's reasoning and decision-making. Model Studio agents support Qwen series models and custom-deployed models.

1. <strong>Select a model</strong>

   From the model drop-down list, select a model such as `Qwen-Plus`. Click <strong>More Models</strong> to choose from other available models.
2. <strong>Configure parameters</strong>

   Click the settings icon <Image src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/2427319571/p1007468.png" alt="image" className="inline" noZoom width={22} /> to the right of the model drop-down list to configure the following parameters:

   1. <strong>Maximum response length</strong>: The maximum length of the model's generated response, excluding the prompt. The maximum value varies by model.
   2. <strong>Context turns</strong>: The maximum number of historical conversation turns to include in the model's input. A higher number helps maintain better conversational context.
   3. <strong>temperature</strong>: Controls the randomness of the generated content. A higher value increases diversity, while a lower value increases consistency. The value must be in the range of \[0, 2).
   4. <strong>enable\_thinking</strong>: Toggles the model's thinking mode. This parameter is only available for supported models.

      > When thinking mode is enabled, the model performs more in-depth reasoning before generating a response, which increases token consumption.

### System prompt <span id="ddecb789a81hy" /> <span id="34b832e1e01ib" />

A system prompt defines an agent's role, behavior, and constraints to ensure that its responses are consistent and task-oriented. To write an effective prompt, consider the following points:

- <strong>Define a persona</strong>: Specify the role the model should adopt and the expertise it should have.
- <strong>Specify an output format</strong>: Describe the desired structure, length, or style of the response.
- <strong>Set constraints</strong>: Instruct the model on what content to avoid or which rules to follow.
- <strong>Guide tool usage</strong>: Explicitly mention tool names and explain when they should be used.

  1. <strong>Configure a prompt</strong>

     Set the system prompt to `Please answer my questions in the style of 'One Hundred Years of Solitude'`. The following is a comparison of the results:

     - <strong>Without the system prompt:</strong> When the user asks "Who are you?", the model provides its default introduction: "I am Qwen, a large language model developed by the Tongyi Lab of Alibaba Group. I can help you answer questions, provide information, create content, write code, and perform logical reasoning."
     - <strong>With the system prompt:</strong> In the <strong>text conversation</strong> interface, when the user asks "Who are you?", the AI introduces itself in the literary style of "One Hundred Years of Solitude," referencing elements from the novel such as Macondo and the Buendía family. This confirms the system prompt has taken effect. The interaction statistics show 234 words, 245 input tokens, and 177 output tokens.

### Knowledge base (RAG) <span id="2b4792c3deeui" /> <span id="37aa8c3652g8b" />

Retrieval-augmented generation (RAG) lets an agent query an external knowledge base and use the retrieved content as grounding for answers. For private or domain-specific Q\&A, RAG can significantly improve accuracy and reduce hallucinations. For more information, see [Create and use a knowledge base](/help/en/model-studio/rag-knowledge-base).

> <strong>Note</strong>: Text retrieved from a knowledge base consumes the model's context window. You may need to adjust your retrieval strategy and the length of the retrieved text to use the context window efficiently and avoid exceeding its limit.

### Plugins <span id="d1da8df94a98c" /> <span id="550c6b3ddevkl" />

Agents call plugins to perform specific tasks, such as code execution, web searches, and text-to-image generation. Plugins are useful when an agent needs to perform operations or generate content beyond its native capabilities. Model Studio provides a variety of official plugins and also supports custom plugins. For more information, see [Plugin overview](/help/en/model-studio/plug-in-overview).

## Agent interaction <span id="e148e74828qm8" /> <span id="0147cca5e7sz6" />

### Text conversation <span id="a15b32b91179a" /> <span id="c9ad7efdd1cjt" />

Text conversation is the primary method for interacting with an agent and supports multi-turn conversations.

Text conversation supports two input methods:

1. <strong>Text input:</strong> Enter text to chat with the agent.
2. <strong>File upload:</strong> Upload files, such as documents, images, videos, or audio clips, as attachments.

## Publish and call <span id="8024d5cd363s1" /> <span id="5bd04d954boke" />

After publishing, agents can be called through API/SDK, published to third-party platforms such as DingTalk and WeChat Official Accounts, or published as reusable components for integration into your business systems.

### Publish an application <span id="8e05ebad8eg87" /> <span id="81d4d6f9fc5cr" />

<Tip>
  You must publish an application before you can call or integrate it.
</Tip>

In the upper-right corner of the agent application management page, click <strong>Publish</strong> and then click <strong>Confirm Publish</strong>.

> When republishing the application, a dialog box appears and displays the changes made since the last publication.

<Note>
  If the application was created by a RAM user, make sure you have the `ram:CreateServiceLinkedRole` permission before publishing. For more information, see [service-linked role](/help/en/model-studio/bailian-service-linked-role).
</Note>

### API call <span id="d6ec5f242b81v" /> <span id="dd72d0c973qlj" />

On the <strong>Publish Channel</strong> tab of your agent application, click <strong>View API</strong> next to <strong>API Call</strong> to view the API methods.

> Replace `YOUR_API_KEY` with your actual Model Studio API key before you invoke the API.

## Agent management <span id="556fedd7714sq" /> <span id="5bf0ea709334p" />

### Copy and delete <span id="88e8eb49cd51h" /> <span id="ccfd2f8259oa8" />

On the <strong>My Applications</strong> page, find the application card. From the <strong>More</strong> > <strong>Copy Application/Delete Application</strong> menu, you can copy, delete, or rename the agent.

Common scenarios for copying an application include:

- Creating test versions that use different prompts or models.
- Customizing an agent for different audiences or use cases.
- Creating a backup before making major configuration changes.

### Version management <span id="8435a952fculc" /> <span id="d46bbde887rel" />

Version management lets you edit historical version descriptions or revert to a previously published version.

1. On the <strong>Configure</strong> tab of the agent application, click <strong>Version Management</strong> in the upper-right corner of the top navigation bar.
2. In the list of historical versions, select a target version. The <strong>Version History</strong> panel opens and displays a timeline that includes the <strong>current draft</strong>, the <strong>online version</strong> (marked with a <strong>Latest</strong> tag), and other historical version entries. Each entry lists the version ID, publication time, publisher, and version information.

   - To edit the version information, hover over the edit icon <Image src="https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/6849833471/p934804.png" alt="image" className="inline" noZoom width={18} /> and click it. In the <strong>Edit Version Description</strong> dialog box, make your changes and then click <strong>OK</strong>.
   - To use this historical version, click <strong>Overwrite Current Draft</strong>, and then click <strong>Confirm</strong> in the confirmation dialog box.

     > This action overwrites the current draft with the content of the selected historical version.

## Billing <span id="df7c0b297f7dw" /> <span id="91ec1140f7rpq" />

Agent billing includes the following:

1. <strong>Model calls</strong>

   Agents incur model call fees, which depend on the model type and token usage.

   For billing details, see the [Model Studio console](https://modelstudio.console.alibabacloud.com/cn-beijing?tab=model#/model-market/all).
2. <strong>Knowledge base</strong>

   - The knowledge base feature is free of charge for a limited time.
   - Text chunks retrieved from the knowledge base increase the number of input tokens, which can increase model call fees.
3. <strong>MCPs</strong>

   - Some official Model Customization Platforms (MCPs) are billed based on model calls, such as MCPs for text-to-image, text-to-video, and speech synthesis.
   - Some MCP services involve third-party API calls, which may incur fees charged by the third-party service provider. Model Studio does not charge additional fees for these calls.
4. <strong>Long-term memory</strong>

   - Data storage for long-term memory is free of charge.
   - During a Q\&A session, the system merges content from memory into the prompt and passes it to the large language model, which increases token consumption. <strong>Tokens consumed by content from memory are currently not charged.</strong>

## Supported models <span id="fa8805da2e215" /> <span id="93d5702b06zm1" />

<Note>
  This list may not be up-to-date. For the latest list of supported models, refer to the agent application interface.
</Note>

- Qwen-Plus
- Qwen-Max
- QwenVL-Max
- QwenVL-Plus
- Qwen-Turbo

## FAQ <span id="eec6a65baff0q" /> <span id="80550724deslw" />

<Accordion title="How are Model Studio applications billed?">
  Creating an application is free. When you call an application for a Q\&A session, you are charged for model calls based on the model type used.
</Accordion>

<Accordion title="I've configured a knowledge base, but the agent's answers are unrelated to its content. How can I fix this?">
  First, run a knowledge base hit test to check the similarity score between the query and the knowledge base content. If the score is low, adjust the retrieval configuration to ensure that the model prioritizes results from the knowledge base.

  In the system prompt, explicitly instruct the model to answer questions based only on the knowledge base content and not use its own built-in knowledge. If the issue persists, try using a different model for more stable results.
</Accordion>

<Accordion title="Is there a timeout limit for custom plugins?">
  Yes, the timeout limit is 5 seconds.
</Accordion>

<Accordion title="Can I create agent applications by using an API?">
  You can use the Assistant API to create large language model applications similar to agent applications. However, applications created with the Assistant API <strong>cannot be managed on the console</strong>. For more information, see the [Assistant API documentation](/help/en/model-studio/assistant-api).
</Accordion>