QuickStart

This quickstart will guide you to implement an agent using a few lines of code in just a few minutes.

Preparation: Model Service

You can either use the model service provided by Alibaba Cloud’s DashScope , or deploy and use your own model service using the open-source Qwen models.

If you choose to use the model service offered by DashScope, please ensure that you set the environment variable DASHSCOPE_API_KEY to your unique DashScope API key.
Alternatively, if you prefer to deploy and use your own model service, please follow the instructions provided in the README of Qwen3 for deploying an OpenAI-compatible API service. Specifically, consult the SGLang or vLLM section for high-throughput GPU deployment.

Tool Call Parser Options

Model server’s native tool call parser

Qwen-Agent supports reading the tool call response of the model, which requires enabling the tool call parser parameter when deploying the model.
For Qwen3-Coder, it is recommended to use the tool parser of model server, i.e. adding the --enable-auto-tool-choice and --tool-call-parser qwen3_coder parameters in vLLM /SGLang server.
This is combine with the use_raw_api parameter usage. Soon, this will become the default mode.

Qwen-Agent’s built-in tool call parser

Because some model deployment methods do not provide native tool call capabilities, or tool call support is incomplete, Qwen-Agent’s built-in tool call parsing can be used. Qwen-Agent provides hermes parsing format by default, supporting tool call parsers for QwQ and Qwen3 series model. Currently, this is the default mode.
For the QwQ and Qwen3 series model, it is recommended to use the built-in tool call parser of Qwen-Agent, i.e. do not add the --enable-auto-tool-choice and --tool-call-parser hermes parameters in vLLM/SGLang server.

Developing Your Own Agent

Qwen-Agent offers atomic components, such as LLMs (which inherit from class BaseChatModel and come with function calling ) and Tools (which inherit from class BaseTool), along with high-level components like Agents (derived from class Agent).

The following example illustrates the process of creating an agent capable of reading PDF files and utilizing tools, as well as incorporating a custom tool:


import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print
 
 
# Step 1 (Optional): Add a custom tool named `my_image_gen`.
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    # The `description` tells the agent the functionality of this tool.
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    # The `parameters` tell the agent what input parameters the tool has.
    parameters = {
        'type': 'object',
        'properties': {
            'prompt': {
                'type': 'string',
                'description': 'Detailed description of the desired image content, in English',
            }
        },
        'required': ['prompt'],
    }
 
    def call(self, params: str, **kwargs) -> str:
        # `params` are the arguments generated by the LLM agent.
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)
 
 
# Step 2: Configure the LLM you are using.
llm_cfg = {
    # Use the model service provided by DashScope:
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    # It will use the `DASHSCOPE_API_KEY' environment variable if 'api_key' is not set here.
 
    # Use a model service compatible with the OpenAI API, such as vLLM or Ollama:
    # 'model': 'Qwen3-8B',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, also known as api_base
    # 'api_key': 'EMPTY',
 
    # (Optional) LLM hyperparameters for generation:
    'generate_cfg': {
        'top_p': 0.8
    }
}
 
# Step 3: Create an agent. Here we use the `Assistant` agent as an example, which is capable of using tools and reading files.
system_instruction = '''After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''
tools = ['my_image_gen', 'code_interpreter']  # `code_interpreter` is a built-in tool for executing code.
files = ['./examples/resource/doc.pdf']  # Give the bot a PDF file to read.
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)
 
# Step 4: Run the agent as a chatbot.
messages = []  # This stores the chat history.
while True:
    # For example, enter the query "draw a dog and rotate it 90 degrees".
    query = input('\nuser query: ')
    # Append the user query to the chat history.
    messages.append({'role': 'user', 'content': query})
    response = []
    response_plain_text = ''
    print('bot response:')
    for response in bot.run(messages=messages):
        # Streaming output.
        response_plain_text = typewriter_print(response, response_plain_text)
    # Append the bot responses to the chat history.
    messages.extend(response)

In addition to using built-in agent implementations such as class Assistant, you can also develop your own agent by inheriting from class Agent.

The framework also provides a convenient GUI interface, supporting the rapid deployment of Gradio Demos for Agents. For example, in the case above, you can quickly launch a Gradio Demo using the following code:


from qwen_agent.gui import WebUI
WebUI(bot).run()  # bot is the agent defined in the above code, we do not repeat the definition here for saving space.

Now you can chat with the Agent in the web UI. Please refer to the examples directory for more usage examples.