Metadata-Version: 2.1
Name: agentscope
Version: 0.0.3
Summary: AgentScope: A Flexible yet Robust Multi-Agent Platform.
Home-page: https://github.com/modelscope/agentscope
Download-URL: https://github.com/modelscope/agentscope/archive/v0.0.3.tar.gz
Author: SysML team of Alibaba Tongyi Lab 
Author-email: gaodawei.gdw@alibaba-inc.com
License: Apache License 2.0
Keywords: deep-learning,multi agents,agents
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docstring-parser
Requires-Dist: loguru ==0.6.0
Requires-Dist: tiktoken
Requires-Dist: Pillow
Requires-Dist: requests
Requires-Dist: chardet
Requires-Dist: inputimeout
Requires-Dist: openai >=1.3.0
Requires-Dist: numpy
Requires-Dist: Flask ==3.0.0
Requires-Dist: Flask-Cors ==4.0.0
Requires-Dist: Flask-SocketIO ==5.3.6
Requires-Dist: dashscope ==1.14.1
Requires-Dist: ollama >=0.1.7
Requires-Dist: google-generativeai >=0.4.0
Provides-Extra: dev
Requires-Dist: docstring-parser ; extra == 'dev'
Requires-Dist: loguru ==0.6.0 ; extra == 'dev'
Requires-Dist: tiktoken ; extra == 'dev'
Requires-Dist: Pillow ; extra == 'dev'
Requires-Dist: requests ; extra == 'dev'
Requires-Dist: chardet ; extra == 'dev'
Requires-Dist: inputimeout ; extra == 'dev'
Requires-Dist: openai >=1.3.0 ; extra == 'dev'
Requires-Dist: numpy ; extra == 'dev'
Requires-Dist: Flask ==3.0.0 ; extra == 'dev'
Requires-Dist: Flask-Cors ==4.0.0 ; extra == 'dev'
Requires-Dist: Flask-SocketIO ==5.3.6 ; extra == 'dev'
Requires-Dist: dashscope ==1.14.1 ; extra == 'dev'
Requires-Dist: ollama >=0.1.7 ; extra == 'dev'
Requires-Dist: google-generativeai >=0.4.0 ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Provides-Extra: distribute
Requires-Dist: docstring-parser ; extra == 'distribute'
Requires-Dist: loguru ==0.6.0 ; extra == 'distribute'
Requires-Dist: tiktoken ; extra == 'distribute'
Requires-Dist: Pillow ; extra == 'distribute'
Requires-Dist: requests ; extra == 'distribute'
Requires-Dist: chardet ; extra == 'distribute'
Requires-Dist: inputimeout ; extra == 'distribute'
Requires-Dist: openai >=1.3.0 ; extra == 'distribute'
Requires-Dist: numpy ; extra == 'distribute'
Requires-Dist: Flask ==3.0.0 ; extra == 'distribute'
Requires-Dist: Flask-Cors ==4.0.0 ; extra == 'distribute'
Requires-Dist: Flask-SocketIO ==5.3.6 ; extra == 'distribute'
Requires-Dist: dashscope ==1.14.1 ; extra == 'distribute'
Requires-Dist: ollama >=0.1.7 ; extra == 'distribute'
Requires-Dist: google-generativeai >=0.4.0 ; extra == 'distribute'
Requires-Dist: grpcio ==1.60.0 ; extra == 'distribute'
Requires-Dist: grpcio-tools ==1.60.0 ; extra == 'distribute'
Requires-Dist: protobuf ==4.25.0 ; extra == 'distribute'
Requires-Dist: expiringdict ; extra == 'distribute'
Provides-Extra: full
Requires-Dist: docstring-parser ; extra == 'full'
Requires-Dist: loguru ==0.6.0 ; extra == 'full'
Requires-Dist: tiktoken ; extra == 'full'
Requires-Dist: Pillow ; extra == 'full'
Requires-Dist: requests ; extra == 'full'
Requires-Dist: chardet ; extra == 'full'
Requires-Dist: inputimeout ; extra == 'full'
Requires-Dist: openai >=1.3.0 ; extra == 'full'
Requires-Dist: numpy ; extra == 'full'
Requires-Dist: Flask ==3.0.0 ; extra == 'full'
Requires-Dist: Flask-Cors ==4.0.0 ; extra == 'full'
Requires-Dist: Flask-SocketIO ==5.3.6 ; extra == 'full'
Requires-Dist: dashscope ==1.14.1 ; extra == 'full'
Requires-Dist: ollama >=0.1.7 ; extra == 'full'
Requires-Dist: google-generativeai >=0.4.0 ; extra == 'full'
Requires-Dist: grpcio ==1.60.0 ; extra == 'full'
Requires-Dist: grpcio-tools ==1.60.0 ; extra == 'full'
Requires-Dist: protobuf ==4.25.0 ; extra == 'full'
Requires-Dist: expiringdict ; extra == 'full'
Requires-Dist: docker ; extra == 'full'
Requires-Dist: pymongo ; extra == 'full'
Requires-Dist: pymysql ; extra == 'full'
Requires-Dist: beautifulsoup4 ; extra == 'full'
Requires-Dist: sphinx ; extra == 'full'
Requires-Dist: sphinx-autobuild ; extra == 'full'
Requires-Dist: sphinx-rtd-theme ; extra == 'full'
Requires-Dist: myst-parser ; extra == 'full'
Requires-Dist: sphinxcontrib-mermaid ; extra == 'full'
Requires-Dist: pytest ; extra == 'full'
Requires-Dist: pytest-cov ; extra == 'full'
Requires-Dist: pre-commit ; extra == 'full'
Requires-Dist: gradio ==4.19.1 ; extra == 'full'
Requires-Dist: modelscope-studio ==0.0.5 ; extra == 'full'

English | [**中文**](README_ZH.md)

# AgentScope

Start building LLM-empowered multi-agent applications in an easier way.

[![](https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C)](https://arxiv.org/abs/2402.14034)
[![](https://img.shields.io/badge/python-3.9+-blue)](https://pypi.org/project/agentscope/)
[![](https://img.shields.io/badge/pypi-v0.0.2-blue?logo=pypi)](https://pypi.org/project/agentscope/)
[![](https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown)](https://modelscope.github.io/agentscope/#welcome-to-agentscope-tutorial-hub)
[![](https://img.shields.io/badge/Docs-API_Reference-blue?logo=markdown)](https://modelscope.github.io/agentscope/)
[![](https://img.shields.io/badge/ModelScope-Demos-4e29ff.svg?logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMjI0IDEyMS4zMyIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxwYXRoIGQ9Im0wIDQ3Ljg0aDI1LjY1djI1LjY1aC0yNS42NXoiIGZpbGw9IiM2MjRhZmYiIC8+Cgk8cGF0aCBkPSJtOTkuMTQgNzMuNDloMjUuNjV2MjUuNjVoLTI1LjY1eiIgZmlsbD0iIzYyNGFmZiIgLz4KCTxwYXRoIGQ9Im0xNzYuMDkgOTkuMTRoLTI1LjY1djIyLjE5aDQ3Ljg0di00Ny44NGgtMjIuMTl6IiBmaWxsPSIjNjI0YWZmIiAvPgoJPHBhdGggZD0ibTEyNC43OSA0Ny44NGgyNS42NXYyNS42NWgtMjUuNjV6IiBmaWxsPSIjMzZjZmQxIiAvPgoJPHBhdGggZD0ibTAgMjIuMTloMjUuNjV2MjUuNjVoLTI1LjY1eiIgZmlsbD0iIzM2Y2ZkMSIgLz4KCTxwYXRoIGQ9Im0xOTguMjggNDcuODRoMjUuNjV2MjUuNjVoLTI1LjY1eiIgZmlsbD0iIzYyNGFmZiIgLz4KCTxwYXRoIGQ9Im0xOTguMjggMjIuMTloMjUuNjV2MjUuNjVoLTI1LjY1eiIgZmlsbD0iIzM2Y2ZkMSIgLz4KCTxwYXRoIGQ9Im0xNTAuNDQgMHYyMi4xOWgyNS42NXYyNS42NWgyMi4xOXYtNDcuODR6IiBmaWxsPSIjNjI0YWZmIiAvPgoJPHBhdGggZD0ibTczLjQ5IDQ3Ljg0aDI1LjY1djI1LjY1aC0yNS42NXoiIGZpbGw9IiMzNmNmZDEiIC8+Cgk8cGF0aCBkPSJtNDcuODQgMjIuMTloMjUuNjV2LTIyLjE5aC00Ny44NHY0Ny44NGgyMi4xOXoiIGZpbGw9IiM2MjRhZmYiIC8+Cgk8cGF0aCBkPSJtNDcuODQgNzMuNDloLTIyLjE5djQ3Ljg0aDQ3Ljg0di0yMi4xOWgtMjUuNjV6IiBmaWxsPSIjNjI0YWZmIiAvPgo8L3N2Zz4K)](https://modelscope.cn/studios?name=agentscope&page=1&sort=latest)

[![](https://img.shields.io/badge/license-Apache--2.0-black)](./LICENSE)
[![](https://img.shields.io/badge/Contribute-Welcome-green)](https://modelscope.github.io/agentscope/tutorial/contribute.html)

If you find our work helpful, please kindly
cite [our paper](https://arxiv.org/abs/2402.14034).

Welcome to join our community on

| [Discord](https://discord.gg/eYMpfnkG8h)                                                                                         | DingTalk                                                                                                                          |
|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i2/O1CN01tuJ5971OmAqNg9cOw_!!6000000001747-0-tps-444-460.jpg" width="100" height="100"> |

----

## News

- ![new](https://img.alicdn.com/imgextra/i4/O1CN01kUiDtl1HVxN6G56vN_!!6000000000764-2-tps-43-19.png)
[2024-03-19] We release **AgentScope** v0.0.2 now! In this new version,
AgentScope supports [ollama](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#supported-models)(A local CPU inference engine), [DashScope](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#supported-models) and Google [Gemini](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#supported-models) APIs.

- ![new](https://img.alicdn.com/imgextra/i4/O1CN01kUiDtl1HVxN6G56vN_!!6000000000764-2-tps-43-19.png)
[2024-03-19] New examples ["Autonomous Conversation with Mentions"](./examples/conversation_with_mentions) and ["Basic Conversation with LangChain library"](./examples/conversation_with_langchain) are available now!

- ![new](https://img.alicdn.com/imgextra/i4/O1CN01kUiDtl1HVxN6G56vN_!!6000000000764-2-tps-43-19.png)
[2024-03-19] The [Chinese tutorial](https://modelscope.github.io/agentscope/zh_CN/index.html) of AgentScope is online now!

- [2024-02-27] We release **AgentScope v0.0.1** now, which is also
available in [PyPI](https://pypi.org/project/agentscope/)!
- [2024-02-14] We release our paper "AgentScope: A Flexible yet Robust
Multi-Agent Platform" in [arXiv](https://arxiv.org/abs/2402.14034) now!

---

## What's AgentScope?

AgentScope is an innovative multi-agent platform designed to empower developers
to build multi-agent applications with large-scale models.
It features three high-level capabilities:

- 🤝 **Easy-to-Use**: Designed for developers, with [fruitful components](https://modelscope.github.io/agentscope/en/tutorial/204-service.html#),
[comprehensive documentation](https://modelscope.github.io/agentscope/en/index.html), and broad compatibility.

- ✅ **High Robustness**: Supporting customized fault-tolerance controls and
retry mechanisms to enhance application stability.

- 🚀 **Actor-Based Distribution**: Building distributed multi-agent
applications in a centralized programming manner for streamlined development.

**Supported Model Libraries**

AgentScope provides a list of `ModelWrapper` to support both local model
services and third-party model APIs.

| API                    | Task            | Model Wrapper                                                                                                                   | Example Configuration                                                                       |
|------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| OpenAI API             | Chat            | [`OpenAIChatWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/openai_model.py)                 | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#openai-api)       |
|                        | Embedding       | [`OpenAIEmbeddingWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/openai_model.py)            | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#openai-api)       |
|                        | DALL·E          | [`OpenAIDALLEWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/openai_model.py)                | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#openai-api)       |
| DashScope API          | Chat            | [`DashScopeChatWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/dashscope_model.py)           | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#dashscope-api)    |
|                        | Image Synthesis | [`DashScopeImageSynthesisWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/dashscope_model.py) | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#dashscope-api)    |
|                        | Text Embedding  | [`DashScopeTextEmbeddingWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/dashscope_model.py)  | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#dashscope-api)    |
| Gemini API             | Chat            | [`GeminiChatWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/gemini_model.py)                 | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#gemini-api)       |
|                        | Embedding       | [`GeminiEmbeddingWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/gemini_model.py)            | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#gemini-api)       |
| ollama                 | Chat            | [`OllamaChatWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/ollama_model.py)                 | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#ollama-api)       |
|                        | Embedding       | [`OllamaEmbeddingWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/ollama_model.py)            | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#ollama-api)       |
|                        | Generation      | [`OllamaGenerationWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/ollama_model.py)           | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#ollama-api)       |
| Post Request based API | -               | [`PostAPIModelWrapper`](https://github.com/modelscope/agentscope/blob/main/src/agentscope/models/post_model.py)                 | [link](https://modelscope.github.io/agentscope/en/tutorial/203-model.html#post-request-api) |

**Supported Local Model Deployment**

AgentScope enables developers to rapidly deploy local model services using
the following libraries.

- [ollama (CPU inference)](https://github.com/modelscope/agentscope/blob/main/scripts/README.md#ollama)
- [Flask + Transformers](https://github.com/modelscope/agentscope/blob/main/scripts/README.md#with-transformers-library)
- [Flask + ModelScope](https://github.com/modelscope/agentscope/blob/main/scripts/README.md#with-modelscope-library)
- [FastChat](https://github.com/modelscope/agentscope/blob/main/scripts/README.md#fastchat)
- [vllm](https://github.com/modelscope/agentscope/blob/main/scripts/README.md#vllm)

**Supported Services**

- Web Search
- Data Query
- Retrieval
- Code Execution
- File Operation
- Text Processing

**Example Applications**

- Conversation
  - [Basic Conversation](./examples/conversation_basic)
  - [Autonomous Conversation with Mentions](./examples/conversation_with_mentions)
  - [Self-Organizing Conversation](./examples/conversation_self_organizing)
  - [Basic Conversation with LangChain library](./examples/conversation_with_langchain)
  - [Conversation with ReAct Agent](./examples/conversation_with_react_agent)
  - [Conversation with RAG Agent](./examples/conversation_with_RAG_agents)

- Game
  - [Gomoku](./examples/game_gomoku)
  - [Werewolf](./examples/game_werewolf)

- Distribution
  - [Distributed Conversation](./examples/distributed_basic)
  - [Distributed Debate](./examples/distributed_debate)
  - [Distributed Parallel Search](./examples/distributed_search)

More models, services and examples are coming soon!

## Installation

AgentScope requires **Python 3.9** or higher.

**_Note: This project is currently in active development, it's recommended to
install AgentScope from source._**

### From source

- Install AgentScope in editable mode:

```bash
# Pull the source code from GitHub
git clone https://github.com/modelscope/agentscope.git

# Install the package in editable mode
cd agentscope
pip install -e .
```

- To build distributed multi-agent applications:

```bash
# On windows
pip install -e .[distribute]
# On mac
pip install -e .\[distribute\]
```

### Using pip

- Install AgentScope from pip:

```bash
pip install agentscope
```

## Quick Start

### Configuration

In AgentScope, the model deployment and invocation are decoupled by
`ModelWrapper`.

To use these model wrappers, you need to prepare a model config file as
follows.

```python
model_config = {
    # The identifies of your config and used model wrapper
    "config_name": "{your_config_name}",          # The name to identify the config
    "model_type": "{model_type}",                 # The type to identify the model wrapper

    # Detailed parameters into initialize the model wrapper
    # ...
}
```

Taking OpenAI Chat API as an example, the model configuration is as follows:

```python
openai_model_config = {
    "config_name": "my_openai_config",             # The name to identify the config
    "model_type": "openai",                        # The type to identify the model wrapper

    # Detailed parameters into initialize the model wrapper
    "model_name": "gpt-4",                         # The used model in openai API, e.g. gpt-4, gpt-3.5-turbo, etc.
    "api_key": "xxx",                              # The API key for OpenAI API. If not set, env
                                                   # variable OPENAI_API_KEY will be used.
    "organization": "xxx",                         # The organization for OpenAI API. If not set, env
                                                   # variable OPENAI_ORGANIZATION will be used.
}
```

More details about how to set up local model services and prepare model
configurations is in our
[tutorial](https://modelscope.github.io/agentscope/index.html#welcome-to-agentscope-tutorial-hub).

### Create Agents

Create built-in user and assistant agents as follows.

```python
from agentscope.agents import DialogAgent, UserAgent
import agentscope

# Load model configs
agentscope.init(model_configs="./model_configs.json")

# Create a dialog agent and a user agent
dialog_agent = DialogAgent(name="assistant",
                           model_config_name="my_openai_config")
user_agent = UserAgent()
```

### Construct Conversation

In AgentScope, **message** is the bridge among agents, which is a
**dict** that contains two necessary fields `name` and `content` and an
optional field `url` to local files (image, video or audio) or website.

```python
from agentscope.message import Msg

x = Msg(name="Alice", content="Hi!")
x = Msg("Bob", "What about this picture I took?", url="/path/to/picture.jpg")
```

Start a conversation between two agents (e.g. dialog_agent and user_agent)
with the following code:

```python
x = None
while True:
    x = dialog_agent(x)
    x = user_agent(x)
    if x.content == "exit":  # user input "exit" to exit the conversation_basic
        break
```

### AgentScope Studio

AgentScope provides an easy-to-use runtime user interface capable of
displaying multimodal output on the front end, including text, images,
audio and video. To start a studio, you should install the `full` version
of AgentScope.

```
# On windows
pip install -e .[full]
# On mac
pip install -e .\[full\]
```

Once installed, you can just run

```
as_studio  path/to/your/script.py
```

Then the studio will be launched at `localhost:xxxx`, and you can see the UI similar to the
following:
![](https://gw.alicdn.com/imgextra/i3/O1CN01X673v81WaHV1oCxEN_!!6000000002804-0-tps-2992-1498.jpg)
To be able to use the `as_studio` functionality, please implement the `main` function in your code. More detail can be found in [src/agentscope/web/README.md](src/agentscope/web/README.md).

## Tutorial

- [Getting Started](https://modelscope.github.io/agentscope/en/tutorial/quick_start.html)
  - [About AgentScope](https://modelscope.github.io/agentscope/en/tutorial/101-agentscope.html)
  - [Installation](https://modelscope.github.io/agentscope/en/tutorial/102-installation.html)
  - [Quick Start](https://modelscope.github.io/agentscope/en/tutorial/103-example.html)
  - [Crafting Your First Application](https://modelscope.github.io/agentscope/en/tutorial/104-usecase.html)
  - [Logging and WebUI](https://modelscope.github.io/agentscope/en/tutorial/105-logging.html#)
- [Advanced Exploration](https://modelscope.github.io/agentscope/en/tutorial/advance.html)
  - [Customize Your Own Agent](https://modelscope.github.io/agentscope/en/tutorial/201-agent.html)
  - [Pipeline and MsgHub](https://modelscope.github.io/agentscope/en/tutorial/202-pipeline.html)
  - [Model](https://modelscope.github.io/agentscope/en/tutorial/203-model.html)
  - [Service](https://modelscope.github.io/agentscope/en/tutorial/204-service.html)
  - [Memory](https://modelscope.github.io/agentscope/en/tutorial/205-memory.html)
  - [Prompt Engineering](https://modelscope.github.io/agentscope/en/tutorial/206-prompt.html)
  - [Monitor](https://modelscope.github.io/agentscope/en/tutorial/207-monitor.html)
  - [Distribution](https://modelscope.github.io/agentscope/en/tutorial/208-distribute.html)
- [Get Involved](https://modelscope.github.io/agentscope/en/tutorial/contribute.html)
  - [Join AgentScope Community](https://modelscope.github.io/agentscope/en/tutorial/301-community.html)
  - [Contribute to AgentScope](https://modelscope.github.io/agentscope/en/tutorial/302-contribute.html)

## License

AgentScope is released under Apache License 2.0.

## Contributing

Contributions are always welcomed!

We provide a developer version with additional pre-commit hooks to perform
checks compared to the official version:

```bash
# For windows
pip install -e .[dev]
# For mac
pip install -e .\[dev\]

# Install pre-commit hooks
pre-commit install
```

Please refer to our [Contribution Guide](https://modelscope.github.io/agentscope/en/tutorial/302-contribute.html) for more details.

## References

If you find our work helpful for your research or application, please
cite [our paper](https://arxiv.org/abs/2402.14034):

```
@article{agentscope,
  author  = {Dawei Gao and
             Zitao Li and
             Weirui Kuang and
             Xuchen Pan and
             Daoyuan Chen and
             Zhijian Ma and
             Bingchen Qian and
             Liuyi Yao and
             Lin Zhu and
             Chen Cheng and
             Hongzhu Shi and
             Yaliang Li and
             Bolin Ding and
             Jingren Zhou},
  title   = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
  journal = {CoRR},
  volume  = {abs/2402.14034},
  year    = {2024},
}
```
