Skip to main content

​
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:
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:
# 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

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)
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
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

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.'
Check that Docker is running:
docker ps  # Should not return an error
Make sure you’re iterating through the generator:
for response in bot.run(messages=messages):
    # Process each chunk
    pass

Build docs developers (and LLMs) love

Get started for freeTalk to us