Qwen-Agent

Um framework para desenvolver aplicações LLM com capacidades como uso de ferramentas, planejamento e memória, baseado no modelo Qwen.

GitHub
17.1k
Experimente este MCPPatrocinado

Documentação

中文 ｜ English


💜 Qwen Chat   |   🤗 Hugging Face   |   🤖 ModelScope   |    📑 Blog    ｜   📖 Documentation
📊 Benchmark   |   💬 WeChat (微信)   |   🫨 Discord  

Qwen-Agent é um framework para desenvolver aplicações de LLM baseadas nas capacidades de seguir instruções, uso de ferramentas, planejamento e memória do Qwen. Ele também inclui aplicações de exemplo, como Assistente de Navegador, Interpretador de Código e Assistente Personalizado. Atualmente, o Qwen-Agent atua como backend do Qwen Chat.

Novidades

Primeiros Passos

Instalação

  • Instale a versão estável do PyPI:
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Or use `pip install -U qwen-agent` for the minimal requirements.
# The optional requirements, specified in double brackets, are:
#   [gui] for Gradio-based GUI support;
#   [rag] for RAG support;
#   [code_interpreter] for Code Interpreter support;
#   [mcp] for MCP support.
  • Alternativamente, você pode instalar a versão de desenvolvimento mais recente a partir do código-fonte:
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
# Or `pip install -e ./` for minimal requirements.

Preparação: Serviço de Modelos

Você pode usar o serviço de modelos fornecido pelo DashScope da Alibaba Cloud, ou implantar e usar seu próprio serviço de modelos com os modelos Qwen de código aberto.

  • Se você optar por usar o serviço de modelos oferecido pelo DashScope, certifique-se de definir a variável de ambiente DASHSCOPE_API_KEY com sua chave de API exclusiva do DashScope.

  • Alternativamente, se você preferir implantar e usar seu próprio serviço de modelos, siga as instruções fornecidas no README do Qwen2 para implantar um serviço de API compatível com OpenAI. Especificamente, consulte a seção vLLM para implantação em GPU de alto throughput ou a seção Ollama para implantação local em CPU (+GPU). Para os modelos QwQ e Qwen3, é recomendado não adicionar os parâmetros --enable-auto-tool-choice e --tool-call-parser hermes, pois o Qwen-Agent fará o parsing das saídas de ferramentas do vLLM por conta própria. Para o Qwen3-Coder, é recomendado habilitar ambos os parâmetros acima, usar o parsing de ferramentas integrado do vLLM e combinar com o uso do parâmetro use_raw_api.

Desenvolvendo Seu Próprio Agente

O Qwen-Agent oferece componentes atômicos, como LLMs (que herdam de class BaseChatModel e vêm com function calling) e Ferramentas (que herdam de class BaseTool), além de componentes de alto nível, como Agentes (derivados de class Agent).

O exemplo a seguir ilustra o processo de criação de um agente capaz de ler arquivos PDF e utilizar ferramentas, além de incorporar uma ferramenta personalizada:

import pprint
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 = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    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': 'Qwen2.5-7B-Instruct',
    # '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. For configuration details, please refer to the FAQ.
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)

Além de usar implementações de agente integradas, como class Assistant, você também pode desenvolver sua própria implementação de agente herdando de class Agent.

O framework também fornece uma interface GUI conveniente, com suporte à implantação rápida de Demos Gradio para Agentes. Por exemplo, no caso acima, você pode iniciar rapidamente uma Demo Gradio usando o seguinte código:

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.

Agora você pode conversar com o Agente na interface web. Consulte o diretório de exemplos para mais exemplos de uso.

FAQ

Como Usar a Ferramenta de Interpretador de Código?

Implementamos uma ferramenta de interpretador de código baseada em contêineres Docker locais. Você pode habilitar a ferramenta integrada code interpreter para seu agente, permitindo que ele escreva código de forma autônoma de acordo com cenários específicos, execute-o com segurança em um ambiente de sandbox isolado e retorne os resultados da execução.

⚠️ Observação: Antes de usar esta ferramenta, certifique-se de que o Docker esteja instalado e em execução no seu sistema operacional local. O tempo necessário para criar a imagem do contêiner pela primeira vez depende das condições da sua rede. Para instruções de instalação e configuração do Docker, consulte a documentação oficial.

Como Usar MCP?

Você pode selecionar as ferramentas necessárias no site de servidores MCP de código aberto e configurar o ambiente relevante.

Exemplo de formato de invocação MCP:

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
        },
        "sqlite" : {
            "command": "uvx",
            "args": [
                "mcp-server-sqlite",
                "--db-path",
                "test.db"
            ]
        }
    }
}

Para mais detalhes, consulte o exemplo de uso do MCP

As dependências necessárias para executar este exemplo são as seguintes:

# Node.js (Download and install the latest version from the Node.js official website)
# uv 0.4.18 or higher (Check with uv --version)
# Git (Check with git --version)
# SQLite (Check with sqlite3 --version)

# For macOS users, you can install these components using Homebrew:
brew install uv git sqlite3

# For Windows users, you can install these components using winget:
winget install --id=astral-sh.uv -e
winget install git.git sqlite.sqlite

Você tem function calling (também conhecido como chamada de ferramentas)?

Sim. As classes de LLM fornecem function calling. Além disso, algumas classes de Agente também são construídas sobre a capacidade de function calling, por exemplo, FnCallAgent e ReActChat.

O template atual padrão de chamada de ferramentas suporta nativamente Chamadas de Função Paralelas.

Como passar parâmetros de LLM para o Agente?

llm_cfg = {
    # The model name being used:
    'model': 'qwen3-32b',
    # The model service being used:
    'model_type': 'qwen_dashscope',
    # If 'api_key' is not set here, it will default to reading the `DASHSCOPE_API_KEY` environment variable:
    'api_key': 'YOUR_DASHSCOPE_API_KEY',

    # Using an OpenAI API compatible model service, such as vLLM or Ollama:
    # 'model': 'qwen3-32b',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, also known as api_base
    # 'api_key': 'EMPTY',

    # (Optional) LLM hyperparameters:
    'generate_cfg': {
        # This parameter will affect the tool-call parsing logic. Default is False:
          # Set to True: when content is `<think>this is the thought</think>this is the answer`
          # Set to False: when response consists of reasoning_content and content
        # 'thought_in_content': True,

        # tool-call template: default is nous (recommended for qwen3):
        # 'fncall_prompt_type': 'nous'

        # Maximum input length, messages will be truncated if they exceed this length, please adjust according to model API:
        # 'max_input_tokens': 58000

        # Parameters that will be passed directly to the model API, such as top_p, enable_thinking, etc., according to the API specifications:
        # 'top_p': 0.8

        # Using the API's native tool call interface
        # 'use_raw_api': True,
    }
}

Como fazer perguntas e respostas sobre documentos superlongos envolvendo 1M de tokens?

Disponibilizamos uma solução RAG rápida, bem como um agente caro, porém competitivo, para responder perguntas sobre documentos superlongos. Eles conseguiram superar modelos nativos de contexto longo em dois benchmarks desafiadores, sendo mais eficientes, e apresentam desempenho perfeito no teste de pressão "agulha no palheiro" de agulha única envolvendo contextos de 1M de tokens. Consulte o blog para detalhes técnicos.

Aplicação: BrowserQwen

O BrowserQwen é um assistente de navegador construído sobre o Qwen-Agent. Consulte sua documentação para detalhes.

Aviso Legal

O interpretador de código baseado em contêiner Docker monta apenas o diretório de trabalho especificado e implementa isolamento básico de sandbox, mas ainda deve ser usado com cautela em ambientes de produção.