add docs for all tutorial

.github/workflows/sphinx_docs.yml

@@ -1,8 +1,13 @@
 name: Deploy Sphinx documentation to Pages
 
 on:
-  release:
-    types: [published]
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - 'docs/**/*'
+  push:
+    branches:
+      - main
 
 jobs:
   pages:
@@ -12,19 +17,27 @@ jobs:
       OS: ${{ matrix.os }}
       PYTHON: '3.9'
     steps:
-    - uses: actions/checkout@master
+    - name: Checkout repository
+      uses: actions/checkout@master
     - name: Setup Python ${{ matrix.python-version }}
       uses: actions/setup-python@master
       with:
         python_version: ${{ matrix.python-version }}
     - id: deployment
+      name: Build Documentation
       uses: sphinx-notes/pages@v3
       with:
         documentation_path: ./docs/sphinx_doc/source
         python_version: ${{ matrix.python-version }}
         publish: false
         requirements_path: ./docs/sphinx_doc/requirements.txt
+    - name: Upload Documentation
+      uses: actions/upload-artifact@v3
+      with:
+        name: SphinxDoc
+        path: ${{ steps.deployment.outputs.artifact }}
     - uses: peaceiris/actions-gh-pages@v3
+      if: github.event_name == 'push' && github_ref == 'refs/heads/main'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ${{ steps.deployment.outputs.artifact }}

docs/sphinx_doc/source/conf.py

@@ -35,8 +35,13 @@
     "sphinx.ext.napoleon",
     "sphinxcontrib.mermaid",
     "myst_parser",
+    "sphinx.ext.autosectionlabel",
 ]
 
+# Prefix document path to section labels, otherwise autogenerated labels would
+# look like 'heading' rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/sphinx_doc/source/index.rst

@@ -8,8 +8,23 @@
 AgentScope Documentation
 ======================================
 
+
+.. include:: tutorial/main.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+   :caption: AgentScope Tutorial
+
+   tutorial/quick_start.rst
+   tutorial/advance.rst
+   tutorial/contribute.rst
+
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :glob:
    :caption: AgentScope API Reference
 
@@ -24,15 +39,6 @@ AgentScope Documentation
    agentscope.web_ui
    agentscope
 
-.. include:: tutorial/main.md
-   :parser: myst_parser.sphinx_
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-   :hidden:
-   :caption: AgentScope Tutorial
-
 Indices and tables
 ==================
 

docs/sphinx_doc/source/tutorial/101-installation.md

@@ -0,0 +1,68 @@
+(101-installation)=
+
+# Installation
+
+To install AgentScope, you need to have Python 3.9 or higher installed. We recommend setting up a new virtual environment specifically for AgentScope:
+
+### Create a Virtual Environment
+
+#### Using Conda
+
+If you're using Conda as your package and environment management tool, you can create a new virtual environment with Python 3.9 using the following commands:
+
+```bash
+# Create a new virtual environment named 'agentscope' with Python 3.9
+conda create -n agentscope python=3.9
+
+# Activate the virtual environment
+conda activate agentscope
+```
+
+#### Using Virtualenv
+
+Alternatively, if you prefer `virtualenv`, you can install it first (if it's not already installed) and then create a new virtual environment as shown:
+
+```bash
+# Install virtualenv if it is not already installed
+pip install virtualenv
+
+# Create a new virtual environment named 'agentscope' with Python 3.9
+virtualenv agentscope --python=python3.9
+
+# Activate the virtual environment
+source agentscope/bin/activate  # On Windows use `agentscope\Scripts\activate`
+```
+
+### Installing AgentScope
+
+#### Install with Pip
+
+If you prefer to install AgentScope from Pypi, you can do so easily using `pip`:
+
+```bash
+# For centralized multi-agent applications
+pip install agentscope
+# For distributed multi-agent applications
+pip install agentscope[distribute]  # On Mac use `pip install agentscope\[distribute\]`
+```
+
+#### Install from Source
+
+For users who prefer to install AgentScope directly from the source code, follow these steps to clone the repository and install the platform in editable mode:
+
+**_Note: This project is under active development, it's recommended to install AgentScope from source._**
+
+```bash
+# Pull the source code from Github
+git clone https://github.com/alibaba/AgentScope.git
+cd AgentScope
+
+# For centralized multi-agent applications
+pip install -e .
+# For distributed multi-agent applications
+pip install -e .[distribute]  # On Mac use `pip install -e .\[distribute\]`
+```
+
+**Note**: The `[distribute]` option installs additional dependencies required for distributed applications. Remember to activate your virtual environment before running these commands.
+
+[[Return to the top]](#installation)

docs/sphinx_doc/source/tutorial/102-concepts.md

@@ -0,0 +1,46 @@
+(102-concepts)=
+
+# Fundamental Concepts
+
+In this tutorial, you'll have an initial understanding of the **fundamental concepts** of AgentScope. We will focus on how a multi-agent application runs based on our platform and familiarize you with the essential terms. Let's get started!
+
+![Concepts](https://img.alicdn.com/imgextra/i1/O1CN01ELiTw41KGKqTmWZua_!!6000000001136-2-tps-756-598.png)
+
+## Essential Terms and Concepts
+
+* **Agent** refers to an autonomous entity capable of performing actions to achieve specific objectives (probably powered by LLMs). In AgentScope, an agent takes the message as input and generates a corresponding response message. Agents can interact with each other to simulate human-like behaviors (e.g., discussion or debate) and cooperate to finish complicated tasks (e.g., generate runnable and reliable code).
+* **Message** is a carrier of communication information among agents. It encapsulates information that needs to be conveyed, such as instructions, multi-modal data, or status updates.  In AgentScope, a message is a subclass of Python's dict with additional features for inter-agent communication, including fields such as `name` and `content` for identification and payload delivery.
+* **Memory** refers to the structures (e.g., list-like memory, database-based memory) used to store and manage `Msg` (Message) that agents need to remember and store. This can include chat history, knowledge, or other data that informs the agent's future actions.
+* **Service** is a collection of functionality tools (e.g., web search, code interpreter, file processing) that provide specific capabilities or processes that are independent of an agent's memory state. Services can be invoked by agents or other components and designed to be reusable across different scenarios.
+* **Pipeline** refers to the interaction order or pattern of agents in a task. AgentScope provides built-in `pipelines` to streamline the process of collaboration across multiple agents, such as `SequentialPipeline` and `ForLoopPipeline`. When a `Pipeline` is executed, the *message* passes from predecessors to successors with intermediate results for the task.
+
+## Code Structure
+
+```bash
+AgentScope
+├── src
+│   ├── agentscope
+│   |   ├── agents               # Core components and implementations pertaining to agents.
+│   |   ├── configs              # Configurations that can be customized for the application's needs.
+│   |   ├── memory               # Structures for agent memory.
+│   |   ├── models               # Interfaces for integrating diverse model APIs.
+│   |   ├── pipeline             # Fundamental components and implementations for running pipelines.
+│   |   ├── rpc                  # Rpc module for agent distributed deployment.
+│   |   ├── service              # Services offering functions independent of memory and state.
+│   |   ├── utils                # Auxiliary utilities and helper functions.
+│   |   ├── message.py           # Definitions and implementations of messaging between agents.
+|   |   ├── web_ui               # WebUI used to show dialogs.
+│   |   ├── prompt.py            # Prompt engineering module for model input.
+│   |   ├── ... ..
+│   |   ├── ... ..
+├── scripts                      # Scripts for launching local Model API
+├── examples                     # Pre-built examples of different applications.
+├── docs                         # Documentation tool for API reference.
+├── tests                        # Unittest modules for continuous integration.
+├── LICENSE                      # The official licensing agreement for AgentScope usage.
+└── setup.py                     # Setup script for installing.
+├── ... ..
+└── ... ..
+```
+
+[[Return to the top]](#fundamental-concepts)

docs/sphinx_doc/source/tutorial/103-example.md

@@ -0,0 +1,102 @@
+(103-example)=
+
+# Getting Started with a Simple Example
+
+AgentScope is a versatile platform for building and running multi-agent applications. We provide various pre-built examples that will help you quickly understand how to create and use multi-agent for various applications. In this tutorial, you will learn how to set up a **simple agent-based interaction**.
+
+## Step1: Prepare Model Configs
+
+Agent is the basic composition and communication unit in AgentScope. To initialize a model-based agent, you need to prepare your configs for avaliable models. AgentScope supports a variety of APIs for pre-trained models. Here is a table outlining the supported APIs and the type of arguments required for each:
+
+|   Model Usage               | Type Argument in AgentScope     | Supported APIs                                                              |
+| -------------------- | ------------------ |-----------------------------------------------------------------------------|
+| Text generation     | `openai`           | Standard *OpenAI* chat API, FastChat and vllm                               |
+| Image generation   | `openai_dall_e`    | *DALL-E* API for generating images                                          |
+| Embedding | `openai_embedding` | API for text embeddings                                                     |
+| General usages in POST       | `post_api`         | *Huggingface* and *ModelScope* Inference API, and other customized post API |
+
+Each API has its specific configuration requirements. For example, to configure an OpenAI API, you would need to fill out the following fields in the model config in a dict, a yaml file or a json file:
+
+```python
+model_config = {
+    "type": "openai",               # Choose from "openai", "openai_dall_e", or "openai_embedding"
+    "name": "{your_config_name}",   # A unique identifier for your config
+    "model_name": "{model_name}",   # The model identifier used in the OpenAI API, such as "gpt-3.5-turbo", "gpt-4", or "text-embedding-ada-002"
+    "api_key": "xxx",               # Your OpenAI API key. If unset, the environment variable OPENAI_API_KEY is used.
+    "organization": "xxx",          # Your OpenAI organization ID. If unset, the environment variable OPENAI_ORGANIZATION is used.
+}
+```
+
+For open-source models, we support integration with various model interfaces such as HuggingFace, ModelScope, FastChat, and vllm. You can find scripts on deploying these services in the `scripts` directory, and we defer the detailed instructions to [[Using Different Model Sources with Model API]](203-model).
+
+You can register your configuration by calling AgentScope's initilization method as follow. Besides, you can also load more than one config by calling init mutliple times.
+
+```python
+import agentscope
+
+# init once by passing a list of config dict
+openai_cfg_dict = {...dict_filling...}
+modelscope_cfg_dict = {...dict_filling...}
+agentscope.init(model_configs=[openai_cfg_dict, modelscope_cfg_dict])
+```
+
+## Step2: Create Agents
+
+Creating agents is straightforward in AgentScope. After initializing AgentScope with your model configurations (Step 1 above), you can then define each agent with its corresponding role and specific model.
+
+```python
+import agentscope
+from agentscope.agents import DialogAgent, UserAgent
+
+# read model configs
+agentscope.init(model_configs="./openai_model_configs.json")
+
+# Create a dialog agent and a user agent
+dialogAgent = DialogAgent(name="assistant", model="gpt-4")
+userAgent = UserAgent()
+```
+
+**NOTE**: Please refer to [[Customizing Your Custom Agent with Agent Pool]](201-agent) for all available agents.
+
+## Step3: Agent Conversation
+
+"Message" is the primary means of communication between agents in AgentScope. They are Python dictionaries comprising essential fields like the actual `content` of this message and the sender's `name`. Optionally, a message can include a `url` to either a local file (image, video or audio) or website.
+
+```python
+from agentscope.message import Msg
+
+# Example of a simple text message from Alice
+message_from_alice = Msg("Alice", "Hi!")
+
+# Example of a message from Bob with an attached image
+message_from_bob = Msg("Bob", "What about this picture I took?", url="/path/to/picture.jpg")
+```
+
+To start a conversation between two agents, such as `dialog_agent` and `user_agent`, you can use the following loop. The conversation continues until the user inputs `"exit"` which terminates the interaction.
+
+```python
+x = None
+while True:
+    x = dialogAgent(x)
+    x = userAgent(x)
+
+    # Terminate the conversation if the user types "exit"
+    if x.content == "exit":
+        print("Exiting the conversation.")
+        break
+```
+
+For a more advanced approach, AgentScope offers the option of using pipelines to manage the flow of messages between agents. The `sequentialpipeline` stands for sequential speech, where each agent receive message from last agent and generate its response accordingly.
+
+```python
+from agentscope.pipelines.functional import sequentialpipeline
+
+# Execute the conversation loop within a pipeline structure
+x = None
+while x is None or x.content != "exit":
+  x = sequentialpipeline([dialog_agent, user_agent])
+```
+
+For more details about how to utilize pipelines for complex agent interactions, please refer to [[Agent Interactions: Dive deeper into Pipelines and Message Hub]](202-pipeline).
+
+[[Return to the top]](#getting-started-with-a-simple-example)