Quickstart

Build your first Qwen-Agent application in 5 minutes

Introduction

This quickstart guide will help you create a functional AI agent with tool-calling capabilities in just 5 minutes. By the end, you’ll have a working agent that can generate images and interact with users.

Prerequisites: Complete the installation steps and configure your model service (DashScope or self-hosted) before proceeding.

Your First Agent

Let’s build a simple weather assistant that can answer questions about the weather.

1. Create Your Project

   Create a new directory and Python file for your agent:

   mkdir my-qwen-agent
   cd my-qwen-agent
   touch weather_agent.py
   
2. Import Required Modules

   Open weather_agent.py and add the necessary imports:

   weather_agent.py

   import os
   from qwen_agent.agents import Assistant
   from qwen_agent.gui import WebUI
   

   These imports provide:

   • Assistant: The high-level agent class with built-in tool support
   • WebUI: A Gradio-based interface for interacting with your agent
3. Configure the LLM

   Set up your language model configuration:

   DashScope

   llm_cfg = {
       'model': 'qwen-max-latest',
       'model_type': 'qwen_dashscope',
       # API key will be read from DASHSCOPE_API_KEY env var
   }
   

   If using DashScope, ensure your DASHSCOPE_API_KEY environment variable is set.

4. Create the Agent

   Initialize an Assistant agent with a system message:

   weather_agent.py

   # Create the agent
   bot = Assistant(
       llm=llm_cfg,
       name='Weather Assistant',
       description='A helpful assistant that provides weather information',
       system_message='You are a friendly weather assistant. Provide clear and concise weather information when asked.'
   )
   
5. Run the Agent

   Add code to interact with your agent:

   CLI Interface

   # Chat loop for command-line interaction
   messages = []
   
   while True:
       query = input('\nYou: ')
       if query.lower() in ['exit', 'quit']:
           break
           
       messages.append({'role': 'user', 'content': query})
       
       response = []
       print('Bot: ', end='', flush=True)
       for response in bot.run(messages=messages):
           # Stream the response
           if response:
               print(response[-1].get('content', ''), end='', flush=True)
       
       messages.extend(response)
       print()  # New line after response
   
6. Test Your Agent

   Run your agent:

   python weather_agent.py
   

   Try asking questions like:

   • “What’s the weather like today?”
   • “Tell me about typical weather patterns”
   • “Should I bring an umbrella?”

Adding Custom Tools

Now let’s enhance your agent by adding a custom image generation tool.

1. Define a Custom Tool

   Add this code before creating your agent:

   weather_agent.py

   import json
   import urllib.parse
   import json5
   from qwen_agent.tools.base import BaseTool, register_tool
   
   # Define a custom image generation tool
   @register_tool('my_image_gen')
   class MyImageGen(BaseTool):
       # Description tells the agent what this tool does
       description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
       
       # Parameters define the tool's input schema
       parameters = [{
           'name': 'prompt',
           'type': 'string',
           'description': 'Detailed description of the desired image content, in English',
           'required': True
       }]
   
       def call(self, params: str, **kwargs) -> str:
           # Parse the parameters generated by the LLM
           prompt = json5.loads(params)['prompt']
           prompt = urllib.parse.quote(prompt)
           
           # Return the generated image URL
           return json5.dumps(
               {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
               ensure_ascii=False
           )
   

   The @register_tool decorator automatically registers your tool with Qwen-Agent, making it available to all agents.

2. Add Tool to Agent

   Update your agent configuration to include the custom tool:

   weather_agent.py

   bot = Assistant(
       llm=llm_cfg,
       name='Creative Assistant',
       description='An assistant that can generate images',
       system_message='You are a helpful assistant with image generation capabilities. When users ask for images, use the image generation tool.',
       function_list=['my_image_gen']  # Add your custom tool
   )
   
3. Test Tool Calling

   Run your agent and try:

   • “Generate an image of a sunset over mountains”
   • “Create a picture of a cute dog”
   • “Draw a futuristic cityscape”

   The agent will automatically call your custom tool and return the image URL.

Using Built-in Tools

Qwen-Agent comes with powerful built-in tools like the Code Interpreter.

1. Add Code Interpreter

   Create a new file code_agent.py:

   code_agent.py

   import os
   from qwen_agent.agents import Assistant
   from qwen_agent.gui import WebUI
   
   llm_cfg = {
       'model': 'qwen-max-latest',
       'model_type': 'qwen_dashscope',
   }
   
   bot = Assistant(
       llm=llm_cfg,
       name='Code Assistant',
       description='An assistant that can write and execute code',
       system_message='You are a helpful coding assistant. You can write Python code to solve problems and execute it to provide results.',
       function_list=['code_interpreter']  # Built-in code execution tool
   )
   
   WebUI(bot).run()
   

   Important: Ensure Docker is installed and running before using the Code Interpreter tool.

2. Test Code Execution

   Run the agent and try:

   • “Calculate the sum of numbers from 1 to 100”
   • “Create a bar chart showing sales data: [10, 25, 35, 50]”
   • “Generate 10 random numbers and find their average”

   The agent will write Python code, execute it securely in a Docker container, and return the results.

Complete Example: Image Generator with Code

Here’s a complete, production-ready example combining custom tools and built-in capabilities:

complete_agent.py

import os
import json
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.gui import WebUI

# Step 1: Define custom image generation tool
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        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 LLM
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Step 3: Create agent with multiple tools
system_instruction = '''After receiving the user's request, you should:
- First draw an image using the image generation tool
- Then write code to download and process the image if requested
- Provide clear explanations of what you're doing

Be creative and helpful!'''

tools = ['my_image_gen', 'code_interpreter']

bot = Assistant(
    llm=llm_cfg,
    system_message=system_instruction,
    function_list=tools,
    name='Creative Code Assistant',
    description='An AI assistant that combines image generation and code execution'
)

# Step 4: Launch web interface
if __name__ == '__main__':
    chatbot_config = {
        'prompt.suggestions': [
            'Draw a beautiful landscape with mountains and lakes',
            'Generate an image of a futuristic robot and analyze it',
            'Create a picture of a sunset and calculate its average color values',
        ]
    }
    
    WebUI(bot, chatbot_config=chatbot_config).run()

Run this example:

python complete_agent.py

Then open your browser to the displayed URL (usually http://localhost:7860).

Working with Files

Agents can read and process various file formats:

file_agent.py

import os
from qwen_agent.agents import Assistant

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
}

# Give the agent PDF files to read
bot = Assistant(
    llm=llm_cfg,
    name='Document Assistant',
    description='An assistant that can read and analyze documents',
    system_message='You are a document analysis assistant. Read the provided files and answer questions about their content.',
    files=['./documents/report.pdf', './documents/data.xlsx']  # Files to process
)

# Ask questions about the files
messages = [
    {'role': 'user', 'content': 'Summarize the key points from the report'}
]

for response in bot.run(messages=messages):
    print(response)

Supported file formats:

• PDF (.pdf)
• Word documents (.docx)
• PowerPoint (.pptx)
• Excel (.xlsx)
• Text files (.txt, .md, .csv)

Advanced Configuration

Customizing Generation Parameters

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {
        'top_p': 0.8,              # Nucleus sampling
        'max_input_tokens': 58000,  # Maximum context length
        'fncall_prompt_type': 'nous',  # Function calling template
    }
}

Using Streaming Responses

from qwen_agent.utils.output_beautify import typewriter_print

messages = [{'role': 'user', 'content': 'Tell me a story'}]
response_text = ''

for response in bot.run(messages=messages):
    # Typewriter effect for streaming output
    response_text = typewriter_print(response, response_text)

Multi-turn Conversations

# Maintain conversation history
messages = []

while True:
    query = input('You: ')
    if query.lower() in ['exit', 'quit']:
        break
    
    # Add user message
    messages.append({'role': 'user', 'content': query})
    
    # Get agent response
    response = []
    for response in bot.run(messages=messages):
        pass  # Process streaming response
    
    # Add agent response to history
    messages.extend(response)
    print(f"Bot: {response[-1].get('content', '')}")

Next Steps

MCP Integration

Connect external tools via Model Context Protocol

RAG Tutorial

Build retrieval-augmented generation systems

Advanced Agents

Explore multi-agent systems and custom workflows

API Reference

Full API documentation

Common Patterns

Function Calling Without Agents

You can use function calling directly with LLM classes:

from qwen_agent.llm import get_chat_model
import json

llm = get_chat_model({
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
})

functions = [{
    'name': 'get_weather',
    'description': 'Get current weather',
    'parameters': {
        'type': 'object',
        'properties': {
            'location': {
                'type': 'string',
                'description': 'City name'
            }
        },
        'required': ['location']
    }
}]

messages = [{'role': 'user', 'content': "What's the weather in Tokyo?"}]

for response in llm.chat(messages=messages, functions=functions, stream=True):
    print(response)

Custom Agent Classes

Inherit from Agent to create specialized agents:

from qwen_agent.agents import Agent

class MyCustomAgent(Agent):
    def _run(self, messages, **kwargs):
        # Your custom agent logic here
        # Must yield responses in the expected format
        pass

Error Handling

Handle errors gracefully in production:

try:
    for response in bot.run(messages=messages):
        process_response(response)
except Exception as e:
    print(f"Error: {e}")
    # Implement retry logic or fallback behavior

Troubleshooting

Agent not calling tools

Ensure your system message clearly instructs the agent to use tools:

system_message='You have access to tools. When appropriate, use them to fulfill user requests.'

Code Interpreter fails

Check that Docker is running:

docker ps  # Should not return an error

Streaming output issues

Make sure you’re iterating through the generator:

for response in bot.run(messages=messages):
    # Process each chunk
    pass