[δΈζ](https://github.com/QwenLM/Qwen-Agent/blob/main/README_CN.md) ο½ English
<p align="center">
<img src="https://qianwen-res.oss-cn-beijing.aliyuncs.com/assets/qwen_agent/logo-qwen-agent.png" width="400"/>
<p>
<br>
Qwen-Agent is a framework for developing LLM applications based on the instruction following, tool usage, planning, and
memory capabilities of Qwen.
It also comes with example applications such as Browser Assistant, Code Interpreter, and Custom Assistant.
# News
* Dec 3, 2024: Upgrade GUI to Gradio 5 based. Note: GUI requires Python 3.10 or higher.
* π₯π₯π₯ Sep 18, 2024: Added [Qwen2.5-Math Demo](./examples/tir_math.py) to showcase the Tool-Integrated Reasoning capabilities of Qwen2.5-Math. Note: The python executor is not sandboxed and is intended for local testing only, not for production use.
# Getting Started
## Installation
- Install the stable version from PyPI:
```bash
pip install -U "qwen-agent[gui,rag,code_interpreter,python_executor]"
# 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;
# [python_executor] for Tool-Integrated Reasoning with Qwen2.5-Math.
```
- Alternatively, you can install the latest development version from the source:
```bash
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,python_executor]"
# Or `pip install -e ./` for minimal requirements.
```
## Preparation: Model Service
You can either use the model service provided by Alibaba
Cloud's [DashScope](https://help.aliyun.com/zh/dashscope/developer-reference/quick-start), 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 Qwen2 for deploying an OpenAI-compatible API service.
Specifically, consult the [vLLM](https://github.com/QwenLM/Qwen2?tab=readme-ov-file#vllm) section for high-throughput GPU deployment or the [Ollama](https://github.com/QwenLM/Qwen2?tab=readme-ov-file#ollama) section for local CPU (+GPU) deployment.
## Developing Your Own Agent
Qwen-Agent offers atomic components, such as LLMs (which inherit from `class BaseChatModel` and come with [function calling](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py)) 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:
```py
import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
# 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',
'model_server': '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-7B-Chat',
# '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 = '''You are a helpful assistant.
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('user query: ')
# Append the user query to the chat history.
messages.append({'role': 'user', 'content': query})
response = []
for response in bot.run(messages=messages):
# Streaming output.
print('bot response:')
pprint.pprint(response, indent=2)
# 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 implemetation 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:
```py
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](https://github.com/QwenLM/Qwen-Agent/blob/main/examples) directory for more usage examples.
# FAQ
## Do you have function calling (aka tool calling)?
Yes. The LLM classes provide [function calling](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py). Additionally, some Agent classes also are built upon the function calling capability, e.g., FnCallAgent and ReActChat.
## How to do question-answering over super-long documents involving 1M tokens?
We have released [a fast RAG solution](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py), as well as [an expensive but competitive agent](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py), for doing question-answering over super-long documents. They have managed to outperform native long-context models on two challenging benchmarks while being more efficient, and perform perfectly in the single-needle "needle-in-the-haystack" pressure test involving 1M-token contexts. See the [blog](https://qwenlm.github.io/blog/qwen-agent-2405/) for technical details.
<p align="center">
<img src="https://qianwen-res.oss-cn-beijing.aliyuncs.com/assets/qwen_agent/qwen-agent-2405-blog-long-context-results.png" width="400"/>
<p>
# Application: BrowserQwen
BrowserQwen is a browser assistant built upon Qwen-Agent. Please refer to its [documentation](https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen.md) for details.
# Disclaimer
The code interpreter is not sandboxed, and it executes code in your own environment. Please do not ask Qwen to perform dangerous tasks, and do not directly use the code interpreter for production purposes.
Raw data
{
"_id": null,
"home_page": "https://github.com/QwenLM/Qwen-Agent",
"name": "qwen-agent",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "LLM, Agent, Function Calling, RAG, Code Interpreter",
"author": "Qwen Team",
"author_email": "tujianhong.tjh@alibaba-inc.com",
"download_url": "https://files.pythonhosted.org/packages/80/5f/e110ddf9e8d82a9124a4e6d752c6fdde0b15c24138a0a17562a5dd168aae/qwen-agent-0.0.15.tar.gz",
"platform": null,
"description": "[\u4e2d\u6587](https://github.com/QwenLM/Qwen-Agent/blob/main/README_CN.md) \uff5c English\n\n<p align=\"center\">\n <img src=\"https://qianwen-res.oss-cn-beijing.aliyuncs.com/assets/qwen_agent/logo-qwen-agent.png\" width=\"400\"/>\n<p>\n<br>\n\nQwen-Agent is a framework for developing LLM applications based on the instruction following, tool usage, planning, and\nmemory capabilities of Qwen.\nIt also comes with example applications such as Browser Assistant, Code Interpreter, and Custom Assistant.\n\n# News\n* Dec 3, 2024: Upgrade GUI to Gradio 5 based. Note: GUI requires Python 3.10 or higher.\n* \ud83d\udd25\ud83d\udd25\ud83d\udd25 Sep 18, 2024: Added [Qwen2.5-Math Demo](./examples/tir_math.py) to showcase the Tool-Integrated Reasoning capabilities of Qwen2.5-Math. Note: The python executor is not sandboxed and is intended for local testing only, not for production use.\n\n# Getting Started\n\n## Installation\n\n- Install the stable version from PyPI:\n```bash\npip install -U \"qwen-agent[gui,rag,code_interpreter,python_executor]\"\n# Or use `pip install -U qwen-agent` for the minimal requirements.\n# The optional requirements, specified in double brackets, are:\n# [gui] for Gradio-based GUI support;\n# [rag] for RAG support;\n# [code_interpreter] for Code Interpreter support;\n# [python_executor] for Tool-Integrated Reasoning with Qwen2.5-Math.\n```\n\n- Alternatively, you can install the latest development version from the source:\n```bash\ngit clone https://github.com/QwenLM/Qwen-Agent.git\ncd Qwen-Agent\npip install -e ./\"[gui,rag,code_interpreter,python_executor]\"\n# Or `pip install -e ./` for minimal requirements.\n```\n\n## Preparation: Model Service\n\nYou can either use the model service provided by Alibaba\nCloud's [DashScope](https://help.aliyun.com/zh/dashscope/developer-reference/quick-start), or deploy and use your own\nmodel service using the open-source Qwen models.\n\n- If you choose to use the model service offered by DashScope, please ensure that you set the environment\nvariable `DASHSCOPE_API_KEY` to your unique DashScope API key.\n\n- Alternatively, if you prefer to deploy and use your own model service, please follow the instructions provided in the README of Qwen2 for deploying an OpenAI-compatible API service.\nSpecifically, consult the [vLLM](https://github.com/QwenLM/Qwen2?tab=readme-ov-file#vllm) section for high-throughput GPU deployment or the [Ollama](https://github.com/QwenLM/Qwen2?tab=readme-ov-file#ollama) section for local CPU (+GPU) deployment.\n\n## Developing Your Own Agent\n\nQwen-Agent offers atomic components, such as LLMs (which inherit from `class BaseChatModel` and come with [function calling](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py)) and Tools (which inherit\nfrom `class BaseTool`), along with high-level components like Agents (derived from `class Agent`).\n\nThe following example illustrates the process of creating an agent capable of reading PDF files and utilizing tools, as\nwell as incorporating a custom tool:\n\n```py\nimport pprint\nimport urllib.parse\nimport json5\nfrom qwen_agent.agents import Assistant\nfrom qwen_agent.tools.base import BaseTool, register_tool\n\n\n# Step 1 (Optional): Add a custom tool named `my_image_gen`.\n@register_tool('my_image_gen')\nclass MyImageGen(BaseTool):\n # The `description` tells the agent the functionality of this tool.\n description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'\n # The `parameters` tell the agent what input parameters the tool has.\n parameters = [{\n 'name': 'prompt',\n 'type': 'string',\n 'description': 'Detailed description of the desired image content, in English',\n 'required': True\n }]\n\n def call(self, params: str, **kwargs) -> str:\n # `params` are the arguments generated by the LLM agent.\n prompt = json5.loads(params)['prompt']\n prompt = urllib.parse.quote(prompt)\n return json5.dumps(\n {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},\n ensure_ascii=False)\n\n\n# Step 2: Configure the LLM you are using.\nllm_cfg = {\n # Use the model service provided by DashScope:\n 'model': 'qwen-max',\n 'model_server': 'dashscope',\n # 'api_key': 'YOUR_DASHSCOPE_API_KEY',\n # It will use the `DASHSCOPE_API_KEY' environment variable if 'api_key' is not set here.\n\n # Use a model service compatible with the OpenAI API, such as vLLM or Ollama:\n # 'model': 'Qwen2-7B-Chat',\n # 'model_server': 'http://localhost:8000/v1', # base_url, also known as api_base\n # 'api_key': 'EMPTY',\n\n # (Optional) LLM hyperparameters for generation:\n 'generate_cfg': {\n 'top_p': 0.8\n }\n}\n\n# Step 3: Create an agent. Here we use the `Assistant` agent as an example, which is capable of using tools and reading files.\nsystem_instruction = '''You are a helpful assistant.\nAfter receiving the user's request, you should:\n- first draw an image and obtain the image url,\n- then run code `request.get(image_url)` to download the image,\n- and finally select an image operation from the given document to process the image.\nPlease show the image using `plt.show()`.'''\ntools = ['my_image_gen', 'code_interpreter'] # `code_interpreter` is a built-in tool for executing code.\nfiles = ['./examples/resource/doc.pdf'] # Give the bot a PDF file to read.\nbot = Assistant(llm=llm_cfg,\n system_message=system_instruction,\n function_list=tools,\n files=files)\n\n# Step 4: Run the agent as a chatbot.\nmessages = [] # This stores the chat history.\nwhile True:\n # For example, enter the query \"draw a dog and rotate it 90 degrees\".\n query = input('user query: ')\n # Append the user query to the chat history.\n messages.append({'role': 'user', 'content': query})\n response = []\n for response in bot.run(messages=messages):\n # Streaming output.\n print('bot response:')\n pprint.pprint(response, indent=2)\n # Append the bot responses to the chat history.\n messages.extend(response)\n```\n\nIn addition to using built-in agent implementations such as `class Assistant`, you can also develop your own agent implemetation by inheriting from `class Agent`.\n\nThe framework also provides a convenient GUI interface, supporting the rapid deployment of Gradio Demos for Agents.\nFor example, in the case above, you can quickly launch a Gradio Demo using the following code:\n\n```py\nfrom qwen_agent.gui import WebUI\nWebUI(bot).run() # bot is the agent defined in the above code, we do not repeat the definition here for saving space.\n```\nNow you can chat with the Agent in the web UI. Please refer to the [examples](https://github.com/QwenLM/Qwen-Agent/blob/main/examples) directory for more usage examples.\n\n# FAQ\n\n## Do you have function calling (aka tool calling)?\n\nYes. The LLM classes provide [function calling](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/function_calling.py). Additionally, some Agent classes also are built upon the function calling capability, e.g., FnCallAgent and ReActChat.\n\n## How to do question-answering over super-long documents involving 1M tokens?\n\nWe have released [a fast RAG solution](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_rag.py), as well as [an expensive but competitive agent](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/parallel_doc_qa.py), for doing question-answering over super-long documents. They have managed to outperform native long-context models on two challenging benchmarks while being more efficient, and perform perfectly in the single-needle \"needle-in-the-haystack\" pressure test involving 1M-token contexts. See the [blog](https://qwenlm.github.io/blog/qwen-agent-2405/) for technical details.\n\n<p align=\"center\">\n <img src=\"https://qianwen-res.oss-cn-beijing.aliyuncs.com/assets/qwen_agent/qwen-agent-2405-blog-long-context-results.png\" width=\"400\"/>\n<p>\n\n# Application: BrowserQwen\n\nBrowserQwen is a browser assistant built upon Qwen-Agent. Please refer to its [documentation](https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen.md) for details.\n\n# Disclaimer\n\nThe code interpreter is not sandboxed, and it executes code in your own environment. Please do not ask Qwen to perform dangerous tasks, and do not directly use the code interpreter for production purposes.\n",
"bugtrack_url": null,
"license": null,
"summary": "Qwen-Agent: Enhancing LLMs with Agent Workflows, RAG, Function Calling, and Code Interpreter.",
"version": "0.0.15",
"project_urls": {
"Homepage": "https://github.com/QwenLM/Qwen-Agent"
},
"split_keywords": [
"llm",
" agent",
" function calling",
" rag",
" code interpreter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e4292400f0fb750d9ad0dda9d2b064b0542582bed677390857832ecb1a1ebad",
"md5": "ef4e4142137613f54ee00f57a4eb3d04",
"sha256": "208d4496226fbcc9373199545180a8321bfb33b7fc10445be4ce65edcd3aa5ef"
},
"downloads": -1,
"filename": "qwen_agent-0.0.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef4e4142137613f54ee00f57a4eb3d04",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7074956,
"upload_time": "2024-12-13T06:56:04",
"upload_time_iso_8601": "2024-12-13T06:56:04.082739Z",
"url": "https://files.pythonhosted.org/packages/9e/42/92400f0fb750d9ad0dda9d2b064b0542582bed677390857832ecb1a1ebad/qwen_agent-0.0.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "805fe110ddf9e8d82a9124a4e6d752c6fdde0b15c24138a0a17562a5dd168aae",
"md5": "1783395bb393b1024df7915ed9333817",
"sha256": "11b10c958f289fcb6eaffc3fb094cb957a768f7c019d45594209f94addd7d4ae"
},
"downloads": -1,
"filename": "qwen-agent-0.0.15.tar.gz",
"has_sig": false,
"md5_digest": "1783395bb393b1024df7915ed9333817",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7030512,
"upload_time": "2024-12-13T06:56:07",
"upload_time_iso_8601": "2024-12-13T06:56:07.108312Z",
"url": "https://files.pythonhosted.org/packages/80/5f/e110ddf9e8d82a9124a4e6d752c6fdde0b15c24138a0a17562a5dd168aae/qwen-agent-0.0.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 06:56:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "QwenLM",
"github_project": "Qwen-Agent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "qwen-agent"
}
JSON
