Skip to content

Build and run agents you can see, understand and trust.

Initial commit

AgentScopeTeam296cd0efd908
diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 000000000..04973fa06
Binary files /dev/null and b/.DS_Store differ
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 000000000..cfd1697e7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[Bug]:'
+labels: 'bug'
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. You code
+2. How to execute
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Error messages**
+Detailed error messages.
+
+**Environment (please complete the following information):**
+
+- AgentScope Version: [e.g. 1.0.0 via `print(agentscope.__version__)`]
+- Python Version: [e.g. 3.10]
+- OS: [e.g. macos, windows]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md
new file mode 100644
index 000000000..8ff2e28ce
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/custom.md
@@ -0,0 +1,13 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+
+
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 000000000..6d6921243
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[Feature]: '
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
\ No newline at end of file
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 000000000..b7103f366
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,18 @@
+---
+name: Pull Request
+about: Create a pull request
+---
+## Description
+
+[Please describe the background, purpose, changes made, and how to test this PR]
+
+
+
+## Checklist
+
+Please check the following items before code is ready to be reviewed.
+
+- [ ] Code has passed all tests
+- [ ] Docstrings have been added/updated in Google Style
+- [ ] Documentation has been updated
+- [ ] Code is ready for review
\ No newline at end of file
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
new file mode 100644
index 000000000..195a8d8a4
--- /dev/null
+++ b/.github/workflows/pre-commit.yml
@@ -0,0 +1,38 @@
+name: Pre-commit
+
+on: [push, pull_request]
+
+jobs:
+ run:
+ runs-on: ${{ matrix.os }}
+ strategy:
+ fail-fast: True
+ matrix:
+ os: [ubuntu-latest]
+ env:
+ OS: ${{ matrix.os }}
+ PYTHON: '3.10'
+ steps:
+ - uses: actions/checkout@master
+ - name: Setup Python
+ uses: actions/setup-python@master
+ with:
+ python-version: 3.10
+ - name: Update setuptools
+ run: |
+ pip install setuptools==68.2.2 wheel==0.41.2
+ - name: Install AgentScope
+ run: |
+ pip install -q -e .[full]
+ - name: Install pre-commit
+ run: |
+ pre-commit install
+ - name: Pre-commit starts
+ run: |
+ pre-commit run --all-files > pre-commit.log 2>&1 || true
+ cat pre-commit.log
+ if grep -q Failed pre-commit.log; then
+ echo -e "\e[41m [**FAIL**] Please install pre-commit and format your code first. \e[0m"
+ exit 1
+ fi
+ echo -e "\e[46m ********************************Passed******************************** \e[0m"
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
new file mode 100644
index 000000000..cc756cad7
--- /dev/null
+++ b/.github/workflows/publish-pypi.yml
@@ -0,0 +1,44 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Publish PyPi Package
+
+on:
+ workflow_dispatch:
+ release:
+ types: [published]
+
+permissions:
+ contents: read
+
+jobs:
+ deploy:
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: 3.10
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install setuptools wheel build
+ - name: Build package
+ run: python -m build
+ - name: Test installation
+ run: |
+ pip install dist/*.whl
+ python -c "import your_package; print(your_package.__version__)"
+ - name: Publish package
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ user: __token__
+ password: ${{ secrets.PYPI_API_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/sphinx_docs.yml b/.github/workflows/sphinx_docs.yml
new file mode 100644
index 000000000..89fafcc96
--- /dev/null
+++ b/.github/workflows/sphinx_docs.yml
@@ -0,0 +1,91 @@
+name: Deploy Sphinx documentation to Pages
+
+on:
+ push:
+ branches:
+ - main
+
+jobs:
+ build_en:
+ timeout-minutes: 20
+ runs-on: ${{ matrix.os }}
+ strategy:
+ matrix:
+ os: [ubuntu-latest]
+ python-version: ['3.10']
+ env:
+ OS: ${{ matrix.os }}
+ PYTHON: '3.10'
+ steps:
+ - uses: actions/checkout@v3
+ - name: Setup Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+ - name: Update setuptools
+ run: |
+ pip install setuptools==78.1.1 wheel==0.45.1
+ - name: Install Dependencies
+ run: |
+ pip install -q -e .[full]
+ - name: Add execute permission to build.sh
+ run: |
+ chmod +x docs/tutorial/en/build.sh
+ - name: Build English Documentation
+ env:
+ DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+ run: |
+ cd docs/tutorial/en/
+ ./build.sh
+ - name: Deploy English Documentation
+ uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: docs/tutorial/en/build/html
+ cname: doc.agentscope.io
+
+ build_zh:
+ needs: build_en
+ timeout-minutes: 20
+ runs-on: ${{ matrix.os }}
+ strategy:
+ matrix:
+ os: [ ubuntu-latest ]
+ python-version: [ '3.10' ]
+ env:
+ OS: ${{ matrix.os }}
+ PYTHON: '3.10'
+ steps:
+ - uses: actions/checkout@v3
+ - name: Setup Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+ - name: Setup Node.js
+ uses: actions/setup-node@v3
+ with:
+ node-version: '16'
+ - name: Verify npm installation
+ run: npm --version
+ - name: Update setuptools
+ run: |
+ pip install setuptools==78.1.1 wheel==0.45.1
+ - name: Install Dependencies
+ run: |
+ pip install -q -e .[full]
+ - name: Add execute permission to build.sh
+ run: |
+ chmod +x docs/tutorial/zh_CN/build.sh
+ - name: Build Chinese Documentation
+ env:
+ DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+ run: |
+ cd docs/tutorial/zh_CN/
+ ./build.sh
+ - name: Deploy Chinese Documentation
+ uses: peaceiris/actions-gh-pages@v4
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: docs/tutorial/zh_CN/build/html
+ destination_dir: zh_CN
+ cname: doc.agentscope.io
diff --git a/.github/workflows/unittest.yml b/.github/workflows/unittest.yml
new file mode 100644
index 000000000..fd1e1ca25
--- /dev/null
+++ b/.github/workflows/unittest.yml
@@ -0,0 +1,39 @@
+name: Python Unittest Coverage
+
+on: [push, pull_request]
+
+jobs:
+ test:
+ if: false == contains(github.event.pull_request.title, 'WIP')
+ runs-on: ${{ matrix.os }}
+ strategy:
+ matrix:
+ os: [ubuntu-latest, macos-13]
+ python-version: ['3.10', '3.11', '3.12']
+ env:
+ OS: ${{ matrix.os }}
+ steps:
+ - uses: actions/checkout@master
+ - name: Setup Python ${{ matrix.python-version }}
+ uses: actions/setup-python@master
+ with:
+ python-version: ${{ matrix.python-version }}
+ - name: Update setuptools
+ run: |
+ pip install setuptools==78.1.1 wheel==0.45.1
+# - name: Install Minimal Dependencies
+# run: |
+# pip install -q -e .
+# - name: Run minimal import tests
+# run: |
+# python tests/minimal.py
+ - name: Install Full Dependencies
+ run: |
+ pip install -q -e .[full]
+ pip install coverage pytest
+ - name: Run tests with coverage
+ run: |
+ coverage run -m pytest tests
+ - name: Generate coverage report
+ run: |
+ coverage report -m
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 000000000..adee77870
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+__pycache__/
+*egg-info/
\ No newline at end of file
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 000000000..4e2ef6557
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,107 @@
+repos:
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v4.3.0
+ hooks:
+ - id: check-ast
+ - id: sort-simple-yaml
+ - id: check-yaml
+ exclude: |
+ (?x)^(
+ meta.yaml
+ )$
+ - id: check-xml
+ - id: check-toml
+ - id: check-docstring-first
+ - id: check-json
+ - id: fix-encoding-pragma
+ - id: detect-private-key
+ - id: trailing-whitespace
+ - repo: https://github.com/asottile/add-trailing-comma
+ rev: v3.1.0
+ hooks:
+ - id: add-trailing-comma
+ - repo: https://github.com/pre-commit/mirrors-mypy
+ rev: v1.7.0
+ hooks:
+ - id: mypy
+ exclude:
+ (?x)(
+ pb2\.py$
+ | grpc\.py$
+ | ^docs
+ | \.html$
+ )
+ args: [ --disallow-untyped-defs,
+ --disallow-incomplete-defs,
+ --ignore-missing-imports,
+ --disable-error-code=var-annotated,
+ --disable-error-code=union-attr,
+ --disable-error-code=assignment,
+ --disable-error-code=attr-defined,
+ --disable-error-code=import-untyped,
+ --disable-error-code=truthy-function,
+ --disable-error-code=typeddict-item,
+ --follow-imports=skip,
+ --explicit-package-bases,
+ ]
+ # - repo: https://github.com/numpy/numpydoc
+ # rev: v1.6.0
+ # hooks:
+ # - id: numpydoc-validation
+ - repo: https://github.com/psf/black
+ rev: 23.3.0
+ hooks:
+ - id: black
+ args: [--line-length=79]
+ - repo: https://github.com/PyCQA/flake8
+ rev: 6.1.0
+ hooks:
+ - id: flake8
+ args: ["--extend-ignore=E203"]
+ exclude: ^docs
+ - repo: https://github.com/pylint-dev/pylint
+ rev: v3.0.2
+ hooks:
+ - id: pylint
+ exclude:
+ (?x)(
+ ^docs
+ | pb2\.py$
+ | grpc\.py$
+ | \.demo$
+ | \.md$
+ | \.html$
+ | ^examples/paper_llm_based_algorithm/
+ )
+ args: [
+ --disable=W0511,
+ --disable=W0718,
+ --disable=W0122,
+ --disable=C0103,
+ --disable=R0913,
+ --disable=E0401,
+ --disable=E1101,
+ --disable=C0415,
+ --disable=W0603,
+ --disable=R1705,
+ --disable=R0914,
+ --disable=E0601,
+ --disable=W0602,
+ --disable=W0604,
+ --disable=R0801,
+ --disable=R0902,
+ --disable=R0903,
+ --disable=C0123,
+ --disable=W0231,
+ --disable=W1113,
+ --disable=W0221,
+ --disable=R0401,
+ --disable=W0632,
+ --disable=W0123,
+ --disable=C3001,
+ ]
+ - repo: https://github.com/regebro/pyroma
+ rev: "4.0"
+ hooks:
+ - id: pyroma
+ args: [--min=10, .]
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..d4ceb5f47
--- /dev/null
+++ b/README.md
@@ -0,0 +1,269 @@
+[**中文主页**](https://github.com/agentscope-ai/agentscope/blob/main/README_ZH.md) | [**Tutorial**](https://doc.agentscope.io/) | [**Roadmap**](https://github.com/agentscope-ai/agentscope/blob/main/docs/ROADMAP.md) | [**FAQ**](https://doc.agentscope.io/tutorial/faq.html)
+
+<p align="center">
+ <img
+ src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg"
+ alt="AgentScope Logo"
+ width="200"
+ />
+</p>
+
+<h2 align="center">AgentScope: Agent-Oriented Programming for Building LLM Applications</h2>
+
+<p align="center">
+ <a href="https://arxiv.org/abs/2402.14034">
+ <img
+ src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C"
+ alt="arxiv"
+ />
+ </a>
+ <a href="https://pypi.org/project/agentscope/">
+ <img
+ src="https://img.shields.io/badge/python-3.10+-blue?logo=python"
+ alt="pypi"
+ />
+ </a>
+ <a href="https://pypi.org/project/agentscope/">
+ <img
+ src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version"
+ alt="pypi"
+ />
+ </a>
+ <a href="https://doc.agentscope.io/">
+ <img
+ src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown"
+ alt="docs"
+ />
+ </a>
+ <a href="https://agentscope.io/">
+ <img
+ src="https://img.shields.io/badge/GUI-AgentScope_Studio-blue?logo=look&logoColor=green&color=dark-green"
+ alt="workstation"
+ />
+ </a>
+ <a href="./LICENSE">
+ <img
+ src="https://img.shields.io/badge/license-Apache--2.0-black"
+ alt="license"
+ />
+ </a>
+</p>
+
+<p align="center">
+<img src="https://trendshift.io/api/badge/repositories/10079" alt="modelscope%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
+</p>
+
+## ✨ Why AgentScope?
+
+Easy for beginners, powerful for experts.
+
+- **Transparent to Developers**: Transparent is our **FIRST principle**. Prompt engineering, API invocation, agent building, workflow orchestration, all are visible and controllable for developers. No deep encapsulation or implicit magic.
+- **Realtime Steering**: Interrupt the agent at **ANY** time, and **customize** the handling.
+- **Model Agnostic**: Programming once, run with all models.
+- **LEGO-style Agent Building**: All components are **modular** and **independent**.
+- **Multi-Agent Oriented**: Designed for **multi-agent**, **explicit** message passing and workflow orchestration, NO deep encapsulation.
+- **Highly Customizable**: Tools, prompt, agent, workflow, third-party libs & visualization, customization is encouraged everywhere.
+- **Developer-friendly**: Low-code development, visual tracing & monitoring. From developing to deployment, all in one place.
+
+
+Quick overview of AgentScope's new features in v1.0:
+
+| Module | Feature | Tutorial |
+|------------|------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
+| model | Support async invocation | [Model](https://doc.agentscope.io/tutorial/task_model.html) |
+| | Support reasoning model | |
+| | Support streaming/non-streaming returns | |
+| | Support tools API | |
+| tool | Support async/sync tool functions | [Tool](https://doc.agentscope.io/tutorial/task_tool.html) |
+| | Support streaming/non-streaming returns | |
+| | Support user interruption | |
+| | Support post-processing | |
+| | Support group-wise tool management | |
+| | Support agent-controlled tools management | |
+| MCP | Support streamable HTTP/SSE/StdIO transport | [MCP](https://doc.agentscope.io/tutorial/task_mcp.html) |
+| | Support client- & function-level fine-grained control | |
+| agent | Support async execution | |
+| | Support parallel tool calls | |
+| | Support realtime steering interruption and customized handling | |
+| | Support automatic state management | |
+| | Support agent-controlled long-term memory | |
+| | Support agent hooks | |
+| tracing | Support tracing model, agent, tool | [Tracing](https://doc.agentscope.io/tutorial/task_tracing.html) |
+| | Support connecting to third-party tracing platforms (e.g. Arize-Phoenix, Langfuse) | |
+| memory | Support long-term memory | [Memory](https://doc.agentscope.io/tutorial/task_long_term_memory.html) |
+| session | Provide session/application-level state management | [Session](https://doc.agentscope.io/tutorial/task_state.html) |
+| evaluation | Provide distributed and parallel evaluation | [Evaluation](https://doc.agentscope.io/tutorial/task_eval.html) |
+| formatter | Support multi-agent prompt formatting with tools API | [Prompt Formatter](https://doc.agentscope.io/tutorial/task_prompt.html) |
+| ... | | |
+
+## 📢 News
+- **[2025-08]** The new tutorial of v1 is online now! Check out the [tutorial](https://doc.agentscope.io) for more details.
+- **[2025-08]** 🎉🎉 AgentScope v1 is released now! This version fully embraces the asynchronous execution, providing many new features and improvements. Check out [changelog](https://github.com/agentscope-ai/agentscope/blob/main/docs/changelog.md) for detailed changes.
+
+## 💬 Contact
+
+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/i1/O1CN01LxzZha1thpIN2cc2E_!!6000000005934-2-tps-497-477.png" width="100" height="100"> |
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 🚀 Quickstart
+
+### 💻 Installation
+
+> AgentScope requires **Python 3.10** or higher.
+
+#### 🛠️ From source
+
+```bash
+# Pull the source code from GitHub
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+
+# Install the package in editable mode
+cd agentscope
+pip install -e .
+```
+
+#### 📦 From PyPi
+
+```bash
+pip install agentscope
+```
+
+## 👋 Hello AgentScope!
+
+Start with a conversation between user and a ReAct agent 🤖 named "Friday"!
+
+```python
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.model import DashScopeChatModel
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.tool import Toolkit, execute_python_code, execute_shell_command
+import os, asyncio
+
+
+async def main():
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+ toolkit.register_tool_function(execute_shell_command)
+
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You're a helpful assistant named Friday.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+
+ user = UserAgent(name="user")
+
+ msg = None
+ while True:
+ msg = await agent(msg)
+ msg = await user(msg)
+ if msg.get_text_content() == "exit":
+ break
+
+asyncio.run(main())
+```
+
+## 📖 Documentation
+
+- Tutorial
+ - [Installation](https://doc.agentscope.io/tutorial/quickstart_installation.html)
+ - [Key Concepts](https://doc.agentscope.io/tutorial/quickstart_key_concept.html)
+ - [Create Message](https://doc.agentscope.io/tutorial/quickstart_message.html)
+ - [ReAct Agent](https://doc.agentscope.io/tutorial/quickstart_agent.html)
+- Workflow
+ - [Conversation](https://doc.agentscope.io/tutorial/workflow_conversation.html)
+ - [Multi-Agent Debate](https://doc.agentscope.io/tutorial/workflow_multiagent_debate.html)
+ - [Concurrent Agents](https://doc.agentscope.io/tutorial/workflow_concurrent_agents.html)
+ - [Routing](https://doc.agentscope.io/tutorial/workflow_routing.html)
+ - [Handoffs](https://doc.agentscope.io/tutorial/workflow_handoffs.html)
+- FAQ
+ - [FAQ](https://doc.agentscope.io/tutorial/faq.html)
+- Task Guides
+ - [Model](https://doc.agentscope.io/tutorial/task_model.html)
+ - [Prompt Formatter](https://doc.agentscope.io/tutorial/task_prompt.html)
+ - [Tool](https://doc.agentscope.io/tutorial/task_tool.html)
+ - [Memory](https://doc.agentscope.io/tutorial/task_memory.html)
+ - [Long-Term Memory](https://doc.agentscope.io/tutorial/task_long_term_memory.html)
+ - [Agent](https://doc.agentscope.io/tutorial/task_agent.html)
+ - [State/Session Management](https://doc.agentscope.io/tutorial/task_state.html)
+ - [Agent Hooks](https://doc.agentscope.io/tutorial/task_hook.html)
+ - [MCP](https://doc.agentscope.io/tutorial/task_mcp.html)
+ - [AgentScope Studio](https://doc.agentscope.io/tutorial/task_studio.html)
+ - [Tracing](https://doc.agentscope.io/tutorial/task_tracing.html)
+ - [Evaluation](https://doc.agentscope.io/tutorial/task_eval.html)
+ - [Embedding](https://doc.agentscope.io/tutorial/task_embedding.html)
+ - [Token](https://doc.agentscope.io/tutorial/task_token.html)
+- API
+ - [API Docs](https://doc.agentscope.io/api/agentscope.html)
+
+
+## 💻 AgentScope Studio
+
+Use the following command to install and start AgentScope Studio, to trace and visualize your agent application.
+
+```bash
+npm install -g @agentscope/studio
+
+as_studio
+```
+
+## ⚖️ License
+
+AgentScope is released under Apache License 2.0.
+
+## 📚 Publications
+
+If you find our work helpful for your research or application, please cite our papers.
+
+[AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
+
+```
+@article{agentscope,
+ author = {Dawei Gao and
+ Zitao Li and
+ Xuchen Pan and
+ Weirui Kuang and
+ Zhijian Ma and
+ Bingchen Qian and
+ Fei Wei and
+ Wenhao Zhang and
+ Yuexiang Xie and
+ Daoyuan Chen and
+ Liuyi Yao and
+ Hongyi Peng and
+ Ze Yu Zhang 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},
+}
+```
+
+## ✨ Contributors
+
+All thanks to our contributors:
+
+<a href="https://github.com/agentscope-ai/agentscope/graphs/contributors">
+ <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" />
+</a>
\ No newline at end of file
diff --git a/README_zh.md b/README_zh.md
new file mode 100644
index 000000000..7bd18d168
--- /dev/null
+++ b/README_zh.md
@@ -0,0 +1,269 @@
+[**English Homepage**](https://github.com/agentscope-ai/agentscope/blob/main/README.md) | [**Tutorial**](https://doc.agentscope.io/zh_CN/) | [**Roadmap**](https://github.com/agentscope-ai/agentscope/blob/main/docs/ROADMAP.md) | [**FAQ**](https://doc.agentscope.io/zh_CN/tutorial/faq.html)
+
+<p align="center">
+ <img
+ src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg"
+ alt="AgentScope Logo"
+ width="200"
+ />
+</p>
+
+<h2 align="center">AgentScope: Agent-Oriented Programming for Building LLM Applications</h2>
+
+<p align="center">
+ <a href="https://arxiv.org/abs/2402.14034">
+ <img
+ src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C"
+ alt="arxiv"
+ />
+ </a>
+ <a href="https://pypi.org/project/agentscope/">
+ <img
+ src="https://img.shields.io/badge/python-3.10+-blue?logo=python"
+ alt="pypi"
+ />
+ </a>
+ <a href="https://pypi.org/project/agentscope/">
+ <img
+ src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version"
+ alt="pypi"
+ />
+ </a>
+ <a href="https://doc.agentscope.io/">
+ <img
+ src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown"
+ alt="docs"
+ />
+ </a>
+ <a href="https://agentscope.io/">
+ <img
+ src="https://img.shields.io/badge/GUI-AgentScope_Studio-blue?logo=look&logoColor=green&color=dark-green"
+ alt="workstation"
+ />
+ </a>
+ <a href="./LICENSE">
+ <img
+ src="https://img.shields.io/badge/license-Apache--2.0-black"
+ alt="license"
+ />
+ </a>
+</p>
+
+<p align="center">
+<img src="https://trendshift.io/api/badge/repositories/10079" alt="modelscope%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
+</p>
+
+## ✨ Why AgentScope?
+
+浅显入门,精深致用。
+
+- **对开发者透明**: 透明是 AgentScope 的**首要原则**。无论提示工程、API调用、智能体构建还是工作流程编排,坚持对开发者可见&可控。拒绝深度封装或隐式魔法。
+- **实时引导**: 支持在**任意**时刻打断智能体回复,并支持**自定义**处理方式。
+- **模型无关**: 一次编程,适配所有模型。
+- **“乐高式”智能体构建**: 所有组件保持**模块化**且**相互独立**。
+- **面向多智能体**:专为**多智能体**设计,**显式**的消息传递和工作流编排,拒绝深度封装。
+- **高度可定制**: 工具、提示、Agent、工作流、第三方库和可视化,AgentScope 支持&鼓励开发者进行定制。
+- **开发者友好**: 低代码开发,可视化追踪和监控。从开发到部署,一站式解决。
+
+AgentScope v1.0 新功能概览:
+
+| 模块 | 功能 | 文档 |
+|------------|-------------------------------------|-------------------------------------------------------------------------------|
+| model | 支持异步调用 | [Model](https://doc.agentscope.io/zh_CN/tutorial/task_model.html) |
+| | 支持推理模型 | |
+| | 支持流式/非流式返回 | |
+| | 支持工具API | |
+| tool | 支持异步/同步工具函数 | [Tool](https://doc.agentscope.io/zh_CN/tutorial/task_tool.html) |
+| | 支持工具函数流式/非流式返回 | |
+| | 支持用户打断 | |
+| | 支持工具函数的后处理 | |
+| | 支持分组工具管理 | |
+| | 允许智能体自主管理工具 | |
+| MCP | 支持 Streamable HTTP/SSE/StdIO 传输 | [MCP](https://doc.agentscope.io/zh_CN/tutorial/task_mcp.html) |
+| | 支持函数级别的精细控制 | |
+| agent | 支持异步执行 | |
+| | 支持并行工具调用 | |
+| | 支持用户实时中断和自定义的中断处理 | |
+| | 支持自动状态管理 | |
+| | 允许智能体自主控制长期记忆 | |
+| | 支持智能体钩子函数 | |
+| tracing | 支持追踪模型、智能体、工具 | [Tracing](https://doc.agentscope.io/zh_CN/tutorial/task_tracing.html) |
+| | 支持连接到第三方平台(如Arize-Phoenix、Langfuse) | |
+| memory | 支持长期记忆 | [Memory](https://doc.agentscope.io/zh_CN/tutorial/task_long_term_memory.html) |
+| session | 提供会话/应用级状态管理 | [Session](https://doc.agentscope.io/zh_CN/tutorial/task_state.html) |
+| evaluation | 提供分布式和并行评估 | [Evaluation](https://doc.agentscope.io/zh_CN/tutorial/task_eval.html) |
+| formatter | 支持多Agent提示格式化与工具API | [Prompt Formatter](https://doc.agentscope.io/zh_CN/tutorial/task_prompt.html) |
+| ... | | |
+
+## 📢 新闻
+- **[2025-08]** v1 版本 Tutorial 已上线!查看[tutorial](https://doc.agentscope.io)了解更多详情。
+- **[2025-08]** 🎉🎉 AgentScope v1现已发布!在完全拥抱异步执行的基础上提供许多新功能和改进。查看[changelog](https://github.com/agentscope-ai/agentscope/blob/main/docs/changelog.md)了解详细变更。
+
+## 💬 联系我们
+
+欢迎加入我们的社区,获取最新的更新和支持!
+
+| [Discord](https://discord.gg/eYMpfnkG8h) | 钉钉 |
+|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| <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/i1/O1CN01LxzZha1thpIN2cc2E_!!6000000005934-2-tps-497-477.png" width="100" height="100"> |
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 🚀 快速开始
+
+### 💻 安装
+
+> AgentScope需要**Python 3.10**或更高版本。
+
+#### 🛠️ 从源码安装
+
+```bash
+# 从 GitHub 拉取源码
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+
+# 以可编辑模式安装包
+cd agentscope
+pip install -e .
+```
+
+#### 📦 从PyPi安装
+
+```bash
+pip install agentscope
+```
+
+## 👋 Hello AgentScope!
+
+使用 AgentScope 显式地创建一个名为“Friday”的助手🤖,并与之对话。
+
+```python
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.model import DashScopeChatModel
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.tool import Toolkit, execute_python_code, execute_shell_command
+import os, asyncio
+
+
+async def main():
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+ toolkit.register_tool_function(execute_shell_command)
+
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You're a helpful assistant named Friday.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+
+ user = UserAgent(name="user")
+
+ msg = None
+ while True:
+ msg = await agent(msg)
+ msg = await user(msg)
+ if msg.get_text_content() == "exit":
+ break
+
+asyncio.run(main())
+```
+
+## 📖 文档
+
+- 教程
+ - [安装](https://doc.agentscope.io/zh_CN/tutorial/quickstart_installation.html)
+ - [核心概念](https://doc.agentscope.io/zh_CN/tutorial/quickstart_key_concept.html)
+ - [创建消息](https://doc.agentscope.io/zh_CN/tutorial/quickstart_message.html)
+ - [ReAct Agent](https://doc.agentscope.io/zh_CN/tutorial/quickstart_agent.html)
+- 工作流
+ - [对话(Conversation)](https://doc.agentscope.io/zh_CN/tutorial/workflow_conversation.html)
+ - [多智能体辩论(Multi-Agent Debate)](https://doc.agentscope.io/zh_CN/tutorial/workflow_multiagent_debate.html)
+ - [智能体并发(Concurrent Agents)](https://doc.agentscope.io/zh_CN/tutorial/workflow_concurrent_agents.html)
+ - [路由(Routing)](https://doc.agentscope.io/zh_CN/tutorial/workflow_routing.html)
+ - [交接(Handoffs)](https://doc.agentscope.io/zh_CN/tutorial/workflow_handoffs.html)
+- 常见问题
+ - [FAQ](https://doc.agentscope.io/zh_CN/tutorial/faq.html)
+- 任务指南
+ - [模型](https://doc.agentscope.io/zh_CN/tutorial/task_model.html)
+ - [提示格式化器](https://doc.agentscope.io/zh_CN/tutorial/task_prompt.html)
+ - [工具](https://doc.agentscope.io/zh_CN/tutorial/task_tool.html)
+ - [记忆](https://doc.agentscope.io/zh_CN/tutorial/task_memory.html)
+ - [长期记忆](https://doc.agentscope.io/zh_CN/tutorial/task_long_term_memory.html)
+ - [智能体](https://doc.agentscope.io/zh_CN/tutorial/task_agent.html)
+ - [管道(Pipeline)](https://doc.agentscope.io/zh_CN/tutorial/task_pipeline.html)
+ - [状态/会话管理](https://doc.agentscope.io/zh_CN/tutorial/task_state.html)
+ - [智能体钩子函数](https://doc.agentscope.io/zh_CN/tutorial/task_hook.html)
+ - [MCP](https://doc.agentscope.io/zh_CN/tutorial/task_mcp.html)
+ - [AgentScope Studio](https://doc.agentscope.io/zh_CN/tutorial/task_studio.html)
+ - [追踪](https://doc.agentscope.io/zh_CN/tutorial/task_tracing.html)
+ - [智能体评测](https://doc.agentscope.io/zh_CN/tutorial/task_eval.html)
+ - [嵌入(Embedding)](https://doc.agentscope.io/zh_CN/tutorial/task_embedding.html)
+ - [Token计数](https://doc.agentscope.io/zh_CN/tutorial/task_token.html)
+- API
+ - [API文档](https://doc.agentscope.io/zh_CN/api/agentscope.html)
+
+## 💻 AgentScope Studio
+
+使用以下命令安装并启动 AgentScope Studio,以追踪和可视化您的Agent应用。
+
+```bash
+npm install -g @agentscope/studio
+
+as_studio
+```
+
+## ⚖️ 许可
+
+AgentScope 基于 Apache License 2.0发布。
+
+## 📚 论文
+
+如果我们的工作对您的研究或应用有帮助,请引用我们的论文。
+
+[AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
+
+```
+@article{agentscope,
+ author = {Dawei Gao and
+ Zitao Li and
+ Xuchen Pan and
+ Weirui Kuang and
+ Zhijian Ma and
+ Bingchen Qian and
+ Fei Wei and
+ Wenhao Zhang and
+ Yuexiang Xie and
+ Daoyuan Chen and
+ Liuyi Yao and
+ Hongyi Peng and
+ Ze Yu Zhang 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},
+}
+```
+
+## ✨ 贡献者
+
+感谢所有贡献者:
+
+<a href="https://github.com/agentscope-ai/agentscope/graphs/contributors">
+ <img src="https://contrib.rocks/image?repo=modelscope/agentscope&max=999&columns=12&anon=1" />
+</a>
+
diff --git a/docs/.DS_Store b/docs/.DS_Store
new file mode 100644
index 000000000..882742d92
Binary files /dev/null and b/docs/.DS_Store differ
diff --git a/docs/changelog.md b/docs/changelog.md
new file mode 100644
index 000000000..6b69714b5
--- /dev/null
+++ b/docs/changelog.md
@@ -0,0 +1,98 @@
+# CHANGELOG of v1.0.0
+
+> ➡️ change; ✅ new feature; ❌ deprecate
+
+The overall changes from v0.x.x to v1.0.0 are summarized below.
+
+## Overview
+- ✅ Support asynchronous execution throughout the library
+- ✅ Support tools API thoroughly
+
+
+## ✨Session
+- ✅ Support automatic state management
+- ✅ Support session/application-level state management
+
+
+## ✨Tracing
+- ✅ Support OpenTelemetry-based tracing
+- ✅ Support third-party tracing platforms, e.g. Arize-Phoenix, Langfuse, etc.
+
+
+## ✨MCP
+- ✅ Support both client- and function-level control over MCP by a new MCP module
+- ✅ Support both "pay-as-you-go" and persistent session management
+- ✅ Support streamable HTTP, SSE and StdIO transport protocols
+
+
+## ✨Memory
+- ✅ Support long-term memory by providing a `LongTermMemoryBase` class
+- ✅ Provide a Mem0-based long-term memory implementation
+- ✅ Support both static- and agent-controlled long-term memory modes
+
+
+## Formatter
+- ✅ Support prompt construction/formatting with token count estimation
+- ✅ Support tools API in multi-agent prompt formatting
+
+
+## Model
+- ❌ Deprecate model configuration, use explicit object instantiation instead
+- ✅ Provide a new `ModelResponse` class for structured model responses
+- ✅ Support asynchronous model invocation
+- ✅ Support reasoning models
+- ✅ Support any combination of streaming/non-streaming, reasoning/non-reasoning and tools API
+
+
+## Agent
+- ❌ Deprecate `DialogAgent`, `DictDialogAgent` and prompt-based ReAct agent class
+- ➡️ Expose memory, formatter interfaces to the agent's constructor in ReActAgent
+- ➡️ Unify the signature of pre- and post- agent hooks
+- ✅ Support pre-/post-reasoning and pre-/post-acting hooks in ReActAgent class
+- ✅ Support asynchronous agent execution
+- ✅ Support interrupting agent's replying and customized interruption handling
+- ✅ Support automatic state management
+- ✅ Support parallel tool calls
+- ✅ Support two-modes long-term memory in ReActAgent class
+
+
+## Tool
+- ✅ Provide a more powerful `Toolkit` class for tools management
+- ✅ Provide a new `ToolResponse` class for structured and multimodal tool responses
+- ✅ Support group-wise tool management
+- ✅ Support agent to manage tools by itself
+- ✅ Support post-processing of tool responses
+- Tool function
+ - ✅ Support both async and sync functions
+ - ✅ Support both streaming and non-streaming return
+
+
+## Evaluation
+- ✅ Support ReAct agent-oriented evaluation
+- ✅ Support Ray-based distributed and concurrent evaluation
+- ✅ Support statistical analysis over evaluation results
+
+
+## AgentScope Studio
+- ✅ Support runtime tracing
+- ✅ Provide a built-in copilot agent named Friday
+
+
+## Logging
+- ❌ Deprecate `loguru` and use Python native `logging` module instead
+
+
+## Distribution
+- ❌ Deprecate distribution functionality momentarily, a new distribution module is coming soon
+
+
+## RAG
+- ❌ Deprecate RAG functionality momentarily, a new RAG module is coming soon
+
+
+## Parsers
+- ❌ Deprecate parsers module
+
+
+## WebBrowser
+- ❌ Deprecate the `WebBrowser` class and shift to MCP-based web browsing
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 000000000..779e018a2
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,49 @@
+# Roadmap
+
+## Long-term Goals
+
+Offering **agent-oriented programming (AOP)** as a new programming paradigm to organize the design and implementation of next-generation LLM-empowered applications.
+
+## Short-term Goals
+
+### AgentScope V1.0.0 Roadmap
+
+We are deeply grateful for the continuous support from the open-source community that has witnessed AgentScope's
+growth. Throughout our journey, we have maintained **developer-centric transparency** as our core principle,
+which will continue to guide our future development.
+
+As the AI agent ecosystem rapidly evolves, we recognize the need to adapt AgentScope to meet emerging trends and
+requirements. We are excited to announce the upcoming release of AgentScope v1.0.0, which marks a significant shift
+towards deployment-focused and secondary development direction. This new version will provide comprehensive support for agent developers
+with enhanced deployment capabilities and practical features. Specifically, the update will include:
+
+- ✨New Features
+ - 🛠️ Tool/MCP
+ - Support both sync/async tool functions
+ - Support streaming tool function
+ - Support parallel execution of tool functions
+ - Provide more flexible support for the MCP server
+
+ - 💾 Memory
+ - Enhance the existing short-term memory
+ - Support long-term memory
+
+ - 🤖 Agent
+ - Provide powerful ReAct-based out-of-the-box agents
+
+- 👨‍💻 Development
+ - Provide enhanced AgentScope Studio with visual components for developing, tracing and debugging
+ - Provide a built-in copilot for developing/drafting AgentScope applications
+
+- 🔍 Evaluation
+ - Provide built-in benchmarking and evaluation toolkit for agents
+ - Support result visualization
+
+- 🏗️ Deployment
+ - Support asynchronous agent execution
+ - Support session/state management
+ - Provide sandbox for tool execution
+
+Stay tuned for our detailed release notes and beta version, which will be available soon. Follow our GitHub
+repository and official channels for the latest updates. We look forward to your valuable feedback and continued
+support in shaping the future of AgentScope.
\ No newline at end of file
diff --git a/docs/tutorial/.DS_Store b/docs/tutorial/.DS_Store
new file mode 100644
index 000000000..589172ecb
Binary files /dev/null and b/docs/tutorial/.DS_Store differ
diff --git a/docs/tutorial/_static/.DS_Store b/docs/tutorial/_static/.DS_Store
new file mode 100644
index 000000000..2a5ad157f
Binary files /dev/null and b/docs/tutorial/_static/.DS_Store differ
diff --git a/docs/tutorial/_static/css/gallery.css b/docs/tutorial/_static/css/gallery.css
new file mode 100644
index 000000000..bedf6e4cc
--- /dev/null
+++ b/docs/tutorial/_static/css/gallery.css
@@ -0,0 +1,147 @@
+.sphx-glr-download-link-note.admonition.note {
+ display: none;
+}
+
+.sphx-glr-download {
+ display: none;
+}
+
+.bordered-image {
+ border: 1px solid #e5e5e5;
+}
+
+:root {
+ --item-card-width: 200px;
+ --item-card-margin: 10px;
+ --item-card-title-height: 50px;
+
+ --item-card-img-length: calc(var(--item-card-width) - 2*var(--item-card-margin));
+ --item-card-title-width: calc(var(--item-card-width) - 2*var(--item-card-margin));
+ --item-card-title-margin-top: var(--item-card-margin);
+
+ --item-card-height: calc(var(--item-card-margin) * 3 + var(--item-card-img-length) + var(--item-card-title-height));
+}
+
+td .highlight-python.notranslate {
+ margin-bottom: 0 !important;
+}
+
+/*cite {*/
+/* background: rgba(229, 229, 229, 0.69) !important;*/
+/* padding-left: 0.25rem !important;*/
+/* padding-right: 0.25rem !important;*/
+/* border-radius: 4px !important;*/
+/* font-style: normal !important;*/
+/* font-weight: 600 !important;*/
+/*}*/
+
+.sidebar-brand-text {
+ display: flex;
+ justify-content: center;
+}
+
+.sidebar-logo-container {
+ height: 100px;
+ width: 100%;
+ .sidebar-logo {
+ width: 100px;
+ height: 100%;
+ }
+}
+
+.gallery-item {
+ position: relative;
+ display: inline-block;
+ width: var(--item-card-width);
+ height: var(--item-card-height);
+ box-shadow: 0 0 8px rgba(0, 0, 0, 0.2);
+ margin: 7px;
+}
+
+.docutils.align-default {
+ white-space: normal !important;
+ max-width: 100% !important;
+ width: 100% !important;
+ td {
+ white-space: normal !important;
+ }
+}
+
+.sphx-glr-script-out.highlight-none.notranslate .highlight pre{
+ /*正常打印回车*/
+ white-space: pre-wrap !important;
+ /*white-space: normal !important;*/
+ max-width: 100% !important;
+ width: 100% !important;
+}
+
+.gallery-item-card {
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: var(--item-card-width);
+ height: var(--item-card-height);
+ display: flex;
+ flex-direction: column;
+ margin: var(--item-card-margin);
+}
+
+.gallery-item-card-img {
+ height: var(--item-card-img-length);
+ width: var(--item-card-img-length);
+ min-width: var(--item-card-img-length);
+ min-height: var(--item-card-img-length);
+ display: block;
+}
+
+.gallery-item-card-title {
+ text-align: center;
+ margin-top: var(--item-card-margin);
+ font-weight: bold;
+ min-height: var(--item-card-title-height);
+ height: var(--item-card-title-height);
+ width: var(--item-card-title-width);
+ display: flex;
+ align-items: center;
+ justify-content: center;
+}
+
+.gallery-item-description {
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100%;
+ height: 100%;
+ background-color: rgba(255, 255, 255, 0.9);
+ /*background-color: #1e8449;*/
+ color: black;
+ display: none;
+ justify-content: center;
+ align-items: flex-start;
+}
+
+.gallery-item:hover .gallery-item-description {
+ display: flex;
+ padding: 10px;
+ border: 1px solid rgba(0, 0, 0, 0.22);
+}
+
+.language-switch-button {
+ background: transparent;
+ display: flex;
+ align-content: center;
+ justify-content: center;
+ font-size: 15px;
+ margin-top: 0;
+ margin-bottom: 4px;
+ border: none;
+ color: rgb(4, 4, 4);
+ height: 20px;
+ width: 20px;
+ border-radius: 6px;
+ font-weight: 325;
+}
+
+.language-switch-button:hover {
+ color: #2758DA;
+}
\ No newline at end of file
diff --git a/docs/tutorial/_static/images/embedding_cache.png b/docs/tutorial/_static/images/embedding_cache.png
new file mode 100644
index 000000000..91372fd77
Binary files /dev/null and b/docs/tutorial/_static/images/embedding_cache.png differ
diff --git a/docs/tutorial/_static/images/evaluation.png b/docs/tutorial/_static/images/evaluation.png
new file mode 100644
index 000000000..8776f3983
Binary files /dev/null and b/docs/tutorial/_static/images/evaluation.png differ
diff --git a/docs/tutorial/_static/images/handoffs.png b/docs/tutorial/_static/images/handoffs.png
new file mode 100644
index 000000000..6518a57e9
Binary files /dev/null and b/docs/tutorial/_static/images/handoffs.png differ
diff --git a/docs/tutorial/_static/images/interruption_en.gif b/docs/tutorial/_static/images/interruption_en.gif
new file mode 100644
index 000000000..67d312e20
Binary files /dev/null and b/docs/tutorial/_static/images/interruption_en.gif differ
diff --git a/docs/tutorial/_static/images/interruption_zh.gif b/docs/tutorial/_static/images/interruption_zh.gif
new file mode 100644
index 000000000..b33815f4a
Binary files /dev/null and b/docs/tutorial/_static/images/interruption_zh.gif differ
diff --git a/docs/tutorial/_static/images/logo.png b/docs/tutorial/_static/images/logo.png
new file mode 100644
index 000000000..93bed0036
Binary files /dev/null and b/docs/tutorial/_static/images/logo.png differ
diff --git a/docs/tutorial/_static/images/logo.svg b/docs/tutorial/_static/images/logo.svg
new file mode 100644
index 000000000..e781d9c87
--- /dev/null
+++ b/docs/tutorial/_static/images/logo.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="none" version="1.1" width="550" height="550" viewBox="0 0 550 550"><defs><linearGradient x1="0.01500389538705349" y1="0.4831196665763855" x2="0.9407116114637801" y2="0.3076102348892569" id="master_svg0_8_2390"><stop offset="0%" stop-color="#01C5FF" stop-opacity="1"/><stop offset="100%" stop-color="#019DFB" stop-opacity="1"/></linearGradient><linearGradient x1="0.21085502207279205" y1="0.38703426718711853" x2="0.9523109409029081" y2="0.390888421140005" id="master_svg1_8_1638"><stop offset="0%" stop-color="#4701EF" stop-opacity="1"/><stop offset="100%" stop-color="#395EEF" stop-opacity="1"/></linearGradient></defs><g><g></g><g><g><path d="M275.4998779296875,211.25Q275.4998779296875,279.5,373.4999779296875,310.5Q338.4998779296875,287.5,343.9998779296875,232Q344.4969779296875,227.19400000000002,345.9004779296875,222.498Q352.96577792968753,198.857,382.9998779296875,178L415.9998779296875,193.5L469.7738779296875,193.5C477.0958779296875,193.5,481.9218779296875,185.91559999999998,478.3148779296875,179.543Q441.5068779296875,114.5,372.9998779296875,114.5C343.9998779296875,114.5,275.4998779296875,143,275.4998779296875,211.25Z" fill="url(#master_svg0_8_2390)" fill-opacity="1"/></g><g><path d="M343.9999162890625,231.99999791015625Q337.9999162890625,287.5000079101562,373.5000462890625,310.5000079101562L433.4998462890625,333.00010791015626Q449.4994462890625,314.2500079101562,449.4994462890625,295.5000079101562Q449.4994462890625,276.7500079101562,433.4998462890625,258.0000079101562L345.9004862890625,222.49810791015625Q344.4970462890625,227.19412791015625,343.9999162890625,231.99999791015625Z" fill="#0064FC" fill-opacity="1"/></g><g><path d="M122.9998779296875,351.5C124.3900479296875,350.6567,125.7727179296875,349.8325,127.1479779296875,349.0269Q125.0392779296875,350.2098,122.9998779296875,351.5ZM127.1479779296875,349.0269Q150.3716779296875,336,181.9998779296875,336C186.2692779296875,335.7983,190.4211779296875,335.9808,194.4638779296875,336.502C250.5488779296875,343.7327,285.6218779296875,416.14300000000003,321.9998779296875,432Q350.1248779296875,444,377.9998779296875,444Q405.8748779296875,444,433.4998779296875,432Q489.9998779296875,400,489.9998779296875,344.5Q489.9998779296875,283,433.4998779296875,258Q449.4998779296875,276.75,449.4998779296875,295.5Q449.4998779296875,314.25,433.4998779296875,333C394.3168779296875,374.257,360.65987792968747,359.947,319.4498779296875,342.4251C286.9518779296875,328.6077,249.7568779296875,312.7935,201.4527779296875,320.6594C179.2413779296875,324.2763,154.6808779296875,332.9,127.1479779296875,349.0269Z" fill="url(#master_svg1_8_1638)" fill-opacity="1"/></g><g><path d="M61,437.99973876953123L133.8305,437.99973876953123C141.5661,437.99973876953123,148.608,433.53913876953123,151.9131,426.54513876953126L194.464,336.50202976953125C190.421,335.98083496953126,186.269,335.79829376953126,182,335.99999996953125Q147.4999,335.99999996953125,122.9999,351.5000387695313C93.5,373.5000387695313,87,387.0000387695313,61,437.99973876953123Z" fill="#0064FC" fill-opacity="1"/></g><g><path d="M61,438.00038301849366C87,387.00038301849366,93.5,373.50038301849366,122.9999,351.50038301849366C152.2215,333.77438301849367,178.132,324.45738301849366,201.453,320.65938301849366L256.597,207.04148301849364C259.081,201.92438301849364,259.26800000000003,195.99188301849364,257.11199999999997,190.72838301849367L227.948,119.52337301849366C225.653,113.91851301849366,217.805,113.67667301849366,215.169,119.12954301849365L61,438.00038301849366Z" fill="#01C8FF" fill-opacity="1"/></g></g></g></svg>
\ No newline at end of file
diff --git a/docs/tutorial/_static/images/multiagent_msgs.png b/docs/tutorial/_static/images/multiagent_msgs.png
new file mode 100644
index 000000000..27995e126
Binary files /dev/null and b/docs/tutorial/_static/images/multiagent_msgs.png differ
diff --git a/docs/tutorial/_static/images/sequential_hook.png b/docs/tutorial/_static/images/sequential_hook.png
new file mode 100644
index 000000000..983d3c07b
Binary files /dev/null and b/docs/tutorial/_static/images/sequential_hook.png differ
diff --git a/docs/tutorial/_static/images/studio_home.webp b/docs/tutorial/_static/images/studio_home.webp
new file mode 100644
index 000000000..60b8b9884
Binary files /dev/null and b/docs/tutorial/_static/images/studio_home.webp differ
diff --git a/docs/tutorial/_static/images/studio_project.webp b/docs/tutorial/_static/images/studio_project.webp
new file mode 100644
index 000000000..9a516aabe
Binary files /dev/null and b/docs/tutorial/_static/images/studio_project.webp differ
diff --git a/docs/tutorial/_static/images/studio_run.webp b/docs/tutorial/_static/images/studio_run.webp
new file mode 100644
index 000000000..e80e50e45
Binary files /dev/null and b/docs/tutorial/_static/images/studio_run.webp differ
diff --git a/docs/tutorial/_static/images/studio_tracing.png b/docs/tutorial/_static/images/studio_tracing.png
new file mode 100644
index 000000000..a49a1f00e
Binary files /dev/null and b/docs/tutorial/_static/images/studio_tracing.png differ
diff --git a/docs/tutorial/_static/language_switch.js b/docs/tutorial/_static/language_switch.js
new file mode 100644
index 000000000..8fb43e27e
--- /dev/null
+++ b/docs/tutorial/_static/language_switch.js
@@ -0,0 +1,7 @@
+function switchLanguage() {
+ if (window.location.href.includes("zh_CN")) {
+ window.location.href = "https://doc.agentscope.io";
+ } else {
+ window.location.href = "https://doc.agentscope.io/zh_CN";
+ }
+}
diff --git a/docs/tutorial/_templates/components/language-switch.html b/docs/tutorial/_templates/components/language-switch.html
new file mode 100644
index 000000000..c146a725c
--- /dev/null
+++ b/docs/tutorial/_templates/components/language-switch.html
@@ -0,0 +1,6 @@
+{# _templates/components/language-switch.html #}
+<button onclick="switchLanguage()" class="language-switch-button" title="Switch to Chinese">
+ <script>
+ document.write(window.location.href.includes("zh_CN") ? "En": "中");
+ </script>
+</button>
\ No newline at end of file
diff --git a/docs/tutorial/_templates/module.rst_t b/docs/tutorial/_templates/module.rst_t
new file mode 100644
index 000000000..74d73a4c5
--- /dev/null
+++ b/docs/tutorial/_templates/module.rst_t
@@ -0,0 +1,5 @@
+{{ basename | heading }}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+ :{{ option }}:
+{%- endfor %}
\ No newline at end of file
diff --git a/docs/tutorial/_templates/package.rst_t b/docs/tutorial/_templates/package.rst_t
new file mode 100644
index 000000000..0c0f707da
--- /dev/null
+++ b/docs/tutorial/_templates/package.rst_t
@@ -0,0 +1,10 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+ :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{{- pkgname | heading }}
+
+{{ automodule(pkgname, automodule_options) }}
\ No newline at end of file
diff --git a/docs/tutorial/_templates/page.html b/docs/tutorial/_templates/page.html
new file mode 100644
index 000000000..b4027017a
--- /dev/null
+++ b/docs/tutorial/_templates/page.html
@@ -0,0 +1,239 @@
+{% extends "base.html" %}
+
+{% block body -%}
+{{ super() }}
+{% include "partials/icons.html" %}
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
+<label class="overlay sidebar-overlay" for="__navigation">
+ <div class="visually-hidden">Hide navigation sidebar</div>
+</label>
+<label class="overlay toc-overlay" for="__toc">
+ <div class="visually-hidden">Hide table of contents sidebar</div>
+</label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">
+ {%- trans -%}
+ Skip to content
+ {%- endtrans -%}
+</a>
+
+{% if theme_announcement -%}
+<div class="announcement">
+ <aside class="announcement-content">
+ {% block announcement %} {{ theme_announcement }} {% endblock announcement %}
+ </aside>
+</div>
+{%- endif %}
+
+<div class="page">
+ <header class="mobile-header">
+ <div class="header-left">
+ <label class="nav-overlay-icon" for="__navigation">
+ <div class="visually-hidden">Toggle site navigation sidebar</div>
+ <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+ </label>
+ </div>
+ <div class="header-center">
+ <a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
+ </div>
+ <div class="header-right">
+ <div class="theme-toggle-container theme-toggle-header">
+ <button class="theme-toggle">
+ <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+ <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+ <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+ <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+ <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+ </button>
+ </div>
+ <label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+ <div class="visually-hidden">Toggle table of contents sidebar</div>
+ <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+ </label>
+ </div>
+ </header>
+ <aside class="sidebar-drawer">
+ <div class="sidebar-container">
+ {% block left_sidebar %}
+ <div class="sidebar-sticky">
+ {%- for sidebar_section in sidebars %}
+ {%- include sidebar_section %}
+ {%- endfor %}
+ </div>
+ {% endblock left_sidebar %}
+ </div>
+ </aside>
+ <div class="main">
+ <div class="content">
+ <div class="article-container">
+ <a href="#" class="back-to-top muted-link">
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+ <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+ </svg>
+ <span>{% trans %}Back to top{% endtrans %}</span>
+ </a>
+ <div class="content-icon-container">
+ {% if theme_top_of_page_button != "edit" -%}
+ {{ warning("Got configuration for 'top_of_page_button': this is deprecated.") }}
+ {%- endif -%}
+
+ {%- if theme_top_of_page_buttons == "" -%}
+ {% if theme_top_of_page_button == None -%}
+ {#- We respect the old configuration of disabling all the buttons -#}
+ {%- set theme_top_of_page_buttons = [] -%}
+ {% else %}
+ {%- set theme_top_of_page_buttons = ["view", "edit"] -%}
+ {%- endif -%}
+ {% else -%}
+ {% if theme_top_of_page_button != "edit" -%}
+ {%- set theme_top_of_page_buttons = [] -%}
+ {{ warning("Got configuration for both 'top_of_page_button' and 'top_of_page_buttons', ignoring both and removing all top of page buttons.") }}
+ {%- endif -%}
+ {%- endif -%}
+ {%- include "components/language-switch.html" with context -%}
+ {% for button in theme_top_of_page_buttons -%}
+ {% if button == "view" %}
+ {%- include "components/view-this-page.html" with context -%}
+ {% elif button == "edit" %}
+ {%- include "components/edit-this-page.html" with context -%}
+ {% else %}
+ {{ warning("Got an unsupported value in 'top_of_page_buttons' for theme configuration") }}
+ {% endif %}
+ {%- endfor -%}
+ {#- Theme toggle -#}
+ <div class="theme-toggle-container theme-toggle-content">
+ <button class="theme-toggle">
+ <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+ <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+ <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
+ <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+ <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+ </button>
+ </div>
+ <label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+ <div class="visually-hidden">Toggle table of contents sidebar</div>
+ <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+ </label>
+ </div>
+ <article role="main" id="furo-main-content">
+ {% block content %}{{ body }}{% endblock %}
+ </article>
+ </div>
+ <footer>
+ {% block footer %}
+ <div class="related-pages">
+ {% if next -%}
+ <a class="next-page" href="{{ next.link }}">
+ <div class="page-info">
+ <div class="context">
+ <span>{{ _("Next") }}</span>
+ </div>
+ <div class="title">{{ next.title }}</div>
+ </div>
+ <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+ </a>
+ {%- endif %}
+ {% if prev -%}
+ <a class="prev-page" href="{{ prev.link }}">
+ <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+ <div class="page-info">
+ <div class="context">
+ <span>{{ _("Previous") }}</span>
+ </div>
+ {% if prev.link == pathto(master_doc) %}
+ <div class="title">{{ _("Home") }}</div>
+ {% else %}
+ <div class="title">{{ prev.title }}</div>
+ {% endif %}
+ </div>
+ </a>
+ {%- endif %}
+ </div>
+ <div class="bottom-of-page">
+ <div class="left-details">
+ {%- if show_copyright %}
+ <div class="copyright">
+ {%- if hasdoc('copyright') %}
+ {% trans path=pathto('copyright'), copyright=copyright|e -%}
+ <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+ {%- endtrans %}
+ {%- else %}
+ {% trans copyright=copyright|e -%}
+ Copyright &#169; {{ copyright }}
+ {%- endtrans %}
+ {%- endif %}
+ </div>
+ {%- endif %}
+ {% trans %}Made with {% endtrans -%}
+ {%- if show_sphinx -%}
+ {% trans %}<a href="https://www.sphinx-doc.org/">Sphinx</a> and {% endtrans -%}
+ <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
+ {% endif -%}
+ {% trans %}
+ <a href="https://github.com/pradyunsg/furo">Furo</a>
+ {% endtrans %}
+ {%- if last_updated -%}
+ <div class="last-updated">
+ {% trans last_updated=last_updated|e -%}
+ Last updated on {{ last_updated }}
+ {%- endtrans -%}
+ </div>
+ {%- endif %}
+ </div>
+ <div class="right-details">
+ {% if theme_footer_icons or READTHEDOCS -%}
+ <div class="icons">
+ {% if theme_footer_icons -%}
+ {% for icon_dict in theme_footer_icons -%}
+ <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
+ {{- icon_dict.html -}}
+ </a>
+ {% endfor %}
+ {%- else -%}
+ {#- Show Read the Docs project -#}
+ {%- if READTHEDOCS and slug -%}
+ <a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
+ <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
+ <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
+ </svg>
+ </a>
+ {%- endif -%}
+ {#- Show GitHub repository home -#}
+ {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
+ <a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
+ <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+ <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+ </svg>
+ </a>
+ {%- endif -%}
+ {%- endif %}
+ </div>
+ {%- endif %}
+ </div>
+ </div>
+ {% endblock footer %}
+ </footer>
+ </div>
+ <aside class="toc-drawer{% if furo_hide_toc %} no-toc{% endif %}">
+ {% block right_sidebar %}
+ {% if not furo_hide_toc %}
+ <div class="toc-sticky toc-scroll">
+ <div class="toc-title-container">
+ <span class="toc-title">
+ {{ _("On this page") }}
+ </span>
+ </div>
+ <div class="toc-tree-container">
+ <div class="toc-tree">
+ {{ toc }}
+ </div>
+ </div>
+ </div>
+ {% endif %}
+ {% endblock right_sidebar %}
+ </aside>
+ </div>
+</div>
+{%- endblock %}
diff --git a/docs/tutorial/en/.DS_Store b/docs/tutorial/en/.DS_Store
new file mode 100644
index 000000000..902c5b486
Binary files /dev/null and b/docs/tutorial/en/.DS_Store differ
diff --git a/docs/tutorial/en/Makefile b/docs/tutorial/en/Makefile
new file mode 100644
index 000000000..92dd33a1a
--- /dev/null
+++ b/docs/tutorial/en/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/tutorial/en/build.sh b/docs/tutorial/en/build.sh
new file mode 100755
index 000000000..40258e648
--- /dev/null
+++ b/docs/tutorial/en/build.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -e
+
+# Generate the API rst files
+sphinx-apidoc -o api ../../../src/agentscope -t ../_templates -e
+
+# Build the html
+sphinx-build -M html ./ build
\ No newline at end of file
diff --git a/docs/tutorial/en/conf.py b/docs/tutorial/en/conf.py
new file mode 100644
index 000000000..568513ffd
--- /dev/null
+++ b/docs/tutorial/en/conf.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "AgentScope"
+copyright = "2025, Alibaba"
+author = "Alibaba Tongyi Lab"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ "myst_parser",
+ "sphinx_gallery.gen_gallery",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.napoleon",
+]
+
+myst_enable_extensions = [
+ "colon_fence",
+]
+
+sphinx_gallery_conf = {
+ "download_all_examples": False,
+ "examples_dirs": [
+ "src",
+ ],
+ "gallery_dirs": [
+ "tutorial",
+ ],
+ "filename_pattern": "src/.*\.py",
+ "example_extensions": [".py"],
+}
+
+templates_path = ["../_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+languages = ["en", "zh_CN"]
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_title = "AgentScope"
+html_logo = "../_static/images/logo.svg"
+html_static_path = ["../_static"]
+html_css_files = [
+ "css/gallery.css",
+]
+
+html_js_files = [
+ "language_switch.js",
+]
+
+source_suffix = [".md", ".rst"]
+
+
+# -- Options for API documentation -------------------------------------------
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_class_signature = "separated"
+autodoc_default_options = {
+ "special-members": "__call__",
+}
+
+add_module_names = False
+python_display_short_literal_types = True
+
+
+def skip_member(app, what, name, obj, skip, options):
+ if name in [
+ "__call__",
+ "_format",
+ "_format_agent_message",
+ "_format_tool_sequence",
+ ]:
+ return False
+
+ return skip
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", skip_member)
diff --git a/docs/tutorial/en/index.rst b/docs/tutorial/en/index.rst
new file mode 100644
index 000000000..4d0669828
--- /dev/null
+++ b/docs/tutorial/en/index.rst
@@ -0,0 +1,71 @@
+.. AgentScope Doc documentation master file, created by
+ sphinx-quickstart on Thu Aug 8 15:07:21 2024.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to AgentScope's documentation!
+==========================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Tutorial
+
+ tutorial/quickstart_installation
+ tutorial/quickstart_key_concept
+ tutorial/quickstart_message
+ tutorial/quickstart_agent
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Workflow
+
+ tutorial/workflow_conversation
+ tutorial/workflow_multiagent_debate
+ tutorial/workflow_concurrent_agents
+ tutorial/workflow_routing
+ tutorial/workflow_handoffs
+
+.. toctree::
+ :maxdepth: 1
+ :caption: FAQ
+
+ tutorial/faq
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Task Guides
+
+ tutorial/task_model
+ tutorial/task_prompt
+ tutorial/task_tool
+ tutorial/task_memory
+ tutorial/task_long_term_memory
+ tutorial/task_agent
+ tutorial/task_pipeline
+ tutorial/task_state
+ tutorial/task_hook
+ tutorial/task_mcp
+ tutorial/task_studio
+ tutorial/task_tracing
+ tutorial/task_eval
+ tutorial/task_embedding
+ tutorial/task_token
+
+.. toctree::
+ :maxdepth: 1
+ :caption: API Docs
+
+ api/agentscope
+ api/agentscope.message
+ api/agentscope.model
+ api/agentscope.formatter
+ api/agentscope.module
+ api/agentscope.pipeline
+ api/agentscope.agent
+ api/agentscope.memory
+ api/agentscope.tool
+ api/agentscope.mcp
+ api/agentscope.token
+ api/agentscope.tracing
+ api/agentscope.session
+ api/agentscope.exception
diff --git a/docs/tutorial/en/make.bat b/docs/tutorial/en/make.bat
new file mode 100644
index 000000000..dc1312ab0
--- /dev/null
+++ b/docs/tutorial/en/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/tutorial/en/src/README.md b/docs/tutorial/en/src/README.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/tutorial/en/src/faq.py b/docs/tutorial/en/src/faq.py
new file mode 100644
index 000000000..9134c8f33
--- /dev/null
+++ b/docs/tutorial/en/src/faq.py
@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+.. _faq:
+
+FAQ
+========================================
+
+About AgentScope
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*What is AgentScope?*
+ AgentScope is a multi-agent framework, aiming to provide a simple yet efficient way to build LLM-empowered agent applications.
+
+*What is the difference between AgentScope v1.0 and v0.x?*
+ AgentScope v1.0 is a complete refactoring of the framework, equipped with new features and improvements. Refer to for detailed changes.
+
+
+About Model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*How to integrate my own model with AgentScope?*
+ Create your own model by inheriting ``agentscope.model.ChatModelBase`` and implement the ``__call__`` method.
+
+*What models are supported by AgentScope?*
+ Currently, AgentScope has built-in support for DashScope, Gemini, OpenAI, Anthropic, and Ollama APIs, and the ``OpenAIChatModel`` compatible with DeepSeek and vLLMs models.
+
+*How to monitor the token usage in AgentScope?*
+ In AgentScope Studio, we provide visualization of token usage and tracing. Refer :ref:`studio` section for more details.
+
+
+About Agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*How to create my own agent?*
+ You can choose to use the ``ReActAgent`` class directly, or create your own agent by inheriting from ``AgentBase`` or ``ReActAgentBase`` classes. Refer to the :ref:`agent` section for more details.
+
+
+*How to forward the (streaming) output of agents to my own frontend or application?*
+ Use the pre hook of the ``print`` function to forward printing messages. Refer to the :ref:`hook` section.
+
+
+About Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*How many tools are provided by AgentScope?*
+ AgentScope provides a set of built-in tools, including ``execute_python_code``, ``execute_shell_command``, ``write_text_file`` , etc. You can find them under ``agentscope.tool`` module.
+
+
+About Reporting Bugs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*How can I report a bug in AgentScope?*
+ If you encounter a bug while using AgentScope, please report it by opening an issue on our GitHub repository.
+
+*How can I report a security bug in AgentScope?*
+ If you discover a security issue in AgentScope, please report it to us through the `Alibaba Security Response Center (ASRC) <https://security.alibaba.com/>`_.
+
+"""
diff --git a/docs/tutorial/en/src/prompt.py b/docs/tutorial/en/src/prompt.py
new file mode 100644
index 000000000..26f3d6ff1
--- /dev/null
+++ b/docs/tutorial/en/src/prompt.py
@@ -0,0 +1,334 @@
+# -*- coding: utf-8 -*-
+"""
+.. _prompt:
+
+Prompt Formatter
+=========================
+
+The formatter module in AgentScope is responsible for
+
+- converting messages into the expected format for different LLM APIs,
+- (optional) truncating messages to fit within token limits,
+- (optional) prompt engineering, e.g. summarizing long conversations.
+
+The last two are optional and can also be handled by developers within the memory or at the agent level.
+
+In AgentScope, there are two types of formatters, "ChatFormatter" and "MultiAgentFormatter", distinguished by the agent identities in their input messages.
+
+- **ChatFormatter**: Designed for standard user-assistant scenario (chatbot), using the ``role`` field to identify the user and assistant.
+- **MultiAgentFormatter**: Designed for multi-agent scenario, use the ``name`` field to identify different agents, which will combine conversation history into a single user message dictionary.
+
+The built-in formatters are listed below
+
+.. list-table:: The built-in formatters in AgentScope
+ :header-rows: 1
+
+ * - API Provider
+ - User-assistant Scenario
+ - Multi-Agent Scenario
+ * - OpenAI
+ - ``OpenAIChatFormatter``
+ - ``OpenAIMultiAgentFormatter``
+ * - Anthropic
+ - ``AnthropicChatFormatter``
+ - ``AnthropicMultiAgentFormatter``
+ * - DashScope
+ - ``DashScopeChatFormatter``
+ - ``DashScopeMultiAgentFormatter``
+ * - Gemini
+ - ``GeminiChatFormatter``
+ - ``GeminiChatFormatter``
+ * - Ollama
+ - ``OllamaChatFormatter``
+ - ``OllamaMultiAgentFormatter``
+ * - DeedSeek
+ - ``DeepSeekChatFormatter``
+ - ``DeepSeekMultiAgentFormatter``
+ * - vLLM
+ - ``OpenAIChatFormatter``
+ - ``OpenAIMultiAgentFormatter``
+
+.. tip:: The OpenAI API supports the `name` field, so that `OpenAIChatFormatter` can also be used in multi-agent scenario. You can also use the `OpenAIMultiAgentFormatter` instead, which combine conversation history into a single user message.
+
+Besides, the built-in formatters support to convert different message blocks into the expected format for the target API, which are list below:
+
+.. list-table:: The supported message blocks in the built-in formatters
+ :header-rows: 1
+
+ * - Formatter
+ - tool_use/result
+ - image
+ - audio
+ - video
+ - thinking
+ * - ``OpenAIChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``DashScopeChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``DashScopeMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``AnthropicChatFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ - ✅
+ * - ``AnthropicMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ - ✅
+ * - ``GeminiChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ -
+ * - ``GeminiMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ -
+ * - ``OllamaChatFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ -
+ * - ``OllamaMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ -
+ * - ``DeepSeekChatFormatter``
+ - ✅
+ - ❌
+ - ❌
+ - ❌
+ -
+ * - ``DeepSeekMultiAgentFormatter``
+ - ✅
+ - ❌
+ - ❌
+ - ❌
+ -
+
+.. note:: As stated in the `official documentation <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_, only Anthropic suggests to preserve the thinking blocks in prompt formatting. For the others, we just ignore the thinking blocks in the input messages.
+
+ReAct-Oriented Formatting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The built-in formatters are all designed to support ReAct-style agents, where the input messages **consist of alternating conversation history and tool call sequences**.
+
+In user-assistant scenario, the conversation history includes the user and assistant messages, we just convert them into the expected format directly.
+However, in multi-agent scenario, the conversation history is a list of messages from different agents as follows:
+
+.. figure:: ../../_static/images/multiagent_msgs.png
+ :alt: example of multiagent messages
+ :width: 85%
+ :align: center
+
+ *Example of multi-agent messages*
+
+
+Therefore, we have to merge the conversation history into a single user message with tags "<history>" and "</history>".
+Taking DashScope as an example, the formatted message will look like this:
+"""
+
+from agentscope.token import HuggingFaceTokenCounter
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg, ToolResultBlock, ToolUseBlock, TextBlock
+import asyncio, json
+
+
+input_msgs = [
+ # System prompt
+ Msg("system", "You're a helpful assistant named Friday", "system"),
+ # Conversation history
+ Msg("Bob", "Hi, Alice, do you know the nearest library?", "assistant"),
+ Msg(
+ "Alice",
+ "Sorry, I don't know. Do you have any idea, Charlie?",
+ "assistant",
+ ),
+ Msg(
+ "Charlie",
+ "No, let's ask Friday. Friday, get me the nearest library.",
+ "assistant",
+ ),
+ # Tool sequence
+ Msg(
+ "Friday",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ name="get_current_location",
+ id="1",
+ input={},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ name="get_current_location",
+ id="1",
+ output=[TextBlock(type="text", text="104.48, 36.30")],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "Friday",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ name="search_around",
+ id="2",
+ input={"location": [104.48, 36.30], "keyword": "library"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ name="search_around",
+ id="2",
+ output=[TextBlock(type="text", text="[...]")],
+ ),
+ ],
+ "system",
+ ),
+ # Conversation history continues
+ Msg("Friday", "The nearest library is ...", "assistant"),
+ Msg("Bob", "Thanks, Friday!", "user"),
+ Msg("Alice", "Let's go together.", "user"),
+]
+
+
+async def run_formatter_example() -> list[dict]:
+ """Example of how to format multi-agent messages."""
+ formatter = DashScopeMultiAgentFormatter()
+ formatted_message = await formatter.format(input_msgs)
+ print("The formatted message:")
+ print(json.dumps(formatted_message, indent=4))
+ return formatted_message
+
+
+formatted_message = asyncio.run(run_formatter_example())
+
+# %%
+# Specifically, the conversation histories are formatted into:
+#
+print("The first conversation history:")
+print(formatted_message[1]["content"])
+
+print("\nThe second conversation history:")
+print(formatted_message[-1]["content"])
+
+# %%
+# Truncation-based Formatting
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# With the token module in AgentScope, the built-in formatters support to truncate the input messages by **deleting the oldest messages** (except the system prompt message) when the token exceeds the limit.
+#
+# Taking OpenAIFormatter as an example, we first calculate the total number of tokens of the input messages.
+#
+
+
+async def run_token_counter() -> int:
+ """Compute the token number of the input messages."""
+ # We use huggingface token counter for dashscope models.
+ token_counter = HuggingFaceTokenCounter(
+ "Qwen/Qwen2.5-VL-3B-Instruct",
+ use_mirror=True,
+ )
+
+ return await token_counter.count(formatted_message)
+
+
+n_tokens = asyncio.run(run_token_counter())
+print("The tokens in the formatted messages are: ", n_tokens)
+
+
+# %%
+# Then we set the maximum token limit to 20 tokens less than the total number of tokens and run the formatter.
+#
+
+
+async def run_truncated_formatter() -> None:
+ """Example of how to format messages with truncation."""
+ token_counter = HuggingFaceTokenCounter(
+ pretrained_model_name_or_path="Qwen/Qwen2.5-VL-3B-Instruct",
+ use_mirror=True,
+ )
+ formatter = DashScopeMultiAgentFormatter(
+ token_counter=token_counter,
+ max_tokens=n_tokens - 20,
+ )
+ truncated_formatted_message = await formatter.format(input_msgs)
+ n_truncated_tokens = await token_counter.count(truncated_formatted_message)
+ print("The tokens after truncation: ", n_truncated_tokens)
+
+ print("\nThe conversation history after truncation:")
+ print(truncated_formatted_message[1]["content"])
+
+
+asyncio.run(run_truncated_formatter())
+
+# %%
+# We can see the first two messages from Bob and Alice are removed to fit within the context length limits.
+#
+#
+# Customizing Formatter
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope provides two base classes ``FormatterBase`` and its child class ``TruncatedFormatterBase``.
+# The ``TruncatedFormatterBase`` class provides the FIFO truncation strategy, and all the built-in formatters are inherited from it.
+#
+# .. list-table:: The base classes of formatters in AgentScope
+# :header-rows: 1
+#
+# * - Class
+# - Abstract Method
+# - Description
+# * - ``FormatterBase``
+# - ``format``
+# - Format the input ``Msg`` objects into the expected format for the target API
+# * - ``TruncatedFormatterBase``
+# - ``_format_agent_message``
+# - Format the agent messages, which may contain multiple identities in multi-agent scenario
+# * -
+# - ``_format_tool_sequence``
+# - Format the tool use and result sequence into the expected format
+# * -
+# - ``_format`` (optional)
+# - Format the input ``Msg`` objects into the expected format for the target API
+#
+# .. tip:: - The ``_format`` in ``TruncatedFormatterBase`` groups input messages into agent messages and tool sequences, and then format them by calling ``_format_agent_message`` and ``_format_tool_sequence`` respectively. You can override it to implement your own formatting strategy.
+# - Optionally, you can override the ``_truncate`` method in ``TruncatedFormatterBase`` to implement your own truncation strategy.
+#
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`token`
+# - :ref:`model`
+#
diff --git a/docs/tutorial/en/src/quickstart_agent.py b/docs/tutorial/en/src/quickstart_agent.py
new file mode 100644
index 000000000..f2d6a1989
--- /dev/null
+++ b/docs/tutorial/en/src/quickstart_agent.py
@@ -0,0 +1,239 @@
+# -*- coding: utf-8 -*-
+"""
+.. _react-agent:
+
+Create ReAct Agent
+====================
+
+AgentScope provides out-of-the-box ReAct agent ``ReActAgent`` under ``agentscope.agent`` that can be used directly.
+
+It supports the following features at the same time:
+
+- ✨ Basic features
+ - Support **hooks** around ``reply``, ``observe``, ``print``, ``_reasoning`` and ``_acting`` functions
+ - Support structured output
+- ✋ Realtime Steering
+ - Support user **interrupt**
+ - Support customized **interruption handling**
+- 🛠️ Tools
+ - Support both **sync/async** tool functions
+ - Support **streaming** tool response
+ - Support **stateful** tools management
+ - Support **parallel** tool calls
+ - Support **MCP** server
+- 💾 Memory
+ - Support **agent-controlled** long-term memory management
+ - Support static long-term memory management
+
+.. tip:: Refer to the :ref:`agent` section for more details about these
+ features. In quickstart, we focus on how to create a ReAct agent and run it.
+
+"""
+
+from agentscope.agent import ReActAgent, AgentBase
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+import asyncio
+import os
+
+from agentscope.tool import Toolkit, execute_python_code
+
+
+# %%
+# Creating ReAct Agent
+# ------------------------------
+# To improve the flexibility, the ``ReActAgent`` class exposes the following parameters in its constructor:
+#
+# .. list-table:: Initialization parameters of ``ReActAgent`` class
+# :header-rows: 1
+#
+# * - Parameter
+# - Further Reading
+# - Description
+# * - ``name`` (required)
+# -
+# - The name of the agent
+# * - ``sys_prompt`` (required)
+# -
+# - The system prompt of the agent
+# * - ``model`` (required)
+# - :ref:`model`
+# - The model used by the agent to generate responses
+# * - ``formatter`` (required)
+# - :ref:`prompt`
+# - The prompt construction strategy, should be consisted with the model
+# * - ``toolkit``
+# - :ref:`tool`
+# - The toolkit to register/call tool functions.
+# * - ``memory``
+# - :ref:`memory`
+# - The short-term memory used to store the conversation history
+# * - ``long_term_memory``
+# - :ref:`long-term-memory`
+# - The long-term memory
+# * - ``long_term_memory_mode``
+# - :ref:`long-term-memory`
+# - The mode of the long-term memory:
+#
+# - ``agent_control``: allow agent to control the long-term memory by itself
+# - ``static_control``: retrieving and recording from/to long-term memory will happen in the beginning/end of each reply.
+# - ``both``: active the above two modes at the same time
+# * - ``enable_meta_tool``
+# - :ref:`tool`
+# - Whether to enable the meta tool, which allows the agent to manage tools by itself
+# * - ``parallel_tool_calls``
+# - :ref:`agent`
+# - Whether to allow parallel tool calls
+# * - ``max_iters``
+# -
+# - The maximum number of iterations for the agent to generate a response
+#
+# Taking DashScope API as example, we create an agent object as follows:
+
+
+async def creating_react_agent() -> None:
+ """Create a ReAct agent and run a simple task."""
+ # Prepare tools
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+
+ jarvis = ReActAgent(
+ name="Jarvis",
+ sys_prompt="You're a helpful assistant named Jarvis",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ enable_thinking=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+ )
+
+ msg = Msg(
+ name="user",
+ content="Hi! Jarvis, run Hello World in Python.",
+ role="user",
+ )
+
+ await jarvis(msg)
+
+
+asyncio.run(creating_react_agent())
+
+# %%
+# Creating From Scratch
+# --------------------------------
+# You may want to create an agent from scratch, AgentScope provides two base classes for you to inherit from:
+#
+# .. list-table::
+# :header-rows: 1
+#
+# * - Class
+# - Abstract Methods
+# - Description
+# * - ``AgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``handle_interrupt``
+# - - The base class for all agents, supporting pre- and post- hooks around ``reply``, ``observe`` and ``print`` functions.
+# - Implement the realtime steering within the ``__call__`` method.
+# * - ``ReActAgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``handle_interrupt``
+# | ``_reasoning``
+# | ``_acting``
+# - Add two abstract functions ``_reasoning`` and ``_acting`` on the basis of ``AgentBase``, as well as their hooks.
+#
+# Please refer to the :ref:`agent` section for more details about the agent class.
+#
+# Taking the ``AgentBase`` class as an example, we can create a custom agent
+# class by inheriting from it and implementing the ``reply`` method.
+
+
+class MyAgent(AgentBase):
+ """A custom agent class"""
+
+ def __init__(self) -> None:
+ """Initialize the agent"""
+ super().__init__()
+
+ self.name = "Friday"
+ self.sys_prompt = "You're a helpful assistant named Friday."
+ self.model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ )
+ self.formatter = DashScopeChatFormatter()
+ self.memory = InMemoryMemory()
+
+ async def reply(self, msg: Msg | list[Msg] | None) -> Msg:
+ """Reply to the message."""
+ await self.memory.add(msg)
+
+ # Prepare the prompt
+ prompt = await self.formatter.format(
+ [
+ Msg("system", self.sys_prompt, "system"),
+ *await self.memory.get_memory(),
+ ],
+ )
+
+ # Call the model
+ response = await self.model(prompt)
+
+ msg = Msg(
+ name=self.name,
+ content=response.content,
+ role="assistant",
+ )
+
+ # Record the response in memory
+ await self.memory.add(msg)
+
+ # Print the message
+ await self.print(msg)
+ return msg
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Observe the message."""
+ # Store the message in memory
+ await self.memory.add(msg)
+
+ async def handle_interrupt(self) -> Msg:
+ """Postprocess the interrupt."""
+ # Taking a fixed response as example
+ return Msg(
+ name=self.name,
+ content="I noticed you interrupted me, how can I help you?",
+ role="assistant",
+ )
+
+
+async def run_custom_agent() -> None:
+ """Run the custom agent."""
+ agent = MyAgent()
+ msg = Msg(
+ name="user",
+ content="Who are you?",
+ role="user",
+ )
+ await agent(msg)
+
+
+asyncio.run(run_custom_agent())
+
+# %%
+#
+# Further Reading
+# ---------------------
+# - :ref:`agent`
+# - :ref:`model`
+# - :ref:`prompt`
+# - :ref:`tool`
+#
diff --git a/docs/tutorial/en/src/quickstart_installation.py b/docs/tutorial/en/src/quickstart_installation.py
new file mode 100644
index 000000000..90cae53f3
--- /dev/null
+++ b/docs/tutorial/en/src/quickstart_installation.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""
+.. _installation:
+
+Installation
+============================
+
+AgentScope requires Python 3.10 or higher. You can install from source or pypi.
+
+From PyPI
+----------------
+.. code-block:: bash
+
+ pip install agentscope
+
+From Source
+----------------
+To install AgentScope from source, you need to clone the repository from
+GitHub and install by the following commands
+
+.. code-block:: bash
+
+ git clone -b main https://github.com/agentscope-ai/agentscope
+ cd agentscope
+ pip install -e .
+
+To ensure AgentScope is installed successfully, check via executing the following code:
+"""
+
+import agentscope
+
+print(agentscope.__version__)
+
+# %%
+# Extra Dependencies
+# ----------------------------
+#
+# To satisfy the requirements of different functionalities, AgentScope provides
+# extra dependencies that can be installed based on your needs.
+#
+# - full: Including extra dependencies for model APIs and tool functions
+# - dev: Development dependencies, including testing and documentation tools
+#
+# For example, when installing the full dependencies, the installation command varies depending on your operating system.
+#
+# For Windows users:
+#
+# .. code-block:: bash
+#
+# pip install agentscope[full]
+#
+# For Mac and Linux users:
+#
+# .. code-block:: bash
+#
+# pip install agentscope\[full\]
diff --git a/docs/tutorial/en/src/quickstart_key_concept.py b/docs/tutorial/en/src/quickstart_key_concept.py
new file mode 100644
index 000000000..f3cc7aefd
--- /dev/null
+++ b/docs/tutorial/en/src/quickstart_key_concept.py
@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""
+.. key-concepts:
+
+Key Concepts
+====================================
+
+This chapter establishes key concepts from an engineering
+perspective to introduce AgentScope's design.
+
+.. note:: The goal of introducing the key concepts in AgentScope is to claim what practical problems AgentScope addresses and how it supports developers, rather than to offer formal definitions.
+
+State
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In AgentScope, state management is a fundamental building block that maintains snapshots of objects' runtime data.
+
+AgentScope separates object initialization from state management, allowing
+object to be restored to different states after initialization through
+``load_state_dict`` and ``state_dict`` methods.
+
+In AgentScope, agent, memory, long-term memory and toolkit are all stateful
+objects. AgentScope links the state management of these objects together by supporting nested state management.
+
+Message
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In AgentScope, message is the fundamental data structure,
+used to
+
+- exchange information between agents,
+- display information in the user interface,
+- store information in memory,
+- act as a unified medium between AgentScope and different LLM APIs.
+
+Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A tool in AgentScope refers to callable object, no matter it's a
+
+- function,
+- partial function,
+- instance method,
+- class method,
+- static method, or
+- callable instance with ``__call__`` method.
+
+Besides, the callable object can be either
+
+- async or sync,
+- streaming or non-streaming.
+
+So feel free to use any callable object as a tool in AgentScope.
+
+Agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In AgentScope, the agent behaviors are abstracted into three core functions in
+``AgentBase`` class:
+
+- ``reply``: Handle incoming message(s) and generate a response message.
+- ``observe``: Receive message(s) from the environment or other agents without returning a response.
+- ``print``: Display message(s) to the target terminal, web interface, etc.
+
+To support realtime steering, an additional ``handle_interrupt`` function is
+provided to handle user interrupts during the agent's reply process.
+
+Additionally, ReAct agent is the most important agent in AgentScope, where
+the agent's reply process is divided into two stages:
+
+- reasoning: thinking and generating tool calls by calling the LLM
+- acting: execute the tool functions.
+
+Thus, we provide two additional core functions in ``ReActAgentBase`` class,
+``_reasoning`` and ``_acting``.
+
+Formatter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Formatter is the core component for LLM compatibility in AgentScope,
+responsible for converting message objects into the required format for
+LLM APIs.
+
+Besides, additional functionality such as prompt engineering, truncation,
+and message validation can also be implemented in the formatter.
+
+Within the formatter, the "multi-agent" (or "multi-identity") concept differs
+from the common multi-agent orchestration concept.
+It focuses on the scenario where multiple identities are involved in the
+given messages, so that the common used ``role`` field (usually "role",
+"assistant" or "system") in LLM APIs cannot distinguish them.
+
+Therefore, AgentScope provides multi-agent formatter to handle
+this scenario, usually used in games, multi-person chats, and social
+simulations.
+
+.. note:: Multi-agent workflow **!=** multi-agent in formatter.
+ For example, even if the following code snippet may involve multiple
+ agents (the ``tool_agent`` and the ``tool_function`` caller), the input query
+ is wrapped into a **user** message, so the ``role`` field can still distinguish
+ between them.
+
+ .. code-block:: python
+
+ async def tool_function(query: str) -> str:
+ \"\"\"Tool function calling another agent\"\"\"
+ msg = Msg("user", query, role="user")
+ tool_agent = Agent(name="Programmer")
+ return await tool_agent(msg)
+
+ Understanding this distinction helps developers better grasp AgentScope's formatter design.
+
+
+Long-Term Memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Although providing different base classes for short- and
+long-term memory, there are no strict distinctions between them in AgentScope.
+
+In our view, everything should be **requirement-driven**. As long as your
+needs are excellently met, developers can completely use just one powerful
+memory system.
+
+For ensuring the flexibility of AgentScope, we provide a two mode long-term
+memory system, allowing the agent to manage (record and retrieve) the
+long-term memory by its own.
+"""
diff --git a/docs/tutorial/en/src/quickstart_message.py b/docs/tutorial/en/src/quickstart_message.py
new file mode 100644
index 000000000..cf6bad84c
--- /dev/null
+++ b/docs/tutorial/en/src/quickstart_message.py
@@ -0,0 +1,267 @@
+# -*- coding: utf-8 -*-
+"""
+.. _message:
+
+Create Message
+====================
+
+Message is the core concept in AgentScope, used to support multimodal data, tools API, information storage/exchange and prompt construction.
+
+A message consists of four fields:
+
+- ``name``,
+- ``role``,
+- ``content``, and
+- ``metadata``
+
+The types and descriptions of these fields are as follows:
+
+.. list-table:: The fields in a message object
+ :header-rows: 1
+
+ * - Field
+ - Type
+ - Description
+ * - name
+ - ``str``
+ - The name/identity of the message sender
+ * - role
+ - | ``Literal[``
+ | ``"system",``
+ | ``"assistant",``
+ | ``"user"``
+ | ``]``
+ - The role of the message sender, which must be one of "system", "assistant", or "user".
+ * - content
+ - ``str | list[ContentBlock]``
+ - The data of the message, which can be a string or a list of blocks.
+ * - metadata
+ - ``dict[str, JSONSerializableObject] | None``
+ - A dict containing additional metadata about the message, usually used for structured output.
+
+.. tip:: - In application with multiple identities, the ``name`` field is used to distinguish between different identities.
+ - The ``metadata`` field is recommended for structured output, which won't be included in the prompt construction.
+
+Next, we introduce the supported blocks in the ``content`` field by their corresponding scenarios.
+"""
+
+from agentscope.message import (
+ Msg,
+ Base64Source,
+ TextBlock,
+ ThinkingBlock,
+ ImageBlock,
+ AudioBlock,
+ VideoBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+import json
+
+# %%
+# Creating Textual Message
+# -----------------------------
+# Creating a message object by providing the ``name``, ``role``, and ``content`` fields.
+#
+
+msg = Msg(
+ name="Jarvis",
+ role="assistant",
+ content="Hi! How can I help you?",
+)
+
+print(f"The name of the sender: {msg.name}")
+print(f"The role of the sender: {msg.role}")
+print(f"The content of the message: {msg.content}")
+
+# %%
+# Creating Multimodal Message
+# --------------------------------------
+# The message class supports multimodal content by providing different content blocks:
+#
+# .. list-table:: Multimodal content blocks in AgentScope
+# :header-rows: 1
+#
+# * - Class
+# - Description
+# - Example
+# * - TextBlock
+# - Pure text data
+# - .. code-block:: python
+#
+# TextBlock(
+# type="text",
+# text="Hello, world!"
+# )
+# * - ImageBlock
+# - The image data
+# - .. code-block:: python
+#
+# ImageBlock(
+# type="image",
+# source=URLSource(
+# type="url",
+# url="https://example.com/image.jpg"
+# )
+# )
+# * - AudioBlock
+# - The audio data
+# - .. code-block:: python
+#
+# AudioBlock(
+# type="audio",
+# source=URLSource(
+# type="url",
+# url="https://example.com/audio.mp3"
+# )
+# )
+# * - VideoBlock
+# - The video data
+# - .. code-block:: python
+#
+# VideoBlock(
+# type="video",
+# source=URLSource(
+# type="url",
+# url="https://example.com/video.mp4"
+# )
+# )
+#
+# For ``ImageBlock``, ``AudioBlock`` and ``VideoBlock``, you can use either a base64 encoded string as the source:
+#
+
+msg = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ TextBlock(
+ type="text",
+ text="This is a multimodal message with base64 encoded data.",
+ ),
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type="image/jpeg",
+ data="/9j/4AAQSkZ...",
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/mpeg",
+ data="SUQzBAAAAA...",
+ ),
+ ),
+ VideoBlock(
+ type="video",
+ source=Base64Source(
+ type="base64",
+ media_type="video/mp4",
+ data="AAAAIGZ0eX...",
+ ),
+ ),
+ ],
+)
+
+# %%
+# Creating Thinking Message
+# --------------------------------------
+# The ``ThinkingBlock`` is to support reasoning models, containing the thinking process of the model.
+#
+
+msg_thinking = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ ThinkingBlock(
+ type="thinking",
+ thinking="I'm building an example for thinking block in AgentScope.",
+ ),
+ TextBlock(
+ type="text",
+ text="This is an example for thinking block.",
+ ),
+ ],
+)
+
+# %%
+# .. _tool-block:
+#
+# Creating Tool Use/Result Message
+# --------------------------------------
+# The ``ToolUseBlock`` and ``ToolResultBlock`` are to support tools API:
+#
+
+msg_tool_call = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ ToolUseBlock(
+ type="tool_use",
+ id="343",
+ name="get_weather",
+ input={
+ "location": "Beijing",
+ },
+ ),
+ ],
+)
+
+msg_tool_res = Msg(
+ name="system",
+ role="system",
+ content=[
+ ToolResultBlock(
+ type="tool_result",
+ id="343",
+ name="get_weather",
+ output="The weather in Beijing is sunny with a temperature of 25°C.",
+ ),
+ ],
+)
+
+
+# %%
+# .. tip:: Refer to the :ref:`tool` section for more information about tools API in AgentScope.
+#
+# Serialization and Deserialization
+# ------------------------------------------------
+# Message object can be serialized and deserialized by ``to_dict`` and ``from_dict`` methods, respectively.
+
+serialized_msg = msg.to_dict()
+
+print(type(serialized_msg))
+print(json.dumps(serialized_msg, indent=4))
+
+# %%
+# Deserialize a message from a string in JSON format.
+
+new_msg = Msg.from_dict(serialized_msg)
+
+print(type(new_msg))
+print(f'The sender of the message: "{new_msg.name}"')
+print(f'The role of the sender: "{new_msg.role}"')
+print(f'The content of the message: "{json.dumps(new_msg.content, indent=4)}"')
+
+# %%
+# Property Functions
+# ------------------------------------------------
+# To ease the use of message object, AgentScope provides these functions:
+#
+# .. list-table:: Functions of the message object
+# :header-rows: 1
+#
+# * - Function
+# - Parameters
+# - Description
+# * - get_text_content
+# - \-
+# - Gather content from all ``TextBlock`` in to a single string (separated by "\\n").
+# * - get_content_blocks
+# - ``block_type``
+# - Return a list of content blocks of the specified type. If ``block_type`` not provided, return content in blocks format.
+# * - has_content_blocks
+# - ``block_type``
+# - Check whether the message has content blocks of the specified type. The ``str`` content is considered as a ``TextBlock`` type.
diff --git a/docs/tutorial/en/src/task_agent.py b/docs/tutorial/en/src/task_agent.py
new file mode 100644
index 000000000..068d8d571
--- /dev/null
+++ b/docs/tutorial/en/src/task_agent.py
@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+"""
+.. _agent:
+
+Agent
+=========================
+
+In this tutorial, we first focus on introducing the ReAct agent in AgentScope,
+then we briefly introduce how to customize your own agent from scratch.
+
+ReAct Agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In AgentScope, the ``ReActAgent`` class integrates various features into a final implementation, including
+
+.. list-table:: Features of ``ReActAgent``
+ :header-rows: 1
+
+ * - Feature
+ - Reference
+ * - Support realtime steering
+ -
+ * - Support parallel tool calls
+ -
+ * - Support structured output
+ -
+ * - Support fine-grained MCP control
+ - :ref:`mcp`
+ * - Support agent-controlled tools management (Meta tool)
+ - :ref:`tool`
+ * - Support self-controlled long-term memory
+ - :ref:`long-term-memory`
+ * - Support automatic state management
+ - :ref:`state`
+
+
+Due to limited space, in this tutorial we only demonstrate the first three
+features of ``ReActAgent`` class, leaving the others to the corresponding sections
+listed above.
+
+"""
+
+import asyncio
+import json
+import os
+from datetime import datetime
+import time
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import TextBlock, Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit, ToolResponse
+
+
+# %%
+# Realtime Steering
+# ---------------------------------------
+#
+# The realtime steering allows user to interrupt the agent's reply at any time,
+# which is implemented based on the asyncio cancellation mechanism.
+#
+# Specifically, when calling the ``interrupt`` method of the agent, it will
+# cancel the current reply task, and execute the ``handle_interrupt`` method
+# for postprocessing.
+#
+# .. hint:: With the feature of supporting streaming tool results in
+# :ref:`tool`, users can interrupt the tool execution if it takes too long or
+# deviates from user expectations by Ctrl+C in the terminal or calling the
+# ``interrupt`` method of the agent in your code.
+#
+# The interruption logic has been implemented in the ``AgentBase`` class as a
+# basic feature, leaving a ``handle_interrupt`` method for users to customize the
+# post-processing of interruption as follows:
+#
+# .. code-block:: python
+#
+# # code snippet of AgentBase
+# class AgentBase:
+# ...
+# async def __call__(self, *args: Any, **kwargs: Any) -> Msg:
+# ...
+# reply_msg: Msg | None = None
+# try:
+# self._reply_task = asyncio.current_task()
+# reply_msg = await self.reply(*args, **kwargs)
+#
+# except asyncio.CancelledError:
+# # Catch the interruption and handle it by the handle_interrupt method
+# reply_msg = await self.handle_interrupt(*args, **kwargs)
+#
+# ...
+#
+# @abstractmethod
+# async def handle_interrupt(self, *args: Any, **kwargs: Any) -> Msg:
+# pass
+#
+#
+# In ``ReActAgent`` class, we return a fixed message "I noticed that you have
+# interrupted me. What can I do for you?" as follows:
+#
+# .. figure:: ../../_static/images/interruption_en.gif
+# :width: 100%
+# :align: center
+# :class: bordered-image
+# :alt: Example of interruption
+#
+# Example of interruption
+#
+# You can override it with your own implementation, for example, calling the LLM
+# to generate a simple response to the interruption.
+#
+#
+# Parallel Tool Calls
+# ----------------------------------------
+# ``ReActAgent`` supports parallel tool calls by providing a ``parallel_tool_calls``
+# argument in its constructor.
+# When multiple tool calls are generated, and ``parallel_tool_calls`` is set to ``True``,
+# they will be executed in parallel by the ``asyncio.gather`` function.
+#
+
+
+# prepare a tool function
+def example_tool_function(tag: str) -> ToolResponse:
+ """A sample example tool function"""
+ start_time = datetime.now().strftime("%H:%M:%S.%f")
+
+ # Sleep for 3 seconds to simulate a long-running task
+ time.sleep(3)
+
+ end_time = datetime.now().strftime("%H:%M:%S.%f")
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Tag {tag} started at {start_time} and ended at {end_time}. ",
+ ),
+ ],
+ )
+
+
+toolkit = Toolkit()
+toolkit.register_tool_function(example_tool_function)
+
+# Create an ReAct agent
+agent = ReActAgent(
+ name="Jarvis",
+ sys_prompt="You're a helpful assistant named Jarvis.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ parallel_tool_calls=True,
+)
+
+
+async def example_parallel_tool_calls() -> None:
+ """Example of parallel tool calls"""
+ # prompt the agent to generate two tool calls at once
+ await agent(
+ Msg(
+ "user",
+ "Generate two tool calls of the 'example_tool_function' function with tag as 'tag1' and 'tag2' AT ONCE so that they can execute in parallel.",
+ "user",
+ ),
+ )
+
+
+asyncio.run(example_parallel_tool_calls())
+
+# %%
+# Structured Output
+# ----------------------------------------
+# To generate a structured output, the ``ReActAgent`` instance receives a child class
+# of the ``pydantic.BaseModel`` as the ``structured_model`` argument in its ``__call__`` function.
+# Then we can get the structured output from the ``metadata`` field of the returned message.
+#
+#
+# Taking introducing Einstein as an example:
+#
+
+# Create an ReAct agent
+agent = ReActAgent(
+ name="Jarvis",
+ sys_prompt="You're a helpful assistant named Jarvis.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ # Preset the generation kwargs to enable parallel tool calls
+ generate_kwargs={
+ "parallel_tool_calls": True,
+ },
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ parallel_tool_calls=True,
+)
+
+
+# The structured model
+class Model(BaseModel):
+ name: str = Field(description="The name of the person")
+ description: str = Field(
+ description="A one-sentence description of the person",
+ )
+ age: int = Field(description="The age")
+ honor: list[str] = Field(description="A list of honors of the person")
+
+
+async def example_structured_output() -> None:
+ """The example structured output"""
+ res = await agent(
+ Msg(
+ "user",
+ "Introduce Einstein",
+ "user",
+ ),
+ structured_model=Model,
+ )
+ print("\nThe structured output:")
+ print(json.dumps(res.metadata, indent=4))
+
+
+asyncio.run(example_structured_output())
+
+# %%
+# Customizing Agent
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope provides two base classes, ``AgentBase`` and ``ReActAgentBase``, which
+# differ in the abstract methods they define and the hooks they support.
+# Specifically, the ``ReActAgentBase`` extends ``AgentBase`` with additional ``_reasoning`` and ``_acting``
+# abstract methods, as well as their pre- and post- hooks.
+#
+# Developers can choose to inherit from either of these base classes based on their needs.
+# We summarize the agent under ``agentscope.agent`` module as follows:
+#
+# .. list-table:: Agent classes in AgentScope
+# :header-rows: 1
+#
+# * - Class
+# - Abstract Method
+# - Support Hooks
+# - Description
+# * - ``AgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``print``
+# | ``handle_interrupt``
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# - The base class for all agents, providing the basic interface and hooks.
+# * - ``ReActAgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``print``
+# | ``handle_interrupt``
+# | ``_reasoning``
+# | ``_acting``
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# | pre\_/post_reasoning
+# | pre\_/post_acting
+# - The abstract class for ReAct agent, extending ``AgentBase`` with reasoning and acting abstract methods and their hooks.
+# * - ``ReActAgent``
+# - \-
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# | pre\_/post_reasoning
+# | pre\_/post_acting
+# - An implementation of ``ReActAgentBase``
+# * - ``UserAgent``
+# -
+# -
+# - A special agent that represents the user, used to interact with the agent
+#
+#
+#
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`tool`
+# - :ref:`hook`
+#
diff --git a/docs/tutorial/en/src/task_embedding.py b/docs/tutorial/en/src/task_embedding.py
new file mode 100644
index 000000000..258e6d0d5
--- /dev/null
+++ b/docs/tutorial/en/src/task_embedding.py
@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""
+.. _embedding:
+
+Embedding
+=========================
+
+In AgentScope, the embedding module provides a unified interface for vector representation generation, which features:
+
+- Support **caching embeddings** to avoid redundant API calls
+- Support **multiple embedding providers** with a consistent API
+
+AgentScope has built-in embedding classes for the following API providers:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Provider
+ - Class
+ * - OpenAI
+ - ``OpenAITextEmbedding``
+ * - Gemini
+ - ``GeminiTextEmbedding``
+ * - DashScope
+ - ``DashScopeTextEmbedding``
+ * - Ollama
+ - ``OllamaTextEmbedding``
+
+All classes inherit from ``EmbeddingModelBase``, implementing the ``__call__`` method and generating ``EmbeddingResponse`` object with the embeddings and usage information.
+
+Taking the DashScope embedding class as an example, you can use it as follows:
+"""
+
+import asyncio
+import os
+import tempfile
+
+from agentscope.embedding import DashScopeTextEmbedding, FileEmbeddingCache
+
+
+async def example_dashscope_embedding() -> None:
+ """Example usage of DashScope text embedding."""
+ texts = [
+ "What is the capital of France?",
+ "Paris is the capital city of France.",
+ ]
+
+ # Initialize the DashScope text embedding instance
+ embedding_model = DashScopeTextEmbedding(
+ model_name="text-embedding-v2",
+ api_key=os.getenv("DASHSCOPE_API_KEY"),
+ )
+
+ # Get the embedding from the model
+ response = await embedding_model(texts)
+
+ print("The embedding ID: ", response.id)
+ print("The embedding create at: ", response.created_at)
+ print("The embedding usage: ", response.usage)
+ print("The embedding:")
+ print(response.embeddings)
+
+
+asyncio.run(example_dashscope_embedding())
+
+# %%
+# You can customize your embedding model by subclassing ``EmbeddingModelBase`` and implementing the ``__call__`` method.
+#
+# Embedding Cache
+# ---------------------
+# AgentScope provides a base class ``EmbeddingCacheBase`` for caching embeddings, as well as a file-based implementation ``FileEmbeddingCache``.
+# It works as follows in the embedding module:
+#
+# .. image:: ../../_static/images/embedding_cache.png
+# :align: center
+# :width: 90%
+#
+# To use caching, just pass an instance of ``FileEmbeddingCache`` (or your custom cache) to the embedding model's constructor as follows:
+#
+
+
+async def example_embedding_cache() -> None:
+ """Demonstrate embedding with cache functionality."""
+ # Example texts
+ texts = [
+ "What is the capital of France?",
+ "Paris is the capital city of France.",
+ ]
+
+ # Create a temporary directory for cache demonstration
+ # In real applications, you might want to use a persistent directory
+ cache_dir = tempfile.mkdtemp(prefix="embedding_cache_")
+ print(f"Using cache directory: {cache_dir}")
+
+ # Initialize the embedding model with cache
+ # We limit the cache to 100 files and 10MB for demonstration purposes
+ embedder = DashScopeTextEmbedding(
+ model_name="text-embedding-v3",
+ api_key=os.getenv("DASHSCOPE_API_KEY"),
+ embedding_cache=FileEmbeddingCache(
+ cache_dir=cache_dir,
+ max_file_number=100,
+ max_cache_size=10, # Maximum cache size in MB
+ ),
+ )
+
+ # First call - will fetch from API and store in cache
+ print("\n=== First API Call (No Cache Hit) ===")
+ start_time = asyncio.get_event_loop().time()
+ response1 = await embedder(texts)
+ elapsed_time1 = asyncio.get_event_loop().time() - start_time
+ print(f"Source: {response1.source}") # Should be 'api'
+ print(f"Time taken: {elapsed_time1:.4f} seconds")
+ print(f"Tokens used: {response1.usage.tokens}")
+
+ # Second call with the same texts - should use cache
+ print("\n=== Second API Call (Cache Hit Expected) ===")
+ start_time = asyncio.get_event_loop().time()
+ response2 = await embedder(texts)
+ elapsed_time2 = asyncio.get_event_loop().time() - start_time
+ print(f"Source: {response2.source}") # Should be 'cache'
+ print(f"Time taken: {elapsed_time2:.4f} seconds")
+ print(
+ f"Tokens used: {response2.usage.tokens}",
+ ) # Should be 0 for cached results
+ print(
+ f"Speed improvement: {elapsed_time1 / elapsed_time2:.1f}x faster with cache",
+ )
+
+
+asyncio.run(example_embedding_cache())
diff --git a/docs/tutorial/en/src/task_eval.py b/docs/tutorial/en/src/task_eval.py
new file mode 100644
index 000000000..d7f3902de
--- /dev/null
+++ b/docs/tutorial/en/src/task_eval.py
@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+"""
+.. _eval:
+
+Evaluation
+=========================
+
+AgentScope provides a built-in evaluation framework for assessing agent performance across different tasks and benchmarks, featuring:
+
+- `Ray <https://github.com/ray-project/ray>`_-based parallel and distributed evaluation
+- Support continuation after interruption
+- 🚧 Visualization of evaluation results
+
+.. note:: We are keeping integrating new benchmarks into AgentScope:
+
+ - ✅ `ACEBench <https://github.com/ACEBench/ACEBench>`_
+ - 🚧 `GAIA <https://huggingface.co/datasets/gaia-benchmark/GAIA/tree/main>`_ Benchmark
+
+
+Overview
+---------------------------
+
+The AgentScope evaluation framework consists of several key components:
+
+- **Benchmark**: Collections of tasks for systematic evaluation
+ - **Task**: Individual evaluation units with inputs, ground truth, and metrics
+ - **Metric**: Measurement functions that assess solution quality
+- **Evaluator**: Engine that runs evaluation, aggregates results, and analyzes performance
+ - **Evaluator Storage**: Persistent storage for recording and retrieving evaluation results
+- **Solution**: The user-defined solution
+
+.. figure:: ../../_static/images/evaluation.png
+ :width: 90%
+ :alt: AgentScope Evaluation Framework
+
+ *AgentScope Evaluation Framework*
+
+The current implementation in AgentScope includes:
+
+- Evaluator:
+ - ``RayEvaluator``: A ray-based evaluator that supports parallel and distributed evaluation.
+ - ``GeneralEvaluator``: A general evaluator that runs tasks sequentially, friendly for debugging.
+- Benchmark:
+ - ``ACEBench``: A benchmark for evaluating agent capabilities.
+
+We have provided a toy example in our `GitHub repository <https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench>`_ with ``RayEvaluator`` and the agent multistep tasks in ACEBench.
+
+Core Components
+---------------
+We are going to build a simple toy math question benchmark to demonstrate
+how to use the AgentScope evaluation module.
+"""
+
+TOY_BENCHMARK = [
+ {
+ "id": "math_problem_1",
+ "question": "What is 2 + 2?",
+ "ground_truth": 4.0,
+ "tags": {
+ "difficulty": "easy",
+ "category": "math",
+ },
+ },
+ {
+ "id": "math_problem_2",
+ "question": "What is 12345 + 54321 + 6789 + 9876?",
+ "ground_truth": 83331,
+ "tags": {
+ "difficulty": "medium",
+ "category": "math",
+ },
+ },
+]
+
+# %%
+# From Tasks, Solutions and Metrics to Benchmark
+# ~~~~~~~~~~~~~~~~~~~
+#
+# - A ``SolutionOutput`` contains all information generated by the agent, including the trajectory and final output.
+# - A ``Metric`` represents a single evaluation callable instance that compares the generated solution (e.g., trajectory or final output) to the ground truth.
+# In the toy example, we define a metric that simply checks whether the ``output`` field in the solution matches the ground truth.
+
+from agentscope.evaluate import (
+ SolutionOutput,
+ MetricBase,
+ MetricResult,
+ MetricType,
+)
+
+
+class CheckEqual(MetricBase):
+ def __init__(
+ self,
+ ground_truth: float,
+ ):
+ super().__init__(
+ name="math check number equal",
+ metric_type=MetricType.NUMERICAL,
+ description="Toy metric checking if two numbers are equal",
+ categories=[],
+ )
+ self.ground_truth = ground_truth
+
+ def __call__(
+ self,
+ solution: SolutionOutput,
+ ) -> MetricResult:
+ if solution.output == self.ground_truth:
+ return MetricResult(
+ name=self.name,
+ result=1.0,
+ message="Correct",
+ )
+ else:
+ return MetricResult(
+ name=self.name,
+ result=0.0,
+ message="Incorrect",
+ )
+
+
+# %%
+# - A ``Task`` is a unit in the benchmark that includes all information for the agent to execute and evaluate (e.g., input/query and its ground truth).
+# - A ``Benchmark`` organizes multiple tasks for systematic evaluation.
+
+from typing import Generator
+from agentscope.evaluate import (
+ Task,
+ BenchmarkBase,
+)
+
+
+class ToyBenchmark(BenchmarkBase):
+ def __init__(self):
+ super().__init__(
+ name="Toy bench",
+ description="A toy benchmark for demonstrating the evaluation module.",
+ )
+ self.dataset = self._load_data()
+
+ @staticmethod
+ def _load_data() -> list[Task]:
+ dataset = []
+ for item in TOY_BENCHMARK:
+ dataset.append(
+ Task(
+ id=item["id"],
+ input=item["question"],
+ ground_truth=item["ground_truth"],
+ tags=item.get("tags", {}),
+ metrics=[
+ CheckEqual(item["ground_truth"]),
+ ],
+ metadata={},
+ ),
+ )
+ return dataset
+
+ def __iter__(self) -> Generator[Task, None, None]:
+ """Iterate over the benchmark."""
+ for task in self.dataset:
+ yield task
+
+ def __getitem__(self, index: int) -> Task:
+ """Get a task by index."""
+ return self.dataset[index]
+
+ def __len__(self) -> int:
+ """Get the length of the benchmark."""
+ return len(self.dataset)
+
+
+# %%
+# Evaluators
+# ~~~~~~~~~~
+#
+# Evaluators manage the evaluation process. They can automatically iterate through the
+# tasks in the benchmark and feed each task into a solution-generation function,
+# where developers need to define the logic for running agents and retrieving
+# the execution result and trajectory. Below is an example of
+# running ``GeneralEvaluator`` with our toy benchmark. If there is a large
+# benchmark and the developer wants to get the evaluation more efficiently
+# through parallelization, ``RayEvaluator`` is available as a built-in solution
+# as well.
+
+
+import os
+import asyncio
+from typing import Callable
+from pydantic import BaseModel
+
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.agent import ReActAgent
+
+from agentscope.evaluate import (
+ GeneralEvaluator,
+ FileEvaluatorStorage,
+)
+
+
+class ToyBenchAnswerFormat(BaseModel):
+ answer_as_number: float
+
+
+async def toy_solution_generation(
+ task: Task,
+ pre_hook: Callable,
+) -> SolutionOutput:
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday. "
+ "Your target is to solve the given task with your tools. "
+ "Try to solve the task as best as you can.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ )
+ agent.register_instance_hook(
+ "pre_print",
+ "save_logging",
+ pre_hook,
+ )
+ msg_input = Msg("user", task.input, role="user")
+ res = await agent(
+ msg_input,
+ structured_model=ToyBenchAnswerFormat,
+ )
+ return SolutionOutput(
+ success=True,
+ output=res.metadata.get("answer_as_number", None),
+ trajectory=[],
+ )
+
+
+async def main() -> None:
+ evaluator = GeneralEvaluator(
+ name="ACEbench evaluation",
+ benchmark=ToyBenchmark(),
+ # Repeat how many times
+ n_repeat=1,
+ storage=FileEvaluatorStorage(
+ save_dir="./results",
+ ),
+ # How many workers to use
+ n_workers=1,
+ )
+
+ # Run the evaluation
+ await evaluator.run(toy_solution_generation)
+
+
+asyncio.run(main())
diff --git a/docs/tutorial/en/src/task_hook.py b/docs/tutorial/en/src/task_hook.py
new file mode 100644
index 000000000..410691c0f
--- /dev/null
+++ b/docs/tutorial/en/src/task_hook.py
@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-
+"""
+.. _hook:
+
+Agent Hooks
+===========================
+
+Hooks are extension points in AgentScope that allow developers to customize agent behaviors at specific execution points, providing a flexible way to modify or extend the agent's functionality without changing its core implementation.
+
+In AgentScope, hooks are implemented around the agent's core functions:
+
+
+.. list-table:: Supported hook types in AgentScope
+ :header-rows: 1
+
+ * - Agent Class
+ - Core Function
+ - Hook Types
+ - Description
+ * - | ``AgentBase`` &
+ | its child classes
+ - ``reply``
+ - | ``pre_reply``
+ | ``post_reply``
+ - The hooks before/after agent replying to a message
+ * -
+ - ``print``
+ - | ``pre_print``
+ | ``post_print``
+ - The hook before/after printing a message to the target output (e.g., terminal, web interface)
+ * -
+ - ``observe``
+ - | ``pre_observe``
+ | ``post_observe``
+ - The hooks before/after observing a message from the environment or other agents
+ * - | ``ReActAgentBase`` &
+ | its child classes
+ - | ``reply``
+ | ``print``
+ | ``observe``
+ - | ``pre_reply``
+ | ``post_reply``
+ | ``pre_print``
+ | ``post_print``
+ | ``pre_observe``
+ | ``post_observe``
+ -
+ * -
+ - ``_reasoning``
+ - | ``pre_reasoning``
+ | ``post_reasoning``
+ - The hooks before/after the agent's reasoning process
+ * -
+ - ``_acting``
+ - | ``pre_acting``
+ | ``post_acting``
+ - The hooks before/after the agent's acting process
+
+.. tip:: Since hooks in AgentScope are implemented using a metaclass, they support inheritance.
+
+To simplify the usage, AgentScope provides unified signatures for all hooks.
+
+"""
+import asyncio
+from typing import Any, Type
+
+from agentscope.agent import ReActAgentBase, AgentBase
+from agentscope.message import Msg
+
+
+# %%
+# Hook Signature
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# AgentScope provides unified hook signatures for all pre- and post-hooks as follows:
+#
+# **Pre-Hook Signature**
+#
+# .. list-table:: The signature of all pre-hooks
+# :header-rows: 1
+#
+# * -
+# - Name
+# - Description
+# * - Arguments
+# - ``self: AgentBase | ReActAgentBase``
+# - The agent instance
+# * -
+# - ``kwargs: dict[str, Any]``
+# - | The input arguments of the target
+# | function, or the modified arguments
+# | from the most recent non-None return
+# | value of previous hooks
+# * - Returns
+# - ``dict[str, Any] | None``
+# - The modified arguments or None
+#
+# .. note:: All positional arguments and keyword arguments of the core function are passed as a single ``kwargs`` dict to the hook functions
+#
+# A pre-hook template is defined as follows:
+#
+
+
+def pre_hook_template(
+ self: AgentBase | ReActAgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any] | None: # The modified displayed message
+ """Pre hook template."""
+ pass
+
+
+# %%
+# **Post-Hook Signature**
+#
+# For post hooks, an additional ``output`` argument is added to the signature, which represents the output of the target function.
+# If the core function has no output, the ``output`` argument will be ``None``.
+#
+# .. list-table:: The signature of all post-hooks
+# :header-rows: 1
+#
+# * -
+# - Name
+# - Description
+# * - Arguments
+# - ``self: AgentBase | ReActAgentBase``
+# - The agent instance
+# * -
+# - ``kwargs: dict[str, Any]``
+# - | A dict that contains all the arguments
+# | of the target function
+# * -
+# - ``output: Any``
+# - | The output of the target function or
+# | the most recent non-None return value
+# | from previous hooks
+# * - Returns
+# - ``dict[str, Any] | None``
+# - The modified arguments or None
+#
+
+
+def post_hook_template(
+ self: AgentBase | ReActAgentBase,
+ kwargs: dict[str, Any],
+ output: Any, # The output of the target function
+) -> Any: # The modified output
+ """Post hook template."""
+ pass
+
+
+# %%
+# Hook Management
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# AgentScope provides both instance- and class-level hooks, depending on the effective scope of the hooks.
+# They execute in the following order:
+#
+# .. image:: ../../_static/images/sequential_hook.png
+# :width: 90%
+# :align: center
+# :alt: Hooks in AgentScope
+# :class: bordered-image
+#
+# AgentScope provides built-in methods to manage hooks at both instance and class levels as follows:
+#
+# .. list-table:: Hook management methods in AgentScope
+# :header-rows: 1
+#
+# * - Level
+# - Method
+# - Description
+# * - Instance-level
+# - ``register_instance_hook``
+# - | Register a hook for the current object with
+# | given hook type and name.
+# * -
+# - ``remove_instance_hook``
+# - | Remove a hook for the current object with
+# | given hook type and name.
+# * -
+# - ``clear_instance_hooks``
+# - | Clear all hooks for the current object with
+# | given hook type.
+# * - Class-level
+# - ``register_class_hook``
+# - | Register a hook for all objects of the class
+# | with given hook type and name.
+# * -
+# - ``remove_class_hook``
+# - | Remove a hook for all objects of the class
+# | with given hook type and name.
+# * -
+# - ``clear_class_hooks``
+# - | Clear all hooks for all objects of the
+# | class with given hook type.
+#
+# When using hooks, you MUST follow these rules:
+#
+# .. important:: **Execution Order**
+#
+# - Hooks are executed in registration order
+# - Multiple hooks can be chained together
+# **Return Value Handling**
+#
+# - For pre-hooks: Non-None return values are passed to the next hook or core function
+# - When a hook returns None, the next hook will use the most recent non-None return value from previous hooks
+# - If all previous hooks return None, the next hook receives a copy of the original arguments
+# - The final non-None return value (or original arguments if all hooks return None) is passed to the core function
+# - For post-hooks: Works the same way as pre-hooks.
+# **Important**: Never call the core function (reply/speak/observe/_reasoning/_acting) within a hook to avoid infinite loops
+#
+# Taking the following agent as an example, we can see how to register, remove and clear hooks:
+#
+
+
+# Create a simple test agent class
+class TestAgent(AgentBase):
+ """A test agent for demonstrating hooks."""
+
+ async def reply(self, msg: Msg) -> Msg:
+ """Reply to the message."""
+ return msg
+
+
+# %%
+# We create an instance-level hook and a class-level hook to modify the message content before replying.
+#
+
+
+# Create two pre-reply hooks
+def instance_pre_reply_hook(
+ self: AgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """A pre-reply hook that modifies the message content."""
+ msg = kwargs["msg"]
+ msg.content += "[instance-pre-reply]"
+ # return modified kwargs
+ return {
+ **kwargs,
+ "msg": msg,
+ }
+
+
+def cls_pre_reply_hook(
+ self: AgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """A pre-reply hook that modifies the message content."""
+ msg = kwargs["msg"]
+ msg.content += "[cls-pre-reply]"
+ # return modified kwargs
+ return {
+ **kwargs,
+ "msg": msg,
+ }
+
+
+# Register class hook
+TestAgent.register_class_hook(
+ hook_type="pre_reply",
+ hook_name="test_pre_reply",
+ hook=cls_pre_reply_hook,
+)
+
+# Register instance hook
+agent = TestAgent()
+agent.register_instance_hook(
+ hook_type="pre_reply",
+ hook_name="test_pre_reply",
+ hook=instance_pre_reply_hook,
+)
+
+
+async def example_test_hook() -> None:
+ """An example function to test the hooks."""
+ msg = Msg(
+ name="user",
+ content="Hello, world!",
+ role="user",
+ )
+ res = await agent(msg)
+ print("Response content:", res.content)
+ TestAgent.clear_class_hooks()
+
+
+asyncio.run(example_test_hook())
+
+# %%
+# We can see that a "[instance-pre-reply]" and a "[cls-pre-reply]" are added to the message content.
+#
diff --git a/docs/tutorial/en/src/task_long_term_memory.py b/docs/tutorial/en/src/task_long_term_memory.py
new file mode 100644
index 000000000..817f9dd46
--- /dev/null
+++ b/docs/tutorial/en/src/task_long_term_memory.py
@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""
+.. _long-term-memory:
+
+Long-Term Memory
+========================
+
+In AgentScope, we provide a basic class for long-term memory (``LongTermMemoryBase``) and an implementation based on the `mem0 <https://github.com/mem0ai/mem0>`_ library (``Mem0LongTermMemory``).
+Together with the design of ``ReActAgent`` class in :ref:`agent` section, we provide two long-term memory modes:
+
+- ``agent_control``: the agent autonomously manages long-term memory by tool calls, and
+- ``static_control``: the developer explicitly controls long-term memory operations.
+
+Developers can also use the ``both`` mode, which activates both memory management modes.
+
+.. hint:: These memory modes are suitable for different usage scenarios. Developers can choose the appropriate mode based on their needs.
+
+Using mem0 Long-Term Memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: We provide an example of using mem0 long-term memory in the GitHub repository under the ``examples/long_term_memory/mem0`` directory.
+
+"""
+
+import os
+import asyncio
+
+from agentscope.message import Msg
+from agentscope.memory import InMemoryMemory
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+
+
+# Create mem0 long-term memory instance
+from agentscope.memory import Mem0LongTermMemory
+from agentscope.embedding import DashScopeTextEmbedding
+
+
+long_term_memory = Mem0LongTermMemory(
+ agent_name="Friday",
+ user_name="user_123",
+ model=DashScopeChatModel(
+ model_name="qwen-max-latest",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ stream=False,
+ ),
+ embedding_model=DashScopeTextEmbedding(
+ model_name="text-embedding-v2",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ ),
+ on_disk=False,
+)
+
+# %%
+# The ``Mem0LongTermMemory`` class provides two main methods for long-term memory operations:
+# ``record`` and ``retrieve``.
+# They take a list of messages as input and record/retrieve information from long-term memory.
+#
+# As an example, we first store a user preference and then retrieve related information from long-term memory.
+#
+
+
+# Basic usage example
+async def basic_usage():
+ """Basic usage example"""
+ # Record memory
+ await long_term_memory.record(
+ [Msg("user", "I like staying in homestays", "user")],
+ )
+
+ # Retrieve memory
+ results = await long_term_memory.retrieve(
+ [Msg("user", "My accommodation preferences", "user")],
+ )
+ print(f"Retrieval results: {results}")
+
+
+asyncio.run(basic_usage())
+
+# %%
+# Integration with ReAct Agent
+# ----------------------------------------
+# In AgentScope, the ``ReActAgent`` class receives a ``long_term_memory``
+# parameter in its constructor, as well as a ``long_term_memory_mode`` parameter
+# that specifies the long-term memory mode.
+#
+# If ``long_term_memory_mode`` is set to ``agent_control`` or ``both``, two
+# tool functions ``record_to_memory`` and ``retrieve_from_memory`` will be
+# registered in the agent's toolkit, allowing the agent to autonomously
+# manage long-term memory through tool calls.
+#
+# .. note:: To achieve the best results, the ``"agent_control"`` mode may require
+# additional instructions in the system prompt.
+#
+
+# Create ReAct agent with long-term memory
+agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are an assistant with long-term memory capabilities.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max-latest",
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+ long_term_memory=long_term_memory,
+ long_term_memory_mode="static_control", # Use static_control mode
+)
+
+
+async def record_preferences():
+ """ReAct agent integration example"""
+ # Conversation example
+ msg = Msg(
+ "user",
+ "When I travel to Hangzhou, I like staying in homestays",
+ "user",
+ )
+ await agent(msg)
+
+
+asyncio.run(record_preferences())
+
+# %%
+# Then we clear the short-term memory and ask the agent about the user's preferences.
+#
+
+
+async def retrieve_preferences():
+ """Retrieve user preferences from long-term memory"""
+ # Clear short-term memory
+ await agent.memory.clear()
+ # The agent will remember previous conversations
+ msg2 = Msg("user", "What are my preferences? Answer briefly.", "user")
+ await agent(msg2)
+
+
+asyncio.run(retrieve_preferences())
+
+
+# %%
+# Customizing Long-Term Memory
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope provides the ``LongTermMemoryBase`` base class, which defines the basic
+#
+# Developers can inherit from ``LongTermMemoryBase`` to implement custom long-term
+# memory systems according to their needs:
+#
+# .. list-table:: Long-term memory classes in AgentScope
+# :header-rows: 1
+#
+# * - Class
+# - Abstract Methods
+# - Description
+# * - ``LongTermMemoryBase``
+# - | ``record``
+# | ``retrieve``
+# | ``record_to_memory``
+# | ``retrieve_from_memory``
+# - - For ``"static_control"`` mode, you must implement the ``record`` and ``retrieve`` methods.
+# - For ``"agent_control"`` mode, the ``record_to_memory`` and ``retrieve_from_memory`` methods must be implemented.
+# * - ``Mem0LongTermMemory``
+# - \-
+# - Long-term memory implementation based on the mem0 library, supporting vector storage and retrieval.
+#
+#
+#
+#
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`memory` - Basic memory system
+# - :ref:`agent` - ReAct agent
+# - :ref:`tool` - Tool system
diff --git a/docs/tutorial/en/src/task_mcp.py b/docs/tutorial/en/src/task_mcp.py
new file mode 100644
index 000000000..2db57c1fb
--- /dev/null
+++ b/docs/tutorial/en/src/task_mcp.py
@@ -0,0 +1,206 @@
+# -*- coding: utf-8 -*-
+"""
+.. _mcp:
+
+MCP
+=========================
+
+The tutorial covers the following features of AgentScope in support of the MCP (Model Context Protocol):
+
+- Support both **HTTP** (streamable HTTP and SSE) and **StdIO** MCP servers
+- Provide both **stateful** and **stateless** MCP clients
+- Provide both **server-level** and **function-level** MCP tool management
+
+Here the stateful/stateless distinction refers to whether the client maintains a persistent session with the MCP server or not.
+The table below summarizes the supported MCP client types and protocols:
+
+.. list-table:: Supported MCP client types and protocols
+ :header-rows: 1
+
+ * - Client Type
+ - HTTP (Streamable HTTP and SSE)
+ - StdIO
+ * - Stateful Client
+ - ``HttpStatefulClient``
+ - ``HttpStatelessClient``
+ * - Stateless Client
+ - ``StdIOStatefulClient``
+ -
+
+"""
+import asyncio
+import json
+import os
+
+from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
+from agentscope.tool import Toolkit
+
+# %%
+# MCP Client
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# In AgentScope, MCP clients are responsible for
+#
+# - connecting to the MCP server,
+# - obtaining tool functions from the server, and
+# - calling tool functions in the MCP server.
+#
+# There are two types of MCP clients in AgentScope: **Stateful** and **Stateless**.
+# They only differ in how to manage the session with the MCP server.
+#
+# - Stateful Client: The stateful MCP client **maintains a persistent session** with the MCP server within its lifetime. The developers should explicitly call ``connect()`` and ``close()`` methods to manage the connection lifecycle.
+# - Stateless Client: The stateless MCP client creates a new session when calling the tool function, and destroys the session right after the tool function call, which is much more lightweight.
+#
+# .. note:: - The StdIO MCP server only has stateful client, when ``connect()`` is called, it will start the MCP server locally and then connect to it.
+# - For stateful clients, developers must ensure the client is connected when calling the tool functions.
+#
+# Taking Gaode map MCP server as an example, the creation of stateful and stateless clients are very similar:
+#
+
+stateful_client = HttpStatefulClient(
+ # The name to identify the MCP
+ name="mcp_services_stateful",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+)
+
+stateless_client = HttpStatelessClient(
+ # The name to identify the MCP
+ name="mcp_services_stateless",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+)
+
+# %%
+# Both stateful and stateless clients provide the following methods:
+#
+# .. list-table:: MCP Client Methods
+# :header-rows: 1
+#
+# * - Method
+# - Description
+# * - ``list_tools``
+# - List all tools available in the MCP server.
+# * - ``get_callable_function``
+# - Get a callable function object from the MCP server by its name.
+#
+# MCP as Tool
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope provides fine-grained management of MCP tools, including both server-level and function-level management.
+#
+# Server-Level Management
+# --------------------------------
+# You can register all tools from an MCP server into ``Toolkit`` as follows.
+#
+# .. tip:: Optionally, you can specify a group name to organize the tools. Refer to :ref:`tool` section for group-wise tools management.
+#
+
+toolkit = Toolkit()
+
+
+async def example_register_stateless_mcp() -> None:
+ """Example of registering MCP tools from a stateless client."""
+ # Register all tools from the MCP server
+ await toolkit.register_mcp_client(
+ stateless_client,
+ # group_name="map_services", # Optional group name
+ )
+
+ print(
+ "Total number of MCP tools registered:",
+ len(toolkit.get_json_schemas()),
+ )
+
+ maps_geo = next(
+ tool
+ for tool in toolkit.get_json_schemas()
+ if tool["function"]["name"] == "maps_geo"
+ )
+ print("\nThe example ``maps_geo`` function:")
+ print(
+ json.dumps(
+ maps_geo,
+ indent=4,
+ ensure_ascii=False,
+ ),
+ )
+
+
+asyncio.run(example_register_stateless_mcp())
+
+# %%
+# To remove the registered tools, you can use the ``remove_tool_function`` to remove a specific tool function, or ``remove_mcp_clients`` to remove all tools from a specific MCP.
+#
+
+
+async def example_remove_mcp_tools() -> None:
+ """Example of removing MCP tools."""
+ print(
+ "Total number of tools before removal: ",
+ len(toolkit.get_json_schemas()),
+ )
+
+ # Remove a specific tool function by its name
+ toolkit.remove_tool_function("maps_geo")
+ print("Number of tools: ", len(toolkit.get_json_schemas()))
+
+ # Remove all tools from the MCP client by its name
+ await toolkit.remove_mcp_clients(client_names=["mcp_services_stateless"])
+ print("Number of tools: ", len(toolkit.get_json_schemas()))
+
+
+asyncio.run(example_remove_mcp_tools())
+
+# %%
+# Function-Level Management
+# --------------------------------
+# We notice the demand for more fine-grained control over MCP tools, such as post-processing the tool results, or use them to create a more complex tool function.
+#
+# Therefore, AgentScope supports to obtain the callable function object from MCP by its name, so that you can
+#
+# - call it directly,
+# - wrap it into your own function, or anyway you like.
+#
+# Additionally, you can specify whether to wrap the tool result into ``ToolResponse`` object in AgentScope, so that you can use it seamlessly with the ``Toolkit``.
+# If you set ``wrap_tool_result=False``, the raw result type ``mcp.types.CallToolResult`` will be returned.
+#
+# Taking the ``maps_geo`` function as an example, you can obtain it as a callable function object as follows:
+#
+
+
+async def example_function_level_usage() -> None:
+ """Example of using function-level MCP tool."""
+ func_obj = await stateless_client.get_callable_function(
+ func_name="maps_geo",
+ # Whether to wrap the tool result into ToolResponse in AgentScope
+ wrap_tool_result=True,
+ )
+
+ # You can obtain its name, description and json schema
+ print("Function name:", func_obj.name)
+ print("Function description:", func_obj.description)
+ print(
+ "Function JSON schema:",
+ json.dumps(func_obj.json_schema, indent=4, ensure_ascii=False),
+ )
+
+ # Call the function object directly
+ res = await func_obj(
+ address="Tiananmen Square",
+ city="Beijing",
+ )
+ print("\nFunction call result:")
+ print(res)
+
+
+asyncio.run(example_function_level_usage())
+
+# %%
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# For more details, see:
+#
+# - :ref:`tool`
+# - :ref:`agent`
+#
diff --git a/docs/tutorial/en/src/task_memory.py b/docs/tutorial/en/src/task_memory.py
new file mode 100644
index 000000000..8585d0bb9
--- /dev/null
+++ b/docs/tutorial/en/src/task_memory.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""
+.. _memory:
+
+Memory
+========================
+
+In AgentScope, the memory is used to store the context of the agent, and retrieve it when needed.
+Specifically, AgentScope provides a memory base class ``MemoryBase`` and an in-memory implementation ``InMemoryMemory`` under ``agentscope.memory`` that can be used directly.
+
+Customize Memory
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To customize your own memory, just inherit from ``MemoryBase`` and implement the following methods:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Method
+ - Description
+ * - ``add``
+ - Add ``Msg`` objects to the memory
+ * - ``delete``
+ - Delete items from the memory
+ * - ``size``
+ - The size of the memory
+ * - ``clear``
+ - Clear the memory content
+ * - ``get_memory``
+ - Get the memory content as a list of ``Msg`` objects
+ * - ``state_dict``
+ - Get the state dictionary of the memory
+ * - ``load_state_dict``
+ - Load the state dictionary of the memory
+
+Further Reading
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :ref:`long-term-memory`
+"""
diff --git a/docs/tutorial/en/src/task_model.py b/docs/tutorial/en/src/task_model.py
new file mode 100644
index 000000000..8c8bdc3ac
--- /dev/null
+++ b/docs/tutorial/en/src/task_model.py
@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""
+.. _model:
+
+Model
+====================
+
+In this tutorial, we introduce the model APIs integrated in AgentScope, how to use them and how to integrate new model APIs.
+The supported model APIs and providers include:
+
+.. list-table::
+ :header-rows: 1
+
+ * - API
+ - Class
+ - Compatible
+ - Streaming
+ - Tools
+ - Vision
+ - Reasoning
+ * - OpenAI
+ - ``OpenAIChatModel``
+ - vLLM, DeepSeek
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - DashScope
+ - ``DashScopeChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Anthropic
+ - ``AnthropicChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Gemini
+ - ``GeminiChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Ollama
+ - ``OllamaChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+
+To provide unified model interfaces, the above model classes has the following common methods:
+
+- The first three arguments of the ``__call__`` method are ``messages`` , ``tools`` and ``tool_choice``, representing the input messages, JSON schema of tool functions, and tool selection mode, respectively.
+- The return type are either a ``ChatResponse`` instance or an async generator of ``ChatResponse`` in streaming mode.
+
+.. note:: Different model APIs differ in the input message format, refer to :ref:`prompt` for more details.
+
+The ``ChatResponse`` instance contains the generated thinking/text/tool use content, identity, created time and usage information.
+"""
+import asyncio
+import json
+import os
+
+from agentscope.message import TextBlock, ToolUseBlock, ThinkingBlock, Msg
+from agentscope.model import ChatResponse, DashScopeChatModel
+
+response = ChatResponse(
+ content=[
+ ThinkingBlock(
+ type="thinking",
+ thinking="I should search for AgentScope on Google.",
+ ),
+ TextBlock(type="text", text="I'll search for AgentScope on Google."),
+ ToolUseBlock(
+ type="tool_use",
+ id="642n298gjna",
+ name="google_search",
+ input={"query": "AgentScope?"},
+ ),
+ ],
+)
+
+print(response)
+
+# %%
+# Taking ``DashScopeChatModel`` as an example, we can use it to create a chat model instance and call it with messages and tools:
+
+
+async def example_model_call() -> None:
+ """An example of using the DashScopeChatModel."""
+ model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ )
+
+ res = await model(
+ messages=[
+ {"role": "user", "content": "Hi!"},
+ ],
+ )
+
+ # You can directly create a ``Msg`` object with the response content
+ msg_res = Msg("Friday", res.content, "assistant")
+
+ print("The response:", res)
+ print("The response as Msg:", msg_res)
+
+
+asyncio.run(example_model_call())
+
+# %%
+# Streaming
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# To enable streaming model, set the ``stream`` parameter in the model constructor to ``True``.
+# When streaming is enabled, the ``__call__`` method will return an **async generator** that yields ``ChatResponse`` instances as they are generated by the model.
+#
+# .. note:: The streaming mode in AgentScope is designed to be **cumulative**, meaning the content in each chunk contains all the previous content plus the newly generated content.
+#
+
+
+async def example_streaming() -> None:
+ """An example of using the streaming model."""
+ model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ )
+
+ generator = await model(
+ messages=[
+ {
+ "role": "user",
+ "content": "Count from 1 to 20, and just report the number without any other information.",
+ },
+ ],
+ )
+ print("The type of the response:", type(generator))
+
+ i = 0
+ async for chunk in generator:
+ print(f"Chunk {i}")
+ print(f"\ttype: {type(chunk.content)}")
+ print(f"\t{chunk}\n")
+ i += 1
+
+
+asyncio.run(example_streaming())
+
+# %%
+# Reasoning
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope supports reasoning models by providing the ``ThinkingBlock``.
+#
+
+
+async def example_reasoning() -> None:
+ """An example of using the reasoning model."""
+ model = DashScopeChatModel(
+ model_name="qwen-turbo",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ enable_thinking=True,
+ )
+
+ res = await model(
+ messages=[
+ {"role": "user", "content": "Who am I?"},
+ ],
+ )
+
+ last_chunk = None
+ async for chunk in res:
+ last_chunk = chunk
+ print("The final response:")
+ print(last_chunk)
+
+
+asyncio.run(example_reasoning())
+
+# %%
+# Tools API
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Different model providers differ in their tools APIs, e.g. the tools JSON schema, the tool call/response format.
+# To provide a unified interface, AgentScope solves the problem by:
+#
+# - Providing unified tool call block :ref:`ToolUseBlock <tool-block>` and tool response block :ref:`ToolResultBlock <tool-block>`, respectively.
+# - Providing a unified tools interface in the ``__call__`` method of the model classes, that accepts a list of tools JSON schemas as follows:
+#
+
+json_schemas = [
+ {
+ "type": "function",
+ "function": {
+ "name": "google_search",
+ "description": "Search for a query on Google.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "The search query.",
+ },
+ },
+ "required": ["query"],
+ },
+ },
+ },
+]
+
+# %%
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`message`
+# - :ref:`prompt`
+#
diff --git a/docs/tutorial/en/src/task_pipeline.py b/docs/tutorial/en/src/task_pipeline.py
new file mode 100644
index 000000000..39d002e05
--- /dev/null
+++ b/docs/tutorial/en/src/task_pipeline.py
@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+"""
+.. _pipeline:
+
+Pipeline
+========================
+
+For multi-agent orchestration, AgentScope provides the ``agentscope.pipeline`` module
+as syntax sugar for chaining agents together, including
+
+- **MsgHub**: a message hub for broadcasting messages among multiple agents
+- **sequential_pipeline** and **SequentialPipeline**: a functional and class-based implementation that chains agents in a sequential manner
+
+"""
+
+import os, asyncio
+
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.agent import ReActAgent
+from agentscope.pipeline import MsgHub
+
+# %%
+# Broadcasting with MsgHub
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# The ``MsgHub`` class is an **async context manager**, receiving a list of agents as its participants.
+# When one participant generates a replying message, all other participants will receive this message by calling their ``observe`` method.
+#
+# That means within a ``MsgHub`` context, developers don't need to manually send a replying message from one agent to another.
+# The broadcasting is automatically handled.
+#
+# Here we create four agents: Alice, Bob, Charlie and David.
+# Then we start a meeting with Alice, Bob and Charlie by introducing themselves.
+# Note David is not included in this meeting.
+
+
+def create_agent(name: str, age: int, career: str) -> ReActAgent:
+ """Create agent object by the given information."""
+ return ReActAgent(
+ name=name,
+ sys_prompt=f"You're {name}, a {age}-year-old {career}",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeMultiAgentFormatter(),
+ )
+
+
+alice = create_agent("Alice", 50, "teacher")
+bob = create_agent("Bob", 35, "engineer")
+charlie = create_agent("Charlie", 28, "designer")
+david = create_agent("David", 30, "developer")
+
+# %%
+# Then we start a meeting and let them introduce themselves without manual message passing:
+#
+# .. hint:: The message in ``announcement`` will be broadcasted to all participants when entering the ``MsgHub`` context.
+#
+
+
+async def example_broadcast_message():
+ """Example of broadcasting messages with MsgHub."""
+
+ # Create a message hub
+ async with MsgHub(
+ participants=[alice, bob, charlie],
+ announcement=Msg(
+ "user",
+ "Now introduce yourself in one sentence, including your name, age and career.",
+ "user",
+ ),
+ ) as hub:
+ # Group chat without manual message passing
+ await alice()
+ await bob()
+ await charlie()
+
+
+asyncio.run(example_broadcast_message())
+
+# %%
+# Now let's check if Bob, Charlie and David received Alice's message.
+#
+
+
+async def check_broadcast_message():
+ """Check if the messages are broadcasted correctly."""
+ user_msg = Msg(
+ "user",
+ "Do you know who's Alice, and what she does? Answer me briefly.",
+ "user",
+ )
+
+ await bob(user_msg)
+ await charlie(user_msg)
+ await david(user_msg)
+
+
+asyncio.run(check_broadcast_message())
+
+# %%
+# Now we observe that Bob and Charlie know Alice and her profession, while David has no idea
+# about Alice since he is not included in the ``MsgHub`` context.
+#
+#
+# Dynamic Participant Management
+# ---------------------------------------
+# Additionally, ``MsgHub`` supports to dynamically manage participants by the following methods:
+#
+# - ``add``: add one or multiple agents as new participants
+# - ``delete``: remove one or multiple agents from participants, and they will no longer receive broadcasted messages
+# - ``broadcast``: broadcast a message to all current participants
+#
+# .. note:: The newly added participants will not receive the previous messages.
+#
+# .. code-block:: python
+#
+# async with MsgHub(participants=[alice]) as hub:
+# # Add new participants
+# hub.add(david)
+#
+# # Remove participants
+# hub.delete(alice)
+#
+# # Broadcast to all current participants
+# await hub.broadcast(
+# Msg("system", "Now we begin to ...", "system"),
+# )
+#
+#
+# Pipeline
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Pipeline serves as a syntax sugar for multi-agent orchestration.
+#
+# Currently, AgentScope provides a sequential pipeline implementation, which
+# execute agents one by one in a predefined order.
+# For example, the two following code snippets are equivalent:
+#
+#
+# .. code-block:: python
+# :caption: Code snippet 1: Manually call agents one by one
+#
+# msg = None
+# msg = await alice(msg)
+# msg = await bob(msg)
+# msg = await charlie(msg)
+# msg = await david(msg)
+#
+#
+# .. code-block:: python
+# :caption: Code snippet 2: Use sequential pipeline
+#
+# from agentscope.pipeline import sequential_pipeline
+# msg = await sequential_pipeline(
+# # List of agents to be executed in order
+# agents=[alice, bob, charlie, david],
+# # The first input message, can be None
+# msg=None
+# )
+#
+# .. tip:: By combining `MsgHub` and `sequential_pipeline`, you can create more complex workflows very easily.
+#
+#
+# Additionally, for reusability, we also provide a class-based implementation:
+#
+# .. code-block:: python
+# :caption: Using SequentialPipeline class
+#
+# from agentscope.pipeline import SequentialPipeline
+#
+# # Create a pipeline object
+# pipeline = SequentialPipeline(agents=[alice, bob, charlie, david])
+#
+# # Call the pipeline
+# msg = await pipeline(msg=None)
+#
+# # Reuse the pipeline with different input
+# msg = await pipeline(msg=Msg("user", "Hello!", "user"))
+#
+#
diff --git a/docs/tutorial/en/src/task_state.py b/docs/tutorial/en/src/task_state.py
new file mode 100644
index 000000000..379ee5f54
--- /dev/null
+++ b/docs/tutorial/en/src/task_state.py
@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+"""
+.. _state:
+
+State/Session Management
+=================================
+
+In AgentScope, the **"state"** refers to the agent status in the running application, including its current system prompt, memory, context, equipped tools, and other information that **change over time**.
+
+To manage the state of an application, AgentScope designs an automatic state registration system and session-level state management, which features:
+
+- Support **automatic state registration** for all variables inherited from ``StateModule``
+- Support **manual state registration** with custom serialization/deserialization methods
+- Support **session/application-level management**
+"""
+import asyncio
+import json
+import os
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.module import StateModule
+from agentscope.session import JSONSession
+from agentscope.tool import Toolkit
+
+# %%
+# State Module
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# The ``StateModule`` class is the foundation for state management in AgentScope and provides three basic functions:
+#
+# .. list-table:: Methods of ``StateModule``
+# :header-rows: 1
+#
+# * - Method
+# - Arguments
+# - Description
+# * - ``register_state``
+# - | ``attr_name``,
+# | ``custom_to_json`` (optional),
+# | ``custom_from_json`` (optional)
+# - Register an attribute as its state, with optional serialization/deserialization function.
+# * - ``state_dict``
+# - \-
+# - Get the state dictionary of current object
+# * - ``load_state_dict``
+# - | ``state_dict``,
+# | ``strict`` (optional)
+# - Load the state dictionary to current object
+#
+# Within an object of ``StateModule``, all the following attributes will be treated as parts of its state:
+#
+# - the **attributes** that inherit from ``StateModule``
+# - the **attributes** registered by the ``register_state`` method
+#
+# Note the ``StateModule`` supports **NESTED** serialization and deserialization:
+#
+
+
+class ClassA(StateModule):
+ def __init__(self) -> None:
+ super().__init__()
+ self.cnt = 123
+ # register cnt attribute as state
+ self.register_state("cnt")
+
+
+class ClassB(StateModule):
+ def __init__(self) -> None:
+ super().__init__()
+
+ # attribute "a" inherits from StateModule
+ self.a = ClassA()
+
+ # register attribute "c" as state manually
+ self.c = "Hello, world!"
+ self.register_state("c")
+
+
+obj_b = ClassB()
+
+print("State of obj_b.a:")
+print(obj_b.a.state_dict())
+
+print("\nState of obj_b:")
+print(json.dumps(obj_b.state_dict(), indent=4))
+
+# %%
+# We can observe the state of ``obj_b`` contains the state of its attribute ``a`` automatically.
+#
+# In AgentScope, the ``AgentBase``, ``MemoryBase``, ``LongTermMemoryBase`` and ``Toolkit`` classes all inherit from ``StateModule``, thus supporting automatic and nested state management.
+#
+
+# Creating an agent
+agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You're a assistant named Friday.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeChatFormatter(),
+ memory=InMemoryMemory(),
+ toolkit=Toolkit(),
+)
+
+initial_state = agent.state_dict()
+
+print("Initial state of the agent:")
+print(json.dumps(initial_state, indent=4))
+
+# %%
+# Then we change its state by generating a reply message:
+#
+
+
+async def example_agent_state() -> None:
+ """Example of agent state management"""
+ await agent(Msg("user", "Hello, agent!", "user"))
+
+ print("State of the agent after generating a reply:")
+ print(json.dumps(agent.state_dict(), indent=4))
+
+
+asyncio.run(example_agent_state())
+
+# %%
+# Now we recover the state of the agent to its initial state:
+#
+
+agent.load_state_dict(initial_state)
+
+print("State after loading the initial state:")
+print(json.dumps(agent.state_dict(), indent=4))
+
+# %%
+# Session Management
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# In AgentScope, a session refers to a collection of ``StateModule`` in an application, e.g. multiple agents.
+#
+# AgentScope provides a ``SessionBase`` class with two abstract methods for session
+# management: ``save_session_state`` and ``load_session_state``.
+# Developers can implement these methods with their own storage solution.
+#
+# In AgentScope, we provide a JSON based session class ``JSONSession`` that
+# stores/loads the session state in/from a JSON file named with the session ID.
+#
+# Here we show how to use the JSON based session management in AgentScope.
+#
+# Saving Session State
+# -----------------------------------------
+#
+
+# change the agent state by generating a reply message
+asyncio.run(example_agent_state())
+
+print("\nState of agent:")
+print(json.dumps(agent.state_dict(), indent=4))
+
+# %%
+# Then we save it to a session file:
+
+
+session = JSONSession(
+ session_id="session_2025-08-08", # Use the time as session id
+ save_dir="./user-bob/", # Use the username as the save directory
+)
+
+
+async def example_session() -> None:
+ """Example of session management."""
+ await session.save_session_state(
+ agent=agent,
+ )
+
+ print("The saved state:")
+ with open(session.save_path, "r", encoding="utf-8") as f:
+ print(json.dumps(json.load(f), indent=4))
+
+
+asyncio.run(example_session())
+
+# %%
+# Loading Session State
+# -----------------------------------------
+# Now we load the session state from the saved file:
+
+
+async def example_load_session() -> None:
+ """Example of loading session state."""
+
+ # we first clear the memory of the agent
+ await agent.memory.clear()
+
+ print("Current state of the agent:")
+ print(json.dumps(agent.state_dict(), indent=4))
+
+ # then we load the session state
+ await session.load_session_state(
+ # The keyword argument must be the same as the one used in `save_session_state`
+ agent=agent,
+ )
+ print("After loading the session state:")
+ print(json.dumps(agent.state_dict(), indent=4))
+
+
+asyncio.run(example_load_session())
+
+# %%
+# Now we can see the agent state is restored to the saved state.
+#
diff --git a/docs/tutorial/en/src/task_studio.py b/docs/tutorial/en/src/task_studio.py
new file mode 100644
index 000000000..8d182ffef
--- /dev/null
+++ b/docs/tutorial/en/src/task_studio.py
@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""
+.. _studio:
+
+AgentScope Studio
+=========================
+
+AgentScope Studio is a local-deployed web application that
+
+- provides **project management** for the development of agent applications
+- provides native **visualization** for running applications and tracing
+- provides a **built-in agent** named "Friday" that supports secondary development
+
+.. note:: The Studio is under fast development, more features are coming soon!
+
+.. figure:: ../../_static/images/studio_home.webp
+ :width: 100%
+ :alt: AgentScope Studio Home Page
+ :class: bordered-image
+ :align: center
+
+ AgentScope Studio Home Page
+
+Quick Start
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+AgentScope Studio is installed via ``npm``:
+
+.. code-block:: bash
+
+ npm install -g agentscope-studio
+
+
+Start the Studio with the following command:
+
+.. code-block:: bash
+
+ as_studio
+
+To connect your application to the Studio, use the ``agentscope.init`` function with the ``studio_url`` parameter:
+
+.. code-block:: python
+
+ import agentscope
+
+ agentscope.init(studio_url="http://localhost:8000")
+
+ # your application code
+ ...
+
+Then, you can see your application in the Studio as follows:
+
+.. figure:: ../../_static/images/studio_project.webp
+ :width: 100%
+ :alt: Project management
+ :class: bordered-image
+ :align: center
+
+ Project management in AgentScope Studio
+
+The details about your running application, e.g. token usage, model invocations, and tracing information, can all be viewed in the Studio.
+
+.. figure:: ../../_static/images/studio_run.webp
+ :width: 100%
+ :alt: AgentScope Studio run Page
+ :class: bordered-image
+ :align: center
+
+ Application visualization in AgentScope Studio
+
+
+Friday Agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Friday is an experimental local-deployed agent built by AgentScope, aims at
+
+- answering questions about the AgentScope,
+- providing a quick secondary development environment for developers,
+- integrating all available features in AgentScope to build a more powerful agent, and
+- testing and integrating the advanced features in AgentScope.
+
+.. note:: We highly greet contributions from the community to improve Friday! Feel free to open issues or pull requests on our `GitHub repository <https://github.com/agentscope-ai/agentscope>`_.
+
+We are keeping improving Friday, and currently it integrates the following features in AgentScope:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Feature
+ - Status
+ - Further Reading
+ - Description
+ * - Meta tool
+ - ✅
+ - :ref:`tool`
+ - Group-wise tool management, and allow agent to change equipped tools by itself.
+ * - Agent Hook
+ - ✅
+ - :ref:`hook`
+ - Use hook to forward the printing messages to the frontend.
+ * - Agent Interruption
+ - ✅
+ - :ref:`agent`
+ - Allow use to interrupt the agent's reply process with post-processing.
+ * - Truncated Prompt
+ - ✅
+ - :ref:`prompt`
+ - Support to truncate the prompt with the preset max token limit.
+ * - State & Session Management
+ - ✅
+ - :ref:`state`
+ - Auto state management and session management for agents, maintaining the state between different runs.
+ * - Long-term Memory
+ - 🚧
+ - :ref:`memory`
+ - Support long-term memory management.
+
+
+"""
diff --git a/docs/tutorial/en/src/task_token.py b/docs/tutorial/en/src/task_token.py
new file mode 100644
index 000000000..3c2c3f458
--- /dev/null
+++ b/docs/tutorial/en/src/task_token.py
@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""
+.. _token:
+
+Token
+=========================
+
+AgentScope provides a token counter module under ``agentscope.token`` to
+calculate the number of tokens in the given messages, allowing developers
+to estimate the number of tokens in a prompt before sending it to an API.
+
+Specifically, the following token counters are available:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Provider
+ - Class
+ - Support Image Data
+ - Support Tools
+ * - Anthropic
+ - ``AnthropicTokenCounter``
+ - ✅
+ - ✅
+ * - OpenAI
+ - ``OpenAITokenCounter``
+ - ✅
+ - ✅
+ * - Gemini
+ - ``GeminiTokenCounter``
+ - ✅
+ - ✅
+ * - HuggingFace
+ - ``HuggingFaceTokenCounter``
+ - Depends on the model
+ - Depends on the model
+
+.. tip:: The formatter module has integrated the token counters to support prompt truncation. Refer to the :ref:`prompt` section for more details.
+
+.. note:: For DashScope models, the dashscope library doesn't provide a token counting API. So we recommend using the HuggingFace token counter instead.
+
+We show an example of using the OpenAI token counter to count the number of tokens:
+"""
+
+import asyncio
+from agentscope.token import OpenAITokenCounter
+
+
+async def example_token_counting():
+ # Example messages
+ messages = [
+ {"role": "user", "content": "Hello!"},
+ {"role": "assistant", "content": "Hi, how can I help you?"},
+ ]
+
+ # OpenAI token counting
+ openai_counter = OpenAITokenCounter(model_name="gpt-4.1")
+ n_tokens = await openai_counter.count(messages)
+
+ print(f"Number of tokens: {n_tokens}")
+
+
+asyncio.run(example_token_counting())
+
+
+# %%
+# Further Reading
+# ------------------------------
+#
+# - :ref:`prompt`
+#
diff --git a/docs/tutorial/en/src/task_tool.py b/docs/tutorial/en/src/task_tool.py
new file mode 100644
index 000000000..eebdf9ad0
--- /dev/null
+++ b/docs/tutorial/en/src/task_tool.py
@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""
+.. _tool:
+
+Tool
+=========================
+
+To ensure accurate and reliable tool parsing, AgentScope fully embraces the use of tools API with the following features:
+
+- Support **automatic** tool parsing from Python functions with their docstrings
+- Support both **synchronous and asynchronous** tool functions
+- Support **streaming** tool responses (either synchronous or asynchronous generators)
+- Support **dynamic extension** to the tool JSON Schema
+- Support **interrupting** the tool execution with proper signal handling
+- Support **autonomous tool management** by agents
+
+All above features are implemented by the ``Toolkit`` class in AgentScope, which is responsible for managing tool functions and their execution.
+
+.. tip:: The support of MCP (Model Context Protocol) refers to the :ref:`mcp` section.
+"""
+import asyncio
+import inspect
+import json
+from typing import Any, AsyncGenerator
+
+from pydantic import BaseModel, Field
+
+import agentscope
+from agentscope.message import TextBlock, ToolUseBlock
+from agentscope.tool import ToolResponse, Toolkit, execute_python_code
+
+
+# %%
+# Tool Function
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# In AgentScope, a tool function is a Python function that
+#
+# - returns a ``ToolResponse`` object or a generator that yields ``ToolResponse`` objects
+# - has a docstring that describes the tool's functionality and parameters
+#
+# A template of a tool function is as follows:
+
+
+def tool_function(a: int, b: str) -> ToolResponse:
+ """{function description}
+
+ Args:
+ a (int):
+ {description of the first parameter}
+ b (str):
+ {description of the second parameter}
+ """
+
+
+# %%
+# .. tip:: Instance method and class method can also be used as tool functions, and the ``self`` and ``cls`` parameters will be ignored.
+#
+# AgentScope provides several built-in tool functions under the ``agentscope.tool`` module, such as ``execute_python_code``, ``execute_shell_command`` and text file write/read functions.
+#
+
+print("Built-in Tool Functions:")
+for _ in agentscope.tool.__all__:
+ if _ not in ["Toolkit", "ToolResponse"]:
+ print(_)
+
+# %%
+# Toolkit
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# The ``Toolkit`` class is designed to manage tool functions, extracting their JSON Schema from docstrings and providing a unified interface for tool execution.
+#
+# Basic Usage
+# ------------------------------
+# The basic functionality of the ``Toolkit`` class is to register tool functions and execute them.
+#
+
+
+# Prepare a custom tool function
+async def my_search(query: str, api_key: str) -> ToolResponse:
+ """A simple example tool function.
+
+ Args:
+ query (str):
+ The search query.
+ api_key (str):
+ The API key for authentication.
+ """
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Searching for '{query}' with API key '{api_key}'",
+ ),
+ ],
+ )
+
+
+# Register the tool function in a toolkit
+toolkit = Toolkit()
+toolkit.register_tool_function(my_search)
+
+# %%
+# When registering a tool function, you can get its JSON Schema by calling the ``get_json_schemas`` method.
+#
+
+print("Tool JSON Schemas:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# ``Toolkit`` also allows developers to preset the arguments for tool functions, especially useful for API keys or other sensitive information.
+#
+
+# Clear the toolkit first
+toolkit.clear()
+
+# Register tool function with preset keyword arguments
+toolkit.register_tool_function(my_search, preset_kwargs={"api_key": "xxx"})
+
+print("Tool JSON Schemas with Preset Arguments:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# In ``Toolkit``, the ``call_tool_function`` method takes a tool use block as input and executes the corresponding tool function, returning **a unified asynchronous generator** that yields ``ToolResponse`` objects.
+#
+
+
+async def example_tool_execution() -> None:
+ """Example of executing a tool call."""
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="my_search",
+ input={"query": "AgentScope"},
+ ),
+ )
+
+ # Only one tool response is expected in this case
+ print("Tool Response:")
+ async for tool_response in res:
+ print(tool_response)
+
+
+asyncio.run(example_tool_execution())
+
+# %%
+# Extending JSON Schema Dynamically
+# --------------------------------------
+#
+# Toolkit allows to extend the JSON schemas of tool functions dynamically by calling the ``set_extended_model`` method.
+# Such feature allows to add more parameters to the tool function without modifying its original definition.
+#
+# .. tip:: Related scenarios include dynamic :ref:`structured-output` and CoT (Chain of Thought) reasoning
+#
+# .. note:: The function to be extended should accept variable keyword arguments (``**kwargs``), so that the additional fields can be passed to it.
+#
+# Taking the CoT reasoning as an example, we can extend all tool functions with a ``thinking`` field, allowing the agent to summarize the current state and then decide what to do next.
+#
+
+
+# Example tool function
+def tool_function(**kwargs: Any) -> ToolResponse:
+ """A tool function"""
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Received parameters: {kwargs}",
+ ),
+ ],
+ )
+
+
+# Add a thinking field so that the agent could think before giving the other parameters.
+class ThinkingModel(BaseModel):
+ """A Pydantic model for additional fields."""
+
+ thinking: str = Field(
+ description="Summarize the current state and decide what to do next.",
+ )
+
+
+# Register
+toolkit.set_extended_model("my_search", ThinkingModel)
+
+print("The extended JSON Schema:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# Interrupting Tool Execution
+# ------------------------------
+# The ``Toolkit`` class supports **execution interruption** of **async tool functions** and provides a comprehensive **agent-oriented post-processing mechanism**.
+# Such interruption is implemented based on the asyncio cancellation mechanism, and the post-processing varies depending on the return type of tool function.
+#
+# .. note:: For synchronous tool functions, their execution cannot be interrupted by asyncio cancellation. So the interruption is handled within the agent rather than the toolkit.
+# Refer to the :ref:`agent` section for more information.
+#
+# Specifically, if the tool function returns a ``ToolResponse`` object, a predefined ``ToolResponse`` object with an interrupted message will be yielded.
+# So that the agent can observe the interruption and handle it accordingly.
+# Besides, a flag ``is_interrupted`` will be set to ``True`` in the response, and the external caller can decide whether to throw the ``CancelledError`` exception to the outer layer.
+#
+# An example of async tool function that can be interrupted is as follows:
+#
+
+
+async def non_streaming_function() -> ToolResponse:
+ """A non-streaming tool function that can be interrupted."""
+ await asyncio.sleep(1) # Simulate a long-running task
+
+ # Fake interruption for demonstration
+ raise asyncio.CancelledError()
+
+ # The following code won't be executed due to the cancellation
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="Run successfully!",
+ ),
+ ],
+ )
+
+
+async def example_tool_interruption() -> None:
+ """Example of tool interruption."""
+ toolkit = Toolkit()
+ toolkit.register_tool_function(non_streaming_function)
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="non_streaming_function",
+ input={},
+ ),
+ )
+
+ async for tool_response in res:
+ print("Tool Response:")
+ print(tool_response)
+ print("The interrupted flag:")
+ print(tool_response.is_interrupted)
+
+
+asyncio.run(example_tool_interruption())
+
+# %%
+# For streaming tool functions, which returns an asynchronous generator, the ``Toolkit`` will attach the interrupted message to the previous chunk of the response.
+# By this way, the agent can observe what the tool has returned before the interruption.
+#
+# The example of interrupting a streaming tool function is as follows:
+#
+
+
+async def streaming_function() -> AsyncGenerator[ToolResponse, None]:
+ """A streaming tool function that can be interrupted."""
+ # Simulate a chunk of response
+ yield ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="1234",
+ ),
+ ],
+ )
+
+ # Simulate interruption
+ raise asyncio.CancelledError()
+
+ # The following code won't be executed due to the cancellation
+ yield ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="123456789",
+ ),
+ ],
+ )
+
+
+async def example_streaming_tool_interruption() -> None:
+ """Example of streaming tool interruption."""
+ toolkit = Toolkit()
+ toolkit.register_tool_function(streaming_function)
+
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="streaming_function",
+ input={},
+ ),
+ )
+
+ i = 0
+ async for tool_response in res:
+ print(f"Chunk {i}:")
+ print(tool_response)
+ print("The interrupted flag: ", tool_response.is_interrupted, "\n")
+ i += 1
+
+
+asyncio.run(example_streaming_tool_interruption())
+
+# %%
+# Automatic Tool Management
+# -------------------------------------
+# .. image:: https://img.alicdn.com/imgextra/i3/O1CN013cvRpO27MfesMsTeh_!!6000000007783-2-tps-840-521.png
+# :width: 100%
+# :align: center
+# :alt: Automatic Tool Management
+#
+#
+# The ``Toolkit`` class supports **automatic tool management** by introducing the concept of **tool group**, as well as a **meta tool function** named ``reset_equipped_tools``.
+#
+# The tool group is a set of related tool functions, e.g. browser-use tools, map services tools, etc., which will be managed together.
+# Only the tools in the activated groups will be visible to agents, i.e. accessible by the ``toolkit.get_json_schemas()`` method.
+#
+# Note there is a special group called ``basic``, which is always activated and the tools registered without specifying the group name will be added to this group by default.
+#
+# .. tip:: The ``basic`` group ensures that the basic usage of tools won't be affected by the group features if you don't need them.
+#
+# Now we try to create a tool group named ``browser_use``, which contains some web browsing tools.
+#
+
+
+def navigate(url: str) -> ToolResponse:
+ """Navigate to a web page.
+
+ Args:
+ url (str):
+ The URL of the web page to navigate to.
+ """
+ pass
+
+
+def click_element(element_id: str) -> ToolResponse:
+ """Click an element on the web page.
+
+ Args:
+ element_id (str):
+ The ID of the element to click.
+ """
+ pass
+
+
+toolkit = Toolkit()
+
+# Create a tool group named browser_use
+toolkit.create_tool_group(
+ group_name="browser_use",
+ description="The tool functions for web browsing.",
+ active=False,
+ # The notes when using these tools
+ notes="""1. Use ``navigate`` to open a web page.
+2. When requiring user authentication, ask the user for the credentials
+3. ...""",
+)
+
+toolkit.register_tool_function(navigate, group_name="browser_use")
+toolkit.register_tool_function(click_element, group_name="browser_use")
+
+# We can also register some basic tools
+toolkit.register_tool_function(execute_python_code)
+
+# %%
+# If we check the tools JSON schema, we can only see the ``execute_python_code`` tool, because the ``browser_use`` group is not activated yet:
+
+print("Tool JSON Schemas with Group:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# Use the ``update_tool_groups`` method to activate or deactivate tool groups:
+
+toolkit.update_tool_groups(group_names=["browser_use"], active=True)
+
+print("Tool JSON Schemas with Group:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# Additionally, ``Toolkit`` provides a meta tool function named ``reset_equipped_tools``, taking the current group names as the argument to indicate which groups to activate:
+#
+# .. note:: In ``ReActAgent`` class, you can enable the meta tool function by setting ``enable_meta_tool=True`` in the constructor.
+#
+
+# Register the meta tool function
+toolkit.register_tool_function(toolkit.reset_equipped_tools)
+
+reset_equipped = next(
+ tool
+ for tool in toolkit.get_json_schemas()
+ if tool["function"]["name"] == "reset_equipped_tools"
+)
+print("JSON schema of the ``reset_equipped_tools`` function:")
+print(
+ json.dumps(
+ reset_equipped,
+ indent=4,
+ ensure_ascii=False,
+ ),
+)
+
+# %%
+# When agent calls the ``reset_equipped_tools`` function, the corresponding tool groups will be activated, and the tool response will
+# contain the notes of the activated tool groups.
+#
+
+
+async def mock_agent_reset_tools() -> None:
+ """Mock agent to reset tool groups."""
+ # Call the meta tool function
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="154",
+ name="reset_equipped_tools",
+ input={
+ "browser_user": True,
+ },
+ ),
+ )
+
+ async for tool_response in res:
+ print("Text content in tool Response:")
+ print(tool_response)
+
+
+asyncio.run(mock_agent_reset_tools())
+
+# %%
+# The toolkit also provides a method to gather the notes of the activated tool groups, and you can assemble it into your agent's system prompt.
+#
+# .. tip:: The automatic tool management feature is already implemented in the ``ReActAgent`` class, refer to the :ref:`agent` section for more details.
+#
+
+# Create one more tool group
+toolkit.create_tool_group(
+ group_name="map_service",
+ description="The google map service tools.",
+ active=True,
+ notes="""1. Use ``get_location`` to get the location of a place.
+2. ...""",
+)
+
+print("The gathered notes of the activated tool groups:")
+print(toolkit.get_activated_notes())
+
+# %%
+# Further Reading
+# ---------------------
+# - :ref:`agent`
+# - :ref:`state`
+# - :ref:`mcp`
+#
diff --git a/docs/tutorial/en/src/task_tracing.py b/docs/tutorial/en/src/task_tracing.py
new file mode 100644
index 000000000..ca4e4e1bf
--- /dev/null
+++ b/docs/tutorial/en/src/task_tracing.py
@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+"""
+.. _tracing:
+
+Tracing
+==============================
+
+AgentScope implements OpenTelemetry-based tracing to monitor and debug the
+execution of agent applications, which features
+
+- Provide built-in tracing for LLM, tool, agent, formatter, etc.
+- Support error and exception tracking
+- Provide native tracing **visualization** in AgentScope Studio
+- Support connecting to **third-party platforms** like `Arize-Phoenix <https://github.com/Arize-ai/phoenix>`_, `Langfuse <https://langfuse.com/>`_, etc.
+
+Setting Up
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: Connecting to the :ref:`studio` or third-party tracing endpoint should be done at the beginning of your application by the ``agentscope.init`` function.
+
+AgentScope Studio
+---------------------------------------
+
+.. figure:: ../../_static/images/studio_tracing.png
+ :width: 100%
+ :alt: AgentScope Studio tracing Page
+ :class: bordered-image
+ :align: center
+
+ *Tracing in AgentScope Studio*
+
+When connecting to AgentScope Studio, just provide ``studio_url`` parameter in ``agentscope.init`` function.
+
+.. code-block:: python
+
+ import agentscope
+
+ agentscope.init(studio_url="http://xxx:port")
+
+
+Third-party Platforms
+---------------------------------------
+
+To connect to third-party tracing platforms, set the ``tracing_url`` parameter in the ``agentscope.init`` function.
+The ``tracing_url`` is the URL of your OpenTelemetry collector or any compatible backend that supports OTLP (OpenTelemetry Protocol).
+
+.. code-block:: python
+
+ import agentscope
+
+ # Connect to OpenTelemetry-compatible backends
+ agentscope.init(tracing_url="https://your-tracing-backend:port/traces")
+
+Taking Arize-Phoenix and Langfuse as examples:
+
+**Arize-Phoenix**: You need to set the ``PHOENIX_API_KEY`` in your environment variables.
+
+.. code-block:: python
+ :caption: Connect to Arize Phoenix
+
+ # Arize Phoenix Integration
+ import os
+
+ PHOENIX_API_KEY = os.environ.get("PHOENIX_API_KEY")
+ os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
+
+ agentscope.init(tracing_url="https://app.phoenix.arize.com/v1/traces")
+
+**LangFuse**: You need to set the ``LANGFUSE_PUBLIC_KEY`` and
+``LANGFUSE_SECRET_KEY`` in your environment variables. The authorization
+header is constructed using these keys.
+
+.. code-block:: python
+ :caption: Connect to LangFuse
+
+ import os, base64
+
+ LANGFUSE_PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
+ LANGFUSE_SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
+ LANGFUSE_AUTH_STRING = f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}"
+
+ LANGFUSE_AUTH = base64.b64encode(LANGFUSE_AUTH_STRING.encode("utf-8")).decode("ascii")
+ os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
+
+ # EU data region
+ agentscope.init(tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces")
+ # US data region
+ # agentscope.init(tracing_url="https://us.cloud.langfuse.com/api/public/otel/v1/traces")
+
+
+Customizing Tracing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As stated above, the tracing in AgentScope is implemented based on OpenTelemetry.
+That means your own tracing code implemented by OpenTelemetry sdk is compatible with
+AgentScope natively.
+
+Besides, AgentScope has built-in the following decorators to trace the corresponding modules:
+
+- ``@trace_llm``: Trace the ``__call__`` function of classes inherit from ``ChatModelBase``
+- ``@trace_reply``: Trace the ``reply`` function of classes inherit from ``AgentBase``
+- ``@trace_format``: Trace the ``format`` function of classes inherit from ``FormatterBase``
+- ``@trace``: Trace general functions
+
+
+Tracing LLMs
+----------------------------------------
+
+
+The ``@trace_llm`` decorator is to trace the ``__call__`` function of ``ChatModelBase`` classes.
+
+.. note:: Your LLM class must inherit from ``ChatModelBase``
+
+.. code-block:: python
+ :caption: Tracing new ChatModel class
+
+ class ExampleChatModel(ChatModelBase):
+ \"\"\"An example Model\"\"\"
+
+ ...
+
+ @trace_llm
+ async def __call__(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> AsyncGenerator[ChatResponse, None] | ChatResponse:
+ \"\"\"LLM call\"\"\"
+ ...
+
+
+Tracing Agent
+----------------------------------------
+
+The ``@trace_reply`` decorator is for agent implementations and tracing the `reply` function.
+
+.. note:: Your agent class must inherit from ``AgentBase``
+
+.. code-block:: python
+ :caption: Tracing new Agent class
+
+ class ExampleAgent(AgentBase):
+ \"\"\"An example agent class\"\"\"
+
+ @tracer_reply
+ async def reply(self, *args: Any, **kwargs: Any) -> Msg:
+ \"\"\"Reply to the message.\"\"\"
+ ...
+
+
+Tracing Formatter
+----------------------------------------
+The ``@trace_format`` decorator is for formatters implementations and tracing the `format` function.
+
+.. note:: Your formatter class must inherit from ``FormatterBase``
+
+.. code-block:: python
+ :caption: Tracing new Formatter class
+
+ class ExampleFormatter(FormatterBase):
+ \"\"\"A simple example formatter class\"\"\"
+
+ @trace_format
+ async def format(self, *args: Any, **kwargs: Any) -> list[dict]:
+ \"\"\"Example formatting\"\"\"
+
+
+General Tracing
+----------------------------------------
+
+The ``@trace`` decorator is different from the above decorators, as it is a general-purpose tracing decorator that can be applied to any function.
+It requires a `name` parameter to identify the traced function, and can trace various types of functions, including:
+
+- synchronous functions
+- synchronous generator functions
+- asynchronous functions
+- asynchronous generator functions
+
+.. code-block:: python
+ :caption: General tracing example
+
+ # 1. Synchronous function
+ @trace(name='simple_function')
+ def simple_function(name: str, age: int) -> str:
+ \"\"\"A simple function with automatic tracing.\"\"\"
+ return f"Hello, {name}! You are {age} years old."
+
+ # 2. Synchronous generator function
+ @trace(name='number_generator')
+ def number_generator(n: int) -> Generator[int, None, None]:
+ \"\"\"Generate numbers from 0 to n-1.\"\"\"
+ for i in range(n):
+ yield i
+
+ # 3. Asynchronous function
+ @trace(name='async_function')
+ async def async_function(data: dict) -> dict:
+ \"\"\"Process data asynchronously.\"\"\"
+ return {"processed": data}
+
+ # 4. Asynchronous generator function
+ @trace(name='async_stream')
+ async def async_stream(n: int) -> AsyncGenerator[str, None]:
+ \"\"\"Generate stream of data asynchronously.\"\"\"
+ for i in range(n):
+ yield f"data_{i}"
+
+"""
diff --git a/docs/tutorial/en/src/workflow_concurrent_agents.py b/docs/tutorial/en/src/workflow_concurrent_agents.py
new file mode 100644
index 000000000..af2bc575a
--- /dev/null
+++ b/docs/tutorial/en/src/workflow_concurrent_agents.py
@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""
+Concurrent Agents
+===================================
+With the help of asynchronous programming, the concurrent agents can be executed by ``asyncio.gather`` in Python.
+
+A simple example is shown below, where two agents are created and executed concurrently.
+"""
+import asyncio
+from datetime import datetime
+from typing import Any
+
+from agentscope.agent import AgentBase
+
+
+class ExampleAgent(AgentBase):
+ """The example agent for concurrent execution."""
+
+ def __init__(self, name: str) -> None:
+ """Initialize the agent with its name."""
+ super().__init__()
+ self.name = name
+
+ async def reply(self, *args: Any, **kwargs: Any) -> None:
+ """Reply to the message."""
+ start_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+ print(f"{self.name} started at {start_time}")
+ await asyncio.sleep(3) # Simulate a long-running task
+ end_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+ print(f"{self.name} finished at {end_time}")
+
+
+async def run_concurrent_agents() -> None:
+ """Run the concurrent agents."""
+ agent1 = ExampleAgent("Agent 1")
+ agent2 = ExampleAgent("Agent 2")
+
+ await asyncio.gather(agent1(), agent2())
+
+
+asyncio.run(run_concurrent_agents())
diff --git a/docs/tutorial/en/src/workflow_conversation.py b/docs/tutorial/en/src/workflow_conversation.py
new file mode 100644
index 000000000..47cb25c8c
--- /dev/null
+++ b/docs/tutorial/en/src/workflow_conversation.py
@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+"""
+.. _conversation:
+
+Conversation
+======================
+
+Conversation is a design pattern that agents exchange and share information
+between each other, most commonly in game playing, chatbot, and multi-agent
+discussion scenarios.
+
+In AgentScope, the conversation is built upon the **explicit message
+exchange**. In this tutorial, we will demonstrate how to build a conversation
+
+- between a user and an agent (chatbot)
+- between multiple agents (game playing, discussion, etc.)
+
+Their main difference lies in
+
+- how the **prompt is constructed**, and
+- how the information is **propagated/shared** among agents.
+"""
+import asyncio
+import json
+import os
+
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.memory import InMemoryMemory
+from agentscope.formatter import (
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+)
+from agentscope.model import DashScopeChatModel
+from agentscope.message import Msg
+from agentscope.pipeline import MsgHub
+from agentscope.tool import Toolkit
+
+# %%
+# User-Agent Conversation
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# User-agent conversation, also known as chatbot, is the most common usage
+# scenario of LLM-empowered agents, and the design target of most LLM APIs.
+# Such conversation features only two participants: a user and an agent.
+#
+# In AgentScope, the formatters with **"Chat"** in its name are designed for
+# user-agent conversation, such as ``DashScopeChatFormatter``,
+# ``AnthropicChatFormatter``, etc.
+# They use the ``role`` field in the message to distinguish the user and the
+# agent, and format the messages accordingly.
+#
+# Here we build a simple conversation between agent ``Friday`` and user.
+#
+# .. tip:: AgentScope provides a built-in ``UserAgent`` class for human-in-the-loop (HITL) interaction. Refer to :ref:`user-agent` for more details.
+#
+
+friday = ReActAgent(
+ name="Friday",
+ sys_prompt="You're a helpful assistant named Friday",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeChatFormatter(), # The formatter for user-agent conversation
+ memory=InMemoryMemory(),
+ toolkit=Toolkit(),
+)
+
+# Create a user agent
+user = UserAgent(name="User")
+
+# %%
+# Now, we can program the conversation by exchanging messages between these two agents until the user types "exit" to end the conversation.
+#
+# .. code-block:: python
+#
+# async def run_conversation() -> None:
+# """Run a simple conversation between Friday and User."""
+# msg = None
+# while True:
+# msg = await friday(msg)
+# msg = await user(msg)
+# if msg.get_text_content() == "exit":
+# break
+#
+# asyncio.run(run_conversation())
+#
+
+# %%
+# More than Two Agents
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# As stated in the beginning, we demonstrate how to build conversation with multiple agents in terms of **prompt construction** and **information sharing**.
+#
+# Prompt Construction
+# -------------------------------
+# In AgentScope, we provide built-in formatters for multi-agent conversation, featuring **"MultiAgent"** in their names, such as ``DashScopeMultiAgentFormatter``, ``AnthropicMultiAgentFormatter``, etc.
+#
+# Specifically, they use the ``name`` field in the message to distinguish different agents, and format the conversation history into a single user message.
+# Taking ``DashScopeMultiAgentFormatter`` as an example:
+#
+# .. tip:: More details about the formatter can be found in :ref:`prompt`.
+#
+
+
+async def example_multi_agent_prompt() -> None:
+ msgs = [
+ Msg("system", "You're a helpful assistant named Bob.", "system"),
+ Msg("Alice", "Hi!", "user"),
+ Msg("Bob", "Hi! Nice to meet you guys.", "assistant"),
+ Msg("Charlie", "Me too! I'm Charlie, by the way.", "assistant"),
+ ]
+
+ formatter = DashScopeMultiAgentFormatter()
+ prompt = await formatter.format(msgs)
+
+ print("Formatted prompt:")
+ print(json.dumps(prompt, indent=4, ensure_ascii=False))
+
+ # We print the content of the combined user message here for better
+ # understanding:
+ print("-------------")
+ print("Combined message")
+ print(prompt[1]["content"])
+
+
+asyncio.run(example_multi_agent_prompt())
+
+
+# %%
+# Message Sharing
+# -------------------------------
+# In multi-agent conversation, exchanging messages explicitly may not be efficient and convenient, especially when broadcasting messages among multiple agents.
+#
+# Therefore, AgentScope provides an async context manager named ``MsgHub`` to simplify the operation of broadcasting messages.
+# Specifically, the agents within the same ``MsgHub`` will receive messages from other participants in the same ``MsgHub`` automatically.
+#
+
+model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+)
+formatter = DashScopeMultiAgentFormatter()
+
+alice = ReActAgent(
+ name="Alice",
+ sys_prompt="You're a student named Alice.",
+ model=model,
+ formatter=formatter,
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+)
+
+bob = ReActAgent(
+ name="Bob",
+ sys_prompt="You're a student named Bob.",
+ model=model,
+ formatter=formatter,
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+)
+
+charlie = ReActAgent(
+ name="Charlie",
+ sys_prompt="You're a student named Charlie.",
+ model=model,
+ formatter=formatter,
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+)
+
+
+async def example_msghub() -> None:
+ """Example of using MsgHub for multi-agent conversation."""
+ async with MsgHub(
+ [alice, bob, charlie],
+ announcement=Msg(
+ "system",
+ "Now you meet each other with a brief self-introduction.",
+ "system",
+ ),
+ ):
+ await alice()
+ await bob()
+ await charlie()
+
+
+asyncio.run(example_msghub())
+
+# %%
+# Now we print the memory of Alice to check if her memory is updated correctly.
+#
+
+
+async def example_memory() -> None:
+ """Print the memory of Alice."""
+ print("Memory of Alice:")
+ for msg in await alice.memory.get_memory():
+ print(f"{msg.name}: {msg.get_text_content()}")
+
+
+asyncio.run(example_memory())
+
+# %%
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`prompt`
+# - :ref:`pipeline`
+#
diff --git a/docs/tutorial/en/src/workflow_handoffs.py b/docs/tutorial/en/src/workflow_handoffs.py
new file mode 100644
index 000000000..7af62f05f
--- /dev/null
+++ b/docs/tutorial/en/src/workflow_handoffs.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+Handoffs
+========================================
+
+.. figure:: ../../_static/images/handoffs.png
+ :width: 80%
+ :align: center
+ :alt: Orchestrator-Workers Workflow
+
+ *Handoffs example*
+
+It's very simple to implement the Orchestrator-Workers workflow with tool calls in AgentScope.
+First, we create a function to allow the orchestrator to create workers dynamically.
+
+"""
+
+import asyncio
+import os
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import (
+ ToolResponse,
+ Toolkit,
+ execute_python_code,
+)
+
+
+# The tool function to create a worker
+async def create_worker(
+ task_description: str,
+) -> ToolResponse:
+ """Create a worker to finish the given task. The worker is equipped with python execution tool.
+
+ Args:
+ task_description (``str``):
+ The description of the task to be finished by the worker.
+ """
+ # Equip the worker agent with some tools
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+
+ # Create a worker agent
+ worker = ReActAgent(
+ name="Worker",
+ sys_prompt="You're a worker agent. Your target is to finish the given task.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+ # Let the worker finish the task
+ res = await worker(Msg("user", task_description, "user"))
+ return ToolResponse(
+ content=res.get_content_blocks("text"),
+ )
+
+
+async def run_handoffs() -> None:
+ """Example of handoffs workflow."""
+ # Initialize the orchestrator agent
+ toolkit = Toolkit()
+ toolkit.register_tool_function(create_worker)
+
+ orchestrator = ReActAgent(
+ name="Orchestrator",
+ sys_prompt="You're an orchestrator agent. Your target is to finish the given task by decomposing it into smaller tasks and creating workers to finish them.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+
+ # The task description
+ task_description = "Execute hello world in Python"
+
+ # Create a worker to finish the task
+ await orchestrator(Msg("user", task_description, "user"))
+
+
+asyncio.run(run_handoffs())
diff --git a/docs/tutorial/en/src/workflow_multiagent_debate.py b/docs/tutorial/en/src/workflow_multiagent_debate.py
new file mode 100644
index 000000000..58c053708
--- /dev/null
+++ b/docs/tutorial/en/src/workflow_multiagent_debate.py
@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+"""
+.. _multiagent-debate:
+
+Multi-Agent Debate
+========================
+
+Debate workflow simulates a multi-turn discussion between different agents, mostly several solvers and an aggregator.
+Typically, the solvers generate and exchange their answers, while the aggregator collects and summarizes the answers.
+
+We implement the examples in `EMNLP 2024`_, where two debater agents will discuss a topic in a fixed order, and express their
+arguments based on the previous debate history.
+At each round a moderator agent will decide whether the correct answer can be obtained in the current iteration.
+"""
+import asyncio
+import os
+
+from pydantic import Field, BaseModel
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import (
+ DashScopeMultiAgentFormatter,
+ DashScopeChatFormatter,
+)
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.pipeline import MsgHub
+
+# Prepare a topic
+topic = (
+ "The two circles are externally tangent and there is no relative sliding. "
+ "The radius of circle A is 1/3 the radius of circle B. Circle A rolls "
+ "around circle B one trip back to its starting point. How many times will "
+ "circle A revolve in total?"
+)
+
+
+# Create two debater agents, Alice and Bob, who will discuss the topic.
+def create_solver_agent(name: str) -> ReActAgent:
+ """Get a solver agent."""
+ return ReActAgent(
+ name=name,
+ sys_prompt=f"You're a debater named {name}. Hello and welcome to the "
+ "debate competition. It's unnecessary to fully agree with "
+ "each other's perspectives, as our objective is to find "
+ "the correct answer. The debate topic is stated as "
+ f"follows: {topic}.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeMultiAgentFormatter(),
+ )
+
+
+alice, bob = [create_solver_agent(name) for name in ["Alice", "Bob"]]
+
+# Create a moderator agent
+moderator = ReActAgent(
+ name="Aggregator",
+ sys_prompt=f"""You're a moderator. There will be two debaters involved in a debate competition. They will present their answer and discuss their perspectives on the topic:
+``````
+{topic}
+``````
+At the end of each round, you will evaluate both sides' answers and decide which one is correct.""",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ # Use multiagent formatter because the moderator will receive messages from more than a user and an assistant
+ formatter=DashScopeMultiAgentFormatter(),
+)
+
+
+# A structured output model for the moderator
+class JudgeModel(BaseModel):
+ """The structured output model for the moderator."""
+
+ finished: bool = Field(
+ description="Whether the debate is finished.",
+ )
+ correct_answer: str | None = Field(
+ description="The correct answer to the debate topic, only if the debate is finished. Otherwise, leave it as None.",
+ default=None,
+ )
+
+
+async def run_multiagent_debate() -> None:
+ """Run the multi-agent debate workflow."""
+ while True:
+ # The reply messages in MsgHub from the participants will be broadcasted to all participants.
+ async with MsgHub(participants=[alice, bob, moderator]):
+ await alice(
+ Msg(
+ "user",
+ "You are affirmative side, Please express your viewpoints.",
+ "user",
+ ),
+ )
+ await bob(
+ Msg(
+ "user",
+ "You are negative side. You disagree with the affirmative side. Provide your reason and answer.",
+ "user",
+ ),
+ )
+
+ # Alice and Bob doesn't need to know the moderator's message, so moderator is called outside the MsgHub.
+ msg_judge = await moderator(
+ Msg(
+ "user",
+ "Now you have heard the answers from the others, have the debate finished, and can you get the correct answer?",
+ "user",
+ ),
+ structured_model=JudgeModel,
+ )
+
+ if msg_judge.metadata.get("finished"):
+ print(
+ "\nThe debate is finished, and the correct answer is: ",
+ msg_judge.metadata.get("correct_answer"),
+ )
+ break
+
+
+asyncio.run(run_multiagent_debate())
+
+
+# %%
+# Further Reading
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`pipeline`
+#
+# .. _EMNLP 2024:
+# Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate. EMNLP 2024.
+#
diff --git a/docs/tutorial/en/src/workflow_routing.py b/docs/tutorial/en/src/workflow_routing.py
new file mode 100644
index 000000000..912f9fe7a
--- /dev/null
+++ b/docs/tutorial/en/src/workflow_routing.py
@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""
+.. _routing:
+
+Routing
+==========================
+There are two ways to implement routing in AgentScope, both simple and easy to implement:
+
+- Routing by structured output
+- Routing by tool calls
+
+.. tip:: Considering there is no unified standard/definition for agent routing, we follow the setting in `Building effective agents <https://www.anthropic.com/engineering/building-effective-agents>`_
+
+Routing by Structured Output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By this way, we can directly use the structured output of the agent to determine which agent to route the message to.
+
+Initialize a routing agent
+"""
+import asyncio
+import json
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit, ToolResponse
+
+router = ReActAgent(
+ name="Router",
+ sys_prompt="You're a routing agent. Your target is to route the user query to the right follow-up task.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+)
+
+
+# Use structured output to specify the routing task
+class RoutingChoice(BaseModel):
+ your_choice: Literal[
+ "Content Generation",
+ "Programming",
+ "Information Retrieval",
+ None,
+ ] = Field(
+ description="Choose the right follow-up task, and choose ``None`` if the task is too simple or no suitable task",
+ )
+ task_description: str | None = Field(
+ description="The task description",
+ default=None,
+ )
+
+
+async def example_router_explicit() -> None:
+ """Example of explicit routing with structured output."""
+ msg_user = Msg(
+ "user",
+ "Help me to write a poem",
+ "user",
+ )
+
+ # Route the query
+ msg_res = await router(
+ msg_user,
+ structured_model=RoutingChoice,
+ )
+
+ # The structured output is stored in the metadata field
+ print("The structured output:")
+ print(json.dumps(msg_res.metadata, indent=4, ensure_ascii=False))
+
+
+asyncio.run(example_router_explicit())
+
+# %%
+# Routing by Tool Calls
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+# Another way is to wrap the downstream agents into a tool function, so that the routing agent decides which tool to call based on the user query.
+#
+# We first define several tool functions:
+#
+
+
+async def generate_python(demand: str) -> ToolResponse:
+ """Generate Python code based on the demand.
+
+ Args:
+ demand (``str``):
+ The demand for the Python code.
+ """
+ # An example demand agent
+ python_agent = ReActAgent(
+ name="PythonAgent",
+ sys_prompt="You're a Python expert, your target is to generate Python code based on the demand.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ )
+ msg_res = await python_agent(Msg("user", demand, "user"))
+
+ return ToolResponse(
+ content=msg_res.get_content_blocks("text"),
+ )
+
+
+# Fake some other tool functions for demonstration purposes
+async def generate_poem(demand: str) -> ToolResponse:
+ """Generate a poem based on the demand.
+
+ Args:
+ demand (``str``):
+ The demand for the poem.
+ """
+ pass
+
+
+async def web_search(query: str) -> ToolResponse:
+ """Search the web for the query.
+
+ Args:
+ query (``str``):
+ The query to search.
+ """
+ pass
+
+
+# %%
+# After that, we define a routing agent and equip it with the above tool functions.
+#
+
+toolkit = Toolkit()
+toolkit.register_tool_function(generate_python)
+toolkit.register_tool_function(generate_poem)
+toolkit.register_tool_function(web_search)
+
+# Initialize the routing agent with the toolkit
+router_implicit = ReActAgent(
+ name="Router",
+ sys_prompt="You're a routing agent. Your target is to route the user query to the right follow-up task.",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+)
+
+
+async def example_router_implicit() -> None:
+ """Example of implicit routing with tool calls."""
+ msg_user = Msg(
+ "user",
+ "Help me to generate a quick sort function in Python",
+ "user",
+ )
+
+ # Route the query
+ await router_implicit(msg_user)
+
+
+asyncio.run(example_router_implicit())
diff --git a/docs/tutorial/zh_CN/.DS_Store b/docs/tutorial/zh_CN/.DS_Store
new file mode 100644
index 000000000..c02aa0222
Binary files /dev/null and b/docs/tutorial/zh_CN/.DS_Store differ
diff --git a/docs/tutorial/zh_CN/Makefile b/docs/tutorial/zh_CN/Makefile
new file mode 100644
index 000000000..92dd33a1a
--- /dev/null
+++ b/docs/tutorial/zh_CN/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/tutorial/zh_CN/build.sh b/docs/tutorial/zh_CN/build.sh
new file mode 100755
index 000000000..40258e648
--- /dev/null
+++ b/docs/tutorial/zh_CN/build.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -e
+
+# Generate the API rst files
+sphinx-apidoc -o api ../../../src/agentscope -t ../_templates -e
+
+# Build the html
+sphinx-build -M html ./ build
\ No newline at end of file
diff --git a/docs/tutorial/zh_CN/conf.py b/docs/tutorial/zh_CN/conf.py
new file mode 100644
index 000000000..cd9afab92
--- /dev/null
+++ b/docs/tutorial/zh_CN/conf.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "AgentScope"
+copyright = "2025, Alibaba"
+author = "Alibaba Tongyi Lab"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ "myst_parser",
+ "sphinx_gallery.gen_gallery",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.napoleon",
+]
+
+myst_enable_extensions = [
+ "colon_fence",
+]
+
+sphinx_gallery_conf = {
+ "download_all_examples": False,
+ "examples_dirs": [
+ "src",
+ ],
+ "gallery_dirs": [
+ "tutorial",
+ ],
+ "filename_pattern": "src/.*\.py",
+ "example_extensions": [".py"],
+}
+
+templates_path = ["../_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+languages = ["en", "zh_CN"]
+language = "zh_CN"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_title = "AgentScope"
+html_logo = "../_static/images/logo.svg"
+html_static_path = ["../_static"]
+html_css_files = [
+ "css/gallery.css",
+]
+
+html_js_files = [
+ "language_switch.js",
+]
+
+source_suffix = [".md", ".rst"]
+
+
+# -- Options for API documentation -------------------------------------------
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_class_signature = "separated"
+autodoc_default_options = {
+ "special-members": "__call__",
+}
+
+add_module_names = False
+python_display_short_literal_types = True
+
+
+def skip_member(app, what, name, obj, skip, options):
+ if name in [
+ "__call__",
+ "_format",
+ "_format_agent_message",
+ "_format_tool_sequence",
+ ]:
+ return False
+
+ return skip
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", skip_member)
diff --git a/docs/tutorial/zh_CN/index.rst b/docs/tutorial/zh_CN/index.rst
new file mode 100644
index 000000000..4d0669828
--- /dev/null
+++ b/docs/tutorial/zh_CN/index.rst
@@ -0,0 +1,71 @@
+.. AgentScope Doc documentation master file, created by
+ sphinx-quickstart on Thu Aug 8 15:07:21 2024.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to AgentScope's documentation!
+==========================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Tutorial
+
+ tutorial/quickstart_installation
+ tutorial/quickstart_key_concept
+ tutorial/quickstart_message
+ tutorial/quickstart_agent
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Workflow
+
+ tutorial/workflow_conversation
+ tutorial/workflow_multiagent_debate
+ tutorial/workflow_concurrent_agents
+ tutorial/workflow_routing
+ tutorial/workflow_handoffs
+
+.. toctree::
+ :maxdepth: 1
+ :caption: FAQ
+
+ tutorial/faq
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Task Guides
+
+ tutorial/task_model
+ tutorial/task_prompt
+ tutorial/task_tool
+ tutorial/task_memory
+ tutorial/task_long_term_memory
+ tutorial/task_agent
+ tutorial/task_pipeline
+ tutorial/task_state
+ tutorial/task_hook
+ tutorial/task_mcp
+ tutorial/task_studio
+ tutorial/task_tracing
+ tutorial/task_eval
+ tutorial/task_embedding
+ tutorial/task_token
+
+.. toctree::
+ :maxdepth: 1
+ :caption: API Docs
+
+ api/agentscope
+ api/agentscope.message
+ api/agentscope.model
+ api/agentscope.formatter
+ api/agentscope.module
+ api/agentscope.pipeline
+ api/agentscope.agent
+ api/agentscope.memory
+ api/agentscope.tool
+ api/agentscope.mcp
+ api/agentscope.token
+ api/agentscope.tracing
+ api/agentscope.session
+ api/agentscope.exception
diff --git a/docs/tutorial/zh_CN/make.bat b/docs/tutorial/zh_CN/make.bat
new file mode 100644
index 000000000..dc1312ab0
--- /dev/null
+++ b/docs/tutorial/zh_CN/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/tutorial/zh_CN/src/README.md b/docs/tutorial/zh_CN/src/README.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/tutorial/zh_CN/src/faq.py b/docs/tutorial/zh_CN/src/faq.py
new file mode 100644
index 000000000..6afce30af
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/faq.py
@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+.. _faq:
+
+常见问题
+========================================
+
+关于 AgentScope
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*什么是AgentScope?*
+ AgentScope 是一个多智能体框架,旨在提供一种简单高效的方式来构建基于大语言模型的智能体应用程序。
+
+*AgentScope v1.0 与 v0.x 版本有什么区别?*
+ AgentScope v1.0是对框架的完全重写,配备了新功能和改进。详细变更请参考相关文档。
+
+
+关于模型
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*如何在 AgentScope 中集成我自己的模型?*
+ 通过继承 ``agentscope.model.ChatModelBase`` 并实现 ``__call__`` 方法来创建您自己的模型。
+
+*AgentScope 支持哪些模型?*
+ 目前,AgentScope 内置支持 DashScope、Gemini、OpenAI、Anthropic 和 Ollama API,以及与 DeepSeek 和 vLLMs 模型兼容的 ``OpenAIChatModel``。
+
+*如何在 AgentScope 中监控token 使用情况?*
+ 在 AgentScope Studio中,我们提供了 token 使用情况的可视化和追踪功能。详情请参考:ref:`studio` 部分。
+
+
+关于智能体
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*如何创建我自己的智能体?*
+ 您可以选择直接使用 ``ReActAgent`` 类,或者通过继承 ``AgentBase`` 或 ``ReActAgentBase`` 类来创建您自己的智能体。详情请参考 :ref:`agent` 部分。
+
+
+*如何将智能体的(流式)输出转发到我自己的前端或应用程序?*
+ 使用 ``print`` 函数的前置钩子来转发打印消息。请参考 :ref:`hook` 部分。
+
+
+关于工具
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*AgentScope 提供了多少工具?*
+ AgentScope 提供了一套内置工具,包括 ``execute_python_code``、``execute_shell_command``、``write_text_file`` 等。您可以在 ``agentscope.tool`` 模块下找到它们。
+
+
+关于错误报告
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*如何报告 AgentScope中的错误?*
+ 如果您在使用 AgentScope 时遇到错误,请通过在我们的 GitHub仓库中开启一个issue来报告。
+
+*如何报告AgentScope 中的安全漏洞?*
+ 如果您在AgentScope 中发现安全问题,请通过 `阿里巴巴安全响应中心(ASRC) <https://security.alibaba.com/>`_ 向我们报告。
+
+"""
diff --git a/docs/tutorial/zh_CN/src/quickstart_agent.py b/docs/tutorial/zh_CN/src/quickstart_agent.py
new file mode 100644
index 000000000..dba605b3f
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/quickstart_agent.py
@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""
+.. _react-agent:
+
+创建 ReAct 智能体
+====================
+
+AgentScope 在 ``agentscope.agent`` 模块下提供了开箱即用的 ReAct 智能体 ``ReActAgent`` 供开发者使用。
+
+它同时支持以下功能:
+
+- ✨ 基础功能
+ - 支持围绕 ``reply``、``observe``、``print``、``_reasoning`` 和 ``_acting`` 的 **钩子函数(hooks)**
+ - 支持结构化输出
+- ✋ 实时介入(Realtime Steering)
+ - 支持用户 **中断**
+ - 支持自定义 **中断处理**
+- 🛠️ 工具
+ - 支持 **同步/异步** 工具函数
+ - 支持 **流式** 工具响应
+ - 支持 **状态化** 的工具管理
+ - 支持 **并行** 工具调用
+ - 支持 **MCP** 服务器
+- 💾 记忆
+ - 支持智能体 **自主管理** 长期记忆
+ - 支持“静态”的长期记忆管理
+
+.. tip:: 有关这些功能的更多详细信息,请参考 :ref:`agent` 部分。本章节中,我们重点介绍如何创建 ReAct 智能体并运行。
+
+"""
+
+from agentscope.agent import ReActAgent, AgentBase
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+import asyncio
+import os
+
+from agentscope.tool import Toolkit, execute_python_code
+
+
+# %%
+# 创建 ReAct 智能体
+# ------------------------------
+# 为了提高灵活性,``ReActAgent`` 类在其构造函数中暴露了以下参数:
+#
+# .. list-table:: ``ReActAgent`` 类的初始化参数
+# :header-rows: 1
+#
+# * - 参数
+# - 进一步阅读
+# - 描述
+# * - ``name`` (必需)
+# -
+# - 智能体的名称
+# * - ``sys_prompt`` (必需)
+# -
+# - 智能体的系统提示
+# * - ``model`` (必需)
+# - :ref:`model`
+# - 智能体用于生成响应的模型
+# * - ``formatter`` (必需)
+# - :ref:`prompt`
+# - 提示构建策略,应与使用的模型保持一致
+# * - ``toolkit``
+# - :ref:`tool`
+# - 用于注册/调用工具函数的工具模块
+# * - ``memory``
+# - :ref:`memory`
+# - 用于存储对话历史的短期记忆
+# * - ``long_term_memory``
+# - :ref:`long-term-memory`
+# - 长期记忆
+# * - ``long_term_memory_mode``
+# - :ref:`long-term-memory`
+# - 长期记忆的管理模式:
+#
+# - ``agent_control``: 允许智能体通过工具函数自己控制长期记忆
+# - ``static_control``: 在每次回复(reply)的开始/结束时,会自动从长期记忆中检索/记录信息
+# - ``both``: 同时激活上述两种模式
+# * - ``enable_meta_tool``
+# - :ref:`tool`
+# - 是否启用元工具(Meta tool),即允许智能体自主管理工具函数
+# * - ``parallel_tool_calls``
+# - :ref:`agent`
+# - 是否允许并行工具调用
+# * - ``max_iters``
+# -
+# - 智能体生成响应的最大迭代次数
+#
+# 以 DashScope API 为例,我们创建一个智能体对象如下:
+
+
+async def creating_react_agent() -> None:
+ """创建一个 ReAct 智能体并运行一个简单任务。"""
+ # 准备工具
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+
+ jarvis = ReActAgent(
+ name="Jarvis",
+ sys_prompt="你是一个名为 Jarvis 的助手",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ enable_thinking=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+ )
+
+ msg = Msg(
+ name="user",
+ content="你好!Jarvis,用 Python 运行 Hello World。",
+ role="user",
+ )
+
+ await jarvis(msg)
+
+
+asyncio.run(creating_react_agent())
+
+# %%
+# 从零开始创建
+# --------------------------------
+# 为了支持开发者从零开始创建智能体,AgentScope 提供了两个基类:
+#
+# .. list-table::
+# :header-rows: 1
+#
+# * - 类
+# - 抽象方法
+# - 描述
+# * - ``AgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``handle_interrupt``
+# - - 所有智能体的基类,支持 ``reply``、``observe`` 和 ``print`` 函数的前置和后置钩子函数。
+# - 在 ``__call__`` 函数内实现了基础的实时介入(Realtime Steering)逻辑。
+# * - ``ReActAgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``handle_interrupt``
+# | ``_reasoning``
+# | ``_acting``
+# - 在 ``AgentBase`` 的基础上添加了两个抽象函数 ``_reasoning`` 和 ``_acting``,以及它们的钩子函数。
+#
+# 有关智能体类的更多详细信息,请参考 :ref:`agent` 部分。
+#
+# 以 ``AgentBase`` 类为例,我们可以通过继承它并实现 ``reply`` 方法来创建自定义智能体类。
+
+
+class MyAgent(AgentBase):
+ """自定义智能体类"""
+
+ def __init__(self) -> None:
+ """初始化智能体"""
+ super().__init__()
+
+ self.name = "Friday"
+ self.sys_prompt = "你是一个名为 Friday 的助手。"
+ self.model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ )
+ self.formatter = DashScopeChatFormatter()
+ self.memory = InMemoryMemory()
+
+ async def reply(self, msg: Msg | list[Msg] | None) -> Msg:
+ """直接调用大模型,产生回复消息。"""
+ await self.memory.add(msg)
+
+ # 准备提示
+ prompt = await self.formatter.format(
+ [
+ Msg("system", self.sys_prompt, "system"),
+ *await self.memory.get_memory(),
+ ],
+ )
+
+ # 调用模型
+ response = await self.model(prompt)
+
+ msg = Msg(
+ name=self.name,
+ content=response.content,
+ role="assistant",
+ )
+
+ # 在记忆中记录响应
+ await self.memory.add(msg)
+
+ # 打印消息
+ await self.print(msg)
+ return msg
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """观察消息。"""
+ # 将消息存储在记忆中
+ await self.memory.add(msg)
+
+ async def handle_interrupt(self) -> Msg:
+ """处理中断。"""
+ # 以固定响应为例
+ return Msg(
+ name=self.name,
+ content="我注意到您打断了我的回复,我能为你做些什么?",
+ role="assistant",
+ )
+
+
+async def run_custom_agent() -> None:
+ """运行自定义智能体。"""
+ agent = MyAgent()
+ msg = Msg(
+ name="user",
+ content="你是谁?",
+ role="user",
+ )
+ await agent(msg)
+
+
+asyncio.run(run_custom_agent())
+
+# %%
+#
+# 进一步阅读
+# ---------------------
+# - :ref:`agent`
+# - :ref:`model`
+# - :ref:`prompt`
+# - :ref:`tool`
+#
diff --git a/docs/tutorial/zh_CN/src/quickstart_installation.py b/docs/tutorial/zh_CN/src/quickstart_installation.py
new file mode 100644
index 000000000..b3599f6b8
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/quickstart_installation.py
@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""
+.. _installation:
+
+安装
+============================
+
+AgentScope 需要 Python 3.10 或更高版本。您可以从源代码或 PyPI 安装。
+
+从 PyPI 安装
+----------------
+.. code-block:: bash
+
+ pip install agentscope
+
+从源代码安装
+----------------
+从源代码安装 AgentScope,需要从 GitHub 克隆仓库,并通过以下命令安装
+
+.. code-block:: bash
+
+ git clone -b main https://github.com/agentscope-ai/agentscope
+ cd agentscope
+ pip install -e .
+
+执行以下代码确保 AgentScope 正常安装:
+"""
+
+import agentscope
+
+print(agentscope.__version__)
+
+# %%
+# 额外依赖
+# ----------------------------
+#
+# 为了满足不同功能的需求,AgentScope 提供了额外依赖项。
+#
+# - full: 包含模型 API 和工具函数的额外依赖项
+# - dev: 开发依赖项,包括测试和文档工具
+#
+# 以 full 模式为例,安装命令根据您的操作系统而有所不同。
+#
+# 对于 Windows 用户:
+#
+# .. code-block:: bash
+#
+# pip install agentscope[full]
+#
+# 对于 Mac 和 Linux 用户:
+#
+# .. code-block:: bash
+#
+# pip install agentscope\[full\]
diff --git a/docs/tutorial/zh_CN/src/quickstart_key_concept.py b/docs/tutorial/zh_CN/src/quickstart_key_concept.py
new file mode 100644
index 000000000..4df2fe118
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/quickstart_key_concept.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""
+.. key-concepts:
+
+核心概念
+====================================
+
+本章从工程实践的角度介绍 AgentScope 中的核心概念,从而阐明 AgentScope 的设计理念。
+
+.. note:: 介绍核心概念的目标是为了更好的阐明 AgentScope 在工程实践中解决的问题,以及为开发者提供的帮助,而非给出严谨的定义。
+
+状态
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+状态(State)管理是 AgentScope 框架构建的基础。其中,状态表示对象运行时某一时刻数据的快照。
+
+AgentScope 将对象的“初始化”与“状态管理”分离,对象在初始化后通过 ``load_state_dict`` 和 ``state_dict`` 方法恢复到不同的状态,或导出当前的状态。
+
+在 AgentScope 中,智能体(Agent)、记忆(memory)、长期记忆(Long-term memory)和工具模块(toolkit)都是有状态的对象。
+AgentScope 通过支持嵌套式的状态管理,将这些对象的状态管理联系起来。
+
+消息
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+消息(message)是 AgentScope 最核心的数据结构,用于
+
+- 在智能体之间交换信息,
+- 在用户交互界面显示信息,
+- 在记忆中存储信息,
+- 作为 AgentScope 与不同 LLM API 之间的统一媒介。
+
+工具
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+AgentScope 中的“工具”指的是可调用的 Python 对象,包括
+
+- 函数,
+- 偏函数(Partial function),
+- 实例方法,
+- 类方法,
+- 静态方法,以及
+- 带有 ``__call__`` 方法的可调用实例。
+
+此外,可调用对象可以是
+
+- 异步或同步调用的,
+- 流式或非流式返回结果的。
+
+因此,请放心在 AgentScope 中使用任何调用对象作为智能体的工具。
+
+智能体
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+在 AgentScope 中,智能体(Agent)行为被抽象为 ``AgentBase`` 类中的三个核心函数:
+
+- ``reply``:处理传入的消息并生成响应消息。
+- ``observe``:接收来自环境或其它智能体的消息,但不返回响应。
+- ``print``:将消息显示到目标输出(例如终端、Web 界面)。
+
+为了支持用户实时介入(Realtime Steering),AgentScope 提供了额外
+的 ``handle_interrupt`` 函数来处理智能体回复过程中的用户中断。
+
+此外,ReAct 智能体是 AgentScope 中最重要的智能体,该智能体的回复过程分为两个阶段:
+
+- 推理(Reasoning):通过调用 LLM 进行推理并生成工具调用
+- 行动(Acting):执行工具函数。
+
+因此,我们在 ``ReActAgentBase`` 类中提供了两个额外的核心函数,``_reasoning`` 和 ``_acting``。
+
+提示词格式化
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+提示词格式化器(Prompt Formatter)是 AgentScope 中保证 LLM 兼容性的核心组件,负责将消息对象转换为 LLM API 所需的格式。
+
+此外,诸如提示工程、截断和消息验证等附加功能也可以在格式化器中实现。
+
+在格式化器中,"多智能体"(或"多实体")概念与常见的多智能体编排概念不同。
+它专注于给定消息中包含多个身份实体的场景,因此 LLM API 中常用的 ``role`` 字段(通常取值为 "user"、"assistant" 或 "system")无法区分它们。
+
+因此,AgentScope 提供 MultiAgentFormatter 来处理这种场景,通常用于游戏、多人聊天和社交仿真。
+
+.. note:: 多智能体工作流 **!=** 格式化器中的多智能体。例如,即使以下代码片段可能涉及多个
+ 智能体(``tool_agent`` 和 ``tool_function`` 的调用者),但是输入的 ``query`` 参数
+ 被包装成了 ``role`` 为 **“user”** 消息,因此 ``role`` 字段仍然可以区分它们。
+
+ .. code-block:: python
+
+ async def tool_function(query: str) -> str:
+ \"\"\"调用另一个智能体的工具函数\"\"\"
+ msg = Msg("user", query, role="user")
+ tool_agent = Agent(name="Programmer")
+ return await tool_agent(msg)
+
+ 理解这种区别有助于开发者了解格式化器部分中单智能体和多智能体的区别。
+
+
+长期记忆
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+虽然 AgentScope 为短期记忆和长期记忆提供了不同的基类,但是 AgentScope 中并没有严格区分它们的作用。
+
+在我们看来,一切都应该是 **需求驱动的**。只要开发者的需求得到了很好的满足,完全可以只使用一个强大的记忆系统。
+
+这里为了确保 AgentScope 的灵活性,我们为长期记忆提供了两种运行和管理方式,开发者可以根据自己的需要进行选择。
+其中“agent_control”模式允许智能体自己主动管理长期记忆,而“static_control”则是传统的由开发者管理的长期记忆
+模式。
+"""
diff --git a/docs/tutorial/zh_CN/src/quickstart_message.py b/docs/tutorial/zh_CN/src/quickstart_message.py
new file mode 100644
index 000000000..8136c381a
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/quickstart_message.py
@@ -0,0 +1,267 @@
+# -*- coding: utf-8 -*-
+"""
+.. _message:
+
+创建消息
+====================
+
+消息是 AgentScope 中的核心概念,用于支持多模态数据、工具 API、信息存储/交换和提示构建。
+
+一个消息由四个字段组成:
+
+- ``name``,
+- ``role``,
+- ``content``,以及
+- ``metadata``
+
+这些字段的类型和含义如下:
+
+.. list-table:: 消息对象中的字段
+ :header-rows: 1
+
+ * - 字段
+ - 类型
+ - 描述
+ * - name
+ - ``str``
+ - 消息发送者的名称/身份
+ * - role
+ - | ``Literal[``
+ | ``"system",``
+ | ``"assistant",``
+ | ``"user"``
+ | ``]``
+ - 消息发送者的角色,必须是 "system"、"assistant" 或 "user" 之一。
+ * - content
+ - ``str | list[ContentBlock]``
+ - 消息包含的数据,可以是字符串或 block 的列表。
+ * - metadata
+ - ``dict[str, JSONSerializableObject] | None``
+ - 包含额外元数据的字典,通常用于结构化输出。
+
+.. tip:: - 在具有多个身份实体的应用程序中,``name`` 字段用于区分不同的身份。
+ - 建议将 ``metadata`` 字段用于结构化输出,在 AgentScope 内置的模块中,``metadata`` 不会参与 LLM 的提示构建。
+
+接下来,我们根据不同的场景分别介绍 ``content`` 字段中支持的不同数据结构(block)。
+"""
+
+from agentscope.message import (
+ Msg,
+ Base64Source,
+ TextBlock,
+ ThinkingBlock,
+ ImageBlock,
+ AudioBlock,
+ VideoBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+import json
+
+# %%
+# 创建文本消息
+# -----------------------------
+# 通过提供 ``name``、``role`` 和 ``content`` 字段来创建消息对象。
+#
+
+msg = Msg(
+ name="Jarvis",
+ role="assistant",
+ content="你好!我能怎么帮助你?",
+)
+
+print(f"发送者的名称: {msg.name}")
+print(f"发送者的角色: {msg.role}")
+print(f"消息的内容: {msg.content}")
+
+# %%
+# 创建多模态消息
+# --------------------------------------
+# Message 类通过提供不同的 block 结构来支持多模态内容:
+#
+# .. list-table:: AgentScope 中的多模态 block
+# :header-rows: 1
+#
+# * - 类
+# - 描述
+# - 示例
+# * - TextBlock
+# - 纯文本数据
+# - .. code-block:: python
+#
+# TextBlock(
+# type="text",
+# text="Hello, world!"
+# )
+# * - ImageBlock
+# - 图像数据
+# - .. code-block:: python
+#
+# ImageBlock(
+# type="image",
+# source=URLSource(
+# type="url",
+# url="https://example.com/image.jpg"
+# )
+# )
+# * - AudioBlock
+# - 音频数据
+# - .. code-block:: python
+#
+# AudioBlock(
+# type="audio",
+# source=URLSource(
+# type="url",
+# url="https://example.com/audio.mp3"
+# )
+# )
+# * - VideoBlock
+# - 视频数据
+# - .. code-block:: python
+#
+# VideoBlock(
+# type="video",
+# source=URLSource(
+# type="url",
+# url="https://example.com/video.mp4"
+# )
+# )
+#
+# 对于 ``ImageBlock``、``AudioBlock`` 和 ``VideoBlock``,还可以使用 base64 编码的字符串作为数据源(Source):
+#
+
+msg = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ TextBlock(
+ type="text",
+ text="这是一个包含 base64 编码数据的多模态消息。",
+ ),
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type="image/jpeg",
+ data="/9j/4AAQSkZ...",
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/mpeg",
+ data="SUQzBAAAAA...",
+ ),
+ ),
+ VideoBlock(
+ type="video",
+ source=Base64Source(
+ type="base64",
+ media_type="video/mp4",
+ data="AAAAIGZ0eX...",
+ ),
+ ),
+ ],
+)
+
+# %%
+# 创建推理消息
+# --------------------------------------
+# ``ThinkingBlock`` 用于支持推理模型,包含模型的思考过程。
+#
+
+msg_thinking = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ ThinkingBlock(
+ type="thinking",
+ thinking="我正在为 AgentScope 构建一个思考块的示例。",
+ ),
+ TextBlock(
+ type="text",
+ text="这是一个思考块的示例。",
+ ),
+ ],
+)
+
+# %%
+# .. _tool-block:
+#
+# 创建工具使用/结果消息
+# --------------------------------------
+# ``ToolUseBlock`` 和 ``ToolResultBlock`` 用于支持工具 API:
+#
+
+msg_tool_call = Msg(
+ name="Jarvis",
+ role="assistant",
+ content=[
+ ToolUseBlock(
+ type="tool_use",
+ id="343",
+ name="get_weather",
+ input={
+ "location": "Beijing",
+ },
+ ),
+ ],
+)
+
+msg_tool_res = Msg(
+ name="system",
+ role="system",
+ content=[
+ ToolResultBlock(
+ type="tool_result",
+ id="343",
+ name="get_weather",
+ output="北京的天气是晴天,温度为 25°C。",
+ ),
+ ],
+)
+
+
+# %%
+# .. tip:: AgentScope 中,通常使用 ``role`` 为“system”的消息来记录工具函数的执行结果。有关 AgentScope 中工具的更多信息,请参考 :ref:`tool` 部分。
+#
+# 序列化和反序列化
+# ------------------------------------------------
+# 消息对象可以分别通过 ``to_dict`` 和 ``from_dict`` 方法进行序列化和反序列化。
+
+serialized_msg = msg.to_dict()
+
+print(type(serialized_msg))
+print(json.dumps(serialized_msg, indent=4, ensure_ascii=False))
+
+# %%
+# 从 JSON 格式的数据反序列化消息。
+
+new_msg = Msg.from_dict(serialized_msg)
+
+print(type(new_msg))
+print(f'消息的发送者: "{new_msg.name}"')
+print(f'发送者的角色: "{new_msg.role}"')
+print(f'消息的内容: "{json.dumps(new_msg.content, indent=4, ensure_ascii=False)}"')
+
+# %%
+# 属性函数
+# ------------------------------------------------
+# 为了便于使用 Msg 对象,AgentScope 提供了以下函数:
+#
+# .. list-table:: Msg 对象的函数
+# :header-rows: 1
+#
+# * - 函数
+# - 参数
+# - 描述
+# * - ``get_text_content``
+# -
+# - 将所有 ``TextBlock`` 中的内容收集到单个字符串中(用 "\\n" 分隔)。
+# * - ``get_content_blocks``
+# - ``block_type``
+# - 返回指定类型的内容块列表。如果未提供 ``block_type``,则以块格式返回全部内容。
+# * - ``has_content_blocks``
+# - ``block_type``
+# - 检查消息是否具有指定类型的内容块。``str`` 内容会被视为 ``TextBlock`` 类型。
diff --git a/docs/tutorial/zh_CN/src/task_agent.py b/docs/tutorial/zh_CN/src/task_agent.py
new file mode 100644
index 000000000..2275fc96d
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_agent.py
@@ -0,0 +1,270 @@
+# -*- coding: utf-8 -*-
+"""
+.. _agent:
+
+智能体
+=========================
+
+在章我们首先重点介绍 AgentScope 中的 ReAct 智能体,然后简要介绍如何从零开始自定义智能体。
+
+ReAct 智能体
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+在 AgentScope 中,``ReActAgent`` 类将各种功能集成到最终实现中,具体包括
+
+.. list-table:: ``ReActAgent`` 的功能特性
+ :header-rows: 1
+
+ * - 功能特性
+ - 参考文档
+ * - 支持实时介入(Realtime Steering)
+ -
+ * - 支持并行工具调用
+ -
+ * - 支持结构化输出
+ -
+ * - 支持智能体自主管理工具(Meta tool)
+ - :ref:`tool`
+ * - 支持函数粒度的 MCP 控制
+ - :ref:`mcp`
+ * - 支持智能体自主控制长期记忆
+ - :ref:`long-term-memory`
+ * - 支持自动状态管理
+ - :ref:`state`
+
+
+由于篇幅限制,本章我们仅演示 ``ReActAgent`` 类的前三个功能特性,其它功能我们在对应的章节进行介绍。
+
+"""
+
+import asyncio
+import json
+import os
+from datetime import datetime
+import time
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import TextBlock, Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit, ToolResponse
+
+
+# %%
+# 实时控制
+# ---------------------------------------
+#
+# 实时控制指 **允许用户随时中断智能体的回复,介入智能体的执行过程**,AgentScope 基于 asyncio 取消机制实现了该功能。
+#
+# 具体来说,AgentScope 中智能体提供了 ``interrupt`` 方法,当该函数被调用时,它将取消当前正在执行的 `reply` 函数,并执行 ``handle_interrupt`` 方法进行后处理。
+#
+# .. hint:: 结合 :ref:`tool` 中提到的 AgentScope 支持工具函数流式返回结果的功能,工具执行过程中如果执行时间过长或偏离用户期望,用户可以通过在终端中按 Ctrl+C 或在代码中调用智能体的
+# ``interrupt`` 方法来中断工具执行。
+#
+# .. hint:: ``ReActAgent`` 中提供了完善的中断逻辑,智能体的记忆和状态会在中断发生时被正确的保存。
+#
+# 中断逻辑已在 ``AgentBase`` 类中作为基本功能实现,并提供 ``handle_interrupt`` 抽象方法供用户自定义
+# 中断的后处理,如下所示:
+#
+# .. code-block:: python
+#
+# # AgentBase 的代码片段
+# class AgentBase:
+# ...
+# async def __call__(self, *args: Any, **kwargs: Any) -> Msg:
+# ...
+# reply_msg: Msg | None = None
+# try:
+# self._reply_task = asyncio.current_task()
+# reply_msg = await self.reply(*args, **kwargs)
+#
+# except asyncio.CancelledError:
+# # 捕获中断并通过 handle_interrupt 方法处理
+# reply_msg = await self.handle_interrupt(*args, **kwargs)
+#
+# ...
+#
+# @abstractmethod
+# async def handle_interrupt(self, *args: Any, **kwargs: Any) -> Msg:
+# pass
+#
+#
+# 在 ``ReActAgent`` 类的实现中,我们返回一个固定消息"I noticed that you have interrupted me. What can I do for you?",如下所示:
+#
+# .. figure:: ../../_static/images/interruption_zh.gif
+# :width: 100%
+# :align: center
+# :class: bordered-image
+# :alt: 中断示例
+#
+# 中断智能体 ``reply`` 的执行过程
+#
+# 开发者可以通过覆盖 ``handle_interrupt`` 函数实现自定义的中断后处理逻辑,例如,调用 LLM 生成对中断的简单响应。
+#
+#
+# 并行工具调用
+# ----------------------------------------
+# ``ReActAgent`` 通过在其构造函数中提供 ``parallel_tool_calls`` 参数来支持并行工具调用。
+# 当 LLM 生成多个工具调用且 ``parallel_tool_calls`` 设置为 ``True`` 时,
+# 它们将通过 ``asyncio.gather`` 函数并行执行。
+#
+
+
+# 准备一个工具函数
+def example_tool_function(tag: str) -> ToolResponse:
+ """一个示例工具函数"""
+ start_time = datetime.now().strftime("%H:%M:%S.%f")
+
+ # 休眠 3 秒以模拟长时间运行的任务
+ time.sleep(3)
+
+ end_time = datetime.now().strftime("%H:%M:%S.%f")
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"标签 {tag} 开始于 {start_time},结束于 {end_time}。",
+ ),
+ ],
+ )
+
+
+toolkit = Toolkit()
+toolkit.register_tool_function(example_tool_function)
+
+# 创建一个 ReAct 智能体
+agent = ReActAgent(
+ name="Jarvis",
+ sys_prompt="你是一个名为 Jarvis 的有用助手。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ parallel_tool_calls=True,
+)
+
+
+async def example_parallel_tool_calls() -> None:
+ """并行工具调用示例"""
+ # 提示智能体同时生成两个工具调用
+ await agent(
+ Msg(
+ "user",
+ "同时生成两个 'example_tool_function' 函数的工具调用,标签分别为 'tag1' 和 'tag2',以便它们可以并行执行。",
+ "user",
+ ),
+ )
+
+
+asyncio.run(example_parallel_tool_calls())
+
+# %%
+# 结构化输出
+# ----------------------------------------
+# AgentScope 中的结构化输出是与工具调用紧密结合的。具体来说,``ReActAgent`` 类在其 ``__call__`` 函数中接收 ``pydantic.BaseModel`` 的子类作为 ``structured_model`` 参数。
+# 从而提供复杂的结构化输出限制。
+# 然后我们可以从 返回消息的 ``metadata`` 字段获取结构化输出。
+#
+# 以介绍爱因斯坦为例:
+#
+
+# 创建一个 ReAct 智能体
+agent = ReActAgent(
+ name="Jarvis",
+ sys_prompt="你是一个名为 Jarvis 的有用助手。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeChatFormatter(),
+)
+
+
+# 结构化模型
+class Model(BaseModel):
+ name: str = Field(description="人物的姓名")
+ description: str = Field(description="人物的一句话描述")
+ age: int = Field(description="年龄")
+ honor: list[str] = Field(description="人物荣誉列表")
+
+
+async def example_structured_output() -> None:
+ """结构化输出示例"""
+ res = await agent(
+ Msg(
+ "user",
+ "介绍爱因斯坦",
+ "user",
+ ),
+ structured_model=Model,
+ )
+ print("\n结构化输出:")
+ print(json.dumps(res.metadata, indent=4, ensure_ascii=False))
+
+
+asyncio.run(example_structured_output())
+
+# %%
+# 自定义智能体
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 提供了两个基类:``AgentBase`` 和 ``ReActAgentBase``,它们在抽象方法和支持的钩子函数方面有所不同。
+# 具体来说,``ReActAgentBase`` 扩展了 ``AgentBase``,增加了额外的 ``_reasoning`` 和 ``_acting`` 抽象方法,以及它们的前置和后置钩子函数。
+#
+# 开发者可以根据需要选择继承这两个基类中的任一个。
+# 我们总结了 ``agentscope.agent`` 模块下的智能体如下:
+#
+# .. list-table:: AgentScope 中的智能体类
+# :header-rows: 1
+#
+# * - 类
+# - 抽象方法
+# - 支持的钩子函数
+# - 描述
+# * - ``AgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``print``
+# | ``handle_interrupt``
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# - 所有智能体的基类,提供基本接口和钩子。
+# * - ``ReActAgentBase``
+# - | ``reply``
+# | ``observe``
+# | ``print``
+# | ``handle_interrupt``
+# | ``_reasoning``
+# | ``_acting``
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# | pre\_/post_reasoning
+# | pre\_/post_acting
+# - ReAct 类智能体的抽象类,扩展了 ``AgentBase``,增加了 ``_reasoning`` 和 ``_acting`` 抽象方法及其钩子。
+# * - ``ReActAgent``
+# - \-
+# - | pre\_/post_reply
+# | pre\_/post_observe
+# | pre\_/post_print
+# | pre\_/post_reasoning
+# | pre\_/post_acting
+# - ``ReActAgentBase`` 的实现
+# * - ``UserAgent``
+# -
+# -
+# - 代表用户的特殊智能体,用于与智能体交互
+#
+#
+#
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`tool`
+# - :ref:`hook`
+#
diff --git a/docs/tutorial/zh_CN/src/task_embedding.py b/docs/tutorial/zh_CN/src/task_embedding.py
new file mode 100644
index 000000000..d98bb114c
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_embedding.py
@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""
+.. _embedding:
+
+嵌入(Embedding)
+=========================
+
+AgentScope 中,嵌入模块提供了用于向量生成的统一接口,具有以下特性:
+
+- 支持 **缓存 embedding** 以避免冗余的 API 调用
+- 支持 **不同 embedding API 提供商** 并提供一致的接口
+
+AgentScope 内置支持以下 API:
+
+.. list-table::
+ :header-rows: 1
+
+ * - API 提供商
+ - 类
+ * - OpenAI
+ - ``OpenAITextEmbedding``
+ * - Gemini
+ - ``GeminiTextEmbedding``
+ * - DashScope
+ - ``DashScopeTextEmbedding``
+ * - Ollama
+ - ``OllamaTextEmbedding``
+
+所有类都继承自 ``EmbeddingModelBase``,实现了 ``__call__`` 方法并生成包含嵌入和使用信息的 ``EmbeddingResponse`` 对象。
+
+以 DashScope 嵌入类为例,您可以按如下方式使用:
+"""
+
+import asyncio
+import os
+import tempfile
+
+from agentscope.embedding import DashScopeTextEmbedding, FileEmbeddingCache
+
+
+async def example_dashscope_embedding() -> None:
+ """DashScope 文本嵌入的使用示例。"""
+ texts = [
+ "法国的首都是什么?",
+ "巴黎是法国的首都城市。",
+ ]
+
+ # 初始化 DashScope 文本嵌入实例
+ embedding_model = DashScopeTextEmbedding(
+ model_name="text-embedding-v2",
+ api_key=os.getenv("DASHSCOPE_API_KEY"),
+ )
+
+ # 从模型获取嵌入
+ response = await embedding_model(texts)
+
+ print("嵌入 ID: ", response.id)
+ print("嵌入创建时间: ", response.created_at)
+ print("嵌入使用情况: ", response.usage)
+ print("嵌入向量:")
+ print(response.embeddings)
+
+
+asyncio.run(example_dashscope_embedding())
+
+# %%
+# 可以通过继承 ``EmbeddingModelBase`` 并实现 ``__call__`` 方法来自定义 embedding 模型。
+#
+# Embedding 缓存
+# ---------------------
+# AgentScope 提供了用于缓存 embedding 的基类 ``EmbeddingCacheBase``,以及基于文件的实现 ``FileEmbeddingCache``。
+# 它在 embedding 模块中的工作方式如下:
+#
+# .. image:: ../../_static/images/embedding_cache.png
+# :align: center
+# :width: 90%
+#
+# 要使用缓存,只需将 ``FileEmbeddingCache`` 实例(或自定义缓存)传给模型的构造函数,如下所示:
+#
+
+
+async def example_embedding_cache() -> None:
+ """演示带有缓存功能的 embedding。"""
+ # 示例文本
+ texts = [
+ "法国的首都是什么?",
+ "巴黎是法国的首都城市。",
+ ]
+
+ # 为缓存演示创建临时目录
+ # 在实际应用中,建议使用持久目录以最大发挥缓存效果
+ cache_dir = tempfile.mkdtemp(prefix="embedding_cache_")
+ print(f"使用缓存目录: {cache_dir}")
+
+ # 使用缓存初始化嵌入模型
+ # 为演示目的,我们将缓存限制为 100 个文件和 10MB
+ embedder = DashScopeTextEmbedding(
+ model_name="text-embedding-v3",
+ api_key=os.getenv("DASHSCOPE_API_KEY"),
+ embedding_cache=FileEmbeddingCache(
+ cache_dir=cache_dir,
+ max_file_number=100,
+ max_cache_size=10, # 最大缓存大小(MB)
+ ),
+ )
+
+ # 第一次调用 - 将从 API 获取并存储在缓存中
+ print("\n=== 第一次 API 调用(无缓存命中)===")
+ start_time = asyncio.get_event_loop().time()
+ response1 = await embedder(texts)
+ elapsed_time1 = asyncio.get_event_loop().time() - start_time
+ print(f"来源: {response1.source}") # 应该是 'api'
+ print(f"耗时: {elapsed_time1:.4f} 秒")
+ print(f"使用的 token: {response1.usage.tokens}")
+
+ # 使用相同文本的第二次调用 - 应该使用缓存
+ print("\n=== 第二次 API 调用(预期缓存命中)===")
+ start_time = asyncio.get_event_loop().time()
+ response2 = await embedder(texts)
+ elapsed_time2 = asyncio.get_event_loop().time() - start_time
+ print(f"来源: {response2.source}") # 应该是 'cache'
+ print(f"耗时: {elapsed_time2:.4f} 秒")
+ print(
+ f"使用的 token: {response2.usage.tokens}",
+ ) # 缓存结果应该为 0
+ print(
+ f"速度提升: 使用缓存快 {elapsed_time1 / elapsed_time2:.1f} 倍",
+ )
+
+
+asyncio.run(example_embedding_cache())
diff --git a/docs/tutorial/zh_CN/src/task_eval.py b/docs/tutorial/zh_CN/src/task_eval.py
new file mode 100644
index 000000000..2bf881464
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_eval.py
@@ -0,0 +1,255 @@
+# -*- coding: utf-8 -*-
+"""
+.. _eval:
+
+智能体评测
+=========================
+
+AgentScope 提供了一个内置的评测框架,用于评测智能体在不同任务和基准测试中的性能,主要特性包括:
+
+- 基于 `Ray <https://github.com/ray-project/ray>`_ 的并行和分布式评估
+- 支持中断后继续评估
+- [开发中] 评估结果可视化
+
+.. note:: 我们正在持续集成新的基准测试到 AgentScope 中:
+
+ - ✅ `ACEBench <https://github.com/ACEBench/ACEBench>`_
+ - 🚧 `GAIA <https://huggingface.co/datasets/gaia-benchmark/GAIA/tree/main>`_ 基准测试
+
+
+概述
+---------------------------
+
+AgentScope 评估框架由几个关键组件组成:
+
+- **基准测试 (Benchmark)**: 用于系统性评估的任务集合
+ - **任务 (Task)**: 包含输入、标准答案和指标的独立评估单元
+ - **指标 (Metric)**: 评估解决方案质量的测量函数
+- **评估器 (Evaluator)**: 运行评估的引擎,聚合结果并分析性能
+ - **评估器存储 (Evaluator Storage)**: 用于记录和检索评估结果的持久化存储
+- **解决方案 (Solution)**: 用户定义的解决方案
+
+.. figure:: ../../_static/images/evaluation.png
+ :width: 90%
+ :alt: AgentScope 评估框架
+
+ *AgentScope 评估框架*
+
+AgentScope 当前的实现包括:
+
+- 评估器:
+ - ``RayEvaluator``: 基于 ray 的评估器,支持并行和分布式评估。
+ - ``GeneralEvaluator``: 通用评估器,按顺序运行任务,便于调试。
+- 基准测试:
+ - ``ACEBench``: 用于评估智能体能力的基准测试。
+
+我们在 `GitHub 仓库 <https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench>`_ 中提供了一个使用 ``RayEvaluator`` 和 ACEBench 中智能体多步骤任务的玩具示例。
+
+核心组件
+---------------
+我们将构建一个简单的玩学问题基准测试来演示如何使用 AgentScope 评估模块。
+"""
+
+TOY_BENCHMARK = [
+ {
+ "id": "math_problem_1",
+ "question": "What is 2 + 2?",
+ "ground_truth": 4.0,
+ "tags": {
+ "difficulty": "easy",
+ "category": "math",
+ },
+ },
+ {
+ "id": "math_problem_2",
+ "question": "What is 12345 + 54321 + 6789 + 9876?",
+ "ground_truth": 83331,
+ "tags": {
+ "difficulty": "medium",
+ "category": "math",
+ },
+ },
+]
+
+# %%
+# 从任务、解决方案和指标到基准测试
+# ~~~~~~~~~~~~~~~~~~~
+#
+# - 一个 ``SolutionOutput`` (Agent解决方案输出) 包含智能体生成的所有信息,包括轨迹和最终输出。
+# - 一个 ``Metric`` (评测指标) 代表一个单一的评估可调用实例,它将生成的解决方案(例如,轨迹或最终输出)与标准答案进行比较。
+# 在这个示例中,我们定义了一个指标,简单地检查解决方案中的 ``output`` 字段是否与标准答案匹配。
+
+from agentscope.evaluate import (
+ SolutionOutput,
+ MetricBase,
+ MetricResult,
+ MetricType,
+)
+
+
+class CheckEqual(MetricBase):
+ def __init__(
+ self,
+ ground_truth: float,
+ ):
+ super().__init__(
+ name="math check number equal",
+ metric_type=MetricType.NUMERICAL,
+ description="Toy metric checking if two numbers are equal",
+ categories=[],
+ )
+ self.ground_truth = ground_truth
+
+ def __call__(
+ self,
+ solution: SolutionOutput,
+ ) -> MetricResult:
+ if solution.output == self.ground_truth:
+ return MetricResult(
+ name=self.name,
+ result=1.0,
+ message="Correct",
+ )
+ else:
+ return MetricResult(
+ name=self.name,
+ result=0.0,
+ message="Incorrect",
+ )
+
+
+# %%
+# - 一个 ``Task`` (任务) 是基准测试中的一个单元,包含智能体执行和评估所需的所有信息(例如,输入/查询及其标准答案)。
+# - 一个 ``Benchmark`` (基准测试) 组织多个任务进行系统性评估。
+
+from typing import Generator
+from agentscope.evaluate import (
+ Task,
+ BenchmarkBase,
+)
+
+
+class ToyBenchmark(BenchmarkBase):
+ def __init__(self):
+ super().__init__(
+ name="Toy bench",
+ description="A toy benchmark for demonstrating the evaluation module.",
+ )
+ self.dataset = self._load_data()
+
+ @staticmethod
+ def _load_data() -> list[Task]:
+ dataset = []
+ for item in TOY_BENCHMARK:
+ dataset.append(
+ Task(
+ id=item["id"],
+ input=item["question"],
+ ground_truth=item["ground_truth"],
+ tags=item.get("tags", {}),
+ metrics=[
+ CheckEqual(item["ground_truth"]),
+ ],
+ metadata={},
+ ),
+ )
+ return dataset
+
+ def __iter__(self) -> Generator[Task, None, None]:
+ """遍历基准测试。"""
+ for task in self.dataset:
+ yield task
+
+ def __getitem__(self, index: int) -> Task:
+ """根据索引获取任务。"""
+ return self.dataset[index]
+
+ def __len__(self) -> int:
+ """获取基准测试的长度。"""
+ return len(self.dataset)
+
+
+# %%
+# 评估器
+# ~~~~~~~~~~
+#
+# 评估器 (Evaluators) 管理评估过程。它们可以自动遍历
+# 基准测试中的任务,并将每个任务输入到解决方案生成函数中,
+# 开发者需要在其中定义运行智能体和检索
+# 执行结果和轨迹的逻辑。下面是一个
+# 使用我们的玩具基准测试运行 ``GeneralEvaluator`` (通用评估器) 的示例。如果有一个大型
+# 基准测试,开发者希望通过并行化更高效地进行评估,
+# ``RayEvaluator`` (Ray评估器) 也可作为内置解决方案使用。
+
+
+import os
+import asyncio
+from typing import Callable
+from pydantic import BaseModel
+
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.agent import ReActAgent
+
+from agentscope.evaluate import (
+ GeneralEvaluator,
+ FileEvaluatorStorage,
+)
+
+
+class ToyBenchAnswerFormat(BaseModel):
+ answer_as_number: float
+
+
+async def toy_solution_generation(
+ task: Task,
+ pre_hook: Callable,
+) -> SolutionOutput:
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday. "
+ "Your target is to solve the given task with your tools. "
+ "Try to solve the task as best as you can.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ )
+ agent.register_instance_hook(
+ "pre_print",
+ "save_logging",
+ pre_hook,
+ )
+ msg_input = Msg("user", task.input, role="user")
+ res = await agent(
+ msg_input,
+ structured_model=ToyBenchAnswerFormat,
+ )
+ return SolutionOutput(
+ success=True,
+ output=res.metadata.get("answer_as_number", None),
+ trajectory=[],
+ )
+
+
+async def main() -> None:
+ evaluator = GeneralEvaluator(
+ name="ACEbench evaluation",
+ benchmark=ToyBenchmark(),
+ # 重复多少次
+ n_repeat=1,
+ storage=FileEvaluatorStorage(
+ save_dir="./results",
+ ),
+ # 使用多少个工作进程
+ n_workers=1,
+ )
+
+ # 运行评估
+ await evaluator.run(toy_solution_generation)
+
+
+asyncio.run(main())
diff --git a/docs/tutorial/zh_CN/src/task_hook.py b/docs/tutorial/zh_CN/src/task_hook.py
new file mode 100644
index 000000000..80b880b22
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_hook.py
@@ -0,0 +1,286 @@
+# -*- coding: utf-8 -*-
+"""
+.. _hook:
+
+智能体钩子函数
+===========================
+
+钩子(Hook)是 AgentScope 中的扩展点,允许开发者在特定位置自定义智能体行为,提供了一种灵活的方式来修改或扩展智能体的功能,而无需更改其核心实现。
+
+在 AgentScope 中,钩子围绕智能体的核心函数实现:
+
+
+.. list-table:: AgentScope 中支持的钩子类型
+ :header-rows: 1
+
+ * - 智能体类
+ - 核心函数
+ - 钩子类型
+ - 描述
+ * - | ``AgentBase`` 及其子类
+ - ``reply``
+ - | ``pre_reply``
+ | ``post_reply``
+ - 智能体回复消息前/后的钩子
+ * -
+ - ``print``
+ - | ``pre_print``
+ | ``post_print``
+ - 向目标输出(如终端、Web 界面)打印消息前/后的钩子
+ * -
+ - ``observe``
+ - | ``pre_observe``
+ | ``post_observe``
+ - 从环境或其它智能体观察消息前/后的钩子
+ * - | ``ReActAgentBase`` 及其子类
+ - | ``reply``
+ | ``print``
+ | ``observe``
+ - | ``pre_reply``
+ | ``post_reply``
+ | ``pre_print``
+ | ``post_print``
+ | ``pre_observe``
+ | ``post_observe``
+ -
+ * -
+ - ``_reasoning``
+ - | ``pre_reasoning``
+ | ``post_reasoning``
+ - 智能体推理过程前/后的钩子
+ * -
+ - ``_acting``
+ - | ``pre_acting``
+ | ``post_acting``
+ - 智能体行动过程前/后的钩子
+
+.. tip:: 由于 AgentScope 中的钩子函数是通过 meta class 实现的,因此支持继承。
+
+为了简化使用,AgentScope 为所有钩子提供了统一的签名。
+
+"""
+import asyncio
+from typing import Any, Type
+
+from agentscope.agent import ReActAgentBase, AgentBase
+from agentscope.message import Msg
+
+
+# %%
+# 钩子签名
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# AgentScope 为所有前置(pre_)和后置(post_)钩子提供统一的钩子签名,如下所示:
+#
+# **前置钩子签名**
+#
+# .. list-table:: 所有前置钩子的签名
+# :header-rows: 1
+#
+# * -
+# - 名称
+# - 描述
+# * - 参数
+# - ``self: AgentBase | ReActAgentBase``
+# - 智能体实例
+# * -
+# - ``kwargs: dict[str, Any]``
+# - | 目标函数的输入参数,或来自最近
+# | 一个非 None 返回值的钩子修
+# | 改后的参数
+# * - 返回值
+# - ``dict[str, Any] | None``
+# - 修改后的参数或 None
+#
+# .. note:: 核心函数的所有位置参数(*args)和关键字参数(**kwargs)被统一成单个 ``kwargs`` 字典传递给钩子函数
+#
+# 前置钩子模板定义如下:
+#
+
+
+def pre_hook_template(
+ self: AgentBase | ReActAgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any] | None: # 修改后的输入
+ """前置钩子模板。"""
+ pass
+
+
+# %%
+# **后置钩子签名**
+#
+# 对于后置钩子,在签名中增加了一个额外的 ``output`` 参数,表示目标函数的输出。
+# 如果核心函数没有输出,``output`` 参数将为 ``None``。
+#
+# .. list-table:: 所有后置钩子的签名
+# :header-rows: 1
+#
+# * -
+# - 名称
+# - 描述
+# * - 参数
+# - ``self: AgentBase | ReActAgentBase``
+# - 智能体实例
+# * -
+# - ``kwargs: dict[str, Any]``
+# - | 包含目标函数所有参数的字典
+# * -
+# - ``output: Any``
+# - | 目标函数的输出或来自前序钩子
+# | 最近一个非 None 返回值
+# * - 返回值
+# - ``dict[str, Any] | None``
+# - 修改后的输出或 None
+#
+
+
+def post_hook_template(
+ self: AgentBase | ReActAgentBase,
+ kwargs: dict[str, Any],
+ output: Any, # 目标函数的输出
+) -> Any: # 修改后的输出
+ """后置钩子模板。"""
+ pass
+
+
+# %%
+# 钩子管理
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# AgentScope 提供实例级(instance)和类级(class)钩子,其区别在于钩子函数的作用范围。
+# 它们按以下顺序执行:
+#
+# .. image:: ../../_static/images/sequential_hook.png
+# :width: 90%
+# :align: center
+# :alt: AgentScope 中的钩子
+# :class: bordered-image
+#
+# AgentScope 提供内置方法来管理实例级和类级的钩子,如下所示:
+#
+# .. list-table:: AgentScope 中的钩子管理方法
+# :header-rows: 1
+#
+# * - 级别
+# - 方法
+# - 描述
+# * - 实例级
+# - ``register_instance_hook``
+# - | 为当前对象注册具有给定钩子类型
+# | 和名称的钩子。
+# * -
+# - ``remove_instance_hook``
+# - | 移除当前对象具有给定钩子类型
+# | 和名称的钩子。
+# * -
+# - ``clear_instance_hooks``
+# - | 清除当前对象具有给定钩子类型
+# | 的所有钩子。
+# * - 类级
+# - ``register_class_hook``
+# - | 为该类的所有对象注册具有给定
+# | 钩子类型和名称的钩子。
+# * -
+# - ``remove_class_hook``
+# - | 移除该类所有对象具有给定
+# | 钩子类型和名称的钩子。
+# * -
+# - ``clear_class_hooks``
+# - | 清除该类所有对象具有给定
+# | 钩子类型的所有钩子。
+#
+# 使用钩子时,开发者需要注意以下规则:
+#
+# .. important:: **执行顺序**
+#
+# - 钩子按注册顺序执行
+# - 多个钩子可以链式连接
+# **返回值处理**
+#
+# - 对于前置钩子:非 None 返回值会传递给下一个钩子或核心函数
+# - 当钩子返回 None 时,下一个钩子将使用前序钩子中最近的非 None 返回值
+# - 如果所有前序钩子都返回 None,那该钩子接收原始参数的副本作为输入
+# - 最后一个非 None 返回值(或如果所有钩子都返回 None 则使用原始参数)传递给核心函数
+# - 对于后置钩子:工作方式与前置钩子相似。
+# **重要提示**:不要在钩子内调用核心函数(reply/speak/observe/_reasoning/_acting)以避免循环调用!
+#
+# 以下面的智能体为例,我们可以看到如何注册、移除和清除钩子:
+#
+
+
+# 创建一个简单的测试智能体类
+class TestAgent(AgentBase):
+ """用于演示钩子的测试智能体。"""
+
+ async def reply(self, msg: Msg) -> Msg:
+ """回复消息。"""
+ return msg
+
+
+# %%
+# 我们创建一个实例级钩子和一个类级钩子来在回复前修改消息内容。
+#
+
+
+# 创建两个前置回复钩子
+def instance_pre_reply_hook(
+ self: AgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """修改消息内容的前置回复钩子。"""
+ msg = kwargs["msg"]
+ msg.content += "[instance-pre-reply]"
+ # 返回修改后的 kwargs
+ return {
+ **kwargs,
+ "msg": msg,
+ }
+
+
+def cls_pre_reply_hook(
+ self: AgentBase,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """修改消息内容的前置回复钩子。"""
+ msg = kwargs["msg"]
+ msg.content += "[cls-pre-reply]"
+ # 返回修改后的 kwargs
+ return {
+ **kwargs,
+ "msg": msg,
+ }
+
+
+# 注册类钩子
+TestAgent.register_class_hook(
+ hook_type="pre_reply",
+ hook_name="test_pre_reply",
+ hook=cls_pre_reply_hook,
+)
+
+# 注册实例钩子
+agent = TestAgent()
+agent.register_instance_hook(
+ hook_type="pre_reply",
+ hook_name="test_pre_reply",
+ hook=instance_pre_reply_hook,
+)
+
+
+async def example_test_hook() -> None:
+ """测试钩子的示例函数。"""
+ msg = Msg(
+ name="user",
+ content="Hello, world!",
+ role="user",
+ )
+ res = await agent(msg)
+ print("响应内容:", res.content)
+ TestAgent.clear_class_hooks()
+
+
+asyncio.run(example_test_hook())
+
+# %%
+# 我们可以看到 "[instance-pre-reply]" 和 "[cls-pre-reply]" 被添加到了消息内容中。
+#
diff --git a/docs/tutorial/zh_CN/src/task_long_term_memory.py b/docs/tutorial/zh_CN/src/task_long_term_memory.py
new file mode 100644
index 000000000..fc32b6964
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_long_term_memory.py
@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+"""
+.. _long-term-memory:
+
+长期记忆
+========================
+
+AgentScope 为长期记忆提供了一个基类 ``LongTermMemoryBase`` 和一个基于 `mem0 <https://github.com/mem0ai/mem0>`_ 的具体实现 ``Mem0LongTermMemory``。
+结合 :ref:`agent` 章节中 ``ReActAgent`` 类的设计,我们提供了两种长期记忆模式:
+
+- ``agent_control``:智能体通过工具调用自主管理长期记忆。
+- ``static_control``:开发者通过编程显式控制长期记忆操作。
+
+当然,开发者也可以使用 ``both`` 参数,将同时激活上述两种记忆管理模式。
+
+.. hint:: 不同的记忆模式适用于不同的使用场景,开发者可以根据需要选择合适的模式。
+
+使用 mem0 长期记忆
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: 在 GitHub 仓库的 ``examples/long_term_memory/mem0`` 目录下我们提供了 mem0 长期记忆的使用示例。
+
+"""
+
+import os
+import asyncio
+
+from agentscope.message import Msg
+from agentscope.memory import InMemoryMemory, Mem0LongTermMemory
+from agentscope.agent import ReActAgent
+from agentscope.embedding import DashScopeTextEmbedding
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+
+
+# 创建 mem0 长期记忆实例
+long_term_memory = Mem0LongTermMemory(
+ agent_name="Friday",
+ user_name="user_123",
+ model=DashScopeChatModel(
+ model_name="qwen-max-latest",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ stream=False,
+ ),
+ embedding_model=DashScopeTextEmbedding(
+ model_name="text-embedding-v2",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ ),
+ on_disk=False,
+)
+
+# %%
+# ``Mem0LongTermMemory`` 类提供了两个操作长期记忆的方法,``record` 和 `retrieve`。
+# 它们接收消息对象的列表作为输入,分别记录和检索长期记忆中的信息。
+#
+# 例如下面的例子中,我们先存入用户的一条偏好,然后在长期记忆中检索相关信息。
+#
+
+
+# 基本使用示例
+async def basic_usage():
+ """基本使用示例"""
+ # 记录记忆
+ await long_term_memory.record([Msg("user", "我喜欢住民宿", "user")])
+
+ # 检索记忆
+ results = await long_term_memory.retrieve(
+ [Msg("user", "我的住宿偏好", "user")],
+ )
+ print(f"检索结果: {results}")
+
+
+asyncio.run(basic_usage())
+
+
+# %%
+# 与 ReAct 智能体集成
+# ----------------------------------------
+# AgentScope 中的 ``ReActAgent`` 在构造函数中包含 ``long_term_memory`` 和 ``long_term_memory_mode`` 两个参数,
+# 其中 ``long_term_memory`` 用于指定长期记忆实例,取值为 ``"agent_control"``, ``"static_control"`` 或 ``"both"``。
+#
+# 当 ``long_term_memory_mode`` 设置为 ``"agent_control"`` 或 ``both`` 时,在 ``ReActAgent`` 的构造函数中将
+# 注册两个工具函数:``record_to_memory`` 和 ``retrieve_from_memory``。
+# 从而使智能体能够自主的管理长期记忆。
+#
+# .. note:: 为了达到最好的效果,``"agent_control"`` 模式可能还需要在系统提示(system prompt)中添加相应的说明。
+#
+
+# 创建带有长期记忆的 ReAct 智能体
+agent = ReActAgent(
+ name="Friday",
+ sys_prompt="你是一个具有长期记忆功能的助手。",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max-latest",
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+ long_term_memory=long_term_memory,
+ long_term_memory_mode="static_control", # 使用 static_control 模式
+)
+
+
+async def record_preferences():
+ """ReAct agent integration example"""
+ # 对话示例
+ msg = Msg("user", "我去杭州旅行时,喜欢住民宿", "user")
+ await agent(msg)
+
+
+asyncio.run(record_preferences())
+
+# %%
+# 然后我们清空智能体的短期记忆,以避免造成干扰,并测试智能体是否会记住之前的对话。
+#
+
+
+async def retrieve_preferences():
+ """Retrieve user preferences from long-term memory"""
+ # 我们清空智能体的短期记忆,以避免造成干扰
+ await agent.memory.clear()
+
+ # 测试智能体是否会记住之前的对话
+ msg2 = Msg("user", "我有什么偏好?简要的回答我", "user")
+ await agent(msg2)
+
+
+asyncio.run(retrieve_preferences())
+
+# %%
+# 自定义长期记忆
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 提供了 ``LongTermMemoryBase`` 基类,它定义了长期记忆的基本接口。
+#
+# 开发者可以继承 ``LongTermMemoryBase`` 并实现以下的抽象方法来定义自己的长期记忆类:
+#
+# .. list-table:: AgentScope 中的长期记忆类
+# :header-rows: 1
+#
+# * - 类
+# - 抽象方法
+# - 描述
+# * - ``LongTermMemoryBase``
+# - | ``record``
+# | ``retrieve``
+# | ``record_to_memory``
+# | ``retrieve_from_memory``
+# - - 如果想支持 “static_control” 模式,必须实现``record` 和 `retrieve` 方法。
+# - 想要支持 “agent_control” 模式,必须实现 ``record_to_memory`` 和 ``retrieve_from_memory`` 方法。
+# * - ``Mem0LongTermMemory``
+# - \-
+# - 基于 mem0 库的长期记忆实现,支持向量存储和检索。
+#
+#
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`memory` - 基础记忆系统
+# - :ref:`agent` - ReAct 智能体
+# - :ref:`tool` - 工具系统
diff --git a/docs/tutorial/zh_CN/src/task_mcp.py b/docs/tutorial/zh_CN/src/task_mcp.py
new file mode 100644
index 000000000..666fe0da9
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_mcp.py
@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+.. _mcp:
+
+MCP
+=========================
+
+本章将介绍 AgentScope 对 MCP(Model Context Protocol)的以下支持:
+
+- 支持 **HTTP** (StreamableHTTP 和 SSE)和 **StdIO** 类型的 MCP 服务器
+- 提供 **有状态** 和 **无状态** 两种 MCP 客户端
+- 提供 **MCP 级别** 和 **函数级别** 的 MCP 工具管理
+
+这里的有状态/无状态是指客户端是否会维持与 MCP 服务器的会话(session)。
+无状态客户端只会在调用工具发生时建立会话,并在工具调用结束后立即销毁会话,是一种轻量化的使用方式。
+
+下表总结了支持的 MCP 客户端类型和协议:
+
+.. list-table:: 支持的 MCP 客户端类型和协议
+ :header-rows: 1
+
+ * - 客户端类型
+ - HTTP(StreamableHTTP 和 SSE)
+ - StdIO
+ * - 有状态客户端
+ - ``HttpStatefulClient``
+ - ``StdIOStatefulClient``
+ * - 无状态客户端
+ - ``HttpStatelessClient``
+ -
+
+"""
+import asyncio
+import json
+import os
+
+from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
+from agentscope.tool import Toolkit
+
+# %%
+# MCP 客户端
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# 在 AgentScope 中,MCP 客户端负责
+#
+# - 连接到 MCP 服务器,
+# - 从服务器获取工具函数,以及
+# - 调用 MCP 服务器中的工具函数。
+#
+# AgentScope 中有两种类型的 MCP 客户端:**有状态** 和 **无状态**。
+# 它们仅在 **如何管理与 MCP 服务器的会话** 方面有所不同。
+#
+# - 有状态客户端:有状态 MCP 客户端在其生命周期内 **维持与 MCP 服务器的持久会话**。开发者应显式调用 ``connect()`` 和 ``close()`` 方法来管理会话的生命周期。
+# - 无状态客户端:无状态 MCP 客户端在调用工具函数时创建新会话,在工具函数调用完成后立即销毁会话,更加轻量化。
+#
+# .. note:: - StdIO MCP 服务器只有有状态客户端,当调用 ``connect()`` 时,它将在本地启动 MCP 服务器然后连接到它。
+# - 对于有状态客户端,开发者必须确保在调用工具函数时客户端已连接。
+#
+# 以高德地图 MCP 服务器为例,有状态和无状态客户端的创建非常相似:
+#
+
+stateful_client = HttpStatefulClient(
+ # 用于标识 MCP 的名称
+ name="mcp_services_stateful",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+)
+
+stateless_client = HttpStatelessClient(
+ # 用于标识 MCP 的名称
+ name="mcp_services_stateless",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+)
+
+# %%
+# 有状态和无状态客户端都提供以下方法:
+#
+# .. list-table:: MCP 客户端方法
+# :header-rows: 1
+#
+# * - 方法
+# - 描述
+# * - ``list_tools``
+# - 列出 MCP 服务器中所有可用的工具。
+# * - ``get_callable_function``
+# - 通过名称从 MCP 服务器获取可调用的函数对象。
+#
+# MCP 作为工具
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 提供了对 MCP 工具的细粒度管理,包括 MCP 级别和函数级别的管理。
+#
+# MCP 级别管理
+# --------------------------------
+# 您可以将 MCP 服务器的所有工具一次性注册到 ``Toolkit`` 中,如下所示。
+#
+# .. tip:: 可选地,开发者可以通过指定组名来管理工具。有关分组工具管理,请参考 :ref:`tool` 部分。
+#
+
+toolkit = Toolkit()
+
+
+async def example_register_stateless_mcp() -> None:
+ """注册无状态客户端 MCP 工具的示例。"""
+ # 从 MCP 服务器注册所有工具
+ await toolkit.register_mcp_client(
+ stateless_client,
+ # group_name="map_services", # 可选的组名
+ )
+
+ print("注册的 MCP 工具总数:", len(toolkit.get_json_schemas()))
+
+ maps_geo = next(
+ tool
+ for tool in toolkit.get_json_schemas()
+ if tool["function"]["name"] == "maps_geo"
+ )
+ print("\n示例 ``maps_geo`` 函数:")
+ print(
+ json.dumps(
+ maps_geo,
+ indent=4,
+ ensure_ascii=False,
+ ),
+ )
+
+
+asyncio.run(example_register_stateless_mcp())
+
+# %%
+# 要移除已注册的工具,可以使用 ``remove_tool_function`` 函数,或使用 ``remove_mcp_clients`` 移除特定 MCP 的所有工具。
+#
+
+
+async def example_remove_mcp_tools() -> None:
+ """移除 MCP 工具的示例。"""
+ print("移除前的工具总数:", len(toolkit.get_json_schemas()))
+
+ # 通过名称移除特定的工具函数
+ toolkit.remove_tool_function("maps_geo")
+ print("工具数量:", len(toolkit.get_json_schemas()))
+
+ # 通过名称移除 MCP 客户端的所有工具
+ await toolkit.remove_mcp_clients(client_names=["mcp_services_stateless"])
+ print("工具数量:", len(toolkit.get_json_schemas()))
+
+
+asyncio.run(example_remove_mcp_tools())
+
+# %%
+# 函数级别管理
+# --------------------------------
+# 注意到开发者有对 MCP 工具进行更细粒度控制的需求,例如对工具结果进行后处理,或使用它们创建更复杂的工具函数。
+#
+# 因此,AgentScope 支持通过工具名从 MCP 客户端获取可调用的函数对象,这样开发者可以
+#
+# - 直接调用它,
+# - 将其包装到自己的函数中,或以任何其它方式进行使用。
+#
+# 此外,开发者可以指定是否将工具函数执行结果包装成 ``ToolResponse`` 对象,以便与 ``Toolkit`` 无缝使用。
+# 如果设置 ``wrap_tool_result=False``,将返回原始结果类型 ``mcp.types.CallToolResult``。
+#
+# 以 ``maps_geo`` 函数为例,可以将其获取为可调用的函数对象,如下所示:
+#
+
+
+async def example_function_level_usage() -> None:
+ """使用函数级别 MCP 工具的示例。"""
+ func_obj = await stateless_client.get_callable_function(
+ func_name="maps_geo",
+ # 是否将工具结果包装到 AgentScope 的 ToolResponse 中
+ wrap_tool_result=True,
+ )
+
+ # 您可以获取其名称、描述和 JSON schema
+ print("函数名称:", func_obj.name)
+ print("函数描述:", func_obj.description)
+ print(
+ "函数 JSON schema:",
+ json.dumps(func_obj.json_schema, indent=4, ensure_ascii=False),
+ )
+
+ # 直接调用函数对象
+ res = await func_obj(
+ address="天安门广场",
+ city="北京",
+ )
+ print("\n函数调用结果:")
+ print(res)
+
+
+asyncio.run(example_function_level_usage())
+
+# %%
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# 有关更多详细信息,请参见:
+#
+# - :ref:`tool`
+# - :ref:`agent`
+#
diff --git a/docs/tutorial/zh_CN/src/task_memory.py b/docs/tutorial/zh_CN/src/task_memory.py
new file mode 100644
index 000000000..80253530b
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_memory.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""
+.. _memory:
+
+记忆
+========================
+
+在 AgentScope 中,记忆(memory)用于存储智能体的上下文,并在需要时检索它。
+具体而言,AgentScope 在 ``agentscope.memory`` 模块下提供了记忆基类 ``MemoryBase`` 和一个可直接使用的基于内存实现 ``InMemoryMemory``。
+
+自定义记忆
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+要自定义您自己的记忆,只需继承 ``MemoryBase`` 并实现以下方法:
+
+.. list-table::
+ :header-rows: 1
+
+ * - 方法
+ - 描述
+ * - ``add``
+ - 向记忆中添加 ``Msg`` 对象
+ * - ``delete``
+ - 从记忆中删除项目
+ * - ``size``
+ - 记忆的大小
+ * - ``clear``
+ - 清空记忆内容
+ * - ``get_memory``
+ - 以 ``Msg`` 对象列表的形式获取记忆内容
+ * - ``state_dict``
+ - 获取记忆的状态字典
+ * - ``load_state_dict``
+ - 加载记忆的状态字典
+
+进一步阅读
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :ref:`long-term-memory`
+"""
diff --git a/docs/tutorial/zh_CN/src/task_model.py b/docs/tutorial/zh_CN/src/task_model.py
new file mode 100644
index 000000000..2f1ca5e04
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_model.py
@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""
+.. _model:
+
+模型
+====================
+
+在本教程中,我们介绍 AgentScope 中集成的模型 API、如何使用它们,以及如何集成新的模型 API。
+AgentScope 目前支持的模型 API 和模型提供商包括:
+
+.. list-table::
+ :header-rows: 1
+
+ * - API
+ - 类
+ - 兼容
+ - 流式
+ - 工具
+ - 视觉
+ - 推理
+ * - OpenAI
+ - ``OpenAIChatModel``
+ - vLLM, DeepSeek
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - DashScope
+ - ``DashScopeChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Anthropic
+ - ``AnthropicChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Gemini
+ - ``GeminiChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ * - Ollama
+ - ``OllamaChatModel``
+ -
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+
+为了提供统一的模型接口,上述所有类均被统一为:
+
+- ``__call__`` 函数的前三个参数是 ``messages``,``tools`` 和 ``tool_choice``,分别是输入消息,工具函数的 JSON schema,以及工具选择的模式。
+- 非流式返回时,返回类型是 ``ChatResponse`` 实例;流式返回时,返回的是 ``ChatResponse`` 的异步生成器。
+
+.. note:: 不同的模型 API 在输入消息格式上有所不同,AgentScope 通过 formatter 模块处理消息的转换,请参考 :ref:`format`。
+
+``ChatResponse`` 包含大模型生成的推理/文本/工具使用内容、身份、创建时间和使用信息。
+"""
+import asyncio
+import json
+import os
+
+from agentscope.message import TextBlock, ToolUseBlock, ThinkingBlock, Msg
+from agentscope.model import ChatResponse, DashScopeChatModel
+
+response = ChatResponse(
+ content=[
+ ThinkingBlock(
+ type="thinking",
+ thinking="我应该在 Google 上搜索 AgentScope。",
+ ),
+ TextBlock(type="text", text="我将在 Google 上搜索 AgentScope。"),
+ ToolUseBlock(
+ type="tool_use",
+ id="642n298gjna",
+ name="google_search",
+ input={"query": "AgentScope"},
+ ),
+ ],
+)
+
+print(response)
+
+# %%
+# 以 ``DashScopeChatModel`` 为例,调用和返回结果如下:
+
+
+async def example_model_call() -> None:
+ """使用 DashScopeChatModel 的示例。"""
+ model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ )
+
+ res = await model(
+ messages=[
+ {"role": "user", "content": "你好!"},
+ ],
+ )
+
+ # 您可以直接使用响应内容创建 ``Msg`` 对象
+ msg_res = Msg("Friday", res.content, "assistant")
+
+ print("LLM 返回结果:", res)
+ print("作为 Msg 的响应:", msg_res)
+
+
+asyncio.run(example_model_call())
+
+# %%
+# 流式返回
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 要启用流式返回,请在模型的构造函数中将 ``stream`` 参数设置为 ``True``。
+# 流式返回中,``__call__`` 方法将返回一个 **异步生成器**,该生成器迭代返回 ``ChatResponse`` 实例。
+#
+# .. note:: AgentScope 中的流式返回结果为 **累加式**,这意味着每个 chunk 中的内容包含所有之前的内容加上新生成的内容。
+#
+
+
+async def example_streaming() -> None:
+ """使用流式模型的示例。"""
+ model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ )
+
+ generator = await model(
+ messages=[
+ {
+ "role": "user",
+ "content": "从 1 数到 20,只报告数字,不要任何其他信息。",
+ },
+ ],
+ )
+ print("响应的类型:", type(generator))
+
+ i = 0
+ async for chunk in generator:
+ print(f"块 {i}")
+ print(f"\t类型: {type(chunk.content)}")
+ print(f"\t{chunk}\n")
+ i += 1
+
+
+asyncio.run(example_streaming())
+
+# %%
+# 推理模型
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 通过提供 ``ThinkingBlock`` 来支持推理模型。
+#
+
+
+async def example_reasoning() -> None:
+ """使用推理模型的示例。"""
+ model = DashScopeChatModel(
+ model_name="qwen-turbo",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ enable_thinking=True,
+ )
+
+ res = await model(
+ messages=[
+ {"role": "user", "content": "我是谁?"},
+ ],
+ )
+
+ last_chunk = None
+ async for chunk in res:
+ last_chunk = chunk
+ print("最终响应:")
+ print(last_chunk)
+
+
+asyncio.run(example_reasoning())
+
+# %%
+# 工具 API
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 不同的模型提供商在工具 API 方面有所不同,例如工具 JSON schema、工具调用/响应格式。
+# 为了提供统一的接口,AgentScope 通过以下方式解决了这个问题:
+#
+# - 提供了统一的工具调用结构 block :ref:`ToolUseBlock <tool-block>` 和工具响应结构 :ref:`ToolResultBlock <tool-block>`。
+# - 在模型类的 ``__call__`` 方法中提供统一的工具接口 ``tools``,接受工具 JSON schema 列表,如下所示:
+#
+
+json_schemas = [
+ {
+ "type": "function",
+ "function": {
+ "name": "google_search",
+ "description": "在 Google 上搜索查询。",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "搜索查询。",
+ },
+ },
+ "required": ["query"],
+ },
+ },
+ },
+]
+
+# %%
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# - :ref:`message`
+# - :ref:`prompt`
+#
diff --git a/docs/tutorial/zh_CN/src/task_pipeline.py b/docs/tutorial/zh_CN/src/task_pipeline.py
new file mode 100644
index 000000000..d560f63aa
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_pipeline.py
@@ -0,0 +1,178 @@
+# -*- coding: utf-8 -*-
+"""
+.. _pipeline:
+
+管道 (Pipeline)
+========================
+
+对于多智能体编排,AgentScope 提供了 ``agentscope.pipeline`` 模块
+作为将智能体链接在一起的语法糖,具体包括
+
+- **MsgHub**: 用于多个智能体之间消息的广播
+- **sequential_pipeline** 和 **SequentialPipeline**: 以顺序方式执行多个智能体
+
+"""
+
+import os, asyncio
+
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.agent import ReActAgent
+from agentscope.pipeline import MsgHub
+
+# %%
+# 使用 MsgHub 进行广播
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# ``MsgHub`` 类是一个 **异步上下文管理器**,它接收一个智能体列表作为其参与者。
+# 当一个参与者生成回复消息时,将通过调用所有其他参与者的 ``observe`` 方法广播该消息。
+# 这意味着在 ``MsgHub`` 上下文中,开发者无需手动将回复消息从一个智能体发送到另一个智能体。
+#
+# 这里我们创建四个智能体:Alice、Bob、Charlie 和 David。
+# 然后我们让 Alice、Bob 和 Charlie 通过自我介绍开始一个会议。需要注意的是 David 没有包含在这个会议中。
+#
+
+
+def create_agent(name: str, age: int, career: str) -> ReActAgent:
+ """根据给定信息创建智能体对象。"""
+ return ReActAgent(
+ name=name,
+ sys_prompt=f"你是{name},一个{age}岁的{career}",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeMultiAgentFormatter(),
+ )
+
+
+alice = create_agent("Alice", 50, "老师")
+bob = create_agent("Bob", 35, "工程师")
+charlie = create_agent("Charlie", 28, "设计师")
+david = create_agent("David", 30, "开发者")
+
+# %%
+# 然后我们创建一个 ``MsgHub`` 上下文,并让他们自我介绍:
+#
+# .. hint:: ``announcement`` 中的消息将在进入 ``MsgHub`` 上下文时广播给所有参与者。
+#
+
+
+async def example_broadcast_message():
+ """使用 MsgHub 广播消息的示例。"""
+
+ # 创建消息中心
+ async with MsgHub(
+ participants=[alice, bob, charlie],
+ announcement=Msg(
+ "user",
+ "现在请简要介绍一下自己,包括你的姓名、年龄和职业。",
+ "user",
+ ),
+ ) as hub:
+ # 无需手动消息传递的群聊
+ await alice()
+ await bob()
+ await charlie()
+
+
+asyncio.run(example_broadcast_message())
+
+# %%
+# 现在让我们检查 Bob、Charlie 和 David 是否收到了 Alice 的消息。
+#
+
+
+async def check_broadcast_message():
+ """检查消息是否正确广播。"""
+ user_msg = Msg(
+ "user",
+ "你知道 Alice 是谁吗,她是做什么的?",
+ "user",
+ )
+
+ await bob(user_msg)
+ await charlie(user_msg)
+ await david(user_msg)
+
+
+# %%
+# 现在我们观察到 Bob 和 Charlie 知道 Alice 和她的职业,而 David 对
+# Alice 一无所知,因为他没有包含在 ``MsgHub`` 上下文中。
+#
+#
+# 动态管理
+# ---------------------------
+# 此外,``MsgHub`` 支持通过以下方法动态管理参与者:
+#
+# - ``add``: 添加一个或多个智能体作为新参与者
+# - ``delete``: 从参与者中移除一个或多个智能体,他们将不再接收广播消息
+# - ``broadcast``: 向所有当前参与者广播消息
+#
+# .. note:: 新添加的参与者不会接收到之前的消息。
+#
+# .. code-block:: python
+#
+# async with MsgHub(participants=[alice]) as hub:
+# # 添加新参与者
+# hub.add(david)
+#
+# # 移除参与者
+# hub.delete(alice)
+#
+# # 向所有当前参与者广播
+# await hub.broadcast(
+# Msg("system", "现在我们开始...", "system"),
+# )
+#
+#
+# 管道
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 管道是 AgentScope 中多智能体编排的一种语法糖。
+#
+# 目前,AgentScope 提供了一个顺序管道实现,它按预定义的顺序逐个执行智能体。
+# 例如,以下两个代码片段是等价的:
+#
+# .. code-block:: python
+# :caption: 代码片段 1: 手动消息传递
+#
+# msg = None
+# msg = await alice(msg)
+# msg = await bob(msg)
+# msg = await charlie(msg)
+# msg = await david(msg)
+#
+#
+# .. code-block:: python
+# :caption: 代码片段 2: 使用顺序管道
+#
+# from agentscope.pipeline import sequential_pipeline
+#
+# msg = await sequential_pipeline(
+# # 按顺序执行的智能体列表
+# agents=[alice, bob, charlie, david],
+# # 第一个输入消息,可以是 None
+# msg=None
+# )
+#
+# .. tip:: 通过结合 `MsgHub` 和 `sequential_pipeline`,你可以非常容易地创建更复杂的工作流。
+#
+#
+# 此外,为了可重用性,我们还提供了基于类的实现:
+#
+# .. code-block:: python
+# :caption: 使用 SequentialPipeline 类
+#
+# from agentscope.pipeline import SequentialPipeline
+#
+# # 创建管道对象
+# pipeline = SequentialPipeline(agents=[alice, bob, charlie, david])
+#
+# # 调用管道
+# msg = await pipeline(msg=None)
+#
+# # 使用不同输入复用管道
+# msg = await pipeline(msg=Msg("user", "你好!", "user"))
+#
+#
diff --git a/docs/tutorial/zh_CN/src/task_prompt.py b/docs/tutorial/zh_CN/src/task_prompt.py
new file mode 100644
index 000000000..fca0403a7
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_prompt.py
@@ -0,0 +1,335 @@
+# -*- coding: utf-8 -*-
+"""
+.. _prompt:
+
+提示词格式化
+=========================
+
+AgentScope 中的格式化器(formatter)模块负责
+
+- 将 Msg 对象转换为不同 LLM API 要求的格式,
+- (可选)截断消息以适应 max_token 的限制,
+- (可选)执行提示工程,例如对长对话进行总结。
+
+后两个功能是可选的,开发者也可以选择在记忆(memory)或智能体(agent)层面进行处理和实现。
+
+在 AgentScope 中,有两种类型的格式化器:"ChatFormatter" 和 "MultiAgentFormatter",它们根据输入消息中的“身份实体”进行区分。
+
+- **ChatFormatter**:专为标准的用户-助手场景(聊天机器人)设计,使用 ``role`` 字段来识别用户和助手。
+- **MultiAgentFormatter**:专为多智能体场景设计,使用 ``name`` 字段来识别不同的实体,在格式化的过程中会将多智能体的对话历史合并为单个消息。
+
+AgentScope 内置的格式化器如下所列
+
+.. list-table:: AgentScope 中的内置格式化器
+ :header-rows: 1
+
+ * - API 提供商
+ - 用户-助手场景
+ - 多智能体场景
+ * - OpenAI
+ - ``OpenAIFormatter``
+ - ``OpenAIFormatter``
+ * - Anthropic
+ - ``AnthropicChatFormatter``
+ - ``AnthropicMultiAgentFormatter``
+ * - DashScope
+ - ``DashScopeChatFormatter``
+ - ``DashScopeMultiAgentFormatter``
+ * - Gemini
+ - ``GeminiChatFormatter``
+ - ``GeminiChatFormatter``
+ * - Ollama
+ - ``OllamaChatFormatter``
+ - ``OllamaMultiAgentFormatter``
+ * - DeedSeek
+ - ``DeepSeekChatFormatter``
+ - ``DeepSeekMultiAgentFormatter``
+ * - vLLM
+ - ``OpenAIFormatter``
+ - ``OpenAIFormatter``
+
+.. tip:: OpenAI API 支持 `name` 字段,因此 `OpenAIFormatter` 也可以用于多智能体场景。也可以使用 `OpenAIMultiAgentFormatter` 代替,它会将对话历史合并为单个用户消息。
+
+此外,内置格式化器对于不同的消息块(message blocks)的支持情况如下表所示:
+
+.. list-table:: 内置格式化器中支持的消息块
+ :header-rows: 1
+
+ * - 格式化器
+ - tool_use/result
+ - image
+ - audio
+ - video
+ - thinking
+ * - ``OpenAIChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``DashScopeChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``DashScopeMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ❌
+ -
+ * - ``AnthropicChatFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ - ✅
+ * - ``AnthropicMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ - ✅
+ * - ``GeminiChatFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ -
+ * - ``GeminiMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ✅
+ - ✅
+ -
+ * - ``OllamaChatFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ -
+ * - ``OllamaMultiAgentFormatter``
+ - ✅
+ - ✅
+ - ❌
+ - ❌
+ -
+ * - ``DeepSeekChatFormatter``
+ - ✅
+ - ❌
+ - ❌
+ - ❌
+ -
+ * - ``DeepSeekMultiAgentFormatter``
+ - ✅
+ - ❌
+ - ❌
+ - ❌
+ -
+
+.. note:: 如 `官方文档 <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_ 所述,只有 Anthropic 建议在输入的提示词中保留推理的部分(thinking blocks)。对于其它格式化器,我们忽略输入消息中包含的 ``ThinkingBlock``。
+
+面向 ReAct 的格式化
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+内置的 formatter 均面向 ReAct 智能体进行设计,其中输入消息由交替的 **对话历史** 和 **工具调用序列** 组成。
+
+在用户-助手场景中,对话历史是用户和助手的消息,我们直接将它们转换为所期望的格式。
+然而,在多智能体场景中,对话历史是来自不同智能体的消息列表,如下所示:
+
+.. figure:: ../../_static/images/multiagent_msgs.png
+ :alt: 多智能体消息示例
+ :width: 85%
+ :align: center
+
+ *多智能体消息示例*
+
+
+因此,我们必须将对话历史合并为带有标签 "<history>" 和 "</history>" 的单个用户消息。
+以 DashScope 为例,格式化后的消息将如下所示:
+"""
+
+from agentscope.token import HuggingFaceTokenCounter
+from agentscope.formatter import DashScopeMultiAgentFormatter
+from agentscope.message import Msg, ToolResultBlock, ToolUseBlock, TextBlock
+import asyncio, json
+
+
+input_msgs = [
+ # 系统提示
+ Msg("system", "你是一个名为 Friday 的有用助手", "system"),
+ # 对话历史
+ Msg("Bob", "你好,Alice,你知道最近的图书馆在哪里吗?", "assistant"),
+ Msg(
+ "Alice",
+ "抱歉,我不知道。Charlie,你有什么想法吗?",
+ "assistant",
+ ),
+ Msg(
+ "Charlie",
+ "没有,我们问问 Friday 吧。Friday,帮我找到最近的图书馆。",
+ "assistant",
+ ),
+ # 工具序列
+ Msg(
+ "Friday",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ name="get_current_location",
+ id="1",
+ input={},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ name="get_current_location",
+ id="1",
+ output=[TextBlock(type="text", text="104.48, 36.30")],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "Friday",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ name="search_around",
+ id="2",
+ input={"location": [104.48, 36.30], "keyword": "library"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ name="search_around",
+ id="2",
+ output=[TextBlock(type="text", text="[...]")],
+ ),
+ ],
+ "system",
+ ),
+ # 对话历史继续
+ Msg("Friday", "最近的图书馆是...", "assistant"),
+ Msg("Bob", "谢谢,Friday!", "user"),
+ Msg("Alice", "我们一起去吧。", "user"),
+]
+
+
+async def run_formatter_example() -> list[dict]:
+ """多智能体消息格式化示例。"""
+ formatter = DashScopeMultiAgentFormatter()
+ formatted_message = await formatter.format(input_msgs)
+ print("格式化后的消息:")
+ print(json.dumps(formatted_message, indent=4, ensure_ascii=False))
+ return formatted_message
+
+
+formatted_message = asyncio.run(run_formatter_example())
+
+# %%
+# 具体来说,对话历史被格式化为:
+#
+print("第一段对话历史:")
+print(formatted_message[1]["content"])
+
+print("\n第二段对话历史:")
+print(formatted_message[-1]["content"])
+
+# %%
+# 基于截断的格式化
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 通过 AgentScope 中的 token 模块,内置格式化器支持通过 **删除最旧的消息**(除了系统提示消息)在 token 超过限制时截断输入消息。
+#
+# 以 OpenAIFormatter 为例,我们首先计算输入消息的总 token 数。
+#
+
+
+async def run_token_counter() -> int:
+ """计算输入消息的 token 数量。"""
+ # 我们使用 huggingface token 计数器用于 dashscope 模型。
+ token_counter = HuggingFaceTokenCounter(
+ "Qwen/Qwen2.5-VL-3B-Instruct",
+ use_mirror=True,
+ )
+
+ return await token_counter.count(formatted_message)
+
+
+n_tokens = asyncio.run(run_token_counter())
+print("格式化消息中的 token 数量为:", n_tokens)
+
+
+# %%
+# 然后我们将最大 token 限制设置为比总 token 数少 20 个,并运行格式化器。
+#
+
+
+async def run_truncated_formatter() -> None:
+ """带截断的消息格式化示例。"""
+ token_counter = HuggingFaceTokenCounter(
+ pretrained_model_name_or_path="Qwen/Qwen2.5-VL-3B-Instruct",
+ use_mirror=True,
+ )
+ formatter = DashScopeMultiAgentFormatter(
+ token_counter=token_counter,
+ max_tokens=n_tokens - 20,
+ )
+ truncated_formatted_message = await formatter.format(input_msgs)
+ n_truncated_tokens = await token_counter.count(truncated_formatted_message)
+ print("截断后的 token 数量:", n_truncated_tokens)
+
+ print("\n截断后的对话历史:")
+ print(truncated_formatted_message[1]["content"])
+
+
+asyncio.run(run_truncated_formatter())
+
+# %%
+# 我们可以看到来自 Bob 和 Alice 的前两条消息被删除以适应 ``max_tokens`` 的限制。
+#
+#
+# 自定义格式化器
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 提供了两个基类 ``FormatterBase`` 和其子类 ``TruncatedFormatterBase``。
+# 其中 ``TruncatedFormatterBase`` 类提供了 FIFO(First In First Out)截断策略,所有内置格式化器都继承自它。
+#
+# .. list-table:: AgentScope 中格式化器的基类
+# :header-rows: 1
+#
+# * - 类
+# - 抽象方法
+# - 描述
+# * - ``FormatterBase``
+# - ``format``
+# - 将输入的 ``Msg`` 对象格式化为目标 API 所期望的格式
+# * - ``TruncatedFormatterBase``
+# - ``_format_agent_message``
+# - 格式化智能体消息,在多智能体场景中可能包含多个身份
+# * -
+# - ``_format_tool_sequence``
+# - 将工具使用和结果序列格式化为所期望的格式
+# * -
+# - ``_format`` (可选)
+# - 将输入的 ``Msg`` 对象格式化为目标 API 所期望的格式
+#
+# .. tip:: ``TruncatedFormatterBase`` 中的 ``_format`` 将输入消息分组为智能体消息和工具序列,然后分别通过调用 ``_format_agent_message`` 和 ``_format_tool_sequence`` 来格式化它们。开发者可以重写两个函数来实现自己的格式化策略。
+#
+# .. tip:: 可选地,开发者可以重写 ``TruncatedFormatterBase`` 中的 ``_truncate`` 方法来实现自己的截断策略。
+#
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`token`
+# - :ref:`model`
+#
diff --git a/docs/tutorial/zh_CN/src/task_state.py b/docs/tutorial/zh_CN/src/task_state.py
new file mode 100644
index 000000000..b55c2b9dc
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_state.py
@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+"""
+.. _state:
+
+状态/会话管理
+=================================
+
+在 AgentScope 中,**"状态"** 是指智能体在运行中某一时刻的数据快照,包括其当前的系统提示、记忆、上下文、装备的工具以及其他 **随时间变化** 的信息。
+
+为了管理应用程序的状态,AgentScope 设计实现了 **自动状态注册** 和 **会话级状态管理**,具有以下特性:
+
+- 支持所有继承自 ``StateModule`` 的变量的 **自动状态注册**
+- 支持使用自定义序列化/反序列化方法的 **手动状态注册**
+- 支持 **会话/应用程序级别管理**
+"""
+import asyncio
+import json
+import os
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.module import StateModule
+from agentscope.session import JSONSession
+from agentscope.tool import Toolkit
+
+# %%
+# 状态模块
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# ``StateModule`` 类是 AgentScope 中状态管理的基础,提供三个基本函数:
+#
+# .. list-table:: ``StateModule`` 的方法
+# :header-rows: 1
+#
+# * - 方法
+# - 参数
+# - 描述
+# * - ``register_state``
+# - | ``attr_name``,
+# | ``custom_to_json``(可选),
+# | ``custom_from_json``(可选)
+# - 将属性注册为其状态,带有可选的序列化/反序列化函数。
+# * - ``state_dict``
+# -
+# - 获取当前对象的状态字典
+# * - ``load_state_dict``
+# - | ``state_dict``,
+# | ``strict``(可选)
+# - 将状态字典加载到当前对象
+#
+# 在 ``StateModule`` 的对象中,以下所有属性都将被视为其状态的一部分:
+#
+# - 继承自 ``StateModule`` 的 **属性**
+# - 通过 ``register_state`` 方法注册的 **属性**
+#
+# 注意 ``StateModule`` 支持 **嵌套** 序列化和反序列化,例如下面的示例中,``ClassB`` 中包含一个 ``ClassA`` 的实例:
+#
+
+
+class ClassA(StateModule):
+ def __init__(self) -> None:
+ super().__init__()
+ self.cnt = 123
+ # 将 cnt 属性注册为状态
+ self.register_state("cnt")
+
+
+class ClassB(StateModule):
+ def __init__(self) -> None:
+ super().__init__()
+
+ # 属性 "a" 继承自 StateModule,将自动视为状态的一部分
+ self.a = ClassA()
+
+ # 手动将属性 "c" 注册为状态
+ self.c = "Hello, world!"
+ self.register_state("c")
+
+
+obj_b = ClassB()
+
+print("obj_b.a 的状态:")
+print(obj_b.a.state_dict())
+
+print("\nobj_b 的状态:")
+print(json.dumps(obj_b.state_dict(), indent=4))
+
+# %%
+# 我们可以观察到 ``obj_b`` 的状态自动包含了其属性 ``a`` 的状态。
+#
+# 在 AgentScope 中,``AgentBase``、``MemoryBase``、``LongTermMemoryBase`` 和 ``Toolkit`` 类都继承自 ``StateModule``,因此支持自动和嵌套状态管理。
+#
+
+# 创建一个智能体
+agent = ReActAgent(
+ name="Friday",
+ sys_prompt="你是一个名为 Friday 的助手。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeChatFormatter(),
+ memory=InMemoryMemory(),
+ toolkit=Toolkit(),
+)
+
+initial_state = agent.state_dict()
+
+print("智能体的初始状态:")
+print(json.dumps(initial_state, indent=4, ensure_ascii=False))
+
+# %%
+# 然后我们通过生成回复消息来改变其状态:
+#
+
+
+async def example_agent_state() -> None:
+ """智能体状态管理示例。"""
+ await agent(Msg("user", "你好,智能体!", "user"))
+
+ print("生成回复后智能体的状态:")
+ print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
+
+
+asyncio.run(example_agent_state())
+
+# %%
+# 现在我们将智能体的状态恢复到初始状态:
+#
+
+agent.load_state_dict(initial_state)
+
+print("加载初始状态后:")
+print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
+
+# %%
+# 会话管理
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# 会话(Session)是应用程序中状态的集合,例如多个智能体。
+#
+# AgentScope 提供了 ``SessionBase`` 类,包含两个用于会话管理的抽象方法:``save_session_state`` 和 ``load_session_state``。
+# 开发者可以继承该类来实现自己的状态保存方案,例如对接到自己的数据库或文件系统。
+#
+# 在 AgentScope 中,我们提供了基于 JSON 和文件系统的的会话类 ``JSONSession``,
+# 它会将状态保存到会化 ID 命名的 JSON 文件中,也可以从中加载状态。
+#
+# 保存会话状态
+# -----------------------------------------
+#
+
+# 通过生成回复消息改变智能体状态
+asyncio.run(example_agent_state())
+
+print("\n智能体的状态:")
+print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
+
+# %%
+# 然后我们将其保存到会话文件中:
+
+session = JSONSession(
+ session_id="session_2025-08-08", # 使用时间作为会话 ID
+ save_dir="./user-bob/", # 使用用户名作为保存目录
+)
+
+
+async def example_session() -> None:
+ """会话管理示例。"""
+
+ # 可以保存多个状态,只需要输入的对象为 ``StateModule`` 的子类。
+ await session.save_session_state(
+ agent=agent,
+ )
+
+ print("保存的状态:")
+ with open(session.save_path, "r", encoding="utf-8") as f:
+ print(json.dumps(json.load(f), indent=4, ensure_ascii=False))
+
+
+asyncio.run(example_session())
+
+# %%
+# 加载会话状态
+# -----------------------------------------
+# 然后我们可以从会话文件中加载状态:
+#
+
+
+async def example_load_session() -> None:
+ """加载会话状态示例。"""
+
+ # 清空智能体状态
+ await agent.memory.clear()
+
+ print("当前智能体状态:")
+ print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
+
+ # 从会话文件中加载状态
+ await session.load_session_state(
+ # 这里使用的关键词参数必须与 ``save_session_state`` 中的参数一致
+ agent=agent,
+ )
+ print("加载会话状态后智能体的状态:")
+ print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
+
+
+# %%
+# 此时我们可以观察到智能体的状态已经恢复到之前保存的状态。
+#
diff --git a/docs/tutorial/zh_CN/src/task_studio.py b/docs/tutorial/zh_CN/src/task_studio.py
new file mode 100644
index 000000000..0742b9275
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_studio.py
@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""
+.. _studio:
+
+AgentScope Studio
+=========================
+
+AgentScope Studio 是一个本地部署的 Web 应用程序,它
+
+- 为智能体应用程序的开发提供 **项目管理**
+- 为运行中的应用程序提供 **可视化** 追踪
+- 内置一个为 "Friday" 的 **智能体**,支持用户二次开发
+
+.. note:: Studio 正在快速开发中,更多功能即将推出!
+
+.. figure:: ../../_static/images/studio_home.webp
+ :width: 100%
+ :alt: AgentScope Studio 主页
+ :class: bordered-image
+ :align: center
+
+ AgentScope Studio 主页
+
+快速开始
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+AgentScope Studio 通过 ``npm`` 安装:
+
+.. code-block:: bash
+
+ npm install -g agentscope-studio
+
+
+使用以下命令启动 Studio:
+
+.. code-block:: bash
+
+ as_studio
+
+要将应用程序连接到 Studio,请在 ``agentscope.init`` 函数中使用 ``studio_url`` 参数:
+
+.. code-block:: python
+
+ import agentscope
+
+ agentscope.init(studio_url="http://localhost:8000")
+
+ # 应用程序代码
+ ...
+
+然后可以在 Studio 中看到该应用程序,如下所示:
+
+.. figure:: ../../_static/images/studio_project.webp
+ :width: 100%
+ :alt: 项目管理
+ :class: bordered-image
+ :align: center
+
+ AgentScope Studio 中的项目管理
+
+关于应用程序的详细信息,例如 token 使用情况、模型调用和追踪信息,都可以在 Studio 中查看。
+
+.. figure:: ../../_static/images/studio_run.webp
+ :width: 100%
+ :alt: AgentScope Studio 运行页面
+ :class: bordered-image
+ :align: center
+
+ AgentScope Studio 中的应用程序可视化
+
+
+Friday 智能体
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Friday 是由 AgentScope 构建的实验性本地部署智能体,旨在
+
+- 回答关于 AgentScope 开发的问题,
+- 为开发者提供便捷的二次开发环境,
+- 集成 AgentScope 中所有可用功能以构建更强大的智能体,以及
+- 持续测试和集成 AgentScope 中的高级功能。
+
+.. note:: 我们非常欢迎开源社区贡献并改进 Friday!欢迎在我们的 `GitHub 仓库 <https://github.com/agentscope-ai/agentscope>`_ 上提出问题或拉取请求。
+
+我们正在持续改进 Friday,目前它集成了 AgentScope 中的以下功能:
+
+.. list-table::
+ :header-rows: 1
+
+ * - 功能
+ - 状态
+ - 进一步阅读
+ - 描述
+ * - 元工具
+ - ✅
+ - :ref:`tool`
+ - 分组工具管理,允许智能体自己更改装备的工具。
+ * - 智能体钩子
+ - ✅
+ - :ref:`hook`
+ - 使用钩子将打印消息转发到前端。
+ * - 智能体中断
+ - ✅
+ - :ref:`agent`
+ - 允许用户通过后处理中断智能体的回复过程。
+ * - 截断提示
+ - ✅
+ - :ref:`prompt`
+ - 支持使用预设的最大 token 限制截断提示。
+ * - 状态和会话管理
+ - ✅
+ - :ref:`state`
+ - 智能体的自动状态管理和会话管理,在不同运行之间维护状态。
+ * - 长期记忆
+ - 🚧
+ - :ref:`memory`
+ - 支持长期记忆管理。
+
+
+"""
diff --git a/docs/tutorial/zh_CN/src/task_token.py b/docs/tutorial/zh_CN/src/task_token.py
new file mode 100644
index 000000000..63c6e893e
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_token.py
@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""
+.. _token:
+
+Token 计数
+=========================
+
+AgentScope 在 ``agentscope.token`` 模块下提供了 token 计数功能,用于计算给定消息中
+的 token 数量,允许开发者在调用 LLM API 前预估 token 数量。
+
+具体而言,可用的 token 计数器如下:
+
+.. list-table::
+ :header-rows: 1
+
+ * - LLM API
+ - 类
+ - 实现方式
+ - 支持图像数据
+ - 支持工具
+ * - Anthropic
+ - ``AnthropicTokenCounter``
+ - 官方 API
+ - ✅
+ - ✅
+ * - OpenAI
+ - ``OpenAITokenCounter``
+ - 本地计算
+ - ✅
+ - ✅
+ * - Gemini
+ - ``GeminiTokenCounter``
+ - 官方 API
+ - ✅
+ - ✅
+ * - HuggingFace
+ - ``HuggingFaceTokenCounter``
+ - 基于Tokenizer计算
+ - 取决于模型
+ - 取决于模型
+
+.. tip:: 格式化器模块已集成了 token 计数器以支持提示截断。更多详细信息请参考 :ref:`prompt` 部分。
+
+.. note::
+ - 对于 DashScope 模型,目前 dashscope 库不提供 token 计数 API。因此我们建议使用 HuggingFace token 计数器代替。
+ - 对于 OpenAI 模型,由于官方未提供 token 计数 API,因此可能存在与官方计算结果不一致的情况。
+
+下面展示使用 OpenAI token 计数器计算 token 数量的示例:
+"""
+
+import asyncio
+from agentscope.token import OpenAITokenCounter
+
+
+async def example_token_counting():
+ # 示例消息
+ messages = [
+ {"role": "user", "content": "Hello!"},
+ {"role": "assistant", "content": "Hi, how can I help you?"},
+ ]
+
+ # OpenAI token 计数
+ openai_counter = OpenAITokenCounter(model_name="gpt-4.1")
+ n_tokens = await openai_counter.count(messages)
+
+ print(f"Token 数量: {n_tokens}")
+
+
+asyncio.run(example_token_counting())
+
+
+# %%
+# 进一步阅读
+# ------------------------------
+#
+# - :ref:`prompt`
+#
diff --git a/docs/tutorial/zh_CN/src/task_tool.py b/docs/tutorial/zh_CN/src/task_tool.py
new file mode 100644
index 000000000..d4e00ecb4
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_tool.py
@@ -0,0 +1,456 @@
+# -*- coding: utf-8 -*-
+"""
+.. _tool:
+
+工具
+=========================
+
+为了确保准确可靠的工具解析,AgentScope 全面支持工具 API 的使用,具有以下特性:
+
+- 支持从文档字符串 **自动** 解析工具函数
+- 支持 **同步和异步** 工具函数
+- 支持 **流式** 工具响应(同步或异步生成器)
+- 支持对工具 JSON Schema 的 **动态扩展**
+- 支持用户实时 **中断** 工具的执行
+- 支持智能体的 **自主工具管理**
+
+所有上述功能都由 AgentScope 中的 ``Toolkit`` 类实现,该类负责管理工具函数及其执行。
+
+.. tip:: MCP(模型上下文协议)的支持请参考 :ref:`mcp` 部分。
+"""
+import asyncio
+import inspect
+import json
+from typing import Any, AsyncGenerator
+
+from pydantic import BaseModel, Field
+
+import agentscope
+from agentscope.message import TextBlock, ToolUseBlock
+from agentscope.tool import ToolResponse, Toolkit, execute_python_code
+
+
+# %%
+# 工具函数
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 在 AgentScope 中,工具函数是一个 Python 的可调用对象,它
+#
+# - 返回一个 ``ToolResponse`` 对象或产生 ``ToolResponse`` 对象的生成器(可以是异步或同步)
+# - 具有描述工具功能和参数的文档字符串
+#
+# 工具函数的模板如下:
+
+
+def tool_function(a: int, b: str) -> ToolResponse:
+ """{函数描述}
+
+ Args:
+ a (int):
+ {第一个参数的描述}
+ b (str):
+ {第二个参数的描述}
+ """
+
+
+# %%
+# .. tip:: 实例方法和类方法也可以用作工具函数,``Toolkit`` 中将自动忽略 ``self`` 和 ``cls`` 参数。
+#
+# AgentScope 在 ``agentscope.tool`` 模块下提供了几个内置工具函数,如 ``execute_python_code``、``execute_shell_command`` 和文本文件读写函数。
+#
+
+print("内置工具函数:")
+for _ in agentscope.tool.__all__:
+ if _ not in ["Toolkit", "ToolResponse"]:
+ print(_)
+
+# %%
+# 工具模块(Toolkit)
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# ``Toolkit`` 类设计用于管理工具函数,从文档字符串中提取它们的 JSON Schema,并为工具执行提供统一接口。
+#
+# 基本用法
+# ------------------------------
+# ``Toolkit`` 类的基本功能是注册工具函数并执行它们。
+#
+
+
+# 准备一个自定义工具函数
+async def my_search(query: str, api_key: str) -> ToolResponse:
+ """一个简单的示例工具函数。
+
+ Args:
+ query (str):
+ 搜索查询。
+ api_key (str):
+ 用于身份验证的 API 密钥。
+ """
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"正在使用 API 密钥 '{api_key}' 搜索 '{query}'",
+ ),
+ ],
+ )
+
+
+# 在工具模块中注册工具函数
+toolkit = Toolkit()
+toolkit.register_tool_function(my_search)
+
+# %%
+# 注册工具函数后,可以通过调用 ``get_json_schemas`` 方法获取其 JSON Schema。
+#
+
+print("工具 JSON Schemas:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# ``Toolkit`` 还允许开发者为工具函数预设参数,这对于 API 密钥或其他敏感信息特别有用。
+#
+
+# 先清空工具模块
+toolkit.clear()
+
+# 使用预设关键字参数注册工具函数
+toolkit.register_tool_function(my_search, preset_kwargs={"api_key": "xxx"})
+
+print("带预设参数的工具 JSON Schemas:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# 预设参数后,该参数将从 JSON schema 中被移除,并在工具调用时自动传递给该工具函数。
+#
+# 在 ``Toolkit`` 中,``call_tool_function`` 方法以 ``ToolUseBlock`` 作为输入执行指定的工具函数,统一返回一个 **异步生成器**,该生成器产生 ``ToolResponse`` 对象。
+#
+# .. note:: AgentScope 中,流式返回的工具函数应该是 **“累积的”**,即当前块的内容应包含之前所有块的内容。
+#
+
+
+async def example_tool_execution() -> None:
+ """工具调用执行示例。"""
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="my_search",
+ input={"query": "AgentScope"},
+ ),
+ )
+
+ # 非流式返回的工具函数只有一个 ToolResponse 返回
+ print("工具响应:")
+ async for tool_response in res:
+ print(tool_response)
+
+
+asyncio.run(example_tool_execution())
+
+# %%
+# 动态扩展 JSON Schema
+# --------------------------------------
+#
+# Toolkit 允许通过调用 ``set_extended_model`` 方法动态扩展工具函数的 JSON schemas。
+# 这种功能允许开发者在不修改工具函数原始定义的情况下,向工具函数添加更多参数。
+#
+# .. tip:: 相关场景包括动态 :ref:`structured-output` 和 CoT(思维链)推理
+#
+# .. note:: 要扩展的工具函数应该接受可变关键字参数(``**kwargs``),以便附加字段可以传递给它。
+#
+# 以 CoT 推理为例,我们可以用 ``thinking`` 字段扩展所有工具函数,允许智能体总结当前状态然后决定下一步做什么。
+#
+
+
+# 示例工具函数
+def tool_function(**kwargs: Any) -> ToolResponse:
+ """一个工具函数"""
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"接收到的参数:{kwargs}",
+ ),
+ ],
+ )
+
+
+# 添加一个思考字段,以便智能体在给出其他参数之前可以思考。
+class ThinkingModel(BaseModel):
+ """用于附加字段的 Pydantic 模型。"""
+
+ thinking: str = Field(
+ description="总结当前状态并决定下一步做什么。",
+ )
+
+
+# 注册
+toolkit.set_extended_model("my_search", ThinkingModel)
+
+print("扩展后的 JSON Schema:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# 中断工具执行
+# ------------------------------
+# ``Toolkit`` 类支持 **异步工具函数** 的 **执行中断**,并提供 **面向智能体的后处理机制**。
+# 这种中断基于 asyncio 取消机制实现,其后处理过程根据工具函数的返回类型而有所不同。
+#
+# .. note:: 对于同步(工具)函数,它们的执行无法通过 asyncio 取消来中断。因此其中断在智能体内而不是工具模块内处理。
+# 有关更多信息,请参考 :ref:`agent` 部分。
+#
+# 具体来说,如果工具函数返回 ``ToolResponse`` 对象,将产生一个带有中断消息的 ``ToolResponse`` 对象。
+# 这样智能体可以观察到这一中断并相应地处理它。
+# 此外,该 ``ToolResponse`` 对象中的 ``is_interrupted`` 将设置为 ``True``,外部调用者可以决定是否将 ``CancelledError`` 异常抛出到外层。
+#
+# 可以被中断的异步工具函数示例如下:
+#
+
+
+async def non_streaming_function() -> ToolResponse:
+ """一个可以被中断的非流式工具函数。"""
+ await asyncio.sleep(1) # 模拟长时间运行的任务
+
+ # 为演示目的模拟中断
+ raise asyncio.CancelledError()
+
+ # 由于取消,以下代码不会被执行
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="运行成功!",
+ ),
+ ],
+ )
+
+
+async def example_tool_interruption() -> None:
+ """工具中断示例。"""
+ toolkit = Toolkit()
+ toolkit.register_tool_function(non_streaming_function)
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="non_streaming_function",
+ input={},
+ ),
+ )
+
+ async for tool_response in res:
+ print("工具响应:")
+ print(tool_response)
+ print("中断标志:")
+ print(tool_response.is_interrupted)
+
+
+asyncio.run(example_tool_interruption())
+
+# %%
+# 对于流式工具函数,``Toolkit`` 将把中断消息附加到中断发生时的 ``ToolResponse`` 上。
+# 通过这种方式,智能体可以观察到工具在中断前返回的内容。
+#
+# 中断流式工具函数的示例如下:
+#
+
+
+async def streaming_function() -> AsyncGenerator[ToolResponse, None]:
+ """一个可以被中断的流式工具函数。"""
+ # 模拟一块响应
+ yield ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="1234",
+ ),
+ ],
+ )
+
+ # 模拟中断
+ raise asyncio.CancelledError()
+
+ # 由于取消,以下代码不会被执行
+ yield ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="123456789",
+ ),
+ ],
+ )
+
+
+async def example_streaming_tool_interruption() -> None:
+ """流式工具中断示例。"""
+ toolkit = Toolkit()
+ toolkit.register_tool_function(streaming_function)
+
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="streaming_function",
+ input={},
+ ),
+ )
+
+ i = 0
+ async for tool_response in res:
+ print(f"块 {i}:")
+ print(tool_response)
+ print("中断标志:", tool_response.is_interrupted, "\n")
+ i += 1
+
+
+asyncio.run(example_streaming_tool_interruption())
+
+# %%
+# 自动工具管理
+# -------------------------------------
+# .. image:: https://img.alicdn.com/imgextra/i3/O1CN013cvRpO27MfesMsTeh_!!6000000007783-2-tps-840-521.png
+# :width: 100%
+# :align: center
+# :alt: 自动工具管理
+#
+#
+# ``Toolkit`` 类通过引入 **工具组** (Group) 的概念,以及名为 ``reset_equipped_tools`` 的 **元工具函数** (Meta Tool) 来支持 **自动工具管理** 。
+#
+# 工具组是一组相关工具函数的集合,例如浏览器使用工具、地图服务工具等,它们将被一起管理。工具组有激活和非激活两种状态,
+# 只有工具组被激活,其中的工具函数才对智能体可见,即可以通过 ``toolkit.get_json_schemas()`` 方法访问。
+#
+# 注意有一个名为 ``basic`` 的特殊组,它始终处于激活状态,注册工具时如果未指定组名,则工具函数将默认添加到此组。
+#
+# .. tip:: ``basic`` 组确保开发者不需要“组管理”的功能时,工具的基本使用不会受到影响。
+#
+# 现在我们尝试创建一个名为 ``browser_use`` 的工具组,其中包含一些网页浏览工具。
+#
+
+
+# 我们创建一些浏览器操作相关的工具
+def navigate(url: str) -> ToolResponse:
+ """导航到网页。
+
+ Args:
+ url (str):
+ 要导航到的网页的 URL。
+ """
+ pass
+
+
+def click_element(element_id: str) -> ToolResponse:
+ """点击网页上的元素。
+
+ Args:
+ element_id (str):
+ 要点击的元素的 ID。
+ """
+ pass
+
+
+toolkit = Toolkit()
+
+# 创建一个名为 browser_use 的工具组
+toolkit.create_tool_group(
+ group_name="browser_use",
+ description="用于网页浏览的工具函数。",
+ active=False,
+ # 使用这些工具时的注意事项
+ notes="""1. 使用 ``navigate`` 打开网页。
+2. 当需要用户身份验证时,请向用户询问凭据
+3. ...""",
+)
+
+toolkit.register_tool_function(navigate, group_name="browser_use")
+toolkit.register_tool_function(click_element, group_name="browser_use")
+
+# 我们也可以注册一些基本工具
+toolkit.register_tool_function(execute_python_code)
+
+# %%
+# 此时 ``browser_use`` 未被激活,如果我们检查工具 JSON schema,只能看到 ``execute_python_code`` 工具:
+
+print("此时对智能体可见的工具函数 JSON Schemas:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# 使用 ``update_tool_groups`` 方法激活或停用工具组:
+
+toolkit.update_tool_groups(group_names=["browser_use"], active=True)
+
+print("激活后对智能体可见的工具函数 JSON Schemas:")
+print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
+
+# %%
+# 此外,``Toolkit`` 提供了一个名为 ``reset_equipped_tools`` 的元工具函数,它会将所有组名(除了 "basic")作为一个 bool 型的参数,
+# 让智能体调用该工具来决定要激活哪些工具组:
+#
+# .. note:: 在 ``ReActAgent`` 类的实现中,只需要在构造函数中将 ``enable_meta_tool`` 设置为 ``True`` 即可启用元工具函数。
+#
+
+# 注册元工具函数
+toolkit.register_tool_function(toolkit.reset_equipped_tools)
+
+reset_equipped = next(
+ tool
+ for tool in toolkit.get_json_schemas()
+ if tool["function"]["name"] == "reset_equipped_tools"
+)
+print("``reset_equipped_tools`` 函数的 JSON schema:")
+print(
+ json.dumps(
+ reset_equipped,
+ indent=4,
+ ensure_ascii=False,
+ ),
+)
+
+# %%
+# 当智能体调用 ``reset_equipped_tools`` 时,对应工具组将被激活,同时返回的结果中将包含工具的使用注意事项。
+#
+
+
+async def mock_agent_reset_tools() -> None:
+ """模拟智能体调用 reset_equipped_tools 函数。"""
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="456",
+ name="reset_equipped_tools",
+ input={
+ "browser_use": True, # 激活浏览器使用工具组
+ },
+ ),
+ )
+
+ async for tool_response in res:
+ print("工具响应中的文字返回:")
+ print(tool_response.content[0]["text"])
+
+
+asyncio.run(mock_agent_reset_tools())
+
+# %%
+# 此外,``Toolkit`` 还通过 ``get_activated_notes`` 函数提供已经被激活了的工具组的 notes,开发者也可以将其组装到智能体的系统提示中,从而达到动态管理工具的作用。
+#
+# .. tip:: 自动工具管理功能已在 ``ReActAgent`` 类中实现,有关更多详细信息,请参考 :ref:`agent` 部分。
+#
+
+# 再创建一个工具组
+toolkit.create_tool_group(
+ group_name="map_service",
+ description="谷歌地图服务工具。",
+ active=True,
+ notes="""1. 使用 ``get_location`` 获取地点的位置。
+2. ...""",
+)
+
+print("激活工具组的汇总注意事项:")
+print(toolkit.get_activated_notes())
+
+# %%
+# 进一步阅读
+# ---------------------
+# - :ref:`agent`
+# - :ref:`state`
+# - :ref:`mcp`
+#
diff --git a/docs/tutorial/zh_CN/src/task_tracing.py b/docs/tutorial/zh_CN/src/task_tracing.py
new file mode 100644
index 000000000..57036da5d
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/task_tracing.py
@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+"""
+.. _tracing:
+
+追踪
+==============================
+
+AgentScope 实现了基于 OpenTelemetry 的追踪来监控和调试
+智能体应用程序的执行,具有以下特性
+
+- 为 LLM、工具、智能体、格式化器等提供内置追踪
+- 支持错误和异常追踪
+- 在 AgentScope Studio 中提供原生追踪 **可视化**
+- 支持连接到 **第三方平台**,如 `Arize-Phoenix <https://github.com/Arize-ai/phoenix>`_、`Langfuse <https://langfuse.com/>`_ 等
+
+设置
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: 连接到 :ref:`studio` 或第三方平台应该在应用程序开始时通过调用 ``agentscope.init`` 函数完成。
+
+AgentScope Studio
+---------------------------------------
+
+.. figure:: ../../_static/images/studio_tracing.png
+ :width: 100%
+ :alt: AgentScope Studio 追踪页面
+ :class: bordered-image
+ :align: center
+
+ *AgentScope Studio 中的追踪页面*
+
+
+当连接到 AgentScope Studio 时,只需在 ``agentscope.init`` 函数中提供 ``studio_url`` 参数。
+
+.. code-block:: python
+
+ import agentscope
+
+ agentscope.init(studio_url="http://xxx:port")
+
+
+第三方平台
+---------------------------------------
+
+要连接到第三方追踪平台,请在 ``agentscope.init`` 函数中设置 ``tracing_url`` 参数。
+``tracing_url`` 是您的 OpenTelemetry 收集器或任何支持 OTLP(OpenTelemetry 协议)的服务器 URL。
+
+.. code-block:: python
+
+ import agentscope
+
+ # 连接到 OpenTelemetry 兼容的后端
+ agentscope.init(tracing_url="https://your-tracing-backend:port/traces")
+
+以 Arize-Phoenix 和 Langfuse 为例:
+
+**Arize-Phoenix**:需要在环境变量中设置 ``PHOENIX_API_KEY``。
+
+.. code-block:: python
+ :caption: 连接到 Arize Phoenix
+
+ # Arize Phoenix 集成
+ import os
+
+ PHOENIX_API_KEY = os.environ.get("PHOENIX_API_KEY")
+ os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
+
+ agentscope.init(tracing_url="https://app.phoenix.arize.com/v1/traces")
+
+**LangFuse**:需要在环境变量中设置 ``LANGFUSE_PUBLIC_KEY`` 和 ``LANGFUSE_SECRET_KEY``。
+授权头是使用这些密钥构建的。
+
+.. code-block:: python
+ :caption: 连接到 LangFuse
+
+ import os, base64
+
+ LANGFUSE_PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
+ LANGFUSE_SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
+ LANGFUSE_AUTH_STRING = f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}"
+
+ LANGFUSE_AUTH = base64.b64encode(LANGFUSE_AUTH_STRING.encode("utf-8")).decode("ascii")
+ os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
+
+ # 欧盟数据区域
+ agentscope.init(tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces")
+ # 美国数据区域
+ # agentscope.init(tracing_url="https://us.cloud.langfuse.com/api/public/otel/v1/traces")
+
+
+自定义追踪
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如前所述,AgentScope 中的追踪功能是基于 OpenTelemetry 实现的。
+这意味着 AgentScope 中的追踪与开发者基于 OpenTelemetry SDK 自己实现的的追踪代码**完全兼容**。
+
+此外,AgentScope 内置了以下装饰器来追踪相应的模块,它们对不同类的特殊属性,以及返回值做了相应的特殊处理:
+
+- ``@trace_llm``:追踪 ``ChatModelBase`` 子类的 ``__call__`` 函数
+- ``@trace_reply``:追踪 ``AgentBase`` 子类的 ``reply`` 函数
+- ``@trace_format``:追踪 ``FormatterBase`` 子类的 ``format`` 函数
+- ``@trace``:追踪一般函数
+
+
+追踪大语言模型
+----------------------------------------
+
+``@trace_llm`` 装饰器用于追踪 ``ChatModelBase`` 类的 ``__call__`` 函数。
+
+.. code-block:: python
+ :caption: 追踪新的 ChatModel 类
+
+ class ExampleChatModel(ChatModelBase):
+ \"\"\"示例模型\"\"\"
+
+ ...
+
+ @trace_llm
+ async def __call__(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> AsyncGenerator[ChatResponse, None] | ChatResponse:
+ \"\"\"LLM 调用\"\"\"
+ ...
+
+
+追踪智能体
+----------------------------------------
+
+``@trace_reply`` 装饰器用于追踪智能体的 `reply` 函数。
+
+.. code-block:: python
+ :caption: 追踪新的 Agent 类
+
+ class ExampleAgent(AgentBase):
+ \"\"\"示例智能体类\"\"\"
+
+ @trace_reply
+ async def reply(self, *args: Any, **kwargs: Any) -> Msg:
+ \"\"\"回复消息。\"\"\"
+ ...
+
+
+追踪格式化器
+----------------------------------------
+``@trace_format`` 装饰器用于格式化器实现并追踪 `format` 函数。
+
+.. code-block:: python
+ :caption: 追踪新的 Formatter 类
+
+ class ExampleFormatter(FormatterBase):
+ \"\"\"简单的示例格式化器类\"\"\"
+
+ @trace_format
+ async def format(self, *args: Any, **kwargs: Any) -> list[dict]:
+ \"\"\"示例格式化\"\"\"
+
+
+一般函数追踪
+----------------------------------------
+
+``@trace`` 装饰器与上述装饰器不同,它是一个通用的追踪装饰器,可以应用于任何函数。
+它需要一个 `name` 参数来标识被追踪的函数,并且可以追踪各种类型的函数,包括:
+
+- 同步函数
+- 同步生成器函数
+- 异步函数
+- 异步生成器函数
+
+.. code-block:: python
+ :caption: 一般追踪示例
+
+ # 1. 同步函数
+ @trace(name='simple_function')
+ def simple_function(name: str, age: int) -> str:
+ \"\"\"带有自动追踪的简单函数。\"\"\"
+ return f"你好, {name}! 你的年龄是 {age} 岁。"
+
+ # 2. 同步生成器函数
+ @trace(name='number_generator')
+ def number_generator(n: int) -> Generator[int, None, None]:
+ \"\"\"生成从 0 到 n-1 的数字。\"\"\"
+ for i in range(n):
+ yield i
+
+ # 3. 异步函数
+ @trace(name='async_function')
+ async def async_function(data: dict) -> dict:
+ \"\"\"异步处理数据。\"\"\"
+ return {"processed": data}
+
+ # 4. 异步生成器函数
+ @trace(name='async_stream')
+ async def async_stream(n: int) -> AsyncGenerator[str, None]:
+ \"\"\"异步生成数据流。\"\"\"
+ for i in range(n):
+ yield f"data_{i}"
+
+"""
diff --git a/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py b/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py
new file mode 100644
index 000000000..c6d69e7dd
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""
+
+Concurrent Agents
+===================================
+在异步编程的帮助下,多智能体并发可以通过 Python 中的 ``asyncio.gather`` 执行。
+
+下面展示了一个简单的示例,其中创建了两个智能体并并发执行。
+"""
+import asyncio
+from datetime import datetime
+from typing import Any
+
+from agentscope.agent import AgentBase
+
+
+class ExampleAgent(AgentBase):
+ """用于并发执行的示例智能体。"""
+
+ def __init__(self, name: str) -> None:
+ """使用智能体名称初始化智能体。"""
+ super().__init__()
+ self.name = name
+
+ async def reply(self, *args: Any, **kwargs: Any) -> None:
+ """回复消息。"""
+ start_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+ print(f"{self.name} 开始于 {start_time}")
+ await asyncio.sleep(3) # 模拟长时间运行的任务
+ end_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+ print(f"{self.name} 结束于 {end_time}")
+
+
+async def run_concurrent_agents() -> None:
+ """运行并发智能体。"""
+ agent1 = ExampleAgent("智能体 1")
+ agent2 = ExampleAgent("智能体 2")
+
+ await asyncio.gather(agent1(), agent2())
+
+
+asyncio.run(run_concurrent_agents())
diff --git a/docs/tutorial/zh_CN/src/workflow_conversation.py b/docs/tutorial/zh_CN/src/workflow_conversation.py
new file mode 100644
index 000000000..a96e2f54a
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/workflow_conversation.py
@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+.. _conversation:
+
+Conversation
+======================
+
+Conversation 是一种智能体间交换和共享信息的设计模式,常见于游戏、聊天机器人和多智能体讨论场景。
+
+在 AgentScope 中,conversation 的构建在 **显式的消息传递** 基础上。在本章中,我们将演示如何构建:
+
+- User-assistant 之间的对话(聊天机器人)
+- 多实体对话(游戏、讨论等)
+
+它们的主要区别在于
+
+- **提示的构建方式**,以及
+- 信息在智能体之间的 **传播/共享** 方式。
+"""
+import asyncio
+import json
+import os
+
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.memory import InMemoryMemory
+from agentscope.formatter import (
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+)
+from agentscope.model import DashScopeChatModel
+from agentscope.message import Msg
+from agentscope.pipeline import MsgHub
+from agentscope.tool import Toolkit
+
+# %%
+# User-Assistant 对话
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# User-assistant 对话,也称为聊天机器人(chatbot),是最常见的智能体应用,也是当前大多数 LLM API 的设计模式。
+# 在这种对话只有两个参与者:用户(user)和智能体(assistant)。
+#
+# 在 AgentScope 中,名称中带有 **"Chat"** 的格式化器专为 user-assistant 对话设计,
+# 如 ``DashScopeChatFormatter``、``AnthropicChatFormatter`` 等。
+# 它们使用消息中的 ``role`` 字段来区分用户和智能体,并相应地格式化消息。
+#
+# 这里我们构建智能体 ``Friday`` 和用户之间的简单对话。
+#
+# .. tip:: AgentScope 提供了内置的 ``UserAgent`` 类,用于人机交互(HITL)。更多详细信息请参考 :ref:`user-agent`。
+#
+
+friday = ReActAgent(
+ name="Friday",
+ sys_prompt="你是一个名为 Friday 的有用助手",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ ),
+ formatter=DashScopeChatFormatter(), # 用于 user-assistant 对话的格式化器
+ memory=InMemoryMemory(),
+ toolkit=Toolkit(),
+)
+
+# 创建用户智能体
+user = UserAgent(name="User")
+
+# %%
+# 现在,我们可以通过在这两个智能体之间交换消息来开始对话,直到用户输入"exit"结束对话。
+#
+# .. code-block:: python
+#
+# async def run_conversation() -> None:
+# """运行 Friday 和用户之间的简单对话。"""
+# msg = None
+# while True:
+# msg = await friday(msg)
+# msg = await user(msg)
+# if msg.get_text_content() == "exit":
+# break
+#
+# asyncio.run(run_conversation())
+#
+
+# %%
+# 多实体对话
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# 如开头所述,我们演示如何在 **提示构建** 和 **信息共享** 方面构建多智能体对话。
+#
+# 构建提示
+# -------------------------------
+# 在 AgentScope 中,我们为多智能体对话提供了内置格式化器,其名称中带有 **"MultiAgent"**,
+# 如 ``DashScopeMultiAgentFormatter``、``AnthropicMultiAgentFormatter`` 等。
+#
+# 具体而言,它们使用消息中的 ``name`` 字段来区分不同的实体,并将对话历史格式化为单个用户消息。
+# 以 ``DashScopeMultiAgentFormatter`` 为例:
+#
+# .. tip:: 有关格式化器的更多详细信息可以在 :ref:`prompt` 中找到。
+#
+
+
+async def example_multi_agent_prompt() -> None:
+ msgs = [
+ Msg("system", "你是一个名为 Bob 的有用助手。", "system"),
+ Msg("Alice", "嗨!", "user"),
+ Msg("Bob", "嗨!很高兴见到大家。", "assistant"),
+ Msg("Charlie", "我也是!顺便说一下,我是 Charlie。", "assistant"),
+ ]
+
+ formatter = DashScopeMultiAgentFormatter()
+ prompt = await formatter.format(msgs)
+
+ print("格式化的提示:")
+ print(json.dumps(prompt, indent=4, ensure_ascii=False))
+
+ # 我们在这里打印组合用户消息的内容以便更好地理解:
+ print("-------------")
+ print("组合消息")
+ print(prompt[1]["content"])
+
+
+asyncio.run(example_multi_agent_prompt())
+
+
+# %%
+# 消息共享
+# -------------------------------
+# 在多智能体对话中,显式交换消息可能不够高效和便利,
+# 特别是在多个智能体之间广播消息时。
+#
+# 因此,AgentScope 提供了一个名为 ``MsgHub`` 的异步上下文管理器来简化消息广播。
+# 具体而言,同一个 ``MsgHub`` 中的智能体将自动接收其它参与者通过 ``reply`` 函数返回的消息。
+#
+# 下面我们构建一个多人聊天的场景,多个智能体扮演不同的角色:
+#
+
+model = DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+)
+formatter = DashScopeMultiAgentFormatter()
+
+alice = ReActAgent(
+ name="Alice",
+ sys_prompt="你是一个名为 Alice 的学生。",
+ model=model,
+ formatter=formatter,
+)
+
+bob = ReActAgent(
+ name="Bob",
+ sys_prompt="你是一个名为 Bob 的学生。",
+ model=model,
+ formatter=formatter,
+)
+
+charlie = ReActAgent(
+ name="Charlie",
+ sys_prompt="你是一个名为 Charlie 的学生。",
+ model=model,
+ formatter=formatter,
+)
+
+
+async def example_msghub() -> None:
+ """使用 MsgHub 进行多智能体对话的示例。"""
+ async with MsgHub(
+ [alice, bob, charlie],
+ # 进入 MsgHub 时的公告消息
+ announcement=Msg(
+ "system",
+ "现在大家互相认识一下,简单自我介绍。",
+ "system",
+ ),
+ ):
+ await alice()
+ await bob()
+ await charlie()
+
+
+asyncio.run(example_msghub())
+
+# %%
+# 现在我们打印 Alice 的记忆,检查她的记忆是否正确更新。
+#
+
+
+async def example_memory() -> None:
+ """打印 Alice 的记忆。"""
+ print("Alice 的记忆:")
+ for msg in await alice.memory.get_memory():
+ print(
+ f"{msg.name}: {json.dumps(msg.content, indent=4, ensure_ascii=False)}",
+ )
+
+
+asyncio.run(example_memory())
+
+# %%
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`prompt`
+# - :ref:`pipeline`
+#
diff --git a/docs/tutorial/zh_CN/src/workflow_handoffs.py b/docs/tutorial/zh_CN/src/workflow_handoffs.py
new file mode 100644
index 000000000..799e94f18
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/workflow_handoffs.py
@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+"""
+.. _handoffs:
+
+Handoffs
+========================================
+
+Handoffs 是由 OpenAI 提出的工作流模式,通过调用子智能体的方式来完成目标任务。
+在 AgentScope 中通过工具调用的方式实现 handoffs 非常简单。首先,我们创建一个函数来允许协调者动态创建子智能体。
+
+.. figure:: ../../_static/images/handoffs.png
+ :width: 80%
+ :align: center
+ :alt: 协调者-子智能体工作流
+
+ *Handoffs 示例*
+
+"""
+
+import asyncio
+import os
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import (
+ ToolResponse,
+ Toolkit,
+ execute_python_code,
+)
+
+
+# 创建子智能体的工具函数
+async def create_worker(
+ task_description: str,
+) -> ToolResponse:
+ """创建一个子智能体来完成给定的任务。子智能体配备了 Python 执行工具。
+
+ Args:
+ task_description (``str``):
+ 子智能体要完成的任务描述。
+ """
+ # 为子智能体智能体配备一些工具
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_python_code)
+
+ # 创建子智能体智能体
+ worker = ReActAgent(
+ name="Worker",
+ sys_prompt="你是一个智能体。你的目标是完成给定的任务。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+ # 让子智能体完成任务
+ res = await worker(Msg("user", task_description, "user"))
+ return ToolResponse(
+ content=res.get_content_blocks("text"),
+ )
+
+
+async def run_handoffs() -> None:
+ """交接工作流示例。"""
+ # 初始化协调者智能体
+ toolkit = Toolkit()
+ toolkit.register_tool_function(create_worker)
+
+ orchestrator = ReActAgent(
+ name="Orchestrator",
+ sys_prompt="你是一个协调者智能体。你的目标是通过将任务分解为更小的任务并创建子智能体来完成它们,从而完成给定的任务。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+
+ # 任务描述
+ task_description = "在 Python 中执行 hello world"
+
+ # 创建子智能体来完成任务
+ await orchestrator(Msg("user", task_description, "user"))
+
+
+asyncio.run(run_handoffs())
diff --git a/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py b/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py
new file mode 100644
index 000000000..20358d651
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py
@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""
+.. _multiagent-debate:
+
+Multi-Agent Debate
+========================
+
+Multi-Agent debate 模拟不同智能体之间的多轮讨论场景,通常包括几个 solver 和一个 aggregator。
+典型情况下,solver 生成并交换他们的答案,而 aggregator 收集并总结答案。
+
+我们实现了 `EMNLP 2024`_ 中的示例,其中两个 solver 智能体将按固定顺序讨论一个话题,根据先前的辩论历史表达他们的论点。
+在每一轮中,主持人智能体将决定是否可以在当前轮获得最终的正确答案。
+"""
+import asyncio
+import os
+
+from pydantic import Field, BaseModel
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import (
+ DashScopeMultiAgentFormatter,
+)
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.pipeline import MsgHub
+
+# 准备一个话题
+topic = "两个圆外切且没有相对滑动。圆A的半径是圆B半径的1/3。圆A绕圆B滚动一圈回到起点。圆A总共会旋转多少次?"
+
+
+# 创建两个辩论者智能体,Alice 和 Bob,他们将讨论这个话题。
+def create_solver_agent(name: str) -> ReActAgent:
+ """获取一个解决者智能体。"""
+ return ReActAgent(
+ name=name,
+ sys_prompt=f"你是一个名为 {name} 的辩论者。你好,欢迎来到"
+ "辩论比赛。我们的目标是找到正确答案,因此你没有必要完全同意对方"
+ f"的观点。辩论话题如下所述:{topic}",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeMultiAgentFormatter(),
+ )
+
+
+alice, bob = [create_solver_agent(name) for name in ["Alice", "Bob"]]
+
+# 创建主持人智能体
+moderator = ReActAgent(
+ name="Aggregator",
+ sys_prompt=f"""你是一个主持人。将有两个辩论者参与辩论比赛。他们将就以下话题提出观点并进行讨论:
+``````
+{topic}
+``````
+在每轮讨论结束时,你将评估辩论是否结束,以及话题正确的答案。""",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ # 使用多智能体格式化器,因为主持人将接收来自多于用户和助手的消息
+ formatter=DashScopeMultiAgentFormatter(),
+)
+
+
+# 主持人的结构化输出模型
+class JudgeModel(BaseModel):
+ """主持人的结构化输出模型。"""
+
+ finished: bool = Field(description="辩论是否结束。")
+ correct_answer: str | None = Field(
+ description="辩论话题的正确答案,仅当辩论结束时提供该字段。否则保留为 None。",
+ default=None,
+ )
+
+
+async def run_multiagent_debate() -> None:
+ """运行多智能体辩论工作流。"""
+ while True:
+ # MsgHub 中参与者的回复消息将广播给所有参与者。
+ async with MsgHub(participants=[alice, bob, moderator]):
+ await alice(
+ Msg(
+ "user",
+ "你是正方,请表达你的观点。",
+ "user",
+ ),
+ )
+ await bob(
+ Msg(
+ "user",
+ "你是反方。你不同意正方的观点。请表达你的观点和理由。",
+ "user",
+ ),
+ )
+
+ # Alice 和 Bob 不需要知道主持人的消息,所以主持人在 MsgHub 外部调用。
+ msg_judge = await moderator(
+ Msg(
+ "user",
+ "现在你已经听到了他们的辩论,现在判断辩论是否结束,以及你能得到正确答案吗?",
+ "user",
+ ),
+ structured_model=JudgeModel,
+ )
+
+ if msg_judge.metadata.get("finished"):
+ print(
+ "\n辩论结束,正确答案是:",
+ msg_judge.metadata.get("correct_answer"),
+ )
+ break
+
+
+asyncio.run(run_multiagent_debate())
+
+
+# %%
+# 进一步阅读
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# - :ref:`pipeline`
+#
+# .. _EMNLP 2024:
+# Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate. EMNLP 2024.
+#
diff --git a/docs/tutorial/zh_CN/src/workflow_routing.py b/docs/tutorial/zh_CN/src/workflow_routing.py
new file mode 100644
index 000000000..7f6a99da6
--- /dev/null
+++ b/docs/tutorial/zh_CN/src/workflow_routing.py
@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""
+.. _routing:
+
+Routing
+==========================
+在 AgentScope 中有两种实现 Routing 的方法,都简单易实现:
+
+- 使用结构化输出的显式 routing
+- 使用工具调用的隐式 routing
+
+.. tip:: 考虑到智能体 routing 没有统一的标准/定义,我们遵循 `Building effective agents <https://www.anthropic.com/engineering/building-effective-agents>`_ 中的设置
+
+显式 Routing
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+在显式 routing 中,我们可以直接使用智能体的结构化输出来确定将消息路由到哪个智能体。
+
+初始化 routing 智能体
+"""
+import asyncio
+import json
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit, ToolResponse
+
+router = ReActAgent(
+ name="Router",
+ sys_prompt="你是一个路由智能体。你的目标是将用户查询路由到正确的后续任务,注意你不需要回答用户的问题。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+)
+
+
+# 使用结构化输出指定路由任务
+class RoutingChoice(BaseModel):
+ your_choice: Literal[
+ "Content Generation",
+ "Programming",
+ "Information Retrieval",
+ None,
+ ] = Field(
+ description="选择正确的后续任务,如果任务太简单或没有合适的任务,则选择 ``None``",
+ )
+ task_description: str | None = Field(
+ description="任务描述",
+ default=None,
+ )
+
+
+async def example_router_explicit() -> None:
+ """使用结构化输出进行显式路由的示例。"""
+ msg_user = Msg(
+ "user",
+ "帮我写一首诗",
+ "user",
+ )
+
+ # 路由查询
+ msg_res = await router(
+ msg_user,
+ structured_model=RoutingChoice,
+ )
+
+ # 结构化输出存储在 metadata 字段中
+ print("结构化输出:")
+ print(json.dumps(msg_res.metadata, indent=4, ensure_ascii=False))
+
+
+asyncio.run(example_router_explicit())
+
+# %%
+# 隐式 Routing
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+# 另一种方法是将下游智能体包装成工具函数,这样路由智能体就可以根据用户查询决定调用哪个工具。
+#
+# 我们首先定义几个工具函数:
+#
+
+
+async def generate_python(demand: str) -> ToolResponse:
+ """根据需求生成 Python 代码。
+
+ Args:
+ demand (``str``):
+ 对 Python 代码的需求。
+ """
+ # 示例需求智能体
+ python_agent = ReActAgent(
+ name="PythonAgent",
+ sys_prompt="你是一个 Python 专家,你的目标是根据需求生成 Python 代码。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ memory=InMemoryMemory(),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ )
+ msg_res = await python_agent(Msg("user", demand, "user"))
+
+ return ToolResponse(
+ content=msg_res.get_content_blocks("text"),
+ )
+
+
+# 为演示目的模拟一些其他工具函数
+async def generate_poem(demand: str) -> ToolResponse:
+ """根据需求生成诗歌。
+
+ Args:
+ demand (``str``):
+ 对诗歌的需求。
+ """
+ pass
+
+
+async def web_search(query: str) -> ToolResponse:
+ """在网络上搜索查询。
+
+ Args:
+ query (``str``):
+ 要搜索的查询。
+ """
+ pass
+
+
+# %%
+# 之后,我们定义一个路由智能体并为其配备上述工具函数。
+#
+
+toolkit = Toolkit()
+toolkit.register_tool_function(generate_python)
+toolkit.register_tool_function(generate_poem)
+toolkit.register_tool_function(web_search)
+
+# 使用工具模块初始化路由智能体
+router_implicit = ReActAgent(
+ name="Router",
+ sys_prompt="你是一个路由智能体。你的目标是将用户查询路由到正确的后续任务。",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+)
+
+
+async def example_router_implicit() -> None:
+ """使用工具调用进行隐式路由的示例。"""
+ msg_user = Msg(
+ "user",
+ "帮我在 Python 中生成一个快速排序函数",
+ "user",
+ )
+
+ # 路由查询
+ await router_implicit(msg_user)
+
+
+asyncio.run(example_router_implicit())
diff --git a/examples/.DS_Store b/examples/.DS_Store
new file mode 100644
index 000000000..499e2228a
Binary files /dev/null and b/examples/.DS_Store differ
diff --git a/examples/agent_browser/README.md b/examples/agent_browser/README.md
new file mode 100644
index 000000000..ced1c26ee
--- /dev/null
+++ b/examples/agent_browser/README.md
@@ -0,0 +1,49 @@
+# Browser Agent Example
+
+This example demonstrates how to use AgentScope's BrowserAgent for web automation tasks. The BrowserAgent leverages the Model Context Protocol (MCP) to interact with browser tools powered by Playwright, enabling sophisticated web navigation, data extraction, and automation.
+
+
+## Prerequisites
+
+- Python 3.10 or higher
+- Node.js and npm (for the MCP server)
+- DashScope API key from Alibaba Cloud
+
+## Installation
+
+### Install AgentScope
+
+```bash
+# Install from source
+cd {PATH_TO_AGENTSCOPE}
+pip install -e .
+```
+
+## Setup
+
+### 1. Environment Configuration
+
+Set up your DashScope API key:
+
+```bash
+export DASHSCOPE_API_KEY="your_dashscope_api_key_here"
+```
+
+You can obtain a DashScope API key from [Alibaba Cloud DashScope Console](https://dashscope.console.aliyun.com/).
+
+### 2. About PlayWright MCP Server
+
+Before running the browser agent, you can test whether you can start the Playwright MCP server:
+
+```bash
+npx @playwright/mcp@latest
+```
+
+## Usage
+
+### Basic Example
+You can start running the browser agent in your terminal with the following command
+```bash
+cd examples/agent_browser
+python main.py
+```
diff --git a/examples/agent_browser/browser_agent.py b/examples/agent_browser/browser_agent.py
new file mode 100644
index 000000000..05a237734
--- /dev/null
+++ b/examples/agent_browser/browser_agent.py
@@ -0,0 +1,399 @@
+# -*- coding: utf-8 -*-
+"""Browser Agent"""
+# pylint: disable=W0212
+
+import re
+import uuid
+from typing import Optional, Any
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import FormatterBase
+from agentscope.memory import MemoryBase
+from agentscope.message import (
+ Msg,
+ ToolUseBlock,
+ TextBlock,
+)
+from agentscope.model import ChatModelBase
+from agentscope.tool import Toolkit
+from agentscope.token import TokenCounterBase, OpenAITokenCounter
+
+_BROWSER_AGENT_DEFAULT_SYS_PROMPT = (
+ "You are a helpful browser automation assistant. "
+ "You can navigate websites, take screenshots, and interact with web pages."
+ "Always describe what you see and plan your next steps clearly. "
+ "When taking actions, explain what you're doing and why."
+)
+_BROWSER_AGENT_REASONING_PROMPT = (
+ "You are browsing the current website. "
+ "The snapshot (and screenshot) of the current webpage is (are) given "
+ "below. Since you can only view the latest webpage, "
+ "you must promptly summarize current status, record required data, "
+ "and plan your next steps."
+)
+
+
+async def browser_agent_default_url_pre_reply(
+ self: "BrowserAgent", # pylint: disable=W0613
+ *args: Any, # pylint: disable=W0613
+ **kwargs: Any, # pylint: disable=W0613
+) -> None:
+ """Navigate to start URL if this is the first interaction"""
+ if self.start_url and not self._has_initial_navigated:
+ await self._navigate_to_start_url()
+ self._has_initial_navigated = True
+
+
+async def browser_agent_summarize_mem_pre_reasoning(
+ self: "BrowserAgent", # pylint: disable=W0613
+ *args: Any,
+ **kwargs: Any,
+) -> None:
+ """Summarize memory if too long"""
+ mem_len = await self.memory.size()
+ if mem_len > self.max_memory_length:
+ await self._memory_summarizing()
+
+
+async def browser_agent_observe_pre_reasoning(
+ self: "BrowserAgent", # pylint: disable=W0613
+ *args: Any,
+ **kwargs: Any,
+) -> None:
+ """Get a snapshot in text before reasoning"""
+ snapshot_msg = await self._get_snapshot_in_text()
+ await self.memory.add(snapshot_msg)
+
+
+async def browser_agent_remove_observation_post_reasoning(
+ self: "BrowserAgent", # pylint: disable=W0613
+ *args: Any,
+ **kwargs: Any,
+) -> None:
+ """Remove the snapshot msg after reasoning"""
+ mem_len = await self.memory.size()
+ if mem_len >= 2:
+ await self.memory.delete(mem_len - 2)
+
+
+async def browser_agent_post_acting_clean_content(
+ self: "BrowserAgent", # pylint: disable=W0613
+ *args: Any,
+ **kwargs: Any,
+) -> None:
+ """
+ Hook func for cleaning the messy return after action.
+ Observation will be done before reasoning steps.
+ """
+ mem_msgs = await self.memory.get_memory()
+ mem_length = await self.memory.size()
+ if len(mem_msgs) == 0:
+ return
+ last_output_msg = mem_msgs[-1]
+ for i, b in enumerate(last_output_msg.content):
+ if b["type"] == "tool_result":
+ for j, return_json in enumerate(b.get("output", [])):
+ if isinstance(return_json, dict) and "text" in return_json:
+ last_output_msg.content[i]["output"][j][
+ "output"
+ ] = self._filter_execution_text(return_json["text"])
+ await self.memory.delete(mem_length - 1)
+ await self.memory.add(last_output_msg)
+
+
+class BrowserAgent(ReActAgent):
+ """
+ Browser Agent that extends ReActAgent with browser-specific capabilities.
+
+ The agent leverages MCP (Model Context Protocol) servers to access browser
+ tools with Playwright, enabling sophisticated web automation tasks.
+
+ Example:
+ .. code-block:: python
+
+ agent = BrowserAgent(
+ name="web_navigator",
+ model=my_chat_model,
+ formatter=my_formatter,
+ memory=my_memory,
+ toolkit=browser_toolkit,
+ start_url="https://example.com"
+ )
+
+ response = await agent.reply("Search for Python tutorials")
+ """
+
+ def __init__(
+ self,
+ name: str,
+ model: ChatModelBase,
+ formatter: FormatterBase,
+ memory: MemoryBase,
+ toolkit: Toolkit,
+ sys_prompt: str = _BROWSER_AGENT_DEFAULT_SYS_PROMPT,
+ max_iters: int = 50,
+ start_url: Optional[str] = "https://www.google.com",
+ reasoning_prompt: str = _BROWSER_AGENT_REASONING_PROMPT,
+ token_counter: TokenCounterBase = OpenAITokenCounter("gpt-4o"),
+ max_mem_length: int = 20,
+ ) -> None:
+ """Initialize the Browser Agent.
+
+ Args:
+ name (str):
+ The unique identifier name for the agent instance.
+ model (ChatModelBase):
+ The chat model used for generating responses and reasoning.
+ formatter (FormatterBase):
+ The formatter used to convert messages into the required format
+ for the model API.
+ memory (MemoryBase):
+ The memory component used to store and retrieve dialogue
+ history.
+ toolkit (Toolkit):
+ A toolkit object containing the browser tool functions and
+ utilities.
+ sys_prompt (str, optional):
+ The system prompt that defines the agent's behavior and
+ personality.
+ Defaults to _BROWSER_AGENT_DEFAULT_SYS_PROMPT.
+ max_iters (int, optional):
+ The maximum number of reasoning-acting loop iterations.
+ Defaults to 50.
+ start_url (Optional[str], optional):
+ The initial URL to navigate to when the agent starts.
+ Defaults to "https://www.google.com".
+ reasoning_prompt (str, optional):
+ The prompt used during the reasoning phase to guide
+ decision-making.
+ Defaults to _BROWSER_AGENT_REASONING_PROMPT.
+
+ Returns:
+ None
+ """
+ super().__init__(
+ name=name,
+ sys_prompt=sys_prompt,
+ model=model,
+ formatter=formatter,
+ memory=memory,
+ toolkit=toolkit,
+ max_iters=max_iters,
+ )
+
+ self.start_url = start_url
+ self._has_initial_navigated = False
+ self.reasoning_prompt = reasoning_prompt
+ self.max_memory_length = max_mem_length
+ self.token_estimator = token_counter
+
+ self.register_instance_hook(
+ "pre_reply",
+ "browser_agent_default_url_pre_reply",
+ browser_agent_default_url_pre_reply,
+ )
+
+ self.register_instance_hook(
+ "pre_reasoning",
+ "browser_agent_summarize_mem_pre_reasoning",
+ browser_agent_summarize_mem_pre_reasoning,
+ )
+
+ self.register_instance_hook(
+ "pre_reasoning",
+ "browser_agent_observe_pre_reasoning",
+ browser_agent_observe_pre_reasoning,
+ )
+
+ self.register_instance_hook(
+ "post_reasoning",
+ "browser_agent_remove_observation_post_reasoning",
+ browser_agent_remove_observation_post_reasoning,
+ )
+
+ self.register_instance_hook(
+ "post_acting",
+ "browser_agent_post_acting_clean_content",
+ browser_agent_post_acting_clean_content,
+ )
+
+ async def _navigate_to_start_url(self) -> None:
+ """
+ Navigate to the specified start URL using the browser_navigate tool.
+
+ This method is automatically called during the first interaction to
+ navigate to the configured start URL. It executes the browser
+ navigation tool and processes the response to ensure the
+ initial page is loaded.
+
+ Returns:
+ None
+ """
+ tool_call = ToolUseBlock(
+ id=str(uuid.uuid4()),
+ type="tool_use",
+ name="browser_navigate",
+ input={"url": self.start_url},
+ )
+
+ # Execute the navigation tool
+ await self.toolkit.call_tool_function(tool_call)
+
+ async def _get_snapshot_in_text(self) -> Msg:
+ """Capture a text-based snapshot of the current webpage content.
+
+ This method uses the browser_snapshot tool to retrieve the current
+ webpage content in text format, which is used during the reasoning
+ phase to provide context about the current browser state.
+
+ Returns:
+ str: A text representation of the current webpage content,
+ including elements, structure, and visible text.
+
+ Note:
+ This method is called automatically during the reasoning phase and
+ provides essential context for decision-making about next actions.
+ """
+ snapshot_tool_call = ToolUseBlock(
+ type="tool_use",
+ id=str(uuid.uuid4()), # Generate a unique ID for the tool call
+ name="browser_snapshot",
+ input={}, # No parameters required for this tool
+ )
+ snapshot_response = await self.toolkit.call_tool_function(
+ snapshot_tool_call,
+ )
+ snapshot_str = ""
+ async for chunk in snapshot_response:
+ snapshot_str = chunk.content[0]["text"]
+
+ msg_observe = Msg(
+ "user",
+ content=[
+ TextBlock(
+ type="text",
+ text=self.reasoning_prompt + "\n" + snapshot_str,
+ ),
+ ],
+ role="user",
+ )
+
+ return msg_observe
+
+ async def _memory_summarizing(self) -> None:
+ """Summarize the current memory content to prevent context overflow.
+
+ This method is called periodically to condense the conversation history
+ by generating a summary of progress and maintaining only essential
+ information. It preserves the initial user question and creates a
+ concise summary of what has been accomplished and what remains to be
+ done.
+
+ Returns:
+ None
+
+ Note:
+ This method is automatically called every 10 iterations to manage
+ memory usage and maintain context relevance. The summarization
+ helps prevent token limit issues while preserving important task
+ context.
+ """
+ # Extract the initial user question
+ initial_question = None
+ memory_msgs = await self.memory.get_memory()
+ for msg in memory_msgs:
+ if msg.role == "user":
+ initial_question = msg.content
+ break
+
+ # Generate a summary of the current progress
+ hint_msg = Msg(
+ "user",
+ (
+ "Summarize the current progress and outline the next steps "
+ "for this task. Your summary should include:\n"
+ "1. What has been completed so far.\n"
+ "2. What key information has been found.\n"
+ "3. What remains to be done.\n"
+ "Ensure that your summary is clear, concise, and t"
+ "hat no tasks are repeated or skipped."
+ ),
+ role="user",
+ )
+
+ # Format the prompt for the model
+ prompt = self.formatter.format(
+ msgs=[
+ Msg("system", self.sys_prompt, "system"),
+ *memory_msgs,
+ hint_msg,
+ ],
+ )
+
+ # Call the model to generate the summary
+ res = await self.model(prompt)
+
+ # Handle response
+ summary_text = ""
+ if self.model.stream:
+ async for content_chunk in res:
+ summary_text = content_chunk.content[0]["text"]
+ else:
+ summary_text = res.content[0]["text"]
+
+ # Update the memory with the summarized content
+ summarized_memory = []
+ if initial_question:
+ summarized_memory.append(
+ Msg("user", initial_question, role="user"),
+ )
+ summarized_memory.append(
+ Msg(self.name, summary_text, role="assistant"),
+ )
+
+ # Clear and reload memory
+ await self.memory.clear()
+ for msg in summarized_memory:
+ await self.memory.add(msg)
+
+ @staticmethod
+ def _filter_execution_text(
+ text: str,
+ keep_page_state: bool = False,
+ ) -> str:
+ """
+ Filter and clean browser tool execution output to remove verbose
+ content.
+
+ This utility method removes unnecessary verbose content from browser
+ tool responses, including JavaScript code blocks, console messages,
+ and YAML content that can overwhelm the context window without
+ providing useful information.
+
+ Args:
+ text (str):
+ The raw execution text from browser tools that
+ needs to be filtered.
+ keep_page_state (bool, optional):
+ Whether to preserve page state information
+ including URL and YAML content. Defaults to False.
+
+ Returns:
+ str: The filtered execution text.
+ """
+ if not keep_page_state:
+ # Remove Page Snapshot and YAML content
+ text = re.sub(r"- Page URL.*", "", text, flags=re.DOTALL)
+ text = re.sub(r"```yaml.*?```", "", text, flags=re.DOTALL)
+ # Remove JavaScript code blocks
+ text = re.sub(r"```js.*?```", "", text, flags=re.DOTALL)
+ # Remove console messages section that can be very verbose
+ # (between "### New console messages" and "### Page state")
+ text = re.sub(
+ r"### New console messages.*?(?=### Page state)",
+ "",
+ text,
+ flags=re.DOTALL,
+ )
+ # Trim leading/trailing whitespace
+ return text.strip()
diff --git a/examples/agent_browser/main.py b/examples/agent_browser/main.py
new file mode 100644
index 000000000..d05d22fd2
--- /dev/null
+++ b/examples/agent_browser/main.py
@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""The main entry point of the browser agent example."""
+import asyncio
+import os
+
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+from agentscope.mcp import StdIOStatefulClient
+from agentscope.agent import UserAgent
+
+from browser_agent import BrowserAgent # pylint: disable=C0411
+
+
+async def main() -> None:
+ """The main entry point for the browser agent example."""
+ # Setup toolkit with browser tools from MCP server
+ toolkit = Toolkit()
+ browser_client = StdIOStatefulClient(
+ name="playwright-mcp",
+ command="npx",
+ args=["@playwright/mcp@latest"],
+ )
+
+ try:
+ # Connect to the browser client
+ await browser_client.connect()
+ await toolkit.register_mcp_client(browser_client)
+
+ # Create browser agent
+ agent = BrowserAgent(
+ name="BrowserBot",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ stream=True,
+ ),
+ formatter=DashScopeChatFormatter(),
+ memory=InMemoryMemory(),
+ toolkit=toolkit,
+ max_iters=50,
+ start_url="https://www.google.com",
+ )
+ user = UserAgent("Bob")
+
+ msg = None
+ while True:
+ msg = await user(msg)
+ if msg.get_text_content() == "exit":
+ break
+ msg = await agent(msg)
+
+ except Exception as e:
+ print(f"An error occurred: {e}")
+ print("Cleaning up browser client...")
+ finally:
+ # Ensure browser client is always closed,
+ # regardless of success or failure
+ try:
+ await browser_client.close()
+ print("Browser client closed successfully.")
+ except Exception as cleanup_error:
+ print(f"Error while closing browser client: {cleanup_error}")
+
+
+if __name__ == "__main__":
+ print("Starting Browser Agent Example...")
+ print(
+ "The browser agent will use "
+ "playwright-mcp (https://github.com/microsoft/playwright-mcp)."
+ "Make sure the MCP server is can be install "
+ "by `npx @playwright/mcp@latest`",
+ )
+
+ asyncio.run(main())
diff --git a/examples/evaluation/ace_bench/README.md b/examples/evaluation/ace_bench/README.md
new file mode 100644
index 000000000..256ec08a0
--- /dev/null
+++ b/examples/evaluation/ace_bench/README.md
@@ -0,0 +1,18 @@
+# ACEBench Example
+
+This is an example of agent-oriented evaluation in AgentScope.
+
+We take [ACEBench](https://github.com/ACEBench/ACEBench) as an example benchmark, and run
+a ReAct agent with [Ray](https://github.com/ray-project/ray)-based evaluator, which supports
+**distributed** and **parallel** evaluation.
+
+To run the example, you need to install AgentScope first, and then run the evaluation with the following command:
+
+```bash
+python main.py --data_dir {data_dir} --result_dir {result_dir}
+```
+
+## Further Reading
+
+- [ACEBench](https://github.com/ACEBench/ACEBench)
+- [Ray](https://github.com/ray-project/ray)
diff --git a/examples/evaluation/ace_bench/main.py b/examples/evaluation/ace_bench/main.py
new file mode 100644
index 000000000..2c86166d4
--- /dev/null
+++ b/examples/evaluation/ace_bench/main.py
@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""Example of running ACEBench evaluation with AgentScope."""
+import os
+import asyncio
+from argparse import ArgumentParser
+from typing import Callable
+
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.agent import ReActAgent
+from agentscope.evaluate import (
+ ACEBenchmark,
+ Task,
+ SolutionOutput,
+ RayEvaluator,
+ FileEvaluatorStorage,
+ ACEPhone,
+)
+from agentscope.tool import Toolkit
+
+
+async def react_agent_solution(
+ ace_task: Task,
+ pre_hook: Callable,
+) -> SolutionOutput:
+ """Run ReAct agent with the given task in ACEBench.
+
+ Args:
+ ace_task (`Task`):
+ Task to run in ACEBench.
+ pre_hook (Callable):
+ The pre-hook function to save the agent's pre-print messages.
+ """
+ # Equip tool functions
+ toolkit = Toolkit()
+ for tool, json_schema in ace_task.metadata["tools"]:
+ # register the tool function with the given json schema
+ toolkit.register_tool_function(tool, json_schema=json_schema)
+
+ # Create a ReAct agent
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday. "
+ "Your target is to solve the given task with your tools."
+ "Try to solve the task as best as you can.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ )
+
+ agent.register_instance_hook(
+ "pre_print",
+ "save_logging",
+ pre_hook,
+ )
+
+ # Execute the agent to solve the task
+ msg_input = Msg("user", ace_task.input, role="user")
+ # Print the input by the running agent to call the pre-print hook
+ await agent.print(msg_input)
+ await agent(msg_input)
+
+ # Obtain tool calls sequence
+ memory_msgs = await agent.memory.get_memory()
+ # Obtain tool_use blocks as trajectory
+ traj = []
+ for msg in memory_msgs:
+ traj.extend(msg.get_content_blocks("tool_use"))
+
+ # Obtain the final state of the phone and travel system
+ phone: ACEPhone = ace_task.metadata["phone"]
+ final_state = phone.get_current_state()
+
+ # Wrap into a SolutionOutput
+ solution = SolutionOutput(
+ success=True,
+ output=final_state,
+ trajectory=traj,
+ )
+ return solution
+
+
+async def main() -> None:
+ """Main function for running ACEBench."""
+ # Prepare data and results directories
+ parser = ArgumentParser()
+ parser.add_argument(
+ "--data_dir",
+ type=str,
+ required=True,
+ help="Where to save the dataset.",
+ )
+ parser.add_argument(
+ "--result_dir",
+ type=str,
+ required=True,
+ help="Where to save the evaluation results.",
+ )
+ parser.add_argument(
+ "--n_workers",
+ type=int,
+ default=1,
+ help="The number of ray workers to use for evaluation.",
+ )
+ args = parser.parse_args()
+
+ # Create the evaluator
+ # or GeneralEvaluator, which more suitable for local debug
+ evaluator = RayEvaluator(
+ name="ACEbench evaluation",
+ benchmark=ACEBenchmark(
+ data_dir=args.data_dir,
+ ),
+ # Repeat how many times
+ n_repeat=1,
+ storage=FileEvaluatorStorage(
+ save_dir=args.result_dir,
+ ),
+ # How many workers to use
+ n_workers=args.n_workers,
+ )
+
+ # Run the evaluation
+ await evaluator.run(react_agent_solution)
+
+
+asyncio.run(main())
diff --git a/examples/long_term_memory/mem0/README.md b/examples/long_term_memory/mem0/README.md
new file mode 100644
index 000000000..d21e25b9c
--- /dev/null
+++ b/examples/long_term_memory/mem0/README.md
@@ -0,0 +1,325 @@
+ # Mem0LongTermMemory
+
+## Overview
+
+**Note**: We are working on merging Mem0LongTermMemory into the main AgentScope repository.
+
+Mem0LongTermMemory is a long-term memory implementation built on top of the mem0 library, designed to provide persistent, semantic memory storage for AgentScope agents. It enables agents to record, store, and retrieve conversation history, reasoning processes, and contextual information across sessions, supporting advanced memory management and knowledge retention.
+
+This example demonstrates how to use Mem0LongTermMemory to create persistent memory systems that can store and retrieve information based on semantic similarity, enabling agents to maintain context and learn from past interactions.
+
+## Core Features
+
+### Persistent Memory Storage
+- **Vector-based Storage**: Uses Qdrant vector database for efficient semantic search and retrieval
+- **Configurable Backends**: Support for multiple embedding models (OpenAI, DashScope) and vector stores
+- **Async Operations**: Full async support for non-blocking memory operations
+
+### Semantic Memory Management
+- **Content Recording**: Store conversation messages, tool usage, and reasoning processes
+- **Thinking Integration**: Record agent thinking processes alongside content for better context
+- **Flexible Input Formats**: Support for strings, Msg objects, and dictionaries
+
+### Agent Integration
+- **Direct AgentScope Integration**: Seamless integration with AgentScope's ReActAgent
+- **Memory Modes**: Support for agent_control, dev_control, and both modes
+- **Tool Response Format**: Returns structured ToolResponse objects for easy integration
+
+## File Structure
+
+```
+memory_by_mem0/
+├── README.md # This documentation file
+├── long_term_memory_by_mem0.py # Core Mem0LongTermMemory implementation
+├── memory_example.py # Standalone examples demonstrating memory operations
+├── conversation_agent_with_longterm_mem.py # Interactive conversation example with ReActAgent
+└── utils.py # AgentScope integration utilities for mem0
+```
+
+## Prerequisites
+
+### Clone the AgentScope Repository
+This example depends on AgentScope. Please clone the full repository.
+
+### Install Dependencies
+**Recommended**: Python 3.10+
+
+Install the following dependencies:
+```bash
+pip install mem0ai
+```
+
+### API Keys
+By default, the example uses DashScope/OpenAI for embedding and LLM. Set your API key:
+
+```bash
+export DASHSCOPE_API_KEY='YOUR_API_KEY'
+export DASHSCOPE_API_BASE_URL='YOUR_API_BASE_URL'
+export DASHSCOPE_MODEL_4_MEMORY='USED_MODEL_NAME'
+export DASHSCOPE_EMBEDDING_MODEL='text-embedding-v2'
+```
+
+## How It Works
+
+### 1. Configuration
+The memory system uses a `MemoryConfig` that specifies:
+- **Embedder**: Configuration for embedding models (OpenAI, DashScope)
+- **LLM**: Configuration for language models used in memory processing
+- **Vector Store**: Configuration for vector database (Qdrant with on-disk storage as default)
+
+### 2. Memory Structure
+- **Mem0LongTermMemory**: Inherits from `LongTermMemoryBase` and maintains an async memory server
+- **Single AsyncMemory Instance**: Uses one AsyncMemory instance for all storage and retrieval operations
+- **Agent/User Context**: Maintains separate memory spaces for different agent-user combinations
+
+### 3. Memory Recording Flow
+1. **Input Processing**: Formats various input types (strings, Msg objects, dictionaries) into standardized format
+2. **Content Combination**: Merges thinking processes with content for comprehensive memory storage
+3. **Vector Storage**: Stores processed content with metadata in the vector database
+4. **Response Formatting**: Returns structured ToolResponse objects for easy integration
+
+### 4. Memory Retrieval Flow
+1. **Semantic Search**: Performs vector similarity search in the memory database
+2. **Response Formatting**: Returns retrieved memories in structured format
+
+## Usage Examples
+
+### Basic Usage
+
+Run the standalone memory examples to see the complete memory operations:
+
+```bash
+python ./memory_example.py
+```
+
+
+### Example Scenarios
+
+The example demonstrates several typical use cases:
+
+1. **Basic Conversation Recording**: Store simple user-agent conversations
+2. **Tool Usage and Results**: Record tool usage with thinking processes
+3. **Multi-step Reasoning**: Store complex reasoning processes step by step
+4. **Error Handling**: Record error scenarios and recovery strategies
+5. **User Preferences**: Store user preferences and contextual information
+
+## API Reference
+
+### Mem0LongTermMemory Class
+
+#### Main Methods
+
+**`__init__(agent_name=None, user_name=None, run_name=None, model=None, embedding_model=None, vector_store_config=None, mem0_config=None, default_memory_type=None, **kwargs)`**
+- Initialize the memory instance with agent, user, and run context
+- `agent_name` (str, optional): The name of the agent
+- `user_name` (str, optional): The name of the user
+- `run_name` (str, optional): The name of the run/session
+- `model` (ChatModelBase, optional): The model to use for the long-term memory
+- `embedding_model` (EmbeddingModelBase, optional): The embedding model to use
+- `vector_store_config` (VectorStoreConfig, optional): Vector store configuration
+- `mem0_config` (MemoryConfig, optional): Complete mem0 configuration
+- `default_memory_type` (str, optional): Default memory type for storage
+
+**Note**:
+1. At least one of `agent_name`, `user_name`, or `run_name` is required.
+2. During memory recording, these parameters become metadata for the stored memories.
+3. During memory retrieval, only memories with matching metadata values will be returned.
+
+**`record_to_memory(thinking, content, memory_type=None, **kwargs)`**
+- Record content with thinking process
+- `thinking` (str): Your thinking and reasoning about what to record
+- `content` (list[str]): The content to remember, which is a list of strings
+- `memory_type` (str, optional): The type of memory to use. Default is None, to create a semantic memory. "procedural_memory" is explicitly used for procedural memories
+- Returns: ToolResponse with success/error status
+
+**`retrieve_from_memory(keywords, **kwargs)`**
+- Retrieve memories based on keywords
+- `keywords` (list[str]): Keywords to search for in the memory, which should be specific and concise, e.g. the person's name, the date, the location, etc.
+- `limit_per_search` (int): Number of memories to retrieve per search (default: 5)
+- Returns: ToolResponse with retrieved memories
+
+#### Internal Methods
+
+**`record(msgs, **kwargs)`**
+- Record message sequences to memory
+- `msgs` (Sequence[Msg | None]): Messages to record
+
+**`_record_all(content, thinking=None, memory_type=None, infer=True, **kwargs)`**
+- Record content with comprehensive processing
+- `content` (list[str] | list[Msg] | list[dict]): The content to remember, which is a list of strings or Msg objects or dict objects
+- `thinking` (str, optional): Your thinking and reasoning about what to record, if not provided, the content will be used as the thinking
+- `memory_type` (str, optional): The type of memory to use. Default is None, to create a semantic memory. "procedural_memory" is explicitly used for procedural memories
+- `infer` (bool): Whether to infer memory type (default: True)
+- Handles various input formats and thinking integration
+
+**`retrieve(msg, **kwargs)`**
+- Retrieve memories based on message content
+- `msg` (Msg | list[Msg] | None): The message to search for in the memory, which should be specific and concise, e.g. the person's name, the date, the location, etc.
+- `limit_per_search` (int): Number of results per search (default: 5)
+- Returns: list[str] - A list of retrieved memory strings
+
+### Configuration
+
+
+#### Direct Model Configuration
+```python
+# Initialize with AgentScope models directly
+long_term_memory = Mem0LongTermMemory(
+ agent_name="Friday",
+ user_name="user_123",
+ model=OpenAIChatModel(
+ model_name="gpt-4",
+ api_key="your_api_key",
+ base_url="your_base_url"
+ ),
+ embedding_model=OpenAITextEmbedding(
+ model_name="text-embedding-3-small",
+ api_key="your_api_key",
+ base_url="your_base_url"
+ )
+)
+```
+
+
+
+## Customization & Extension
+
+### Backend Replacement
+Easily customize embedding, LLM, or vector store by modifying the configuration:
+
+```python
+# Example: Using different embedding model
+embedder=EmbedderConfig(
+ provider="dashscope",
+ config={
+ "model": "text-embedding-v1",
+ "api_key": "your_dashscope_key"
+ }
+)
+```
+
+### Memory Config Replacement
+Mem0LongTermMemory supports directly receiving memory configurations defined in mem0, allowing users to easily adopt various memory configurations and backends supported by mem0. This provides flexibility to use different embedding models, LLMs, and vector stores without modifying the core implementation.
+
+```python
+# Example: Using a complete mem0 MemoryConfig
+from mem0.configs.base import MemoryConfig
+from mem0.embeddings.configs import EmbedderConfig
+from mem0.llms.configs import LlmConfig
+from mem0.vector_stores.configs import VectorStoreConfig
+
+# Create a custom mem0 configuration
+mem0_config = MemoryConfig(
+ embedder=EmbedderConfig(
+ provider="openai",
+ config={
+ "model": "text-embedding-3-small",
+ "api_key": "your_openai_key"
+ }
+ ),
+ llm=LlmConfig(
+ provider="openai",
+ config={
+ "model": "gpt-4",
+ "api_key": "your_openai_key"
+ }
+ ),
+ vector_store=VectorStoreConfig(
+ provider="qdrant",
+ config={
+ "on_disk": True,
+ "path": "./memory_data"
+ }
+ )
+)
+
+# Initialize with the custom mem0 configuration
+long_term_memory = Mem0LongTermMemory(
+ agent_name="Friday",
+ user_name="user_123",
+ mem0_config=mem0_config
+)
+```
+
+**Note**: In Mem0LongTermMemory, if the `model`, `embedding_model`, or `vector_store_config` parameters are not None, they will override the corresponding configurations in `mem0_config`. This allows for flexible configuration where you can use a base mem0 configuration and selectively override specific components.
+
+### AgentScope Integration
+The implementation includes custom AgentScope providers for mem0:
+
+- **AgentScopeLLM**: Integrates AgentScope ChatModelBase with mem0
+- **AgentScopeEmbedding**: Integrates AgentScope EmbeddingModelBase with mem0
+
+These providers handle the conversion between mem0's expected format and AgentScope's message/response formats.
+
+### Memory Type Customization
+Add custom memory types for different use cases:
+
+```python
+# Example: Procedural memory
+await memory.record_to_memory(
+ content=["Step 1: Analyze input", "Step 2: Process data"],
+ thinking="This is a procedural workflow for data processing",
+ memory_type="procedural_memory"
+)
+```
+
+
+## Best Practices
+
+### Memory Recording
+1. **Be Specific**: Record specific, actionable information rather than general statements
+2. **Include Context**: Always include relevant context and reasoning when recording
+3. **Use Thinking**: Leverage the thinking parameter to explain why information is important
+4. **Structured Content**: Use structured formats for complex information
+
+### Memory Retrieval
+1. **Specific Keywords**: Use specific, relevant keywords for better search results
+2. **Appropriate Limits**: Set reasonable limits based on your use case
+3. **Context Awareness**: Consider the current context when retrieving memories
+4. **Error Handling**: Always handle potential retrieval errors gracefully
+
+### Performance Optimization
+1. **Batch Operations**: Group related memory operations when possible
+2. **Efficient Queries**: Use specific keywords to reduce search scope
+3. **Memory Cleanup**: Periodically clean up irrelevant or outdated memories
+4. **Configuration Tuning**: Optimize vector store and embedding configurations
+
+## Troubleshooting
+
+### Common Issues
+
+**Memory Not Found**
+- Check if the memory was properly recorded
+- Verify agent_id and user_id consistency
+- Ensure vector store is properly configured
+
+**Poor Search Results**
+- Use more specific keywords
+- Check embedding model configuration
+- Verify content was properly formatted during recording
+
+**Performance Issues**
+- Optimize vector store configuration
+- Reduce search limits
+- Consider using on-disk storage for large datasets
+
+**AgentScope Integration Issues**
+- Ensure AgentScope models are properly configured
+- Check that the custom providers are registered correctly
+- Verify message format compatibility
+
+### Debug Mode
+Enable debug logging to troubleshoot issues:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Reference
+
+- [mem0 Documentation](https://github.com/mem0ai/mem0)
+- [AgentScope Documentation](https://github.com/agentscope-ai/agentscope)
+- [Qdrant Vector Database](https://qdrant.tech/)
+
+For further customization or integration, please refer to the full implementation in the `long_term_memory_by_mem0.py` file and the mem0 official documentation.
\ No newline at end of file
diff --git a/examples/long_term_memory/mem0/memory_example.py b/examples/long_term_memory/mem0/memory_example.py
new file mode 100644
index 000000000..00688ecd2
--- /dev/null
+++ b/examples/long_term_memory/mem0/memory_example.py
@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""Memory example demonstrating long-term memory functionality with mem0.
+
+This module provides examples of how to use the Mem0LongTermMemory class
+for recording and retrieving persistent memories.
+"""
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from agentscope.memory import Mem0LongTermMemory
+from agentscope.agent import ReActAgent
+from agentscope.embedding import DashScopeTextEmbedding
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+
+load_dotenv()
+
+
+async def main() -> None:
+ """Run the memory examples."""
+ # Initialize long term memory
+ long_term_memory = Mem0LongTermMemory(
+ agent_name="Friday",
+ user_name="user_123",
+ model=DashScopeChatModel(
+ model_name="qwen-max-latest",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ stream=False,
+ ),
+ embedding_model=DashScopeTextEmbedding(
+ model_name="text-embedding-v2",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ ),
+ on_disk=False,
+ )
+
+ print("=== Long Term Memory Examples with mem0 ===\n")
+
+ # Example 1: Basic conversation recording
+ print("1. Basic Conversation Recording")
+ print("-" * 40)
+ results = await long_term_memory.record(
+ msgs=[
+ Msg(
+ role="user",
+ content="Please help me book a hotel, preferably homestay",
+ name="user",
+ ),
+ ],
+ )
+ print(f"Recorded conversation: {results}\n")
+
+ # Example 2: Retrieving memories
+ print("2. Retrieving Memories")
+ print("-" * 40)
+ print("Searching for weather-related memories...")
+ weather_memories = await long_term_memory.retrieve(
+ msg=[
+ Msg(
+ role="user",
+ content="What's the weather like today?",
+ name="user",
+ ),
+ ],
+ )
+ print(f"Retrieved weather memories: {weather_memories}\n")
+
+ print("Searching for user preference memories...")
+ preference_memories = await long_term_memory.retrieve(
+ msg=[
+ Msg(
+ role="user",
+ content=(
+ "I prefer temperatures in Celsius and wind speed in km/h"
+ ),
+ name="user",
+ ),
+ ],
+ )
+ print(f"Retrieved preference memories: {preference_memories}\n")
+
+ # Example 5: ReActAgent with long term memory
+ print("5. ReActAgent with long term memory")
+ print("-" * 40)
+
+ toolkit = Toolkit()
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday.",
+ model=DashScopeChatModel(
+ model_name="qwen-max-latest",
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ stream=False,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+ long_term_memory=long_term_memory,
+ long_term_memory_mode="both",
+ )
+
+ await agent.memory.clear()
+ msg = Msg(
+ role="user",
+ content="When I travel to Hangzhou, I prefer to stay in a homestay",
+ name="user",
+ )
+ msg = await agent(msg)
+ print(f"ReActAgent response: {msg.get_text_content()}\n")
+
+ msg = Msg(role="user", content="what preference do I have?", name="user")
+ msg = await agent(msg)
+ print(f"ReActAgent response: {msg.get_text_content()}\n")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/multi_agent_conversation/main.py b/examples/multi_agent_conversation/main.py
new file mode 100644
index 000000000..a57ac03bb
--- /dev/null
+++ b/examples/multi_agent_conversation/main.py
@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""The multi-agent conversation example."""
+
+
+async def main() -> None:
+ """The main entry point for the multi-agent conversation example."""
diff --git a/examples/react_agent/README.md b/examples/react_agent/README.md
new file mode 100644
index 000000000..a5e780b1e
--- /dev/null
+++ b/examples/react_agent/README.md
@@ -0,0 +1,63 @@
+# ReAct Agent Example
+
+## What This Example Demonstrates
+
+This example showcases a **ReAct Agent** implementation using the
+AgentScope framework. The ReAct agent combines reasoning and action capabilities to solve complex tasks through iterative thought processes and tool usage.
+
+### Key Features:
+- **Intelligent Assistant**: Creates an AI assistant named "Friday" that can think and act
+- **Tool Integration**: Equipped with practical tools including:
+ - Shell command execution
+ - Python code execution
+ - Text file viewing
+- **Interactive Conversation**: Supports real-time conversation between user and agent
+- **Streaming Response**: Enables real-time response streaming for better user experience
+- **Memory Management**: Maintains conversation context using in-memory storage
+
+The agent follows the ReAct paradigm, where it can:
+1. **Reason** about the user's request
+2. **Act** by using available tools when necessary
+3. **Observe** the results and continue reasoning
+4. **Respond** with helpful information or actions
+
+## How to Run This Example
+1. **Set Environment Variable**:
+ ```bash
+ export DASHSCOPE_API_KEY="your_dashscope_api_key_here"
+ ```
+2. Run the script:
+ ```bash
+ python main.py
+ ```
+
+## Replace the Model and Formatter
+AgentScope provides several built-in model implementations that you can easily switch between. You can also implement your own custom model if needed.
+
+For example, to use the OpenAI model, you can replace the model and formatter as follows:
+```
+from agentscope.model import OpenAIChatModel
+from agentscope.formatter import OpenAIChatFormatter
+
+# Replace the model and formatter with:
+agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday.",
+ model=OpenAIChatModel(
+ api_key=os.environ.get("OPENAI_API_KEY"),
+ model_name="gpt-4",
+ stream=True,
+ ),
+ formatter=OpenAIChatFormatter(), # Use matching formatter
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+)
+```
+
+## Notes
+
+⚠️ Formatter Compatibility: Always use the formatter that matches your model. Mismatched formatters can cause communication errors between the agent and the model.
+
+🔧 Tool Usage: Ensure your chosen model supports function calling capabilities to maintain full ReAct functionality with tool usage.
+
+🏠 Local Models: For local models, ensure the model service (like Ollama) is running before starting the agent.
\ No newline at end of file
diff --git a/examples/react_agent/main.py b/examples/react_agent/main.py
new file mode 100644
index 000000000..d5cbe89b4
--- /dev/null
+++ b/examples/react_agent/main.py
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""The main entry point of the ReAct agent example."""
+import asyncio
+import os
+
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import (
+ Toolkit,
+ execute_shell_command,
+ execute_python_code,
+ view_text_file,
+)
+
+
+async def main() -> None:
+ """The main entry point for the ReAct agent example."""
+ toolkit = Toolkit()
+ toolkit.register_tool_function(execute_shell_command)
+ toolkit.register_tool_function(execute_python_code)
+ toolkit.register_tool_function(view_text_file)
+
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ enable_thinking=False,
+ stream=True,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+ )
+ user = UserAgent("Bob")
+
+ msg = None
+ while True:
+ msg = await user(msg)
+ if msg.get_text_content() == "exit":
+ break
+ msg = await agent(msg)
+
+
+asyncio.run(main())
diff --git a/examples/structured_output/README.md b/examples/structured_output/README.md
new file mode 100644
index 000000000..0187aa50e
--- /dev/null
+++ b/examples/structured_output/README.md
@@ -0,0 +1,96 @@
+# Structured Output Example
+
+## What This Example Demonstrates
+
+This example showcases **structured output generation** using AgentScope with Pydantic models. It demonstrates how to constrain AI model outputs to follow specific data structures and formats, ensuring consistent and parseable responses.
+
+### Key Features:
+- **Structured Data Generation**: Forces agent responses to conform to
+ predefined schemas
+- **Pydantic Integration**: Uses Pydantic models to define output structure with validation
+- **Type Safety**: Ensures output data types match expected formats
+- **Field Validation**: Includes constraints like age limits (0-120) and enum choices
+- **JSON Output**: Generates clean, structured JSON responses
+
+### Example Models:
+
+1. **TableModel**: Structured person information
+ - `name`: Person's name (string)
+ - `age`: Person's age (integer,0-120)
+ - `intro`: One-sentence introduction (string)
+ - `honors`: List of honors/achievements (array of strings)
+
+2. **ChoiceModel**: Constrained choice selection
+ - `choice`: Must be one of "apple", "banana", or "orange"
+
+### Use Cases:
+- **Data Extraction**: Extract structured information from unstructured text
+- **Form Generation**: Generate consistent data for databases or APIs
+- **Survey Responses**: Ensure responses fit predefined categories
+- **Content Classification**: Categorize content into specific types
+
+## How to Run This Example
+1. **Set Environment Variable:**
+ ```bash
+ export DASHSCOPE_API_KEY="your_dashscope_api_key_here"
+ ```
+2. **Run the script:**
+ ```bash
+ python main.py
+ ```
+3. **Expected Output:**
+The program will generate two structured responses like below:
+```
+Structured Output 1:
+{
+ "name": "Albert Einstein",
+ "age": 76,
+ "intro": 1,
+ "honors": [
+ "Nobel Prize in Physics (1921)",
+ "Copley Medal (1925)"
+ ]
+}
+Structured Output 2:
+{
+ "choice": "apple"
+}
+```
+
+>💡**Note:** The specific content will vary with each run since the agent generates different responses, but the JSON structure will always conform to the predefined Pydantic models (`TableModel` and `ChoiceModel`).
+
+## How It Works:
+1. The agent receives a query along with a structured_model parameter
+2. The agent generates a response that conforms to the Pydantic model schema
+3. The structured data is returned in res.metadata as a validated JSON object
+4. Pydantic ensures all field types and constraints are satisfied
+
+## Custom Pydantic Models
+Create your own structured output models for specific use cases, for example:
+
+```
+from typing import Optional
+from pydantic import BaseModel, Field, EmailStr
+
+class BusinessModel(BaseModel):
+ """Business information extraction model."""
+
+ company_name: str = Field(description="Name of the company")
+ industry: str = Field(description="Industry sector")
+ founded_year: int = Field(description="Year founded", ge=1800, le=2024)
+ headquarters: str = Field(description="Location of headquarters")
+ employee_count: Optional[int] = Field(description="Number of employees", ge=1)
+ email: Optional[EmailStr] = Field(description="Contact email address")
+ website: Optional[str] = Field(description="Company website URL")
+
+# Usage
+query = Msg("user", "Tell me about Tesla Inc.", "user")
+res = await agent(query, structured_model=BusinessModel)
+```
+
+## Best Practices for Structured Output
+
+1. **Use Descriptive Field Names:** Make field purposes clear
+2. **Add Field Descriptions:** Help the agent understand what data to generate
+3. **Set Validation Constraints:** Use Pydantic validators for data integrity
+4. **Choose Appropriate Types:** Use specific types like EmailStr, datetime, etc.
\ No newline at end of file
diff --git a/examples/structured_output/main.py b/examples/structured_output/main.py
new file mode 100644
index 000000000..a55a636ec
--- /dev/null
+++ b/examples/structured_output/main.py
@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+"""The main entry point of the structured output example."""
+import asyncio
+import json
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.tool import Toolkit
+
+
+class TableModel(BaseModel):
+ """A simple table model for structured output."""
+
+ name: str = Field(description="The name of the person")
+ age: int = Field(description="The age of the person", ge=0, le=120)
+ intro: str = Field(description="A one-sentence introduction of the person")
+ honors: list[str] = Field(
+ description="A list of honors received by this person",
+ )
+
+
+class ChoiceModel(BaseModel):
+ """A simple choice model for structured output."""
+
+ choice: Literal["apple", "banana", "orange"] = Field(
+ description="Your choice of fruit",
+ )
+
+
+async def main() -> None:
+ """The main entry point for the structured output example."""
+ toolkit = Toolkit()
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday.",
+ model=DashScopeChatModel(
+ api_key=os.environ.get("DASHSCOPE_API_KEY"),
+ model_name="qwen-max",
+ stream=True,
+ ),
+ formatter=DashScopeChatFormatter(),
+ toolkit=toolkit,
+ memory=InMemoryMemory(),
+ )
+
+ query_msg_1 = Msg(
+ "user",
+ "Please introduce Einstein",
+ "user",
+ )
+ res = await agent(query_msg_1, structured_model=TableModel)
+ print(
+ "Structured Output 1:\n"
+ "```\n"
+ f"{json.dumps(res.metadata, indent=4)}\n"
+ "```",
+ )
+
+ query_msg_2 = Msg(
+ "user",
+ "Choose one of your favorite fruit",
+ "user",
+ )
+ res = await agent(query_msg_2, structured_model=ChoiceModel)
+ print(
+ "Structured Output 2:\n"
+ "```\n"
+ f"{json.dumps(res.metadata, indent=4)}\n"
+ "```",
+ )
+
+
+asyncio.run(main())
diff --git a/examples/workflows/multiagent_debate/main.py b/examples/workflows/multiagent_debate/main.py
new file mode 100644
index 000000000..e47993508
--- /dev/null
+++ b/examples/workflows/multiagent_debate/main.py
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The multi-agent debate workflow example in AgentScope."""
+import asyncio
+import os
+
+from pydantic import (
+ BaseModel,
+ Field,
+)
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import (
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+)
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.pipeline import MsgHub
+
+topic = (
+ "The two circles are externally tangent and there is no relative sliding. "
+ "The radius of circle A is 1/3 the radius of circle B. Circle A rolls "
+ "around circle B one trip back to its starting point. How many times will "
+ "circle A revolve in total?"
+)
+
+
+# Create two debater agents, Alice and Bob, who will discuss the topic.
+def create_solver_agent(name: str) -> ReActAgent:
+ """Get a solver agent."""
+ return ReActAgent(
+ name=name,
+ sys_prompt=f"You're a debater named {name}. Hello and welcome to the "
+ "debate competition. It's not necessary to fully agree "
+ "with each other's perspectives, as our objective is to "
+ "find the correct answer. The debate topic is stated as "
+ f"follows: {topic}. Use Chinese to answer the question",
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ ),
+ formatter=DashScopeChatFormatter(),
+ )
+
+
+alice, bob = [create_solver_agent(name) for name in ["Alice", "Bob"]]
+
+# Create a moderator agent
+moderator = ReActAgent(
+ name="Aggregator",
+ sys_prompt=(
+ "You're a moderator. There will be two debaters involved in a debate "
+ "competition. They will present their answer and discuss their "
+ "perspectives on the topic:\n"
+ "```\n"
+ "{topic}\n"
+ "```\n"
+ "At the end of each round, you will evaluate both sides' answers "
+ "and decide which one is correct."
+ ),
+ model=DashScopeChatModel(
+ model_name="qwen-max",
+ api_key=os.environ["DASHSCOPE_API_KEY"],
+ stream=True,
+ ),
+ formatter=DashScopeMultiAgentFormatter(),
+)
+
+
+# A structured output model for the moderator
+class JudgeModel(BaseModel):
+ """The structured output model for the moderator."""
+
+ finished: bool = Field(
+ description="Whether the debate is finished.",
+ )
+ correct_answer: str | None = Field(
+ description="The correct answer to the debate topic, only if the "
+ "debate is finished. Otherwise, leave it as None.",
+ default=None,
+ )
+
+
+async def run_multiagent_debate() -> None:
+ """Run the multi-agent debate workflow."""
+ while True:
+ # The reply messages in MsgHub from the participants will be
+ # broadcasted to all participants.
+ async with MsgHub(participants=[alice, bob, moderator]):
+ await alice(
+ Msg(
+ "user",
+ "You are affirmative side, Please express your "
+ "viewpoints.",
+ "user",
+ ),
+ )
+ await bob(
+ Msg(
+ "user",
+ "You are negative side. You disagree with the "
+ "affirmative side. Provide your reason and answer.",
+ "user",
+ ),
+ )
+
+ # Alice and Bob doesn't need to know the moderator's message,
+ # so moderator is called outside the MsgHub.
+ msg_judge = await moderator(
+ Msg(
+ "user",
+ "Now you have heard the answers from the others, have "
+ "the debate finished, and can you get the correct answer?",
+ "user",
+ ),
+ structured_model=JudgeModel,
+ )
+
+ print("【STRUCTURED_OUTPUT】: ", msg_judge.metadata)
+
+ if msg_judge.metadata.get("finished"):
+ print(
+ "The debate is finished, and the correct answer is: ",
+ msg_judge.metadata.get("correct_answer"),
+ )
+ break
+
+
+asyncio.run(run_multiagent_debate())
diff --git a/setup.py b/setup.py
new file mode 100644
index 000000000..1a66d875c
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""Setup script for AgentScope."""
+import re
+import setuptools
+
+# obtain version from src/agentscope/_version.py
+with open("src/agentscope/_version.py", encoding="UTF-8") as f:
+ VERSION = re.search(
+ r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]',
+ f.read(),
+ re.MULTILINE,
+ ).group(1)
+
+NAME = "agentscope"
+URL = "https://github.com/agentscope-ai/agentscope"
+
+minimal_requires = [
+ "aioitertools",
+ "anthropic",
+ "dashscope",
+ "docstring_parser",
+ "json5",
+ "json_repair",
+ "mcp",
+ "numpy",
+ "openai",
+ "python-datauri",
+ "opentelemetry-api",
+ "opentelemetry-sdk",
+ "opentelemetry-exporter-otlp",
+ "json5",
+ "aioitertools",
+ "python-socketio",
+ "shortuuid",
+ "tiktoken",
+ "furo",
+]
+
+extra_requires = [
+ "ollama",
+ "google-genai",
+ "Pillow",
+ "transformers",
+ "jinja2",
+ "ray",
+]
+
+dev_requires = [
+ "pre-commit",
+ "pytest",
+ "sphinx-gallery",
+ "myst_parser",
+ "sphinx_rtd_theme",
+ "matplotlib",
+]
+
+with open("README.md", "r", encoding="UTF-8") as fh:
+ long_description = fh.read()
+
+setuptools.setup(
+ name=NAME,
+ version=VERSION,
+ author="SysML team of Alibaba Tongyi Lab ",
+ author_email="[email protected]",
+ description="AgentScope: A Flexible yet Robust Multi-Agent Platform.",
+ long_description=long_description,
+ long_description_content_type="text/markdown",
+ url=URL,
+ download_url=f"{URL}/archive/v{VERSION}.tar.gz",
+ keywords=["deep-learning", "multi agents", "agents"],
+ package_dir={"": "src"},
+ packages=setuptools.find_packages("src"),
+ install_requires=minimal_requires,
+ extras_require={
+ "full": minimal_requires + extra_requires,
+ "dev": minimal_requires + extra_requires + dev_requires,
+ },
+ license="Apache-2.0",
+ classifiers=[
+ "Development Status :: 4 - Beta",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.10",
+ "Operating System :: OS Independent",
+ ],
+ python_requires=">=3.10",
+ entry_points={},
+)
diff --git a/src/agentscope/__init__.py b/src/agentscope/__init__.py
new file mode 100644
index 000000000..12a7a4ccd
--- /dev/null
+++ b/src/agentscope/__init__.py
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""The agentscope serialization module"""
+import os
+
+import requests
+
+from . import exception
+from . import module
+from . import message
+from . import model
+from . import tool
+from . import formatter
+from . import memory
+from . import agent
+from . import session
+from . import embedding
+from . import token
+from . import evaluate
+from . import pipeline
+from . import tracing
+
+from ._logging import (
+ logger,
+ setup_logger,
+)
+from .agent import UserAgent, StudioUserInput
+from .hooks import _equip_as_studio_hooks
+from ._version import __version__
+
+
+def init(
+ project: str | None = None,
+ name: str | None = None,
+ logging_path: str | None = None,
+ logging_level: str = "INFO",
+ studio_url: str | None = None,
+ tracing_url: str | None = None,
+) -> None:
+ """Initialize the agentscope library.
+
+ Args:
+ project (`str | None`, optional):
+ The project name.
+ name (`str | None`, optional):
+ The name of the run.
+ logging_path (`str | None`, optional):
+ The path to saving the log file. If not provided, logs will not be
+ saved.
+ logging_level (`str | None`, optional):
+ The logging level. Defaults to "INFO".
+ studio_url (`str | None`, optional):
+ The URL of the AgentScope Studio to connect to.
+ tracing_url (`str | None`, optional):
+ The URL of the tracing endpoint, which can connect to third-party
+ OpenTelemetry tracing platforms like Arize-Phoenix and Langfuse.
+ If not provided and `studio_url` is provided, it will send traces
+ to the AgentScope Studio's tracing endpoint.
+ """
+
+ from . import _config
+
+ if project:
+ _config.project = project
+
+ if name:
+ _config.name = name
+
+ setup_logger(logging_level, logging_path)
+
+ if studio_url:
+ # Register the run
+ data = {
+ "id": _config.run_id,
+ "project": _config.project,
+ "name": _config.name,
+ "timestamp": _config.created_at,
+ "pid": os.getpid(),
+ "status": "running",
+ # Deprecated fields
+ "run_dir": "",
+ }
+ response = requests.post(
+ url=f"{studio_url}/trpc/registerRun",
+ json=data,
+ )
+ response.raise_for_status()
+
+ UserAgent.override_class_input_method(
+ StudioUserInput(
+ studio_url=studio_url,
+ run_id=_config.run_id,
+ max_retries=3,
+ ),
+ )
+
+ _equip_as_studio_hooks(studio_url)
+
+ if tracing_url:
+ endpoint = tracing_url
+ else:
+ endpoint = studio_url.strip("/") + "/v1/traces" if studio_url else None
+
+ if endpoint:
+ from .tracing import setup_tracing
+
+ setup_tracing(endpoint=endpoint)
+
+
+__all__ = [
+ # modules
+ "exception",
+ "module",
+ "message",
+ "model",
+ "tool",
+ "formatter",
+ "memory",
+ "agent",
+ "session",
+ "logger",
+ "embedding",
+ "token",
+ "evaluate",
+ "pipeline",
+ "tracing",
+ # functions
+ "init",
+ "setup_logger",
+ "__version__",
+]
diff --git a/src/agentscope/_config.py b/src/agentscope/_config.py
new file mode 100644
index 000000000..1311e2299
--- /dev/null
+++ b/src/agentscope/_config.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""The runtime configuration in agentscope.
+
+.. note:: You should import this module as ``import ._config``, then use the
+ variables defined in this module, instead of ``from ._config import xxx``.
+ Because when the variables are changed, the changes will not be reflected in
+ the imported module.
+"""
+from datetime import datetime
+
+import shortuuid
+
+
+def _generate_random_suffix(length: int) -> str:
+ """Generate a random suffix."""
+ return shortuuid.uuid()[:length]
+
+
+project = "UnnamedProject_At" + datetime.now().strftime("%Y%m%d")
+name = datetime.now().strftime("%H%M%S_") + _generate_random_suffix(4)
+run_id: str = shortuuid.uuid()
+created_at: str = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+trace_enabled: bool = False
diff --git a/src/agentscope/_logging.py b/src/agentscope/_logging.py
new file mode 100644
index 000000000..dd5f8c115
--- /dev/null
+++ b/src/agentscope/_logging.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""The logger for agentscope."""
+
+import logging
+
+
+_DEFAULT_FORMAT = (
+ "%(asctime)s | %(levelname)-7s | "
+ "%(module)s:%(funcName)s:%(lineno)s - %(message)s"
+)
+
+logger = logging.getLogger("as")
+
+
+def setup_logger(
+ level: str,
+ filepath: str | None = None,
+) -> None:
+ """Set up the agentscope logger.
+
+ Args:
+ level (`str`):
+ The logging level, chosen from "INFO", "DEBUG", "WARNING",
+ "ERROR", "CRITICAL".
+ filepath (`str | None`, optional):
+ The filepath to save the logging output.
+ """
+ logger.handlers.clear()
+ logger.setLevel(level)
+ handler = logging.StreamHandler()
+ handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+ logger.addHandler(handler)
+
+ if filepath:
+ handler = logging.FileHandler(filepath)
+ handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+ logger.addHandler(handler)
+
+ logger.propagate = False
+
+
+setup_logger("INFO")
diff --git a/src/agentscope/_utils/__init__.py b/src/agentscope/_utils/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.py
new file mode 100644
index 000000000..aedee7da2
--- /dev/null
+++ b/src/agentscope/_utils/_common.py
@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""The common utilities for agentscope library."""
+import asyncio
+import base64
+import functools
+import inspect
+import json
+import os
+import tempfile
+import types
+import typing
+from datetime import datetime
+from typing import Union, Any, Callable
+
+import requests
+from json_repair import repair_json
+
+from .._logging import logger
+
+if typing.TYPE_CHECKING:
+ from mcp.types import Tool
+else:
+ Tool = "mcp.types.Tool"
+
+
+def _json_loads_with_repair(
+ json_str: str,
+) -> Union[dict, list, str, float, int, bool, None]:
+ """The given json_str maybe incomplete, e.g. '{"key', so we need to
+ repair and load it into a Python object.
+ """
+ repaired = json_str
+ try:
+ repaired = repair_json(json_str)
+ except Exception:
+ pass
+
+ try:
+ return json.loads(repaired)
+ except json.JSONDecodeError as e:
+ raise ValueError(
+ f"Failed to decode JSON string `{json_str}` after repairing it "
+ f"into `{repaired}`. Error: {e}",
+ ) from e
+
+
+def _is_accessible_local_file(url: str) -> bool:
+ """Check if the given URL is a local URL."""
+ return os.path.isfile(url)
+
+
+def _get_timestamp(add_random_suffix: bool = False) -> str:
+ """Get the current timestamp in the format YYYY-MM-DD HH:MM:SS.sss."""
+ timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+ if add_random_suffix:
+ # Add a random suffix to the timestamp
+ timestamp += f"_{os.urandom(3).hex()}"
+
+ return timestamp
+
+
+async def _is_async_func(func: Callable) -> bool:
+ """Check if the given function is an async function, including
+ coroutine functions, async generators, and coroutine objects.
+ """
+
+ return (
+ inspect.iscoroutinefunction(func)
+ or inspect.isasyncgenfunction(func)
+ or isinstance(func, types.CoroutineType)
+ or isinstance(func, types.GeneratorType)
+ and asyncio.iscoroutine(func)
+ or isinstance(func, functools.partial)
+ and await _is_async_func(func.func)
+ )
+
+
+async def _execute_async_or_sync_func(
+ func: Callable,
+ *args: Any,
+ **kwargs: Any,
+) -> Any:
+ """Execute an async or sync function based on its type.
+
+ Args:
+ func (`Callable`):
+ The function to be executed, which can be either async or sync.
+ *args (`Any`):
+ Positional arguments to be passed to the function.
+ **kwargs (`Any`):
+ Keyword arguments to be passed to the function.
+
+ Returns:
+ `Any`:
+ The result of the function execution.
+ """
+
+ if await _is_async_func(func):
+ return await func(*args, **kwargs)
+
+ return func(*args, **kwargs)
+
+
+def _get_bytes_from_web_url(
+ url: str,
+ max_retries: int = 3,
+) -> str:
+ """Get the bytes from a given URL.
+
+ Args:
+ url (`str`):
+ The URL to fetch the bytes from.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries.
+ """
+ for _ in range(max_retries):
+ try:
+ response = requests.get(url)
+ response.raise_for_status()
+ return response.content.decode("utf-8")
+
+ except UnicodeDecodeError:
+ return base64.b64encode(response.content).decode("ascii")
+
+ except Exception as e:
+ logger.info(
+ "Failed to fetch bytes from URL %s. Error %s. Retrying...",
+ url,
+ str(e),
+ )
+
+ raise RuntimeError(
+ f"Failed to fetch bytes from URL `{url}` after {max_retries} retries.",
+ )
+
+
+def _save_base64_data(
+ media_type: str,
+ base64_data: str,
+) -> str:
+ """Save the base64 data to a temp file and return the file path. The
+ extension is guessed from the MIME type.
+
+ Args:
+ media_type (`str`):
+ The MIME type of the data, e.g. "image/png", "audio/mpeg".
+ base64_data (`str):
+ The base64 data to be saved.
+ """
+ extension = "." + media_type.split("/")[-1]
+
+ with tempfile.NamedTemporaryFile(
+ suffix=f".{extension}",
+ delete=False,
+ ) as temp_file:
+ decoded_data = base64.b64decode(base64_data)
+ temp_file.write(decoded_data)
+ temp_file.close()
+ return temp_file.name
+
+
+def _extract_json_schema_from_mcp_tool(tool: Tool) -> dict[str, Any]:
+ """Extract JSON schema from MCP tool."""
+
+ return {
+ "type": "function",
+ "function": {
+ "name": tool.name,
+ "description": tool.description,
+ "parameters": {
+ "type": "object",
+ "properties": tool.inputSchema.get(
+ "properties",
+ {},
+ ),
+ "required": tool.inputSchema.get(
+ "required",
+ [],
+ ),
+ },
+ },
+ }
+
+
+def _remove_title_field(schema: dict) -> None:
+ """Remove the title field from the JSON schema to avoid
+ misleading the LLM."""
+ # The top level title field
+ if "title" in schema:
+ schema.pop("title")
+
+ # properties
+ if "properties" in schema:
+ for prop in schema["properties"].values():
+ if isinstance(prop, dict):
+ _remove_title_field(prop)
+
+ # items
+ if "items" in schema and isinstance(schema["items"], dict):
+ _remove_title_field(schema["items"])
+
+ # additionalProperties
+ if "additionalProperties" in schema and isinstance(
+ schema["additionalProperties"],
+ dict,
+ ):
+ _remove_title_field(
+ schema["additionalProperties"],
+ )
diff --git a/src/agentscope/_utils/_mixin.py b/src/agentscope/_utils/_mixin.py
new file mode 100644
index 000000000..1ead2b641
--- /dev/null
+++ b/src/agentscope/_utils/_mixin.py
@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""The mixin for agentscope."""
+
+
+class DictMixin(dict):
+ """The dictionary mixin that allows attribute-style access."""
+
+ __setattr__ = dict.__setitem__
+ __getattr__ = dict.__getitem__
diff --git a/src/agentscope/_version.py b/src/agentscope/_version.py
new file mode 100644
index 000000000..1f397c8a4
--- /dev/null
+++ b/src/agentscope/_version.py
@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""The version of agentscope."""
+
+__version__ = "1.0.0"
diff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.py
new file mode 100644
index 000000000..388d7956a
--- /dev/null
+++ b/src/agentscope/agent/__init__.py
@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""The agent base class."""
+from ._agent_base import AgentBase
+from ._react_agent_base import ReActAgentBase
+from ._react_agent import ReActAgent
+from ._user_input import (
+ UserInputBase,
+ UserInputData,
+ TerminalUserInput,
+ StudioUserInput,
+)
+from ._user_agent import UserAgent
+
+
+__all__ = [
+ "AgentBase",
+ "ReActAgentBase",
+ "ReActAgent",
+ "UserInputData",
+ "UserInputBase",
+ "TerminalUserInput",
+ "StudioUserInput",
+ "UserAgent",
+]
diff --git a/src/agentscope/agent/_agent_base.py b/src/agentscope/agent/_agent_base.py
new file mode 100644
index 000000000..863530433
--- /dev/null
+++ b/src/agentscope/agent/_agent_base.py
@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""The agent base class in agentscope."""
+import asyncio
+import json
+from asyncio import Task
+from collections import OrderedDict
+from typing import Callable, Any, Sequence
+
+import shortuuid
+
+from ._agent_meta import _AgentMeta
+from ..module import StateModule
+from ..message import Msg
+from ..types import AgentHookTypes
+
+
+class AgentBase(StateModule, metaclass=_AgentMeta):
+ """Base class for asynchronous agents."""
+
+ id: str
+ """The agent's unique identifier, generated using shortuuid."""
+
+ supported_hook_types: list[str] = [
+ "pre_reply",
+ "post_reply",
+ "pre_print",
+ "post_print",
+ "pre_observe",
+ "post_observe",
+ ]
+ """Supported hook types for the agent base class."""
+
+ _class_pre_reply_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ ],
+ dict[str, Any] | None, # The modified kwargs or None
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called before the reply
+ function, taking `self` object, the input arguments as input, and
+ generating the modified arguments (if needed). Then input arguments of the
+ reply function will be re-organized into a keyword arguments dictionary.
+ If the one hook returns a new dictionary, the modified arguments will be
+ passed to the next hook or the original reply function."""
+
+ _class_post_reply_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ Msg, # output, the output message
+ ],
+ Msg | None,
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called after the reply
+ function, which takes the `self` object and deep copied
+ positional and keyword arguments (args and kwargs), and the output message
+ as input. If the hook returns a message, the new message will be passed
+ to the next hook or the original reply function. Otherwise, the original
+ output will be passed instead."""
+
+ _class_pre_print_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ ],
+ dict[str, Any] | None, # The modified kwargs or None
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called before printing,
+ which takes the `self` object, a deep copied arguments dictionary as input,
+ and output the modified arguments (if needed). """
+
+ _class_post_print_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ Any, # output, `None` if no output
+ ],
+ Any,
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called after the speak
+ function, which takes the `self` object as input."""
+
+ _class_pre_observe_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ ],
+ dict[str, Any] | None, # The modified kwargs or None
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called before the observe
+ function, which takes the `self` object and a deep copied input
+ arguments dictionary as input. To change the input arguments, the hook
+ function needs to output the modified arguments dictionary, which will be
+ used as the input of the next hook function or the original observe
+ function."""
+
+ _class_post_observe_hooks: dict[
+ str,
+ Callable[
+ [
+ "AgentBase", # self
+ dict[str, Any], # kwargs
+ None, # The output, `None` if no output
+ ],
+ None,
+ ],
+ ] = OrderedDict()
+ """The class-level hook functions that will be called after the observe
+ function, which takes the `self` object as input."""
+
+ def __init__(self) -> None:
+ """Initialize the agent."""
+ super().__init__()
+
+ self.id = shortuuid.uuid()
+
+ # The replying task and identify of the current replying
+ self._reply_task: Task | None = None
+ self._reply_id: str | None = None
+
+ # Initialize the instance-level hooks
+ self._instance_pre_print_hooks = OrderedDict()
+ self._instance_post_print_hooks = OrderedDict()
+
+ self._instance_pre_reply_hooks = OrderedDict()
+ self._instance_post_reply_hooks = OrderedDict()
+
+ self._instance_pre_observe_hooks = OrderedDict()
+ self._instance_post_observe_hooks = OrderedDict()
+
+ # The prefix used in streaming printing
+ self._stream_prefix = {}
+
+ # The subscribers that will receive the reply message by their
+ # `observe` method.
+ self._subscribers: list[AgentBase] = []
+
+ # We add this variable in case developers want to disable the console
+ # output of the agent, e.g., in a production environment.
+ self._disable_console_output: bool = False
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Receive the given message(s) without generating a reply.
+
+ Args:
+ msg (`Msg | list[Msg] | None`):
+ The message(s) to be observed.
+ """
+ raise NotImplementedError(
+ f"The observe function is not implemented in"
+ f" {self.__class__.__name__} class.",
+ )
+
+ async def reply(self, *args: Any, **kwargs: Any) -> Msg:
+ """The main logic of the agent, which generates a reply based on the
+ current state and input arguments."""
+ raise NotImplementedError(
+ "The reply function is not implemented in "
+ f"{self.__class__.__name__} class.",
+ )
+
+ async def print(self, msg: Msg, last: bool = True) -> None:
+ """The function to display the message.
+
+ Args:
+ msg (`Msg`):
+ The message object to be printed.
+ last (`bool`, defaults to `True`):
+ Whether this is the last one in streaming messages. For
+ non-streaming message, this should always be `True`.
+ """
+ if self._disable_console_output:
+ return
+
+ thinking_and_text_to_print = []
+ for block in msg.get_content_blocks():
+ prefix = self._stream_prefix.get(msg.id, "")
+ if block["type"] in ["text", "thinking"]:
+ block_type = block["type"]
+ format_prefix = "" if block_type == "text" else "(thinking)"
+
+ thinking_and_text_to_print.append(
+ f"{msg.name}{format_prefix}: {block[block_type]}",
+ )
+
+ to_print = "\n".join(thinking_and_text_to_print)
+ if len(to_print) > len(prefix):
+ print(to_print[len(prefix) :], end="")
+ self._stream_prefix[msg.id] = to_print
+
+ elif last:
+ if prefix:
+ if not prefix.endswith("\n"):
+ print(
+ "\n"
+ + json.dumps(block, indent=4, ensure_ascii=False),
+ )
+ else:
+ print(json.dumps(block, indent=4, ensure_ascii=False))
+ else:
+ print(
+ f"{msg.name}: "
+ f"{json.dumps(block, indent=4, ensure_ascii=False)}",
+ )
+ if last and msg.id in self._stream_prefix:
+ last_prefix = self._stream_prefix.pop(msg.id)
+ if not last_prefix.endswith("\n"):
+ print()
+
+ async def __call__(self, *args: Any, **kwargs: Any) -> Msg:
+ """Call the reply function with the given arguments."""
+ self._reply_id = shortuuid.uuid()
+
+ reply_msg: Msg | None = None
+ try:
+ self._reply_task = asyncio.current_task()
+ reply_msg = await self.reply(*args, **kwargs)
+
+ except asyncio.CancelledError:
+ reply_msg = await self.handle_interrupt(*args, **kwargs)
+
+ finally:
+ # Broadcast the reply message to all subscribers
+ if reply_msg:
+ await self._broadcast_to_subscribers(reply_msg)
+ self._reply_task = None
+
+ return reply_msg
+
+ async def _broadcast_to_subscribers(
+ self,
+ msg: Msg | list[Msg] | None,
+ ) -> None:
+ """Broadcast the message to all subscribers."""
+ for subscriber in self._subscribers:
+ await subscriber.observe(msg)
+
+ async def handle_interrupt(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """The post-processing logic when the reply is interrupted by the
+ user or something else."""
+ raise NotImplementedError(
+ f"The handle_interrupt function is not implemented in "
+ f"{self.__class__.__name__}",
+ )
+
+ async def interrupt(self, msg: Msg | list[Msg] | None = None) -> None:
+ """Interrupt the current reply process."""
+ if self._reply_task and not self._reply_task.done():
+ self._reply_task.cancel(msg)
+
+ def register_instance_hook(
+ self,
+ hook_type: AgentHookTypes,
+ hook_name: str,
+ hook: Callable,
+ ) -> None:
+ """Register a hook to the agent instance, which only takes effect
+ for the current instance.
+
+ Args:
+ hook_type (`str`):
+ The type of the hook, indicating where the hook is to be
+ triggered.
+ hook_name (`str`):
+ The name of the hook. If the name is already registered, the
+ hook will be overwritten.
+ hook (`Callable`):
+ The hook function.
+ """
+ if not isinstance(self, AgentBase):
+ raise TypeError(
+ "The register_instance_hook method should be called on an "
+ f"instance of AsyncAgentBase, but got {self} of "
+ f"type {type(self)}.",
+ )
+ hooks = getattr(self, f"_instance_{hook_type}_hooks")
+ hooks[hook_name] = hook
+
+ def remove_instance_hook(
+ self,
+ hook_type: AgentHookTypes,
+ hook_name: str,
+ ) -> None:
+ """Remove an instance-level hook from the agent instance.
+
+ Args:
+ hook_type (`AgentHookTypes`):
+ The type of the hook, indicating where the hook is to be
+ triggered.
+ hook_name (`str`):
+ The name of the hook to remove.
+ """
+ if not isinstance(self, AgentBase):
+ raise TypeError(
+ "The remove_instance_hook method should be called on an "
+ f"instance of AsyncAgentBase, but got {self} of "
+ f"type {type(self)}.",
+ )
+ hooks = getattr(self, f"_instance_{hook_type}_hooks")
+ if hook_name in hooks:
+ del hooks[hook_name]
+ else:
+ raise ValueError(
+ f"Hook '{hook_name}' not found in '{hook_type}' hooks of "
+ f"{self.__class__.__name__} instance.",
+ )
+
+ @classmethod
+ def register_class_hook(
+ cls,
+ hook_type: AgentHookTypes,
+ hook_name: str,
+ hook: Callable,
+ ) -> None:
+ """The universal function to register a hook to the agent class, which
+ will take effect for all instances of the class.
+
+ Args:
+ hook_type (`AgentHookTypes`):
+ The type of the hook, indicating where the hook is to be
+ triggered.
+ hook_name (`str`):
+ The name of the hook. If the name is already registered, the
+ hook will be overwritten.
+ hook (`Callable`):
+ The hook function.
+ """
+
+ assert (
+ hook_type in cls.supported_hook_types
+ ), f"Invalid hook type: {hook_type}"
+
+ hooks = getattr(cls, f"_class_{hook_type}_hooks")
+ hooks[hook_name] = hook
+
+ @classmethod
+ def remove_class_hook(
+ cls,
+ hook_type: AgentHookTypes,
+ hook_name: str,
+ ) -> None:
+ """Remove a class-level hook from the agent class.
+
+ Args:
+ hook_type (`AgentHookTypes`):
+ The type of the hook, indicating where the hook is to be
+ triggered.
+ hook_name (`str`):
+ The name of the hook to remove.
+ """
+
+ assert (
+ hook_type in cls.supported_hook_types
+ ), f"Invalid hook type: {hook_type}"
+ hooks = getattr(cls, f"_class_{hook_type}_hooks")
+ if hook_name in hooks:
+ del hooks[hook_name]
+
+ else:
+ raise ValueError(
+ f"Hook '{hook_name}' not found in '{hook_type}' hooks of "
+ f"{cls.__name__} class.",
+ )
+
+ @classmethod
+ def clear_class_hooks(
+ cls,
+ hook_type: AgentHookTypes | None = None,
+ ) -> None:
+ """Clear all class-level hooks.
+
+ Args:
+ hook_type (`AgentHookTypes`, optional):
+ The type of the hook to clear. If not specified, all
+ class-level hooks will be cleared.
+ """
+
+ if hook_type is None:
+ for typ in cls.supported_hook_types:
+ hooks = getattr(cls, f"_class_{typ}_hooks")
+ hooks.clear()
+ else:
+ assert (
+ hook_type in cls.supported_hook_types
+ ), f"Invalid hook type: {hook_type}"
+ hooks = getattr(cls, f"_class_{hook_type}_hooks")
+ hooks.clear()
+
+ def clear_instance_hooks(
+ self,
+ hook_type: AgentHookTypes | None = None,
+ ) -> None:
+ """If `hook_type` is not specified, clear all instance-level hooks.
+ Otherwise, clear the specified type of instance-level hooks."""
+ if hook_type is None:
+ for typ in self.supported_hook_types:
+ if not hasattr(self, f"_instance_{typ}_hooks"):
+ raise ValueError(
+ f"Call super().__init__() in the constructor "
+ f"to initialize the instance-level hooks for "
+ f"{self.__class__.__name__}.",
+ )
+ hooks = getattr(self, f"_instance_{typ}_hooks")
+ hooks.clear()
+
+ else:
+ assert (
+ hook_type in self.supported_hook_types
+ ), f"Invalid hook type: {hook_type}"
+ if not hasattr(self, f"_instance_{hook_type}_hooks"):
+ raise ValueError(
+ f"Call super().__init__() in the constructor "
+ f"to initialize the instance-level hooks for "
+ f"{self.__class__.__name__}.",
+ )
+ hooks = getattr(self, f"_instance_{hook_type}_hooks")
+ hooks.clear()
+
+ def reset_subscribers(self, subscribers: Sequence["AgentBase"]) -> None:
+ """Reset the subscribers of the agent.
+
+ Args:
+ subscribers (`list[AgentBase]`):
+ A list of agents that will receive the reply message from
+ this agent via their `observe` method.
+ """
+ self._subscribers = [_ for _ in subscribers if _ != self]
+
+ def disable_console_output(self) -> None:
+ """This function will disable the console output of the agent, e.g.
+ in a production environment to avoid messy logs."""
+ self._disable_console_output = True
diff --git a/src/agentscope/agent/_agent_meta.py b/src/agentscope/agent/_agent_meta.py
new file mode 100644
index 000000000..a9bc81b5f
--- /dev/null
+++ b/src/agentscope/agent/_agent_meta.py
@@ -0,0 +1,180 @@
+# -*- coding: utf-8 -*-
+"""The metaclass for agents in agentscope."""
+import inspect
+from copy import deepcopy
+from functools import wraps
+from typing import (
+ Any,
+ Dict,
+ TYPE_CHECKING,
+ Callable,
+)
+
+from .._utils._common import _execute_async_or_sync_func
+
+if TYPE_CHECKING:
+ from ._agent_base import AgentBase
+else:
+ AgentBase = "AgentBase"
+
+
+def _normalize_to_kwargs(
+ func: Callable,
+ self: Any,
+ *args: Any,
+ **kwargs: Any,
+) -> dict:
+ """Normalize the provided positional and keyword arguments into a
+ keyword arguments dictionary that matches the function signature."""
+ sig = inspect.signature(func)
+ try:
+ # Bind the provided arguments to the function signature
+ bound = sig.bind(self, *args, **kwargs)
+ # Apply the default values for parameters
+ bound.apply_defaults()
+
+ # Return the arguments in a dictionary format
+ res = dict(bound.arguments)
+ res.pop("self")
+ return res
+
+ except TypeError as e:
+ # If failed to bind, we raise a TypeError with more context
+ param_names = list(sig.parameters.keys())
+ provided_args = len(args)
+ provided_kwargs = list(kwargs.keys())
+
+ raise TypeError(
+ f"Failed to bind parameters for function '{func.__name__}': {e}\n"
+ f"Expected parameters: {param_names}\n"
+ f"Provided {provided_args} positional args and kwargs: "
+ f"{provided_kwargs}",
+ ) from e
+
+
+def _wrap_with_hooks(
+ original_func: Callable,
+) -> Callable:
+ """A decorator to wrap the original async function with pre- and post-hooks
+
+ Args:
+ original_func (`Callable`):
+ The original async function to be wrapped with hooks.
+ """
+ func_name = original_func.__name__.replace("_", "")
+
+ @wraps(original_func)
+ async def async_wrapper(
+ self: AgentBase,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Any:
+ """The wrapped function, which call the pre- and post-hooks before and
+ after the original function."""
+
+ # Unify all positional and keyword arguments into a keyword arguments
+ normalized_kwargs = _normalize_to_kwargs(
+ original_func,
+ self,
+ *args,
+ **kwargs,
+ )
+
+ current_normalized_kwargs = normalized_kwargs
+ assert (
+ hasattr(self, f"_instance_pre_{func_name}_hooks")
+ and hasattr(self, f"_instance_post_{func_name}_hooks")
+ and hasattr(self.__class__, f"_class_pre_{func_name}_hooks")
+ and hasattr(self.__class__, f"_class_post_{func_name}_hooks")
+ ), f"Hooks for {func_name} not found in {self.__class__.__name__}"
+
+ # pre-hooks
+ pre_hooks = list(
+ getattr(self, f"_instance_pre_{func_name}_hooks").values(),
+ ) + list(
+ getattr(self, f"_class_pre_{func_name}_hooks").values(),
+ )
+ for pre_hook in pre_hooks:
+ modified_keywords = await _execute_async_or_sync_func(
+ pre_hook,
+ self,
+ deepcopy(current_normalized_kwargs),
+ )
+ if modified_keywords is not None:
+ assert isinstance(modified_keywords, dict), (
+ f"Pre-hook must return a dict of keyword arguments, rather"
+ f" than {type(modified_keywords)} from hook "
+ f"{pre_hook.__name__}"
+ )
+ current_normalized_kwargs = modified_keywords
+
+ # original function
+ # handle positional and keyword arguments specifically
+ args = current_normalized_kwargs.get("args", [])
+ kwargs = current_normalized_kwargs.get("kwargs", {})
+ others = {
+ k: v
+ for k, v in current_normalized_kwargs.items()
+ if k not in ["args", "kwargs"]
+ }
+ current_output = await original_func(
+ self,
+ *args,
+ **others,
+ **kwargs,
+ )
+
+ # post_hooks
+ post_hooks = list(
+ getattr(self, f"_instance_post_{func_name}_hooks").values(),
+ ) + list(
+ getattr(self, f"_class_post_{func_name}_hooks").values(),
+ )
+ for post_hook in post_hooks:
+ modified_output = await _execute_async_or_sync_func(
+ post_hook,
+ self,
+ deepcopy(current_normalized_kwargs),
+ deepcopy(current_output),
+ )
+ if modified_output is not None:
+ current_output = modified_output
+ return current_output
+
+ return async_wrapper
+
+
+class _AgentMeta(type):
+ """The agent metaclass that wraps the agent's reply, observe and print
+ functions with pre- and post-hooks."""
+
+ def __new__(mcs, name: Any, bases: Any, attrs: Dict) -> Any:
+ """Wrap the agent's functions with hooks."""
+
+ for func_name in [
+ "reply",
+ "print",
+ "observe",
+ ]:
+ if func_name in attrs:
+ attrs[func_name] = _wrap_with_hooks(attrs[func_name])
+
+ return super().__new__(mcs, name, bases, attrs)
+
+
+class _ReActAgentMeta(_AgentMeta):
+ """The ReAct metaclass that adds pre- and post-hooks for the _reasoning
+ and _acting functions."""
+
+ def __new__(mcs, name: Any, bases: Any, attrs: Dict) -> Any:
+ """Wrap the ReAct agent's _reasoning and _acting functions with
+ hooks."""
+
+ for func_name in [
+ "_reasoning",
+ "_acting",
+ ]:
+ if func_name in attrs:
+ attrs[func_name] = _wrap_with_hooks(attrs[func_name])
+
+ return super().__new__(mcs, name, bases, attrs)
diff --git a/src/agentscope/agent/_react_agent.py b/src/agentscope/agent/_react_agent.py
new file mode 100644
index 000000000..a693a24d5
--- /dev/null
+++ b/src/agentscope/agent/_react_agent.py
@@ -0,0 +1,544 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=not-an-iterable
+# mypy: disable-error-code="list-item"
+"""ReAct agent class in agentscope."""
+import asyncio
+from typing import Type, Any, AsyncGenerator, Literal
+
+import shortuuid
+from pydantic import BaseModel, ValidationError
+
+from ._react_agent_base import ReActAgentBase
+from ..formatter import FormatterBase
+from ..memory import MemoryBase, LongTermMemoryBase, InMemoryMemory
+from ..message import Msg, ToolUseBlock, ToolResultBlock, TextBlock
+from ..model import ChatModelBase
+from ..tool import Toolkit, ToolResponse
+from ..tracing import trace_reply
+
+
+def finish_function_pre_print_hook(
+ self: "ReActAgent",
+ kwargs: dict[str, Any],
+) -> dict[str, Any] | None:
+ """A pre-speak hook function that check if finish_function is called. If
+ so, it will wrap the response argument into a message and return it to
+ replace the original message. By this way, the calling of the finish
+ function will be displayed as a text reply instead of a tool call."""
+
+ msg = kwargs["msg"]
+
+ if isinstance(msg.content, str):
+ return None
+
+ if isinstance(msg.content, list):
+ for i, block in enumerate(msg.content):
+ if (
+ block["type"] == "tool_use"
+ and block["name"] == self.finish_function_name
+ ):
+ # Convert the response argument into a text block for
+ # displaying
+ try:
+ msg.content[i] = TextBlock(
+ type="text",
+ text=block["input"].get("response", ""),
+ )
+ return kwargs
+ except Exception:
+ print("Error in block input", block["input"])
+
+ return None
+
+
+class ReActAgent(ReActAgentBase):
+ """A ReAct agent implementation in AgentScope, which supports
+
+ - Realtime steering
+ - API-based (parallel) tool calling
+ - Hooks around reasoning, acting, reply, observe and print functions
+ - Structured output generation
+ """
+
+ finish_function_name: str = "generate_response"
+ """The function name used to finish replying and return a response to
+ the user."""
+
+ def __init__(
+ self,
+ name: str,
+ sys_prompt: str,
+ model: ChatModelBase,
+ formatter: FormatterBase,
+ toolkit: Toolkit | None = None,
+ memory: MemoryBase | None = None,
+ long_term_memory: LongTermMemoryBase | None = None,
+ long_term_memory_mode: Literal[
+ "agent_control",
+ "static_control",
+ "both",
+ ] = "both",
+ enable_meta_tool: bool = False,
+ parallel_tool_calls: bool = False,
+ max_iters: int = 10,
+ ) -> None:
+ """Initialize the ReAct agent
+
+ Args:
+ name (`str`):
+ The name of the agent.
+ sys_prompt (`str`):
+ The system prompt of the agent.
+ model (`ChatModelBase`):
+ The chat model used by the agent.
+ formatter (`FormatterBase`):
+ The formatter used to format the messages into the required
+ format of the model API provider.
+ toolkit (`Toolkit | None`, optional):
+ A `Toolkit` object that contains the tool functions. If not
+ provided, a default empty `Toolkit` will be created.
+ memory (`MemoryBase | None`, optional):
+ The memory used to store the dialogue history. If not provided,
+ a default `InMemoryMemory` will be created, which stores
+ messages in a list in memory.
+ long_term_memory (`LongTermMemoryBase | None`, optional):
+ The optional long-term memory, which will provide two tool
+ functions: `retrieve_from_memory` and `record_to_memory`, and
+ will attach the retrieved information to the system prompt
+ before each reply.
+ enable_meta_tool (`bool`, defaults to `False`):
+ If `True`, a meta tool function `reset_equipped_tools` will be
+ added to the toolkit, which allows the agent to manage its
+ equipped tools dynamically.
+ long_term_memory_mode (`Literal['agent_control', 'static_control',\
+ 'both']`, defaults to `both`):
+ The mode of the long-term memory. If `agent_control`, two
+ tool functions `retrieve_from_memory` and `record_to_memory`
+ will be registered in the toolkit to allow the agent to
+ manage the long-term memory. If `static_control`, retrieving
+ and recording will happen in the beginning and end of
+ each reply respectively.
+ parallel_tool_calls (`bool`, defaults to `False`):
+ When LLM generates multiple tool calls, whether to execute
+ them in parallel.
+ max_iters (`int`, defaults to `10`):
+ The maximum number of iterations of the reasoning-acting loops.
+ """
+ super().__init__()
+
+ assert long_term_memory_mode in [
+ "agent_control",
+ "static_control",
+ "both",
+ ]
+
+ # Static variables in the agent
+ self.name = name
+ self._sys_prompt = sys_prompt
+ self.max_iters = max_iters
+ self.model = model
+ self.formatter = formatter
+
+ # Record the dialogue history in the memory
+ self.memory = memory or InMemoryMemory()
+ # If provide the long-term memory, it will be used to retrieve info
+ # in the beginning of each reply, and the result will be added to the
+ # system prompt
+ self.long_term_memory = long_term_memory
+
+ # The long-term memory mode
+ self._static_control = long_term_memory and long_term_memory_mode in [
+ "static_control",
+ "both",
+ ]
+ self._agent_control = long_term_memory and not self._static_control
+
+ # If None, a default Toolkit will be created
+ self.toolkit = toolkit or Toolkit()
+ self.toolkit.register_tool_function(
+ getattr(self, self.finish_function_name),
+ )
+ if self._agent_control:
+ # Adding two tool functions into the toolkit to allow self-control
+ self.toolkit.register_tool_function(
+ long_term_memory.record_to_memory,
+ )
+ self.toolkit.register_tool_function(
+ long_term_memory.retrieve_from_memory,
+ )
+ # Add a meta tool function to allow agent-controlled tool management
+ if enable_meta_tool:
+ self.toolkit.register_tool_function(
+ self.toolkit.reset_equipped_tools,
+ )
+
+ self.parallel_tool_calls = parallel_tool_calls
+ self.max_iters = max_iters
+
+ # Variables to record the intermediate state
+
+ # If required structured output model is provided
+ self._required_structured_model: Type[BaseModel] | None = None
+
+ # Register the status variables
+ self.register_state("name")
+ self.register_state("_sys_prompt")
+
+ self.register_instance_hook(
+ "pre_print",
+ "finish_function_pre_print_hook",
+ finish_function_pre_print_hook,
+ )
+
+ @property
+ def sys_prompt(self) -> str:
+ """The dynamic system prompt of the agent."""
+ return self._sys_prompt
+
+ @trace_reply
+ async def reply(
+ self,
+ msg: Msg | list[Msg] | None = None,
+ structured_model: Type[BaseModel] | None = None,
+ ) -> Msg:
+ """Generate a reply based on the current state and input arguments.
+
+ Args:
+ msg (`Msg | list[Msg] | None`, optional):
+ The input message(s) to the agent.
+ structured_model (`Type[BaseModel] | None`, optional):
+ The required structured output model. If provided, the agent
+ is expected to generate structured output in the `metadata`
+ field of the output message.
+
+ Returns:
+ `Msg`:
+ The output message generated by the agent.
+ """
+ await self.memory.add(msg)
+
+ # Long-term memory retrieval
+ if self._static_control:
+ # Retrieve information from the long-term memory if available
+ retrieved_info = await self.long_term_memory.retrieve(msg)
+ if retrieved_info:
+ await self.memory.add(
+ Msg(
+ name="long_term_memory",
+ content="<long_term_memory>The content below are "
+ "retrieved from long-term memory, which maybe "
+ f"useful:\n{retrieved_info}</long_term_memory>",
+ role="user",
+ ),
+ )
+
+ self._required_structured_model = structured_model
+ # Record structured output model if provided
+ if structured_model:
+ self.toolkit.set_extended_model(
+ self.finish_function_name,
+ structured_model,
+ )
+
+ # The reasoning-acting loop
+ reply_msg = None
+ for _ in range(self.max_iters):
+ msg_reasoning = await self._reasoning()
+
+ futures = [
+ self._acting(tool_call)
+ for tool_call in msg_reasoning.get_content_blocks(
+ "tool_use",
+ )
+ ]
+
+ # Parallel tool calls or not
+ if self.parallel_tool_calls:
+ acting_responses = await asyncio.gather(*futures)
+
+ else:
+ # Sequential tool calls
+ acting_responses = [await _ for _ in futures]
+
+ # Find the first non-None replying message from the acting
+ for acting_msg in acting_responses:
+ reply_msg = reply_msg or acting_msg
+
+ if reply_msg:
+ break
+
+ # When the maximum iterations are reached
+ if reply_msg is None:
+ reply_msg = await self._summarizing()
+
+ # Post-process the memory, long-term memory
+ if self._static_control:
+ await self.long_term_memory.record(
+ [
+ *([*msg] if isinstance(msg, list) else [msg]),
+ *await self.memory.get_memory(),
+ reply_msg,
+ ],
+ )
+
+ await self.memory.add(reply_msg)
+ return reply_msg
+
+ async def _reasoning(
+ self,
+ ) -> Msg:
+ """Perform the reasoning process."""
+ prompt = await self.formatter.format(
+ msgs=[
+ Msg("system", self.sys_prompt, "system"),
+ *await self.memory.get_memory(),
+ ],
+ )
+
+ res = await self.model(
+ prompt,
+ tools=self.toolkit.get_json_schemas(),
+ )
+
+ # handle output from the model
+ interrupted_by_user = False
+ msg = None
+ try:
+ if self.model.stream:
+ msg = Msg(self.name, [], "assistant")
+ async for content_chunk in res:
+ msg.content = content_chunk.content
+ await self.print(msg, False)
+ await self.print(msg, True)
+
+ else:
+ msg = Msg(self.name, list(res.content), "assistant")
+ await self.print(msg, True)
+
+ return msg
+
+ except asyncio.CancelledError as e:
+ interrupted_by_user = True
+ raise e from None
+
+ finally:
+ if msg and not msg.has_content_blocks("tool_use"):
+ # Turn plain text response into a tool call of the finish
+ # function
+ msg.content = [
+ ToolUseBlock(
+ id=shortuuid.uuid(),
+ type="tool_use",
+ name=self.finish_function_name,
+ input={"response": msg.get_text_content()},
+ ),
+ ]
+
+ # None will be ignored by the memory
+ await self.memory.add(msg)
+
+ # Post-process for user interruption
+ if interrupted_by_user and msg:
+ # Fake tool results
+ tool_use_blocks: list = msg.get_content_blocks(
+ "tool_use",
+ )
+ for tool_call in tool_use_blocks:
+ msg_res = Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id=tool_call["id"],
+ name=tool_call["name"],
+ output="The tool call has been interrupted "
+ "by the user.",
+ ),
+ ],
+ "system",
+ )
+ await self.memory.add(msg_res)
+ await self.print(msg_res, True)
+
+ async def _acting(self, tool_call: ToolUseBlock) -> Msg | None:
+ """Perform the acting process.
+
+ Args:
+ tool_call (`ToolUseBlock`):
+ The tool use block to be executed.
+
+ Returns:
+ `Union[Msg, None]`:
+ Return a message to the user if the `_finish_function` is
+ called, otherwise return `None`.
+ """
+
+ tool_res_msg = Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id=tool_call["id"],
+ name=tool_call["name"],
+ output=[],
+ ),
+ ],
+ "system",
+ )
+ try:
+ # Execute the tool call
+ tool_res = await self.toolkit.call_tool_function(tool_call)
+
+ response_msg = None
+ # Async generator handling
+ async for chunk in tool_res:
+ # Turn into a tool result block
+ tool_res_msg.content[0][ # type: ignore[index]
+ "output"
+ ] = chunk.content
+
+ # Skip the printing of the finish function call
+ if (
+ tool_call["name"] != self.finish_function_name
+ or tool_call["name"] == self.finish_function_name
+ and not chunk.metadata.get("success")
+ ):
+ await self.print(tool_res_msg, chunk.is_last)
+
+ # Return message if generate_response is called successfully
+ if tool_call[
+ "name"
+ ] == self.finish_function_name and chunk.metadata.get(
+ "success",
+ True,
+ ):
+ response_msg = chunk.metadata.get("response_msg")
+
+ return response_msg
+
+ finally:
+ # Record the tool result message in the memory
+ await self.memory.add(tool_res_msg)
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Receive observing message(s) without generating a reply.
+
+ Args:
+ msg (`Msg | list[Msg] | None`):
+ The message or messages to be observed.
+ """
+ await self.memory.add(msg)
+
+ async def _summarizing(self) -> Msg:
+ """Generate a response when the agent fails to solve the problem in
+ the maximum iterations."""
+ hint_msg = Msg(
+ "user",
+ "You have failed to generate response within the maximum "
+ "iterations. Now respond directly by summarizing the current "
+ "situation.",
+ role="user",
+ )
+
+ # Generate a reply by summarizing the current situation
+ prompt = await self.formatter.format(
+ [
+ Msg("system", self.sys_prompt, "system"),
+ *await self.memory.get_memory(),
+ hint_msg,
+ ],
+ )
+ # TODO: handle the structured output here, maybe force calling the
+ # finish_function here
+ res = await self.model(prompt)
+
+ res_msg = Msg(self.name, [], "assistant")
+ if isinstance(res, AsyncGenerator):
+ async for chunk in res:
+ res_msg.content = chunk.content
+ await self.print(res_msg, False)
+ await self.print(res_msg, True)
+
+ else:
+ res_msg.content = res.content
+ await self.print(res_msg, True)
+
+ return res_msg
+
+ async def handle_interrupt(
+ self,
+ _msg: Msg | list[Msg] | None = None,
+ ) -> Msg:
+ """The post-processing logic when the reply is interrupted by the
+ user or something else."""
+
+ response_msg = Msg(
+ self.name,
+ "I noticed that you have interrupted me. What can I "
+ "do for you?",
+ "assistant",
+ metadata={},
+ )
+
+ await self.print(response_msg, True)
+ await self.memory.add(response_msg)
+ await self.memory.clear()
+ return response_msg
+
+ def generate_response(
+ self,
+ response: str,
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """Generate a response. Note only the input argument `response` is
+ visible to the others, you should include all the necessary
+ information in the `response` argument.
+
+ Args:
+ response (`str`):
+ Your response to the user.
+ """
+ response_msg = Msg(
+ self.name,
+ response,
+ "assistant",
+ )
+
+ # Prepare structured output
+ if self._required_structured_model:
+ try:
+ # Use the metadata field of the message to store the
+ # structured output
+ response_msg.metadata = (
+ self._required_structured_model.model_validate(
+ kwargs,
+ ).model_dump()
+ )
+
+ except ValidationError as e:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Arguments Validation Error: {e}",
+ ),
+ ],
+ metadata={
+ "success": False,
+ "response_msg": None,
+ },
+ )
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="Successfully generated response.",
+ ),
+ ],
+ metadata={
+ "success": True,
+ "response_msg": response_msg,
+ },
+ is_last=True,
+ )
diff --git a/src/agentscope/agent/_react_agent_base.py b/src/agentscope/agent/_react_agent_base.py
new file mode 100644
index 000000000..3966cef43
--- /dev/null
+++ b/src/agentscope/agent/_react_agent_base.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""The base class for ReAct agent in agentscope."""
+from abc import abstractmethod
+from collections import OrderedDict
+from typing import Callable, Any
+
+from ._agent_base import AgentBase
+from ._agent_meta import _ReActAgentMeta
+from ..message import Msg
+
+
+class ReActAgentBase(AgentBase, metaclass=_ReActAgentMeta):
+ """The ReAct agent base class.
+
+ To support ReAct algorithm, this class extends the AgentBase class by
+ adding two abstract interfaces: reasoning and acting, while supporting
+ hook functions at four positions: pre-reasoning, post-reasoning,
+ pre-acting, and post-acting by the `_ReActAgentMeta` metaclass.
+ """
+
+ supported_hook_types: list[str] = [
+ "pre_reply",
+ "post_reply",
+ "pre_print",
+ "post_print",
+ "pre_observe",
+ "post_observe",
+ "pre_reasoning",
+ "post_reasoning",
+ "pre_acting",
+ "post_acting",
+ ]
+ """Supported hook types for the agent base class."""
+
+ _class_pre_reasoning_hooks: dict[
+ str,
+ Callable[
+ [
+ "ReActAgentBase", # self
+ dict[str, Any], # kwargs
+ ],
+ dict[str, Any] | None, # The modified kwargs or None
+ ],
+ ] = OrderedDict()
+ """The class-level pre-reasoning hooks, taking `self` object, the input
+ arguments as input"""
+
+ _class_post_reasoning_hooks: dict[
+ str,
+ Callable[
+ [
+ "ReActAgentBase", # self
+ dict[str, Any], # kwargs
+ Any, # output
+ ],
+ Msg | None, # the modified output message or None
+ ],
+ ] = OrderedDict()
+ """The class-level post-reasoning hooks, taking `self` object, the input
+ arguments and the output message as input, and return the modified output
+ message or None if no modification is needed."""
+
+ _class_pre_acting_hooks: dict[
+ str,
+ Callable[
+ [
+ "ReActAgentBase", # self
+ dict[str, Any], # kwargs
+ ],
+ dict[str, Any] | None, # The modified kwargs or None
+ ],
+ ] = OrderedDict()
+ """The class-level pre-acting hooks, taking `self` object, the input
+ arguments as input, and return the modified input arguments or None if no
+ modification is needed."""
+
+ _class_post_acting_hooks: dict[
+ str,
+ Callable[
+ [
+ "ReActAgentBase", # self
+ dict[str, Any], # kwargs
+ Any, # output
+ ],
+ Msg | None, # the modified output message or None
+ ],
+ ] = OrderedDict()
+ """The class-level post-acting hooks, taking `self` object, the input
+ arguments and the output message as input, and return the modified output
+ message or None if no modification is needed."""
+
+ def __init__(
+ self,
+ ) -> None:
+ """Initialize the ReAct agent base class."""
+ super().__init__()
+
+ # Init reasoning and acting hooks
+ self._instance_pre_reasoning_hooks = OrderedDict()
+ self._instance_post_reasoning_hooks = OrderedDict()
+ self._instance_pre_acting_hooks = OrderedDict()
+ self._instance_post_acting_hooks = OrderedDict()
+
+ @abstractmethod
+ async def _reasoning(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Any:
+ """The reasoning process of the ReAct agent, which will be wrapped
+ with pre- and post-hooks."""
+
+ @abstractmethod
+ async def _acting(self, *args: Any, **kwargs: Any) -> Any:
+ """The acting process of the ReAct agent, which will be wrapped with
+ pre- and post-hooks."""
diff --git a/src/agentscope/agent/_user_agent.py b/src/agentscope/agent/_user_agent.py
new file mode 100644
index 000000000..2b6c1c18e
--- /dev/null
+++ b/src/agentscope/agent/_user_agent.py
@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""The user agent class."""
+from typing import Type, Any
+
+from pydantic import BaseModel
+
+from ._agent_base import AgentBase
+from ._user_input import UserInputBase, TerminalUserInput
+from ..message import Msg
+
+
+class UserAgent(AgentBase):
+ """The class for user interaction, allowing developers to handle the user
+ input from different sources, such as web UI, cli, and other interfaces.
+ """
+
+ _input_method: UserInputBase = TerminalUserInput()
+ """The user input method, can be overridden by calling the
+ `register_instance/class_input_method` function."""
+
+ def __init__(
+ self,
+ name: str,
+ ) -> None:
+ """Initialize the user agent with a name."""
+ super().__init__()
+
+ self.name = name
+
+ async def reply(
+ self,
+ msg: Msg | list[Msg] | None = None,
+ structured_model: Type[BaseModel] | None = None,
+ ) -> Msg:
+ """Receive input message(s) and generate a reply message from the user.
+
+ Args:
+ msg (`Msg | list[Msg] | None`, defaults to `None`):
+ The message(s) to be replied. If `None`, the agent will wait
+ for user input.
+ structured_model (`Type[BaseModel] | None`, defaults to `None`):
+ A child class of `pydantic.BaseModel` that defines the
+ structured output format. If provided, the user will be
+ prompted to fill in the required fields.
+
+ Returns:
+ `Msg`:
+ The reply message generated by the user.
+ """
+
+ # Get the input from the specified input method.
+ input_data = await self._input_method(
+ agent_id=self.id,
+ agent_name=self.name,
+ structured_model=structured_model,
+ )
+
+ blocks_input = input_data.blocks_input
+ if (
+ blocks_input
+ and len(blocks_input) == 1
+ and blocks_input[0].get("type") == "text"
+ ):
+ # Turn blocks_input into a string if only one text block exists
+ blocks_input = blocks_input[0].get("text")
+
+ msg = Msg(
+ self.name,
+ content=blocks_input,
+ role="user",
+ metadata=input_data.structured_input,
+ )
+
+ await self.print(msg)
+
+ return msg
+
+ def override_instance_input_method(
+ self,
+ input_method: UserInputBase,
+ ) -> None:
+ """Override the input method of the current UserAgent instance.
+
+ Args:
+ input_method (`UserInputBase`):
+ The callable input method, which should be an object of a
+ class that inherits from `UserInputBase`.
+ """
+ if not isinstance(input_method, UserInputBase):
+ raise ValueError(
+ f"The input method should be an instance of the child class "
+ f"of `UserInputBase`, but got {type(input_method)} instead.",
+ )
+ self._input_method = input_method
+
+ @classmethod
+ def override_class_input_method(
+ cls,
+ input_method: UserInputBase,
+ ) -> None:
+ """Override the input method of the current UserAgent class.
+
+ Args:
+ input_method (`UserInputBase`):
+ The callable input method, which should be an object of a
+ class that inherits from `UserInputBase`.
+ """
+ if not isinstance(input_method, UserInputBase):
+ raise ValueError(
+ f"The input method should be an instance of the child class "
+ f"of `UserInputBase`, but got {type(input_method)} instead.",
+ )
+ cls._input_method = input_method
+
+ async def handle_interrupt(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """The post-processing logic when the reply is interrupted by the
+ user or something else."""
+ raise NotImplementedError(
+ f"The handle_interrupt function is not implemented in "
+ f"{self.__class__.__name__}",
+ )
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Observe the message(s) from the other agents or the environment."""
diff --git a/src/agentscope/agent/_user_input.py b/src/agentscope/agent/_user_input.py
new file mode 100644
index 000000000..86bc2eb5f
--- /dev/null
+++ b/src/agentscope/agent/_user_input.py
@@ -0,0 +1,411 @@
+# -*- coding: utf-8 -*-
+"""The user input related classes."""
+import json.decoder
+import time
+from abc import abstractmethod
+from dataclasses import dataclass
+from queue import Queue
+from threading import Event
+from typing import Any, Type, List
+
+import jsonschema
+import requests
+import shortuuid
+import socketio
+from pydantic import BaseModel
+import json5
+
+from .. import _config
+from .._logging import logger
+from ..message import (
+ TextBlock,
+ VideoBlock,
+ AudioBlock,
+ ImageBlock,
+)
+
+
+@dataclass
+class UserInputData:
+ """The user input data."""
+
+ blocks_input: List[TextBlock | ImageBlock | AudioBlock | VideoBlock] = None
+ """The text input from the user"""
+
+ structured_input: dict[str, Any] | None = None
+ """The structured input from the user"""
+
+
+class UserInputBase:
+ """The base class used to handle the user input from different sources."""
+
+ @abstractmethod
+ async def __call__(
+ self,
+ agent_id: str,
+ agent_name: str,
+ *args: Any,
+ structured_model: Type[BaseModel] | None = None,
+ **kwargs: Any,
+ ) -> UserInputData:
+ """The user input method, which returns the user input and the
+ required structured data.
+
+ Args:
+ agent_id (`str`):
+ The agent identifier.
+ agent_name (`str`):
+ The agent name.
+ structured_model (`Type[BaseModel] | None`, optional):
+ A base model class that defines the structured input format.
+
+ Returns:
+ `UserInputData`:
+ The user input data.
+ """
+
+
+class TerminalUserInput(UserInputBase):
+ """The terminal user input."""
+
+ def __init__(self, input_hint: str = "User Input: ") -> None:
+ """Initialize the terminal user input with a hint."""
+ self.input_hint = input_hint
+
+ async def __call__(
+ self,
+ agent_id: str,
+ agent_name: str,
+ *args: Any,
+ structured_model: Type[BaseModel] | None = None,
+ **kwargs: Any,
+ ) -> UserInputData:
+ """Handle the user input from the terminal.
+
+ Args:
+ agent_id (`str`):
+ The agent identifier.
+ agent_name (`str`):
+ The agent name.
+ structured_model (`Type[BaseModel] | None`, optional):
+ A base model class that defines the structured input format.
+
+ Returns:
+ `UserInputData`:
+ The user input data.
+ """
+
+ text_input = input(self.input_hint)
+
+ structured_input = None
+ if structured_model is not None:
+ structured_input = {}
+
+ json_schema = structured_model.model_json_schema()
+ required = json_schema.get("required", [])
+ print("Structured input (press Enter to skip for optional):)")
+
+ for key, item in json_schema.get("properties").items():
+ requirements = {**item}
+ requirements.pop("title")
+
+ while True:
+ res = input(f"\t{key} ({requirements}): ")
+
+ if res == "":
+ if key in required:
+ print(f"Key {key} is required.")
+ continue
+
+ res = item.get("default", None)
+
+ if item.get("type").lower() == "integer":
+ try:
+ res = json5.loads(res)
+ except json.decoder.JSONDecodeError as e:
+ print(
+ "\033[31mInvalid input with error:\n"
+ "```\n"
+ f"{e}\n"
+ "```\033[0m",
+ )
+ continue
+
+ try:
+ jsonschema.validate(res, item)
+ structured_input[key] = res
+ break
+ except jsonschema.ValidationError as e:
+ print(
+ f"\033[31mValidation error:\n```\n{e}\n```\033[0m",
+ )
+ time.sleep(0.5)
+
+ return UserInputData(
+ blocks_input=[TextBlock(type="text", text=text_input)],
+ structured_input=structured_input,
+ )
+
+
+class StudioUserInput(UserInputBase):
+ """The class that host the user input on the AgentScope Studio."""
+
+ _websocket_namespace: str = "/python"
+
+ def __init__(
+ self,
+ studio_url: str,
+ run_id: str,
+ max_retries: int = 3,
+ reconnect_attempts: int = 3,
+ reconnection_delay: int = 1,
+ reconnection_delay_max: int = 5,
+ ) -> None:
+ """Initialize the StudioUserInput object.
+
+ Args:
+ studio_url (`str`):
+ The URL of the AgentScope Studio.
+ run_id (`str`):
+ The current run identity.
+ max_retries (`int`, defaults to `3`):
+ The maximum number of retries to get user input.
+ """
+ self._is_connected = False
+ self._is_reconnecting = False
+
+ self.studio_url = studio_url
+ self.run_id = run_id
+ self.max_retries = max_retries
+
+ # Init Websocket
+ self.sio = socketio.Client(
+ reconnection=True,
+ reconnection_attempts=reconnect_attempts,
+ reconnection_delay=reconnection_delay,
+ reconnection_delay_max=reconnection_delay_max,
+ )
+ self.input_queues = {}
+ self.input_events = {}
+
+ @self.sio.on("connect", namespace=self._websocket_namespace)
+ def on_connect() -> None:
+ self._is_connected = True
+ logger.info(
+ 'Connected to AgentScope Studio with project name "%s" and '
+ 'run name "%s".',
+ self.studio_url,
+ run_id,
+ )
+ logger.info(
+ "View the run at: %s/dashboard/projects/%s",
+ self.studio_url,
+ _config.project,
+ )
+
+ @self.sio.on("disconnect", namespace=self._websocket_namespace)
+ def on_disconnect() -> None:
+ self._is_connected = False
+ logger.info(
+ "Disconnected from AgentScope Studio at %s",
+ self.studio_url,
+ )
+
+ @self.sio.on("reconnect", namespace=self._websocket_namespace)
+ def on_reconnect(attempt_number: int) -> None:
+ self._is_connected = True
+ self._is_reconnecting = False
+ logger.info(
+ "Reconnected to AgentScope Studio at %s with run_id %s after "
+ "%d attempts",
+ self.studio_url,
+ self.run_id,
+ attempt_number,
+ )
+
+ @self.sio.on("reconnect_attempt", namespace=self._websocket_namespace)
+ def on_reconnect_attempt(attempt_number: int) -> None:
+ self._is_reconnecting = True
+ logger.info(
+ "Attempting to reconnect to AgentScope Studio at %s "
+ "(attempt %d)",
+ self.studio_url,
+ attempt_number,
+ )
+
+ @self.sio.on("reconnect_failed", namespace=self._websocket_namespace)
+ def on_reconnect_failed() -> None:
+ self._is_reconnecting = False
+ logger.error(
+ "Failed to reconnect to AgentScope Studio at %s",
+ self.studio_url,
+ )
+
+ @self.sio.on("reconnect_error", namespace=self._websocket_namespace)
+ def on_reconnect_error(error: Any) -> None:
+ logger.error(
+ "Error while reconnecting to AgentScope Studio at %s: %s",
+ self.studio_url,
+ str(error),
+ )
+
+ # The AgentScope Studio backend send the "sendUserInput" event to
+ # the current python run
+ @self.sio.on("forwardUserInput", namespace=self._websocket_namespace)
+ def receive_user_input(
+ request_id: str,
+ blocks_input: List[
+ TextBlock | ImageBlock | AudioBlock | VideoBlock
+ ],
+ structured_input: dict[str, Any],
+ ) -> None:
+ if request_id in self.input_queues:
+ self.input_queues[request_id].put(
+ UserInputData(
+ blocks_input=blocks_input,
+ structured_input=structured_input,
+ ),
+ )
+ self.input_events[request_id].set()
+
+ try:
+ self.sio.connect(
+ f"{self.studio_url}",
+ namespaces=["/python"],
+ auth={"run_id": self.run_id},
+ )
+ except Exception as e:
+ raise RuntimeError(
+ f"Failed to connect to AgentScope Studio at {self.studio_url}",
+ ) from e
+
+ def _ensure_connected(
+ self,
+ timeout: float = 30.0,
+ check_interval: float = 5.0,
+ ) -> None:
+ """Ensure the connection is established or wait for reconnection.
+
+ Args:
+ timeout (`float`):
+ Maximum time to wait for reconnection in seconds. Defaults
+ to 30.0.
+ check_interval (`float`):
+ Interval between connection checks in seconds. Defaults to 1.0.
+
+ Raises:
+ `RuntimeError`:
+ If connection cannot be established within timeout.
+ """
+ if self._is_connected:
+ return
+
+ if self._is_reconnecting:
+ start_time = time.time()
+ while self._is_reconnecting:
+ # Check timeout
+ elapsed_time = time.time() - start_time
+ if elapsed_time > timeout:
+ raise RuntimeError(
+ f"Reconnection timeout after {elapsed_time} seconds",
+ )
+
+ # Log status
+ logger.info(
+ "Waiting for reconnection... (%.1fs / %.1fs)",
+ elapsed_time,
+ timeout,
+ )
+
+ # Wait for next check
+ time.sleep(check_interval)
+
+ # After reconnection attempt completed, check final status
+ if self._is_connected:
+ return
+
+ # Not connected and not reconnecting
+ raise RuntimeError(
+ f"Not connected to AgentScope Studio at {self.studio_url}.",
+ )
+
+ async def __call__( # type: ignore[override]
+ self,
+ agent_id: str,
+ agent_name: str,
+ *args: Any,
+ structured_model: Type[BaseModel] | None = None,
+ ) -> UserInputData:
+ """Get the user input from AgentScope Studio.
+
+ Args:
+ agent_id (`str`):
+ The identity of the agent.
+ agent_name (`str`):
+ The name of the agent.
+ structured_model (`Type[BaseModel] | None`, optional):
+ The base model class of the structured input.
+
+ Raises:
+ `RuntimeError`:
+ Failed to get user input from AgentScope Studio.
+
+ Returns:
+ `UserInputData`:
+ The user input.
+ """
+ self._ensure_connected()
+
+ request_id = shortuuid.uuid()
+
+ self.input_queues[request_id] = Queue()
+ self.input_events[request_id] = Event()
+
+ if structured_model is None:
+ structured_input = None
+ else:
+ structured_input = structured_model.model_json_schema()
+
+ n_retry = 0
+ while True:
+ try:
+ response = requests.post(
+ f"{self.studio_url}/trpc/requestUserInput",
+ json={
+ "requestId": request_id,
+ "runId": self.run_id,
+ "agentId": agent_id,
+ "agentName": agent_name,
+ "structuredInput": structured_input,
+ },
+ )
+ response.raise_for_status()
+ break
+ except Exception as e:
+ if n_retry < self.max_retries:
+ n_retry += 1
+ continue
+
+ raise RuntimeError(
+ "Failed to get user input from AgentScope Studio",
+ ) from e
+
+ try:
+ self.input_events[request_id].wait()
+ response_data = self.input_queues[request_id].get()
+ return response_data
+
+ finally:
+ self.input_queues.pop(request_id, None)
+ self.input_events.pop(request_id, None)
+
+ def __del__(self) -> None:
+ """Cleanup socket connection when object it destroyed"""
+ try:
+ self.sio.disconnect()
+ except Exception as e:
+ logger.error(
+ "Failed to disconnect from AgentScope Studio at %s: %s",
+ self.studio_url,
+ str(e),
+ )
diff --git a/src/agentscope/embedding/__init__.py b/src/agentscope/embedding/__init__.py
new file mode 100644
index 000000000..8e667b7a8
--- /dev/null
+++ b/src/agentscope/embedding/__init__.py
@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""The embedding module in agentscope."""
+
+from ._embedding_base import EmbeddingModelBase
+from ._embedding_usage import EmbeddingUsage
+from ._embedding_response import EmbeddingResponse
+from ._dashscope_embedding import DashScopeTextEmbedding
+from ._openai_embedding import OpenAITextEmbedding
+from ._gemini_embedding import GeminiTextEmbedding
+from ._ollama_embedding import OllamaTextEmbedding
+from ._cache_base import EmbeddingCacheBase
+from ._file_cache import FileEmbeddingCache
+
+
+__all__ = [
+ "EmbeddingModelBase",
+ "EmbeddingUsage",
+ "EmbeddingResponse",
+ "DashScopeTextEmbedding",
+ "OpenAITextEmbedding",
+ "GeminiTextEmbedding",
+ "OllamaTextEmbedding",
+ "EmbeddingCacheBase",
+ "FileEmbeddingCache",
+]
diff --git a/src/agentscope/embedding/_cache_base.py b/src/agentscope/embedding/_cache_base.py
new file mode 100644
index 000000000..da27b5b14
--- /dev/null
+++ b/src/agentscope/embedding/_cache_base.py
@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""The embedding cache base class."""
+from abc import abstractmethod
+from typing import List, Any
+
+from ..types import (
+ JSONSerializableObject,
+ Embedding,
+)
+
+
+class EmbeddingCacheBase:
+ """Base class for embedding caches, which is responsible for storing and
+ retrieving embeddings."""
+
+ @abstractmethod
+ async def store(
+ self,
+ embeddings: List[Embedding],
+ identifier: JSONSerializableObject,
+ overwrite: bool = False,
+ **kwargs: Any,
+ ) -> None:
+ """Store the embeddings with the given identifier.
+
+ Args:
+ embeddings (`List[Embedding]`):
+ The embeddings to store.
+ identifier (`JSONSerializableObject`):
+ The identifier to distinguish the embeddings.
+ overwrite (`bool`, defaults to `False`):
+ Whether to overwrite existing embeddings with the same
+ identifier. If `True`, existing embeddings will be replaced.
+ """
+
+ @abstractmethod
+ async def retrieve(
+ self,
+ identifier: JSONSerializableObject,
+ ) -> List[Embedding] | None:
+ """Retrieve the embeddings with the given identifier. If not
+ found, return `None`.
+
+ Args:
+ identifier (`JSONSerializableObject`):
+ The identifier to retrieve the embeddings.
+ """
+
+ @abstractmethod
+ async def remove(
+ self,
+ identifier: JSONSerializableObject,
+ ) -> None:
+ """Remove the embeddings with the given identifier.
+
+ Args:
+ identifier (`JSONSerializableObject`):
+ The identifier to remove the embeddings.
+ """
+
+ @abstractmethod
+ async def clear(self) -> None:
+ """Clear all cached embeddings."""
diff --git a/src/agentscope/embedding/_dashscope_embedding.py b/src/agentscope/embedding/_dashscope_embedding.py
new file mode 100644
index 000000000..ea771659d
--- /dev/null
+++ b/src/agentscope/embedding/_dashscope_embedding.py
@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""The dashscope embedding module in agentscope."""
+from datetime import datetime
+from typing import Any, List
+
+from ._cache_base import EmbeddingCacheBase
+from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from ._embedding_base import EmbeddingModelBase
+
+
+class DashScopeTextEmbedding(EmbeddingModelBase):
+ """DashScope text embedding model class"""
+
+ def __init__(
+ self,
+ api_key: str,
+ model_name: str,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ ) -> None:
+ """Initialize the DashScope text embedding model class.
+
+ Args:
+ api_key (`str`):
+ The dashscope API key.
+ model_name (`str`):
+ The name of the embedding model.
+ embedding_cache (`EmbeddingCacheBase`):
+ The embedding cache class instance, used to cache the
+ embedding results to avoid repeated API calls.
+ """
+ super().__init__(model_name)
+
+ self.api_key = api_key
+ self.embedding_cache = embedding_cache
+
+ async def __call__(
+ self,
+ text: List[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the DashScope embedding API.
+
+ Args:
+ text (`List[str]`):
+ The input text to be embedded. It can be a list of strings.
+ """
+
+ kwargs = {
+ "input": text,
+ "model": self.model_name,
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached_embeddings = await self.embedding_cache.retrieve(
+ identifier=kwargs,
+ )
+ if cached_embeddings:
+ return EmbeddingResponse(
+ embeddings=cached_embeddings,
+ usage=EmbeddingUsage(
+ tokens=0,
+ time=0,
+ ),
+ source="cache",
+ )
+
+ import dashscope
+
+ start_time = datetime.now()
+ response = dashscope.embeddings.TextEmbedding.call(
+ api_key=self.api_key,
+ **kwargs,
+ )
+ time = (datetime.now() - start_time).total_seconds()
+
+ if response.status_code != 200:
+ raise RuntimeError(
+ f"Failed to get embedding from DashScope API: {response}",
+ )
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=kwargs,
+ embeddings=[
+ _["embedding"] for _ in response.output["embeddings"]
+ ],
+ )
+
+ embedding_response = EmbeddingResponse(
+ embeddings=[_["embedding"] for _ in response.output["embeddings"]],
+ usage=EmbeddingUsage(
+ tokens=response.usage["total_tokens"],
+ time=time,
+ ),
+ )
+
+ return embedding_response
diff --git a/src/agentscope/embedding/_embedding_base.py b/src/agentscope/embedding/_embedding_base.py
new file mode 100644
index 000000000..1ac8634fd
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_base.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The embedding model base class."""
+from typing import Any, List, TYPE_CHECKING
+
+from ._embedding_response import EmbeddingResponse
+
+if TYPE_CHECKING:
+ from ..model import ChatResponse
+else:
+ ChatResponse = "ChatResponse"
+
+
+class EmbeddingModelBase:
+ """Base class for embedding models."""
+
+ model_name: str
+ """The embedding model name"""
+
+ def __init__(
+ self,
+ model_name: str,
+ ) -> None:
+ """Initialize the embedding model base class.
+
+ Args:
+ model_name (`str`):
+ The name of the embedding model.
+ """
+ self.model_name = model_name
+
+ async def __call__(
+ self,
+ text: List[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the embedding API with the given arguments."""
+ raise NotImplementedError(
+ f"The {self.__class__.__name__} class does not implement "
+ f"the __call__ method.",
+ )
diff --git a/src/agentscope/embedding/_embedding_response.py b/src/agentscope/embedding/_embedding_response.py
new file mode 100644
index 000000000..1a026bfbf
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_response.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""The embedding response class."""
+from dataclasses import dataclass, field
+from typing import Literal, List
+
+from ._embedding_usage import EmbeddingUsage
+from .._utils._common import _get_timestamp
+from .._utils._mixin import DictMixin
+from ..types import Embedding
+
+
+@dataclass
+class EmbeddingResponse(DictMixin):
+ """The embedding response class."""
+
+ embeddings: List[Embedding]
+ """The embedding data"""
+
+ id: str = field(default_factory=lambda: _get_timestamp(True))
+ """The identity of the embedding response"""
+
+ created_at: str = field(default_factory=_get_timestamp)
+ """The timestamp of the embedding response creation"""
+
+ type: Literal["embedding"] = field(default_factory=lambda: "embedding")
+ """The type of the response, must be `embedding`."""
+
+ usage: EmbeddingUsage | None = field(default_factory=lambda: None)
+ """The usage of the embedding model API invocation, if available."""
+
+ source: Literal["cache", "api"] = field(default_factory=lambda: "api")
+ """If the response comes from the cache or the API."""
diff --git a/src/agentscope/embedding/_embedding_usage.py b/src/agentscope/embedding/_embedding_usage.py
new file mode 100644
index 000000000..3f3cb678b
--- /dev/null
+++ b/src/agentscope/embedding/_embedding_usage.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The embedding usage class in agentscope."""
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .._utils._mixin import DictMixin
+
+
+@dataclass
+class EmbeddingUsage(DictMixin):
+ """The usage of an embedding model API invocation."""
+
+ time: float
+ """The time used in seconds."""
+
+ tokens: int | None = field(default_factory=lambda: None)
+ """The number of tokens used, if available."""
+
+ type: Literal["embedding"] = field(default_factory=lambda: "embedding")
+ """The type of the usage, must be `embedding`."""
diff --git a/src/agentscope/embedding/_file_cache.py b/src/agentscope/embedding/_file_cache.py
new file mode 100644
index 000000000..11b6f8dba
--- /dev/null
+++ b/src/agentscope/embedding/_file_cache.py
@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""A file embedding cache implementation for storing and retrieving
+embeddings in binary files."""
+import hashlib
+import json
+import os
+from typing import Any, List
+
+import numpy as np
+
+from ._cache_base import EmbeddingCacheBase
+from .._logging import logger
+from ..types import (
+ Embedding,
+ JSONSerializableObject,
+)
+
+
+class FileEmbeddingCache(EmbeddingCacheBase):
+ """The embedding cache class that stores each embeddings vector in
+ binary files."""
+
+ def __init__(
+ self,
+ cache_dir: str = "./.cache/embeddings",
+ max_file_number: int | None = None,
+ max_cache_size: int | None = None,
+ ) -> None:
+ """Initialize the file embedding cache class.
+
+ Args:
+ cache_dir (`str`, defaults to `"./.cache/embeddings"`):
+ The directory to store the embedding files.
+ max_file_number (`int | None`, defaults to `None`):
+ The maximum number of files to keep in the cache directory. If
+ exceeded, the oldest files will be removed.
+ max_cache_size (`int | None`, defaults to `None`):
+ The maximum size of the cache directory in MB. If exceeded,
+ the oldest files will be removed until the size is within the
+ limit.
+ """
+ self._cache_dir = os.path.abspath(cache_dir)
+ self.max_file_number = max_file_number
+ self.max_cache_size = max_cache_size
+
+ @property
+ def cache_dir(self) -> str:
+ """The cache directory where the embedding files are stored."""
+ if not os.path.exists(self._cache_dir):
+ os.makedirs(self._cache_dir, exist_ok=True)
+ return self._cache_dir
+
+ async def store(
+ self,
+ embeddings: List[Embedding],
+ identifier: JSONSerializableObject,
+ overwrite: bool = False,
+ **kwargs: Any,
+ ) -> None:
+ """Store the embeddings with the given identifier.
+
+ Args:
+ embeddings (`List[Embedding]`):
+ The embeddings to store.
+ identifier (`JSONSerializableObject`):
+ The identifier to distinguish the embeddings, which will be
+ used to generate a hashable filename, so it should be
+ JSON serializable (e.g. a string, number, list, dict).
+ overwrite (`bool`, defaults to `False`):
+ Whether to overwrite existing embeddings with the same
+ identifier. If `True`, existing embeddings will be replaced.
+ """
+ filename = self._get_filename(identifier)
+ path_file = os.path.join(self.cache_dir, filename)
+
+ if os.path.exists(path_file):
+ if not os.path.isfile(path_file):
+ raise RuntimeError(
+ f"Path {path_file} exists but is not a file.",
+ )
+
+ if overwrite:
+ np.save(path_file, embeddings)
+ await self._maintain_cache_dir()
+ else:
+ np.save(path_file, embeddings)
+ await self._maintain_cache_dir()
+
+ async def retrieve(
+ self,
+ identifier: JSONSerializableObject,
+ ) -> List[Embedding] | None:
+ """Retrieve the embeddings with the given identifier. If not found,
+ return `None`.
+
+ Args:
+ identifier (`JSONSerializableObject`):
+ The identifier to retrieve the embeddings, which will be
+ used to generate a hashable filename, so it should be
+ JSON serializable (e.g. a string, number, list, dict).
+ """
+ filename = self._get_filename(identifier)
+ path_file = os.path.join(self.cache_dir, filename)
+
+ if os.path.exists(path_file):
+ return np.load(os.path.join(self.cache_dir, filename)).tolist()
+ return None
+
+ async def remove(self, identifier: JSONSerializableObject) -> None:
+ """Remove the embeddings with the given identifier.
+
+ Args:
+ identifier (`JSONSerializableObject`):
+ The identifiers to remove the embeddings, which will be
+ used to generate a hashable filename, so it should be
+ JSON serializable (e.g. a string, number, list, dict).
+ """
+ filename = self._get_filename(identifier)
+ path_file = os.path.join(self.cache_dir, filename)
+
+ if os.path.exists(path_file):
+ os.remove(path_file)
+ else:
+ raise FileNotFoundError(f"File {path_file} does not exist.")
+
+ async def clear(self) -> None:
+ """Clear the cache directory by removing all files."""
+ for filename in os.listdir(self.cache_dir):
+ if filename.endswith(".npy"):
+ os.remove(os.path.join(self.cache_dir, filename))
+
+ def _get_cache_size(self) -> float:
+ """Get the current size of the cache directory in MB."""
+ total_size = 0
+ for filename in os.listdir(self.cache_dir):
+ if filename.endswith(".npy"):
+ path_file = os.path.join(self.cache_dir, filename)
+ if os.path.isfile(path_file):
+ total_size += os.path.getsize(path_file)
+ return total_size / (1024.0 * 1024.0)
+
+ @staticmethod
+ def _get_filename(identifier: JSONSerializableObject) -> str:
+ """Generate a filename based on the identifier."""
+ json_str = json.dumps(identifier, ensure_ascii=False)
+ return hashlib.sha256(json_str.encode("utf-8")).hexdigest() + ".npy"
+
+ async def _maintain_cache_dir(self) -> None:
+ """Maintain the cache directory by removing old files if the number of
+ files exceeds the maximum limit or if the cache size exceeds the
+ maximum size."""
+ files = [
+ (_.name, _.stat().st_mtime)
+ for _ in os.scandir(self.cache_dir)
+ if _.is_file() and _.name.endswith(".npy")
+ ]
+ files.sort(key=lambda x: x[1])
+
+ if self.max_file_number and len(files) > self.max_file_number:
+ for file_name, _ in files[: 0 - self.max_file_number]:
+ os.remove(os.path.join(self.cache_dir, file_name))
+ logger.info(
+ "Remove cached embedding file %s for limited number "
+ "of files (%d).",
+ file_name,
+ self.max_file_number,
+ )
+ files = files[0 - self.max_file_number :]
+
+ if (
+ self.max_cache_size is not None
+ and self._get_cache_size() > self.max_cache_size
+ ):
+ removed_files = []
+ for filename, _ in files:
+ os.remove(os.path.join(self.cache_dir, filename))
+ removed_files.append(filename)
+ if self._get_cache_size() <= self.max_cache_size:
+ break
+
+ if removed_files:
+ logger.info(
+ "Remove %d cached embedding file(s) for limited "
+ "cache size (%d MB).",
+ len(removed_files),
+ self.max_cache_size,
+ )
diff --git a/src/agentscope/embedding/_gemini_embedding.py b/src/agentscope/embedding/_gemini_embedding.py
new file mode 100644
index 000000000..15ea8ee34
--- /dev/null
+++ b/src/agentscope/embedding/_gemini_embedding.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""The gemini text embedding model class."""
+from datetime import datetime
+from typing import Any, List
+
+from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from ._cache_base import EmbeddingCacheBase
+from ._embedding_base import EmbeddingModelBase
+
+
+class GeminiTextEmbedding(EmbeddingModelBase):
+ """The Gemini text embedding model."""
+
+ def __init__(
+ self,
+ api_key: str,
+ model_name: str,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the Gemini text embedding model class.
+
+ Args:
+ api_key (`str`):
+ The Gemini API key.
+ model_name (`str`):
+ The name of the embedding model.
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
+ The embedding cache class instance, used to cache the
+ embedding results to avoid repeated API calls.
+ """
+ from google import genai
+
+ super().__init__(model_name)
+
+ self.client = genai.Client(api_key=api_key, **kwargs)
+ self.embedding_cache = embedding_cache
+
+ async def __call__(
+ self,
+ text: List[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """The Gemini embedding API call.
+
+ Args:
+ text (`List[str]`):
+ The input text to be embedded. It can be a list of strings.
+ """
+ kwargs = {
+ "model": self.model_name,
+ "contents": text,
+ "config": kwargs,
+ }
+
+ if self.embedding_cache:
+ cached_embeddings = await self.embedding_cache.retrieve(
+ identifier=kwargs,
+ )
+ if cached_embeddings:
+ return EmbeddingResponse(
+ embeddings=cached_embeddings,
+ usage=EmbeddingUsage(
+ tokens=0,
+ time=0,
+ ),
+ source="cache",
+ )
+
+ start_time = datetime.now()
+ response = self.client.models.embed_content(**kwargs)
+ time = (datetime.now() - start_time).total_seconds()
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=kwargs,
+ embeddings=[_.values for _ in response.embeddings],
+ )
+
+ return EmbeddingResponse(
+ embeddings=[_.values for _ in response.embeddings],
+ usage=EmbeddingUsage(
+ time=time,
+ ),
+ )
diff --git a/src/agentscope/embedding/_ollama_embedding.py b/src/agentscope/embedding/_ollama_embedding.py
new file mode 100644
index 000000000..7a913ffca
--- /dev/null
+++ b/src/agentscope/embedding/_ollama_embedding.py
@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""The ollama text embedding model class."""
+import asyncio
+from datetime import datetime
+from typing import List, Any
+
+from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from ._cache_base import EmbeddingCacheBase
+from ..embedding import EmbeddingModelBase
+
+
+class OllamaTextEmbedding(EmbeddingModelBase):
+ """The Ollama embedding model."""
+
+ def __init__(
+ self,
+ model_name: str,
+ host: str | None = None,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the Ollama text embedding model class.
+
+ Args:
+ model_name (`str`):
+ The name of the embedding model.
+ host (`str | None`, defaults to `None`):
+ The host URL for the Ollama API.
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
+ The embedding cache class instance, used to cache the
+ embedding results to avoid repeated API calls.
+ """
+ import ollama
+
+ super().__init__(model_name)
+
+ self.client = ollama.AsyncClient(host=host, **kwargs)
+ self.embedding_cache = embedding_cache
+
+ async def __call__(
+ self,
+ text: List[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the Ollama embedding API.
+
+ Args:
+ text (`List[str]`):
+ The input text to be embedded. It can be a list of strings.
+ """
+
+ if self.embedding_cache:
+ cached_embeddings = await self.embedding_cache.retrieve(
+ identifier=kwargs,
+ )
+ if cached_embeddings:
+ return EmbeddingResponse(
+ embeddings=cached_embeddings,
+ usage=EmbeddingUsage(
+ tokens=0,
+ time=0,
+ ),
+ source="cache",
+ )
+
+ start_time = datetime.now()
+ response = await asyncio.gather(
+ *[
+ self.client.embeddings(self.model_name, _, **kwargs)
+ for _ in text
+ ],
+ )
+ time = (datetime.now() - start_time).total_seconds()
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=kwargs,
+ embeddings=[_.embedding for _ in response],
+ )
+
+ return EmbeddingResponse(
+ embeddings=[_.embedding for _ in response],
+ usage=EmbeddingUsage(
+ time=time,
+ ),
+ )
diff --git a/src/agentscope/embedding/_openai_embedding.py b/src/agentscope/embedding/_openai_embedding.py
new file mode 100644
index 000000000..aa459365e
--- /dev/null
+++ b/src/agentscope/embedding/_openai_embedding.py
@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI text embedding model class."""
+from datetime import datetime
+from typing import Any, List
+
+from ._embedding_response import EmbeddingResponse
+from ._embedding_usage import EmbeddingUsage
+from ._cache_base import EmbeddingCacheBase
+from ._embedding_base import EmbeddingModelBase
+
+
+class OpenAITextEmbedding(EmbeddingModelBase):
+ """OpenAI text embedding model class."""
+
+ def __init__(
+ self,
+ api_key: str,
+ model_name: str,
+ embedding_cache: EmbeddingCacheBase | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the OpenAI text embedding model class.
+
+ Args:
+ api_key (`str`):
+ The OpenAI API key.
+ model_name (`str`):
+ The name of the embedding model.
+ embedding_cache (`EmbeddingCacheBase | None`, defaults to `None`):
+ The embedding cache class instance, used to cache the
+ embedding results to avoid repeated API calls.
+ """
+ import openai
+
+ super().__init__(model_name)
+
+ self.client = openai.AsyncClient(api_key=api_key, **kwargs)
+ self.embedding_cache = embedding_cache
+
+ async def __call__(
+ self,
+ text: List[str],
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """Call the OpenAI embedding API.
+
+ Args:
+ text (`List[str]`):
+ The input text to be embedded. It can be a list of strings.
+ """
+
+ kwargs = {
+ "input": text,
+ "model": self.model_name,
+ "encoding_format": "float",
+ **kwargs,
+ }
+
+ if self.embedding_cache:
+ cached_embeddings = await self.embedding_cache.retrieve(
+ identifier=kwargs,
+ )
+ if cached_embeddings:
+ return EmbeddingResponse(
+ embeddings=cached_embeddings,
+ usage=EmbeddingUsage(
+ tokens=0,
+ time=0,
+ ),
+ source="cache",
+ )
+
+ start_time = datetime.now()
+ response = await self.client.embeddings.create(**kwargs)
+ time = (datetime.now() - start_time).total_seconds()
+
+ if self.embedding_cache:
+ await self.embedding_cache.store(
+ identifier=kwargs,
+ embeddings=[_.embedding for _ in response.data],
+ )
+
+ return EmbeddingResponse(
+ embeddings=[_.embedding for _ in response.data],
+ usage=EmbeddingUsage(
+ tokens=response.usage.total_tokens,
+ time=time,
+ ),
+ )
diff --git a/src/agentscope/evaluate/__init__.py b/src/agentscope/evaluate/__init__.py
new file mode 100644
index 000000000..2f9aabd6f
--- /dev/null
+++ b/src/agentscope/evaluate/__init__.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""The evaluation module in AgentScope."""
+
+from ._evaluator import (
+ EvaluatorBase,
+ RayEvaluator,
+ GeneralEvaluator,
+)
+from ._metric_base import (
+ MetricBase,
+ MetricResult,
+ MetricType,
+)
+from ._task import Task
+from ._solution import SolutionOutput
+from ._benchmark_base import BenchmarkBase
+from ._evaluator_storage import (
+ EvaluatorStorageBase,
+ FileEvaluatorStorage,
+)
+from ._ace_benchmark import (
+ ACEBenchmark,
+ ACEAccuracy,
+ ACEProcessAccuracy,
+ ACEPhone,
+)
+
+__all__ = [
+ "BenchmarkBase",
+ "EvaluatorBase",
+ "RayEvaluator",
+ "GeneralEvaluator",
+ "MetricBase",
+ "MetricResult",
+ "MetricType",
+ "EvaluatorStorageBase",
+ "FileEvaluatorStorage",
+ "Task",
+ "SolutionOutput",
+ "ACEBenchmark",
+ "ACEAccuracy",
+ "ACEProcessAccuracy",
+ "ACEPhone",
+]
diff --git a/src/agentscope/evaluate/_ace_benchmark/__init__.py b/src/agentscope/evaluate/_ace_benchmark/__init__.py
new file mode 100644
index 000000000..28010693c
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/__init__.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The ACE benchmark related implementations in AgentScope."""
+
+from ._ace_benchmark import ACEBenchmark
+from ._ace_metric import (
+ ACEAccuracy,
+ ACEProcessAccuracy,
+)
+from ._ace_tools_zh import ACEPhone
+
+__all__ = [
+ "ACEBenchmark",
+ "ACEPhone",
+ "ACEAccuracy",
+ "ACEProcessAccuracy",
+]
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_benchmark.py b/src/agentscope/evaluate/_ace_benchmark/_ace_benchmark.py
new file mode 100644
index 000000000..2c88df19f
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_benchmark.py
@@ -0,0 +1,240 @@
+# -*- coding: utf-8 -*-
+"""The ACE benchmark class in agentscope. The code is implemented with
+reference to the `ACEBench <https://github.com/ACEBench/ACEBench>`_
+under the MIT license."""
+import json
+import os
+from typing import Generator
+
+import json5
+import requests
+from tqdm import tqdm
+
+from ._ace_metric import ACEAccuracy, ACEProcessAccuracy
+from ._ace_tools_zh import ACEPhone
+from .._benchmark_base import BenchmarkBase
+from .._task import Task
+
+
+class ACEBenchmark(BenchmarkBase):
+ """The ACE benchmark for evaluating AI agents."""
+
+ data_dir_url: str = (
+ "https://raw.githubusercontent.com/ACEBench/ACEBench/main/data_all"
+ )
+ """The URL to the data dir"""
+
+ data_subdir: list[str] = [
+ # "data_en", # TODO: enable English version
+ "data_zh",
+ ]
+
+ ground_truth_dir: str = "possible_answer"
+
+ data_files: list[str] = [
+ "data_agent_multi_step.json",
+ "data_agent_multi_turn.json",
+ # "data_normal_atom_bool.json",
+ # "data_normal_atom_enum.json",
+ # "data_normal_atom_list.json",
+ # "data_normal_atom_number.json",
+ # "data_normal_atom_object_deep.json",
+ # "data_normal_atom_object_short.json",
+ #
+ # "data_normal_multi_turn_user_adjust.json",
+ # "data_normal_multi_turn_user_switch.json",
+ #
+ # "data_normal_preference.json",
+ # "data_normal_similar_api.json",
+ # "data_normal_single_turn_parallel_function.json",
+ # "data_normal_single_turn_single_function.json",
+ #
+ # "data_special_error_param.json",
+ # "data_special_incomplete.json",
+ # "data_special_irrelevant.json",
+ ]
+ """The data filenames"""
+
+ def __init__(
+ self,
+ data_dir: str,
+ ) -> None:
+ """Initialize the ACEBenchmark
+
+ Args:
+ data_dir (`str`):
+ The directory where the dataset is downloaded and saved.
+ """
+ super().__init__(
+ name="ACEBench",
+ description="The ACE benchmark for evaluating AI agents.",
+ )
+
+ self.data_dir = os.path.abspath(data_dir)
+
+ if os.path.exists(data_dir) and not os.path.isdir(data_dir):
+ raise RuntimeError(
+ f"The data_dir `{data_dir}` is not a valid directory path.",
+ )
+
+ os.makedirs(data_dir, exist_ok=True)
+
+ if not self._verify_data():
+ self._download_data()
+
+ self.dataset = self._load_data()
+
+ def _load_data(self) -> list[dict]:
+ """Load the dataset from the data directory."""
+ dataset = []
+ for subdir in self.data_subdir:
+ for filename in self.data_files:
+ file_path = os.path.join(self.data_dir, subdir, filename)
+
+ gt_path = os.path.join(
+ self.data_dir,
+ subdir,
+ self.ground_truth_dir,
+ filename,
+ )
+ gt_dataset = {}
+ with open(gt_path, "r", encoding="utf-8") as gt_file:
+ for line in gt_file:
+ gt_data = json5.loads(line)
+ gt_dataset[gt_data["id"]] = gt_data
+
+ with open(file_path, "r", encoding="utf-8") as f:
+ for line in f:
+ data = json5.loads(line)
+ gt = gt_dataset[data["id"]]
+ gt.pop("id", None)
+ data["ground_truth"] = gt["ground_truth"]
+ data["mile_stone"] = gt["mile_stone"]
+ data["language"] = subdir.rsplit(
+ "_",
+ maxsplit=1,
+ )[-1]
+ data["tags"] = {
+ "language": data["language"],
+ "category": filename.split(
+ ".",
+ maxsplit=1,
+ )[0].removeprefix(
+ "data_",
+ ),
+ }
+ dataset.append(data)
+
+ return dataset
+
+ def _verify_data(self) -> bool:
+ """Verify the data completeness and integrity."""
+ for subdir in self.data_subdir:
+ for filename in self.data_files:
+ file_path = os.path.join(self.data_dir, subdir, filename)
+ if not os.path.exists(file_path):
+ return False
+
+ gt_path = os.path.join(
+ self.data_dir,
+ subdir,
+ self.ground_truth_dir,
+ filename,
+ )
+ if not os.path.exists(gt_path):
+ return False
+
+ return True
+
+ def _download_data(self) -> None:
+ """Download the data from the URL"""
+ for subdir in self.data_subdir:
+ subdir_path = os.path.join(self.data_dir, subdir)
+ subdir_gt_path = os.path.join(subdir_path, self.ground_truth_dir)
+ os.makedirs(subdir_path, exist_ok=True)
+ os.makedirs(subdir_gt_path, exist_ok=True)
+ for filename in tqdm(
+ self.data_files,
+ desc=f"Downloading {subdir}",
+ ):
+ response = requests.get(
+ f"{self.data_dir_url}/{subdir}/{filename}",
+ )
+ response.raise_for_status()
+ with open(os.path.join(subdir_path, filename), "wb") as f:
+ f.write(response.content)
+
+ gt_response = requests.get(
+ f"{self.data_dir_url}/{subdir}/"
+ f"{self.ground_truth_dir}/{filename}",
+ )
+ gt_response.raise_for_status()
+ with open(os.path.join(subdir_gt_path, filename), "wb") as f:
+ f.write(gt_response.content)
+
+ @staticmethod
+ def _data_to_task(item: dict) -> Task:
+ """Convert a dataset item to a Task object."""
+ # Start the simulated phone and load initial configuration
+ ace_phone = ACEPhone()
+ ace_phone.load_initial_config(item["initial_config"])
+
+ # Obtain tool functions
+ tools: list[tuple] = []
+ for function_schema in item["function"]:
+ name = function_schema["name"]
+
+ # Handle the schema differences
+ formatted_schema = json.loads(
+ json.dumps(
+ function_schema,
+ ).replace(
+ '"type": "dict"',
+ '"type": "object"',
+ ),
+ )
+
+ tool_function = ace_phone.get_tool_function(name)
+ tools.append(
+ (
+ tool_function,
+ {
+ "type": "function",
+ "function": formatted_schema,
+ },
+ ),
+ )
+
+ return Task(
+ id=item["id"],
+ input=item["question"],
+ ground_truth={
+ "state": item["ground_truth"],
+ "mile_stone": item.get("mile_stone", []),
+ },
+ tags=item.get("tags", {}),
+ metrics=[
+ ACEAccuracy(item["ground_truth"]),
+ ACEProcessAccuracy(item["mile_stone"]),
+ ],
+ metadata={
+ # The phone is used to extract the final state after finishing
+ # the task.
+ "phone": ace_phone,
+ # The provided tools for this task, used to equip the agent
+ "tools": tools,
+ },
+ )
+
+ def __iter__(self) -> Generator[Task, None, None]:
+ """Iterate over the benchmark."""
+ for item in self.dataset:
+ yield self._data_to_task(item)
+
+ def __getitem__(self, index: int) -> Task:
+ """Get a task by index."""
+ return self._data_to_task(self.dataset[index])
+
+ def __len__(self) -> int:
+ """Get the length of the benchmark."""
+ return len(self.dataset)
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_metric.py b/src/agentscope/evaluate/_ace_benchmark/_ace_metric.py
new file mode 100644
index 000000000..d25b15263
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_metric.py
@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""The ACE benchmark metric implementations in AgentScope."""
+
+from .._solution import SolutionOutput
+from .._metric_base import MetricBase, MetricResult, MetricType
+
+
+class ACEProcessAccuracy(MetricBase):
+ """The ace benchmark process accuracy metric."""
+
+ def __init__(
+ self,
+ mile_stone: list[str],
+ ) -> None:
+ """Initialize the AceBench process accuracy metric."""
+ super().__init__(
+ name="process_accuracy",
+ metric_type=MetricType.NUMERICAL,
+ description="The AceBench Agent eval process accuracy metric.",
+ )
+ self.mile_stone = mile_stone
+
+ def __call__(
+ self,
+ solution: SolutionOutput,
+ ) -> MetricResult:
+ """Calculate the metric result."""
+
+ # Turn the tool use block sequence into ACEBench format
+ # e.g. func(arg1='dfd', arg2=44)
+ gathered_trajectory = []
+ for tool_call in solution.trajectory:
+ if tool_call.get("type") == "tool_use":
+ function_name = tool_call.get("name")
+ kwargs = tool_call.get("input")
+
+ gathered_kwargs = []
+ for key, value in kwargs.items():
+ if isinstance(value, str):
+ gathered_kwargs.append(
+ f"{key}='{value}'",
+ )
+
+ else:
+ gathered_kwargs.append(
+ f"{key}={value}",
+ )
+
+ kwargs_str = ", ".join(gathered_kwargs)
+ gathered_trajectory.append(
+ f"[{function_name}({kwargs_str})]",
+ )
+
+ for stone in self.mile_stone:
+ if stone not in gathered_trajectory:
+ return MetricResult(
+ name=self.name,
+ result=0,
+ message=f"Error: Missing milestone '{stone}' in "
+ "the given trajectory.",
+ )
+
+ return MetricResult(
+ name=self.name,
+ result=1,
+ message="Success",
+ )
+
+
+class ACEAccuracy(MetricBase):
+ """The ace benchmark metric"""
+
+ def __init__(
+ self,
+ state: list[dict],
+ ) -> None:
+ """Initialize the _metric object."""
+ super().__init__(
+ "accuracy",
+ MetricType.NUMERICAL,
+ "The AceBench Agent eval accuracy metric.",
+ )
+ self.state = state
+
+ def __call__(
+ self,
+ solution: SolutionOutput,
+ ) -> MetricResult:
+ """Calculate the metric result."""
+ # Check if the solution matches the ground truth
+ if not isinstance(solution.output, list):
+ raise ValueError("Ground truth state must be a list.")
+
+ # Handle the typos in ACEBench dataset
+ gathered_state = {}
+ for item in self.state:
+ for key, value in item.items():
+ if key.endswith("API"):
+ key = key.replace("API", "Api")
+ elif key.endswith("rpi"):
+ key = key.replace("pi", "Api")
+ gathered_state[key] = value
+
+ gathered_output = {}
+ for item in solution.output:
+ for key, value in item.items():
+ gathered_output[key] = value
+
+ if not set(gathered_state.keys()).issubset(gathered_output.keys()):
+ raise ValueError(
+ "Missing keys in solution output compared to state, "
+ f"ground truth keys: {gathered_state.keys()}, "
+ f"solution keys: {gathered_output.keys()}",
+ )
+
+ for key, value in gathered_state.items():
+ if value != gathered_output.get(key):
+ return MetricResult(
+ name=self.name,
+ result=0,
+ message=(
+ f"Error: Mismatch in key '{key}':"
+ f"\n{value}\n{gathered_output.get(key)}"
+ ),
+ )
+
+ return MetricResult(
+ name=self.name,
+ result=1,
+ message="Success: All keys match",
+ )
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/__init__.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/__init__.py
new file mode 100644
index 000000000..5755314ca
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/__init__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The ACEBench simulation tools in AgentScope."""
+
+from ._message_api import MessageApi
+from ._travel_api import TravelApi
+from ._reminder_api import ReminderApi
+from ._food_platform_api import FoodPlatformApi
+
+__all__ = [
+ "MessageApi",
+ "TravelApi",
+ "ReminderApi",
+ "FoodPlatformApi",
+]
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_food_platform_api.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_food_platform_api.py
new file mode 100644
index 000000000..be231644c
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_food_platform_api.py
@@ -0,0 +1,302 @@
+# -*- coding: utf-8 -*-
+"""The food platform API in the ACEBench evaluation."""
+
+from ._shared_state import SharedState
+
+
+class FoodPlatformApi(SharedState):
+ """The food platform Api in the ACEBench evaluation."""
+
+ tool_functions: list[str] = [
+ "login_food_platform",
+ "view_logged_in_users",
+ "check_balance",
+ "add_food_delivery_order",
+ "get_products",
+ "view_orders",
+ "search_orders",
+ ]
+
+ def __init__(self, shared_state: dict) -> None:
+ super().__init__(shared_state)
+
+ # 设置用户和初始金额
+ self.users: dict = {
+ "Eve": {
+ "user_id": "U100",
+ "password": "password123",
+ "balance": 500.0,
+ },
+ "Frank": {
+ "user_id": "U101",
+ "password": "password456",
+ "balance": 300.0,
+ },
+ "Grace": {
+ "user_id": "U102",
+ "password": "password789",
+ "balance": 150.0,
+ },
+ "Helen": {
+ "user_id": "U103",
+ "password": "password321",
+ "balance": 800.0,
+ },
+ "Isaac": {
+ "user_id": "U104",
+ "password": "password654",
+ "balance": 400.0,
+ },
+ "Jack": {
+ "user_id": "U105",
+ "password": "password654",
+ "balance": 120.0,
+ },
+ }
+
+ # 设置六个商家及其菜单
+ self.merchant_list: dict[str, dict] = {
+ "达美乐": {
+ "merchant_id": "M100",
+ "service_type": "Pizza",
+ "menu": [
+ {"product": "玛格丽特披萨", "price": 68.0},
+ {"product": "超级至尊披萨", "price": 88.0},
+ ],
+ },
+ "米村拌饭": {
+ "merchant_id": "M101",
+ "service_type": "Bibimbap",
+ "menu": [
+ {"product": "石锅拌饭", "price": 35.0},
+ {"product": "韩式牛肉拌饭", "price": 45.0},
+ ],
+ },
+ "海底捞": {
+ "merchant_id": "M102",
+ "service_type": "Hotpot",
+ "menu": [
+ {"product": "牛肉卷", "price": 68.0},
+ {"product": "海鲜拼盘", "price": 88.0},
+ ],
+ },
+ "喜茶": {
+ "merchant_id": "M103",
+ "service_type": "Milk Tea",
+ "menu": [
+ {"product": "芝士奶茶", "price": 25.0},
+ {"product": "四季春奶茶", "price": 22.0},
+ ],
+ },
+ "盒马生鲜": {
+ "merchant_id": "M104",
+ "service_type": "Fresh Grocery",
+ "menu": [
+ {"product": "有机蔬菜包", "price": 15.0},
+ {"product": "生鲜大礼包", "price": 99.0},
+ ],
+ },
+ "九田家烤肉": {
+ "merchant_id": "M105",
+ "service_type": "BBQ",
+ "menu": [
+ {"product": "韩式烤牛肉", "price": 128.0},
+ {"product": "烤五花肉", "price": 78.0},
+ ],
+ },
+ }
+
+ # 设置已登录用户列表
+ self.logged_in_users: list[str] = []
+ # 订单列表
+ self.orders: list = []
+
+ def get_state_dict(self) -> dict:
+ """Get the current state dict of the FoodPlatformApi."""
+ return {
+ "FoodPlatform": {
+ "logged_in_users": self.logged_in_users,
+ "orders": self.orders,
+ "users": self.users,
+ },
+ }
+
+ def login_food_platform(
+ self,
+ username: str,
+ password: str,
+ ) -> dict[str, bool | str]:
+ """使用用户名和密码登录外卖平台。
+
+ Args:
+ username (`str`):
+ 用户的用户名。
+ password (`str`):
+ 用户的密码。
+ """
+ if not self.wifi:
+ return {"status": False, "message": "wifi未打开,无法登录"}
+ if username not in self.users:
+ return {"status": False, "message": "用户不存在"}
+ if self.users[username]["password"] != password:
+ return {"status": False, "message": "密码错误"}
+
+ # 检查是否已经有用户登录
+ if username in self.logged_in_users:
+ return {"status": False, "message": f"{username} 已经登录"}
+
+ # 记录已登录用户
+ self.logged_in_users.append(username)
+ return {"status": True, "message": f"用户{username}登陆成功!"}
+
+ def view_logged_in_users(self) -> dict:
+ """查看当前所有登录的用户。"""
+ if not self.logged_in_users:
+ return {
+ "status": False,
+ "message": "当前没有登录food platform",
+ }
+
+ return {"status": True, "logged_in_users": self.logged_in_users}
+
+ def check_balance(self, user_name: str) -> float:
+ """查询指定用户的余额。
+
+ Args:
+ user_name (`str`):
+ 用户的用户名。
+ """
+ if user_name in self.users:
+ return self.users[user_name]["balance"]
+ else:
+ return 0.0
+
+ def add_food_delivery_order(
+ self,
+ username: str,
+ merchant_name: str,
+ items: list[dict[str, str | int]],
+ ) -> dict[str, bool | str]:
+ """订外卖
+
+ Args:
+ username (`str`):
+ 下订单的用户姓名。
+ merchant_name (`str`):
+ 下订单的商家名称。
+ items (`list[dict[str, str | int]]`):
+ 订单中商品的列表,每个商品包含名称和数量。
+ """
+ if username not in self.logged_in_users:
+ return {
+ "status": False,
+ "message": f"用户 {username} 未登录food platform",
+ }
+
+ if merchant_name not in self.merchant_list:
+ return {"status": False, "message": "商家不存在"}
+
+ total_price = 0.0
+ order_items = []
+
+ for item in items:
+ product_name = item.get("product")
+ quantity = item.get("quantity", 1)
+
+ if not isinstance(quantity, int) or quantity <= 0:
+ return {
+ "status": False,
+ "message": f"无效的数量 {quantity} 对于商品 {product_name}",
+ }
+
+ # 查找商品价格
+ product_found = False
+ for product in self.merchant_list[merchant_name]["menu"]:
+ if product["product"] == product_name:
+ total_price += product["price"] * quantity
+ order_items.append(
+ {
+ "product": product_name,
+ "quantity": quantity,
+ "price_per_unit": product["price"],
+ },
+ )
+ product_found = True
+ break
+ if not product_found:
+ return {
+ "status": False,
+ "message": f"商品 {product_name} 不存在于 "
+ f"{merchant_name} 的菜单中",
+ }
+
+ # 检查余额是否足够
+ if total_price >= self.users[username]["balance"]:
+ return {"status": False, "message": "余额不足,无法下单"}
+
+ # 扣除余额并创建订单
+ self.users[username]["balance"] -= total_price
+ order = {
+ "user_name": username,
+ "merchant_name": merchant_name,
+ "items": order_items,
+ "total_price": total_price,
+ }
+ self.orders.append(order)
+ return {
+ "status": True,
+ "message": f"外卖订单成功下单给 {merchant_name}," f"总金额为 {total_price} 元",
+ }
+
+ def get_products(
+ self,
+ merchant_name: str,
+ ) -> list[dict[str, str | float]] | dict[str, bool | str]:
+ """获取特定商家的商品列表。
+
+ Args:
+ merchant_name (`str`):
+ 要获取商品的商家名称。
+ """
+ merchant = self.merchant_list.get(merchant_name)
+ if merchant:
+ return merchant["menu"]
+ else:
+ return {
+ "status": False,
+ "message": f"商家 '{merchant_name}' 不存在",
+ }
+
+ def view_orders(
+ self,
+ user_name: str,
+ ) -> dict[str, bool | str | list[dict[str, str | int | float]]]:
+ """查看用户的所有订单"""
+ user_orders = [
+ order for order in self.orders if order["user_name"] == user_name
+ ]
+
+ if not user_orders:
+ return {"status": False, "message": "用户没有订单记录"}
+
+ return {"status": True, "orders": user_orders}
+
+ def search_orders(
+ self,
+ keyword: str,
+ ) -> dict[str, bool | str | list[dict[str, str | float]]]:
+ """根据关键字搜索订单。"""
+ matched_orders = [
+ order
+ for order in self.orders
+ if keyword.lower() in order["merchant_name"].lower()
+ or any(
+ keyword.lower() in item.lower()
+ for item in order.get("items", [])
+ )
+ ]
+
+ if not matched_orders:
+ return {"status": False, "message": "没有找到匹配的订单"}
+
+ return {"status": True, "orders": matched_orders}
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_message_api.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_message_api.py
new file mode 100644
index 000000000..c0c071298
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_message_api.py
@@ -0,0 +1,340 @@
+# -*- coding: utf-8 -*-
+"""The Message API in the ACEBench evaluation."""
+from datetime import datetime
+
+from ._shared_state import SharedState
+
+
+class MessageApi(SharedState):
+ """The message Api in the ACEBench evaluation."""
+
+ tool_functions: list[str] = [
+ "send_message",
+ "delete_message",
+ "view_messages_between_users",
+ "search_messages",
+ "get_all_message_times_with_ids",
+ "get_latest_message_id",
+ "get_earliest_message_id",
+ ]
+
+ def __init__(self, share_state: dict) -> None:
+ """Initialize the MessageApi with shared state."""
+ super().__init__(share_state)
+
+ # 设置六个用户
+ self.max_capacity = 6
+ self.user_list: dict[str, dict[str, str | int]] = {
+ "Eve": {
+ "user_id": "USR100",
+ "phone_number": "123-456-7890",
+ "occupation": "Software Engineer",
+ },
+ "Frank": {
+ "user_id": "USR101",
+ "phone_number": "234-567-8901",
+ "occupation": "Data Scientist",
+ },
+ "Grace": {
+ "user_id": "USR102",
+ "phone_number": "345-678-9012",
+ "occupation": "Product Manager",
+ },
+ "Helen": {
+ "user_id": "USR103",
+ "phone_number": "456-789-0123",
+ "occupation": "UX Designer",
+ },
+ "Isaac": {
+ "user_id": "USR104",
+ "phone_number": "567-890-1234",
+ "occupation": "DevOps Engineer",
+ },
+ "Jack": {
+ "user_id": "USR105",
+ "phone_number": "678-901-2345",
+ "occupation": "Marketing Specialist",
+ },
+ }
+
+ # 设置六个用户之间的短信记录
+ # 信息1和reminder配合 信息2和food配合
+ self.inbox: dict[int, dict[str, str | int]] = {
+ 1: {
+ "sender_id": "USR100",
+ "receiver_id": "USR101",
+ "message": "Hey Frank, don't forget about our meeting on "
+ "2024-06-11 at 4 PM in Conference Room 1.",
+ "time": "2024-06-09",
+ },
+ 2: {
+ "sender_id": "USR101",
+ "receiver_id": "USR102",
+ "message": """你能帮我点一个\"玛格丽特披萨\"的外卖吗,商家是达美乐。""",
+ "time": "2024-03-09",
+ },
+ 3: {
+ "sender_id": "USR102",
+ "receiver_id": "USR103",
+ "message": "帮我查一些喜茶有哪些奶茶外卖,买一杯便宜些的奶茶。"
+ "买完以后记得回复我,回复的内容是(已经买好了)",
+ "time": "2023-12-05",
+ },
+ 4: {
+ "sender_id": "USR103",
+ "receiver_id": "USR102",
+ "message": "No problem Helen, I can assist you.",
+ "time": "2024-09-09",
+ },
+ 5: {
+ "sender_id": "USR104",
+ "receiver_id": "USR105",
+ "message": "Isaac, are you available for a call?",
+ "time": "2024-06-06",
+ },
+ 6: {
+ "sender_id": "USR105",
+ "receiver_id": "USR104",
+ "message": "Yes Jack, let's do it in 30 minutes.",
+ "time": "2024-01-15",
+ },
+ }
+
+ self.message_id_counter: int = 6
+
+ def get_state_dict(self) -> dict:
+ """Get the current state dict of the MessageApi."""
+
+ # To avoid the error in ACEBench dataset
+ inbox_state = {}
+ for key, value in self.inbox.items():
+ inbox_state[str(key)] = value
+
+ return {
+ "MessageApi": {
+ "inbox": inbox_state,
+ },
+ }
+
+ def send_message(
+ self,
+ sender_name: str,
+ receiver_name: str,
+ message: str,
+ ) -> dict[str, bool | str]:
+ """将一条消息从一个用户发送给另一个用户。
+
+ Args:
+ sender_name (`str`):
+ 发送消息的用户姓名。
+ receiver_name (`str`):
+ 接收消息的用户姓名。
+ message (`str`):
+ 要发送的消息内容。
+ """
+ if not self.logged_in:
+ return {"status": False, "message": "device未登录,无法发送短信"}
+
+ if not self.wifi:
+ return {"status": False, "message": "wifi关闭,此时不能发送信息"}
+
+ if len(self.inbox) >= self.max_capacity:
+ return {
+ "status": False,
+ "message": "内存容量不够了,你需要询问user删除哪一条短信。",
+ }
+
+ # 验证发送者和接收者是否存在
+ if (
+ sender_name not in self.user_list
+ or receiver_name not in self.user_list
+ ):
+ return {"status": False, "message": "发送者或接收者不存在"}
+
+ sender_id = self.user_list[sender_name]["user_id"]
+ receiver_id = self.user_list[receiver_name]["user_id"]
+
+ # 将短信添加到inbox
+ self.message_id_counter += 1
+ self.inbox[self.message_id_counter] = {
+ "sender_id": sender_id,
+ "receiver_id": receiver_id,
+ "message": message,
+ }
+
+ return {"status": True, "message": f"短信成功发送给{receiver_name}。"}
+
+ def delete_message(self, message_id: int) -> dict[str, bool | str]:
+ """根据消息 ID 删除一条消息。
+
+ Args:
+ message_id (`int`):
+ 要删除的消息的 ID。
+ """
+ if not self.logged_in:
+ return {"status": False, "message": "device未登录,无法删除短信"}
+ if message_id not in self.inbox:
+ return {"status": False, "message": "短信ID不存在"}
+
+ del self.inbox[message_id]
+ return {"status": True, "message": f"短信ID {message_id} 已成功删除。"}
+
+ def view_messages_between_users(
+ self,
+ sender_name: str,
+ receiver_name: str,
+ ) -> dict:
+ """获取特定用户发送给另一个用户的所有消息。
+
+ Args:
+ sender_name (`str`):
+ 发送消息的用户姓名。
+ receiver_name (`str`):
+ 接收消息的用户姓名。
+ """
+ if not self.logged_in:
+ return {
+ "status": False,
+ "message": "device未登录,无法查看短信信息",
+ }
+
+ if sender_name not in self.user_list:
+ return {"status": False, "message": "发送者不存在"}
+
+ if receiver_name not in self.user_list:
+ return {"status": False, "message": "接收者不存在"}
+
+ sender_id = self.user_list[sender_name]["user_id"]
+ receiver_id = self.user_list[receiver_name]["user_id"]
+ messages_between_users = []
+
+ # 遍历 inbox,找出 sender_id 发送给 receiver_id 的短信
+ for msg_id, msg_data in self.inbox.items():
+ if (
+ msg_data["sender_id"] == sender_id
+ and msg_data["receiver_id"] == receiver_id
+ ):
+ messages_between_users.append(
+ {
+ "id": msg_id,
+ "sender": sender_name,
+ "receiver": receiver_name,
+ "message": msg_data["message"],
+ },
+ )
+
+ if not messages_between_users:
+ return {"status": False, "message": "没有找到相关的短信记录"}
+
+ return {"status": True, "messages": messages_between_users}
+
+ def search_messages(
+ self,
+ user_name: str,
+ keyword: str,
+ ) -> dict:
+ """搜索特定用户消息中包含特定关键字的消息。
+
+ Args:
+ user_name (`str`):
+ 要搜索消息的用户姓名。
+ keyword (`str`):
+ 要在消息中搜索的关键字。
+ """
+ if user_name not in self.user_list:
+ return {"status": False, "message": "用户不存在"}
+
+ user_id = self.user_list[user_name]["user_id"]
+ matched_messages = []
+
+ # 遍历 inbox,找到发送或接收中包含关键词的消息
+ for msg_id, msg_data in self.inbox.items():
+ if (
+ user_id in (msg_data["sender_id"], msg_data["receiver_id"])
+ and keyword.lower() in msg_data["message"].lower()
+ ):
+ matched_messages.append(
+ {
+ "id": msg_id,
+ "sender_id": msg_data["sender_id"],
+ "receiver_id": msg_data["receiver_id"],
+ "message": msg_data["message"],
+ },
+ )
+
+ if not matched_messages:
+ return {"status": False, "message": "没有找到包含关键词的短信"}
+
+ return {"status": True, "messages": matched_messages}
+
+ def get_all_message_times_with_ids(
+ self,
+ ) -> dict:
+ """获取所有短信的时间以及对应的短信编号。"""
+ if not self.logged_in:
+ return {
+ "status": False,
+ "message": "device未登录,获取所有短信的时间以及对应的短信编号。",
+ }
+ message_times_with_ids = {
+ msg_id: msg_data["time"] for msg_id, msg_data in self.inbox.items()
+ }
+ return message_times_with_ids
+
+ def get_latest_message_id(self) -> dict:
+ """获取最近发送的消息的 ID。"""
+ if not self.logged_in:
+ return {
+ "status": False,
+ "message": "device未登录,无法获取最新发送的短信ID。",
+ }
+ if not self.inbox:
+ return {"status": False, "message": "短信记录为空"}
+
+ # 遍历所有短信,找出时间最新的短信
+ latest_message_id = None
+ latest_time = None
+
+ for message_id, message_data in self.inbox.items():
+ message_time = datetime.strptime(
+ str(message_data["time"]),
+ "%Y-%m-%d",
+ )
+ if latest_time is None or message_time > latest_time:
+ latest_time = message_time
+ latest_message_id = message_id
+
+ return {
+ "status": True,
+ "message": f"最新的短信ID是 {latest_message_id}",
+ "message_id": latest_message_id,
+ }
+
+ def get_earliest_message_id(self) -> dict:
+ """获取最早发送的消息的 ID。"""
+ if not self.logged_in:
+ return {
+ "status": False,
+ "message": "device未登录,无法获取最早发送的短信ID",
+ }
+ if not self.inbox:
+ return {"status": False, "message": "短信记录为空"}
+
+ # 遍历所有短信,找出时间最早的短信
+ earliest_message_id = None
+ earliest_time = None
+
+ for message_id, message_data in self.inbox.items():
+ message_time = datetime.strptime(
+ str(message_data["time"]),
+ "%Y-%m-%d",
+ )
+ if earliest_time is None or message_time < earliest_time:
+ earliest_time = message_time
+ earliest_message_id = message_id
+
+ return {
+ "status": True,
+ "message": f"最早的短信ID是 {earliest_message_id}",
+ "message_id": earliest_message_id,
+ }
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_reminder_api.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_reminder_api.py
new file mode 100644
index 000000000..02036fa19
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_reminder_api.py
@@ -0,0 +1,214 @@
+# -*- coding: utf-8 -*-
+"""The reminder API in ACEBench simulation tools."""
+from datetime import datetime
+
+from ._shared_state import SharedState
+
+
+class ReminderApi(SharedState):
+ """The reminder Api in the ACEBench evaluation."""
+
+ tool_functions: list[str] = [
+ "view_reminder_by_title",
+ "add_reminder",
+ "delete_reminder",
+ "view_all_reminders",
+ "mark_as_notified",
+ "search_reminders",
+ ]
+
+ def __init__(self, share_state: dict) -> None:
+ """Initialize the Reminder Api in the ACEBench evaluation."""
+ super().__init__(share_state)
+
+ self.max_capacity = 6
+ self.reminder_list: dict[
+ int,
+ dict,
+ ] = {
+ 1: {
+ "reminder_id": 1001,
+ "title": "Doctor's Appointment",
+ "description": "Visit Dr. Smith for a checkup.",
+ "time": "2024-07-15 09:30",
+ "notified": False,
+ },
+ 2: {
+ "reminder_id": 1002,
+ "title": "Team Meeting",
+ "description": "Monthly project review with the team.",
+ "time": "2024-07-17 11:00",
+ "notified": False,
+ },
+ 3: {
+ "reminder_id": 1003,
+ "title": "To-do list",
+ "description": '首先帮Frank在"盒马生鲜"点外卖,'
+ '需要定两个"生鲜大礼包",再发短信告诉Frank:'
+ '"购买商品的价格是()元"。要把括号换成实际金额,'
+ "保留一位小数。",
+ "time": "2024-07-16 11:00",
+ "notified": False,
+ },
+ }
+ self.reminder_id_counter: int = 3
+
+ def get_state_dict(self) -> dict:
+ """Get the current state dict of the ReminderApi."""
+ return {
+ "ReminderApi": {
+ "reminder_list": self.reminder_list,
+ },
+ }
+
+ def _check_capacity(self) -> bool:
+ """检查备忘录容量是否已满。"""
+ return len(self.reminder_list) >= self.max_capacity
+
+ def view_reminder_by_title(
+ self,
+ title: str,
+ ) -> dict[str, str | bool | dict[str, str | bool | datetime]]:
+ """根据提醒的标题查看特定的提醒。
+
+ Args:
+ title (str): 提醒的标题。
+
+ Returns:
+ dict[str, str | bool | dict[str, str | bool | datetime]]:
+ 包含查找状态和提醒详情的字典。
+ """
+ if not self.logged_in:
+ return {"status": False, "message": "device未登录,无法查看提醒"}
+ for reminder in self.reminder_list.values():
+ if reminder["title"] == title:
+ return {"status": True, "reminder": reminder}
+
+ return {"status": False, "message": f"没有找到标题为 '{title}' 的提醒"}
+
+ def add_reminder(
+ self,
+ title: str,
+ description: str,
+ time: datetime,
+ ) -> dict[str, bool | str]:
+ """添加一个新的提醒。
+
+ Args:
+ title (str): 提醒标题。
+ description (str): 提醒描述。
+ time (datetime): 提醒时间, 一定遵循格式"YYYY-MM-DD HH:MM"。
+
+ Returns:
+ dict[str, bool | str]: 包含添加状态和结果的字典。
+ """
+ if not self.logged_in:
+ return {
+ "status": False,
+ "message": "device未登录,无法添加一个新的提醒",
+ }
+ if self._check_capacity():
+ return {"status": False, "message": "提醒容量已满,无法添加新的提醒"}
+
+ self.reminder_id_counter += 1
+ reminder_id = self.reminder_id_counter
+ self.reminder_list[reminder_id] = {
+ "reminder_id": reminder_id,
+ "title": title,
+ "description": description,
+ "time": time,
+ "notified": False,
+ }
+ return {"status": True, "message": f"提醒 '{title}' 已成功添加"}
+
+ def delete_reminder(self, reminder_id: int) -> dict[str, bool | str]:
+ """删除指定的提醒。
+
+ Args:
+ reminder_id (int): 要删除的提醒ID。
+
+ Returns:
+ dict[str, bool | str]: 包含删除状态和结果的字典。
+ """
+ if not self.logged_in:
+ return {"status": False, "message": "device未登录,无法删除指定的提醒"}
+ if reminder_id not in self.reminder_list:
+ return {"status": False, "message": "提醒ID不存在"}
+
+ del self.reminder_list[reminder_id]
+ return {"status": True, "message": f"提醒ID {reminder_id} 已成功删除"}
+
+ def view_all_reminders(
+ self,
+ ) -> dict:
+ """查看所有的提醒。
+
+ Returns:
+ dict:
+ 包含所有提醒的字典列表。
+ """
+ if not self.reminder_list:
+ return {"status": False, "message": "没有任何提醒"}
+
+ reminders = []
+ for reminder in self.reminder_list.values():
+ reminders.append(
+ {
+ "title": reminder["title"],
+ "description": reminder["description"],
+ "time": reminder["time"],
+ "notified": reminder["notified"],
+ },
+ )
+ return {"status": True, "reminders": reminders}
+
+ def mark_as_notified(
+ self,
+ reminder_id: int,
+ ) -> dict[str, bool | str]:
+ """标记提醒为已通知。
+
+ Args:
+ reminder_id (int): 要标记为已通知的提醒ID。
+
+ Returns:
+ dict[str, bool | str]:: 包含操作结果的字典。
+ """
+ if reminder_id not in self.reminder_list:
+ return {"status": False, "message": "提醒ID不存在"}
+
+ self.reminder_list[reminder_id]["notified"] = True
+ return {"status": True, "message": f"提醒ID {reminder_id} 已标记为已通知"}
+
+ def search_reminders(
+ self,
+ keyword: str,
+ ) -> dict:
+ """根据关键词搜索提醒。
+
+ Args:
+ keyword (str): 搜索关键词。
+
+ Returns:
+ `dict`:
+ 包含匹配提醒的字典列表。
+ """
+ matched_reminders = []
+
+ for reminder in self.reminder_list.values():
+ if (
+ keyword.lower() in reminder["title"].lower()
+ or keyword.lower() in reminder["description"].lower()
+ ):
+ matched_reminders.append(
+ {
+ "title": reminder["title"],
+ "description": reminder["description"],
+ "time": reminder["time"].strftime("%Y-%m-%d %H:%M"),
+ },
+ )
+
+ if not matched_reminders:
+ return {"status": False, "message": "没有找到包含该关键词的提醒"}
+
+ return {"status": True, "reminders": matched_reminders}
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_shared_state.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_shared_state.py
new file mode 100644
index 000000000..4ef6b1512
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_shared_state.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The shared state class for ACEBench simulation tools."""
+
+
+class SharedState:
+ """The sharing state class for ACEBench simulation tools."""
+
+ def __init__(self, shared_state: dict) -> None:
+ """Initialize the shared state"""
+ self._shared_state = shared_state
+
+ @property
+ def wifi(self) -> bool:
+ """The WI-FI state"""
+ return self._shared_state["wifi"]
+
+ @property
+ def logged_in(self) -> bool:
+ """The logged in state"""
+ return self._shared_state["logged_in"]
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_travel_api.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_travel_api.py
new file mode 100644
index 000000000..9940d3a49
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_api/_travel_api.py
@@ -0,0 +1,834 @@
+# -*- coding: utf-8 -*-
+# type: ignore
+# pylint: disable=too-many-lines
+# pylint: disable=too-many-statements
+# pylint: disable=too-many-branches
+# pylint: disable=too-many-statements
+# pylint: disable=too-many-return-statements
+"""The travel API for the ACEBench simulation tools in AgentScope."""
+
+from datetime import datetime, timedelta
+
+
+class TravelApi:
+ """旅行预订系统类。
+
+ 提供航班查询、用户认证、预订管理等功能的旅行系统。
+ 支持直飞和中转航班查询、航班预订、预订修改和取消等功能。
+ """
+
+ tool_functions: list[str] = [
+ "get_user_details",
+ "get_flight_details",
+ "get_reservation_details",
+ "reserve_flight",
+ "cancel_reservation",
+ "modify_flight",
+ ]
+
+ def __init__(self) -> None:
+ """初始化旅行系统。
+
+ 设置用户档案和航班信息,包含用户信息、航班数据和预订记录。
+ """
+ # 初始化用户信息
+ self.users = {
+ "user1": {
+ "user_name": "Eve",
+ "password": "password123",
+ "cash_balance": 2000.0,
+ "bank_balance": 50000.0,
+ "membership_level": "regular",
+ },
+ "user2": {
+ "user_name": "Frank",
+ "password": "password456",
+ "cash_balance": 8000.0,
+ "bank_balance": 8000.0,
+ "membership_level": "silver",
+ },
+ "user3": {
+ "user_name": "Grace",
+ "password": "password789",
+ "cash_balance": 1000.0,
+ "bank_balance": 5000.0,
+ "membership_level": "gold",
+ },
+ }
+
+ # 初始化航班信息
+ self.flights = [
+ {
+ "flight_no": "CA1234",
+ "origin": "北京",
+ "destination": "上海",
+ "depart_time": "2024-07-15 08:00:00",
+ "arrival_time": "2024-07-15 10:30:00",
+ "status": "available",
+ "seats_available": 5,
+ "economy_price": 1200,
+ "business_price": 3000,
+ },
+ {
+ "flight_no": "MU5678",
+ "origin": "上海",
+ "destination": "北京",
+ "depart_time": "2024-07-16 09:00:00",
+ "arrival_time": "2024-07-16 11:30:00",
+ "status": "available",
+ "seats_available": 3,
+ "economy_price": 1900,
+ "business_price": 3000,
+ },
+ {
+ "flight_no": "CZ4321",
+ "origin": "上海",
+ "destination": "北京",
+ "depart_time": "2024-07-16 20:00:00",
+ "arrival_time": "2024-07-16 22:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 2500,
+ "business_price": 4000,
+ },
+ {
+ "flight_no": "CZ4352",
+ "origin": "上海",
+ "destination": "北京",
+ "depart_time": "2024-07-17 20:00:00",
+ "arrival_time": "2024-07-17 22:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1600,
+ "business_price": 2500,
+ },
+ {
+ "flight_no": "MU3561",
+ "origin": "北京",
+ "destination": "南京",
+ "depart_time": "2024-07-18 08:00:00",
+ "arrival_time": "2024-07-18 10:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 4000,
+ },
+ {
+ "flight_no": "MU1566",
+ "origin": "北京",
+ "destination": "南京",
+ "depart_time": "2024-07-18 20:00:00",
+ "arrival_time": "2024-07-18 22:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 4000,
+ },
+ {
+ "flight_no": "CZ1765",
+ "origin": "南京",
+ "destination": "深圳",
+ "depart_time": "2024-07-17 20:30:00",
+ "arrival_time": "2024-07-17 22:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 2500,
+ },
+ {
+ "flight_no": "CZ1765",
+ "origin": "南京",
+ "destination": "深圳",
+ "depart_time": "2024-07-18 12:30:00",
+ "arrival_time": "2024-07-18 15:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 2500,
+ },
+ {
+ "flight_no": "MH1765",
+ "origin": "厦门",
+ "destination": "成都",
+ "depart_time": "2024-07-17 12:30:00",
+ "arrival_time": "2024-07-17 15:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 2500,
+ },
+ {
+ "flight_no": "MH2616",
+ "origin": "成都",
+ "destination": "厦门",
+ "depart_time": "2024-07-18 18:30:00",
+ "arrival_time": "2024-07-18 21:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 2500,
+ },
+ {
+ "flight_no": "MH2616",
+ "origin": "成都",
+ "destination": "福州",
+ "depart_time": "2024-07-16 18:30:00",
+ "arrival_time": "2024-07-16 21:00:00",
+ "status": "available",
+ "seats_available": 8,
+ "economy_price": 1500,
+ "business_price": 2500,
+ },
+ ]
+
+ # 初始化预订列表
+ self.reservations = [
+ {
+ "reservation_id": "res_1",
+ "user_id": "user1",
+ "flight_no": "CA1234",
+ "payment_method": "bank",
+ "cabin": "经济舱",
+ "baggage": 1,
+ "origin": "北京",
+ "destination": "上海",
+ },
+ {
+ "reservation_id": "res_2",
+ "user_id": "user1",
+ "flight_no": "MU5678",
+ "payment_method": "bank",
+ "cabin": "商务舱",
+ "baggage": 1,
+ "origin": "上海",
+ "destination": "北京",
+ },
+ {
+ "reservation_id": "res_3",
+ "user_id": "user2",
+ "flight_no": "MH1765",
+ "payment_method": "bank",
+ "cabin": "商务舱",
+ "baggage": 1,
+ "origin": "厦门",
+ "destination": "成都",
+ },
+ {
+ "reservation_id": "res_4",
+ "user_id": "user2",
+ "flight_no": "MU2616",
+ "payment_method": "bank",
+ "cabin": "商务舱",
+ "baggage": 1,
+ "origin": "成都",
+ "destination": "厦门",
+ },
+ ]
+
+ def get_state_dict(self) -> dict:
+ """Get the current state dict of the TravelApi."""
+ return {
+ "Travel": {
+ "users": self.users,
+ "reservations": self.reservations,
+ },
+ }
+
+ # 根据出发地和到达地查询航班
+
+ def get_flight_details(
+ self,
+ origin: str = None,
+ destination: str = None,
+ ) -> list[dict] | str:
+ """根据出发地和到达地查询航班的基本信息。
+
+ Args:
+ origin (str, optional): 出发地城市名称。默认为None。
+ destination (str, optional): 目的地城市名称。默认为None。
+
+ Returns:
+ list[dict] | str: 符合条件的航班列表或无航班的提示信息。
+ """
+ flights = self.flights
+
+ # 过滤出发地
+ if origin:
+ flights = [
+ flight for flight in flights if flight["origin"] == origin
+ ]
+
+ # 过滤到达地
+ if destination:
+ flights = [
+ flight
+ for flight in flights
+ if flight["destination"] == destination
+ ]
+ if len(flights) == 0:
+ return "没有符合条件的直达航班"
+ # 返回查询结果
+ return [
+ {
+ "flight_no": flight["flight_no"],
+ "origin": flight["origin"],
+ "destination": flight["destination"],
+ "depart_time": flight["depart_time"],
+ "arrival_time": flight["arrival_time"],
+ "status": flight["status"],
+ "seats_available": flight["seats_available"],
+ "economy_price": flight["economy_price"],
+ "business_price": flight["business_price"],
+ }
+ for flight in flights
+ ]
+
+ def get_user_details(self, user_id: str, password: str) -> dict:
+ """根据用户名和密码查询用户信息。
+
+ Args:
+ user_id (str): 用户ID。
+ password (str): 用户密码。
+
+ Returns:
+ dict: 用户信息字典(不包含密码)或错误信息。
+ """
+ user = self.users.get(user_id)
+ if user and user["password"] == password:
+ return {
+ key: value for key, value in user.items() if key != "password"
+ }
+ return {"status": "error", "message": "用户名或密码不正确"}
+
+ def get_reservation_details(
+ self,
+ reservation_id: str = None,
+ user_id: str = None,
+ ) -> list[dict] | dict:
+ """根据预订ID或用户ID查询预订信息,包括对应航班的基本信息。
+
+ Args:
+ reservation_id (str, optional): 预订ID。默认为None。
+ user_id (str, optional): 用户ID。默认为None。
+
+ Returns:
+ `list[dict] | dict`:
+ 详细预订信息列表或错误信息字典。
+ """
+ # 根据预订ID或用户ID筛选预订信息
+ if reservation_id:
+ reservations = [
+ reservation
+ for reservation in self.reservations
+ if reservation["reservation_id"] == reservation_id
+ ]
+ elif user_id:
+ reservations = [
+ reservation
+ for reservation in self.reservations
+ if reservation["user_id"] == user_id
+ ]
+ else:
+ return {"status": "error", "message": "请提供有效的预订ID或用户ID"}
+
+ # 对每个预订,附加航班信息
+ detailed_reservations = []
+ for reservation in reservations:
+ flight_info = next(
+ (
+ flight
+ for flight in self.flights
+ if flight["flight_no"] == reservation["flight_no"]
+ ),
+ None,
+ )
+ detailed_reservation = {**reservation, "flight_info": flight_info}
+ detailed_reservations.append(detailed_reservation)
+
+ return detailed_reservations
+
+ def authenticate_user(self, user_id: str, password: str) -> dict:
+ """验证用户身份。
+
+ Args:
+ user_id (str): 用户ID。
+ password (str): 用户密码。
+
+ Returns:
+ `dict`:
+ 用户信息字典或错误信息字典。
+ """
+ user = self.users.get(user_id)
+ if user and user["password"] == password:
+ return user
+ return {"status": "error", "message": "用户名或密码不正确"}
+
+ def get_baggage_allowance(
+ self,
+ membership_level: str,
+ cabin_class: str,
+ ) -> int:
+ """获取用户基于会员等级和舱位的免费托运行李限额。
+
+ Args:
+ membership_level (str): 会员等级 ("regular", "silver", "gold")。
+ cabin_class (str): 舱位 ("基础经济舱", "经济舱", "商务舱")。
+
+ Returns:
+ int: 免费托运行李数量。
+ """
+ allowance = {
+ "regular": {"经济舱": 1, "商务舱": 2},
+ "silver": {"经济舱": 2, "商务舱": 3},
+ "gold": {"经济舱": 3, "商务舱": 3},
+ }
+ return allowance.get(membership_level, {}).get(cabin_class, 0)
+
+ def find_transfer_flights(
+ self,
+ origin_city: str,
+ transfer_city: str,
+ destination_city: str,
+ ) -> list[dict] | str:
+ """查找从出发城市到目的地城市的中转航班。
+
+ 确保第一班航班降落时间早于第二班航班起飞时间。
+
+ Args:
+ origin_city (str): 出发城市。
+ transfer_city (str): 中转城市。
+ destination_city (str): 到达城市。
+
+ Returns:
+ list[dict] | str:
+ 满足条件的中转航班列表,每个航班包含两段航程的信息,或无航班提示。
+ """
+ # 获取从出发城市到中转城市的航班
+ first_leg_flights: list[dict] = [
+ flight
+ for flight in self.flights
+ if flight["origin"] == origin_city
+ and flight["destination"] == transfer_city
+ and flight["status"] == "available"
+ ]
+
+ # 获取从中转城市到目的地城市的航班
+ second_leg_flights = [
+ flight
+ for flight in self.flights
+ if flight["origin"] == transfer_city
+ and flight["destination"] == destination_city
+ and flight["status"] == "available"
+ ]
+
+ # 存储符合条件的中转航班
+ transfer_flights = []
+
+ # 遍历第一段航班和第二段航班,查找符合时间条件的组合
+ for first_flight in first_leg_flights:
+ first_arrival = datetime.strptime(
+ first_flight["arrival_time"],
+ "%Y-%m-%d %H:%M:%S",
+ )
+
+ for second_flight in second_leg_flights:
+ second_departure = datetime.strptime(
+ str(second_flight["depart_time"]),
+ "%Y-%m-%d %H:%M:%S",
+ )
+
+ # 检查第一班航班降落时间早于第二班航班起飞时间
+ if first_arrival < second_departure:
+ transfer_flights.append(
+ {
+ "first_leg": first_flight,
+ "second_leg": second_flight,
+ },
+ )
+
+ # 返回符合条件的中转航班列表
+ if transfer_flights:
+ return transfer_flights
+ else:
+ return "未找到符合条件的中转航班。"
+
+ def calculate_baggage_fee(
+ self,
+ membership_level: str,
+ cabin_class: str,
+ baggage_count: int,
+ ) -> float:
+ """计算行李费用。
+
+ Args:
+ membership_level (str): 会员等级。
+ cabin_class (str): 舱位等级。
+ baggage_count (int): 行李数量。
+
+ Returns:
+ float: 额外行李费用。
+ """
+ free_baggage = {
+ "regular": {"经济舱": 1, "商务舱": 2},
+ "silver": {"经济舱": 2, "商务舱": 3},
+ "gold": {"经济舱": 3, "商务舱": 3},
+ }
+ free_limit = free_baggage[membership_level][cabin_class]
+ additional_baggage = max(baggage_count - free_limit, 0)
+ return additional_baggage * 50
+
+ def update_balance(
+ self,
+ user: dict,
+ payment_method: str,
+ amount: float,
+ ) -> bool:
+ """更新用户的余额。
+
+ Args:
+ user (dict): 用户信息字典。
+ payment_method (str): 支付方式("cash" 或 "bank")。
+ amount (float): 更新金额(正数表示增加,负数表示减少)。
+
+ Returns:
+ bool: 如果余额充足且更新成功,返回 True,否则返回 False。
+ """
+ if payment_method == "cash":
+ if user["cash_balance"] + amount < 0:
+ return False # 余额不足
+ user["cash_balance"] += amount
+ elif payment_method == "bank":
+ if user["bank_balance"] + amount < 0:
+ return False # 余额不足
+ user["bank_balance"] += amount
+ return True
+
+ def reserve_flight(
+ self,
+ user_id: str,
+ password: str,
+ flight_no: str,
+ cabin: str,
+ payment_method: str,
+ baggage_count: int,
+ ) -> str:
+ """预订航班。
+
+ Args:
+ user_id (str): 用户ID。
+ password (str): 用户密码。
+ flight_no (str): 航班号。
+ cabin (str): 舱位等级。
+ payment_method (str): 支付方式。
+ baggage_count (int): 行李数量。
+
+ Returns:
+ str: 预订结果信息。
+ """
+ user = self.authenticate_user(user_id, password)
+ if not user:
+ return "认证失败,请检查用户ID和密码。"
+
+ # 检查航班和座位
+ flight = next(
+ (
+ f
+ for f in self.flights
+ if f["flight_no"] == flight_no and f["status"] == "available"
+ ),
+ None,
+ )
+
+ # 计算航班价格
+ price: int = (
+ flight["economy_price"]
+ if cabin == "经济舱"
+ else flight["business_price"]
+ )
+ total_cost = price
+
+ # 计算行李费用
+ baggage_fee = self.calculate_baggage_fee(
+ user["membership_level"],
+ cabin,
+ baggage_count,
+ )
+ total_cost += baggage_fee
+
+ # 检查支付方式
+ if payment_method not in ["cash", "bank"]:
+ return "支付方式无效"
+
+ # 更新预定后的余额
+ if payment_method == "cash":
+ if total_cost > self.users.get(user_id)["cash_balance"]:
+ return "cash余额不足,请考虑换一种支付方式"
+ self.users.get(user_id)["cash_balance"] -= total_cost
+ else:
+ if total_cost > self.users.get(user_id)["bank_balance"]:
+ return "bank余额不足,请考虑换一种支付方式"
+ self.users.get(user_id)["bank_balance"] -= total_cost
+
+ # 更新航班信息并生成预订
+ flight["seats_available"] -= 1
+ reservation_id = f"res_{len(self.reservations) + 1}"
+ reservation = {
+ "reservation_id": reservation_id,
+ "user_id": user_id,
+ "flight_no": flight_no,
+ "payment_method": payment_method,
+ "cabin": cabin,
+ "baggage": baggage_count,
+ }
+ self.reservations.append(reservation)
+
+ return f"预订成功,预订号:{reservation_id}," f"总费用:{total_cost}元(包含行李费用)。"
+
+ def modify_flight(
+ self,
+ user_id: str,
+ reservation_id: str,
+ new_flight_no: str = None,
+ new_cabin: str = None,
+ add_baggage: int = 0,
+ new_payment_method: str = None,
+ ) -> str:
+ """修改航班预订,包括更改航班、舱位和行李。
+
+ Args:
+ user_id (str): 用户ID。
+ reservation_id (str): 预订ID。
+ new_flight_no (str, optional): 新的航班号。默认为None。
+ new_cabin (str, optional): 新的舱位。默认为None。
+ add_baggage (int, optional): 新增托运行李的数量。默认为0。
+ new_payment_method (str, optional): 新的付款方式。默认为None。
+
+ Returns:
+ str: 修改结果信息。
+ """
+ # 获取对应的预订
+ reservation = next(
+ (
+ r
+ for r in self.reservations
+ if r["reservation_id"] == reservation_id
+ and r["user_id"] == user_id
+ ),
+ None,
+ )
+ if not reservation:
+ return "预订未找到或用户ID不匹配。"
+
+ # 检查当前预订的航班信息
+ current_flight = next(
+ (
+ f
+ for f in self.flights
+ if f["flight_no"] == reservation["flight_no"]
+ ),
+ None,
+ )
+ if not current_flight:
+ return "航班信息未找到。"
+
+ # 获取原始支付方式或新提供的支付方式
+ payment_method = (
+ new_payment_method
+ if new_payment_method
+ else reservation["payment_method"]
+ )
+ user = self.users[user_id]
+ if not user:
+ return "用户信息未找到。"
+
+ # 存储处理结果
+ result_messages = []
+
+ if new_flight_no and new_flight_no != reservation["flight_no"]:
+ # 更新航班号(若提供)但必须匹配出发地和目的地
+ new_flight = next(
+ (f for f in self.flights if f["flight_no"] == new_flight_no),
+ None,
+ )
+ if (
+ new_flight
+ and new_flight["origin"] == current_flight["origin"]
+ and new_flight["destination"] == current_flight["destination"]
+ ):
+ reservation["flight_no"] = new_flight_no
+ result_messages.append("航班号已更改。")
+ else:
+ return "航班更改失败:新的航班号无效或目的地不匹配。"
+
+ # 更新舱位(若提供)并计算价格差价
+ if new_cabin and new_cabin != reservation.get("cabin"):
+ price_difference = self.calculate_price_difference(
+ current_flight,
+ reservation["cabin"],
+ new_cabin,
+ )
+ reservation["cabin"] = new_cabin
+ if price_difference > 0:
+ # 扣除差价
+ if self.update_balance(
+ user,
+ payment_method,
+ -price_difference,
+ ):
+ result_messages.append(
+ f"舱位更改成功。已支付差价: {price_difference}。",
+ )
+ else:
+ result_messages.append("余额不足,无法支付舱位差价。")
+ elif price_difference < 0:
+ # 退款
+ self.update_balance(user, payment_method, -price_difference)
+ result_messages.append(f"舱位更改成功。已退款差价: {-price_difference}。")
+
+ # 增加托运行李,检查免费限额和计算费用
+ if add_baggage > 0:
+ membership = user["membership_level"]
+ max_free_baggage = self.get_baggage_allowance(
+ membership,
+ reservation["cabin"],
+ )
+ current_baggage = reservation.get("baggage", 0)
+ total_baggage = current_baggage + add_baggage
+ extra_baggage = max(0, total_baggage - max_free_baggage)
+ baggage_cost = extra_baggage * 50
+ if baggage_cost > 0:
+ # 扣除行李费用
+ if self.update_balance(user, payment_method, -baggage_cost):
+ result_messages.append(
+ f"行李已增加。需支付额外费用: {baggage_cost}。",
+ )
+ else:
+ result_messages.append("余额不足,无法支付额外行李费用。")
+ reservation["baggage"] = total_baggage
+
+ # 返回最终结果
+ if not result_messages:
+ result_messages.append("修改完成,无需额外费用。")
+ return " ".join(result_messages)
+
+ def cancel_reservation(
+ self,
+ user_id: str,
+ reservation_id: str,
+ reason: str,
+ ) -> str:
+ """取消预订。
+
+ Args:
+ user_id (str): 用户ID。
+ reservation_id (str): 预订ID。
+ reason (str): 取消原因。
+
+ Returns:
+ str: 取消结果信息。
+ """
+ # 设置默认当前时间为 2024年7月14日早上6点
+ current_time = datetime(2024, 7, 14, 6, 0, 0)
+
+ # 验证用户和预订是否存在
+ user = self.users.get(user_id, None)
+ if not user:
+ return "用户ID无效。"
+
+ reservation = next(
+ (
+ r
+ for r in self.reservations
+ if r["reservation_id"] == reservation_id
+ and r["user_id"] == user_id
+ ),
+ None,
+ )
+ if not reservation:
+ return "预订ID无效或与该用户无关。"
+
+ # 检查航班信息是否存在
+ flight = next(
+ (
+ f
+ for f in self.flights
+ if f["flight_no"] == reservation["flight_no"]
+ ),
+ None,
+ )
+ if not flight:
+ return "航班信息无效。"
+
+ # 检查航班是否已起飞
+ depart_time = datetime.strptime(
+ flight["depart_time"],
+ "%Y-%m-%d %H:%M:%S",
+ )
+ if current_time > depart_time:
+ return "航段已使用,无法取消。"
+
+ # 计算距离出发时间
+ time_until_departure = depart_time - current_time
+ cancel_fee = 0
+ refund_amount = 0
+
+ # 获取航班价格
+ flight_price = (
+ flight["economy_price"]
+ if reservation["cabin"] == "经济舱"
+ else flight["business_price"]
+ )
+
+ # 取消政策及退款计算
+ if reason == "航空公司取消航班":
+ # 航空公司取消航班,全额退款
+ refund_amount = flight_price
+ self.process_refund(user, refund_amount)
+ return f"航班已取消,您的预订将被免费取消,已退款{refund_amount}元。"
+
+ elif time_until_departure > timedelta(days=1):
+ # 离出发时间超过24小时免费取消
+ refund_amount = flight_price
+ self.process_refund(user, refund_amount)
+ return f"距离出发时间超过24小时,免费取消成功,已退款{refund_amount}元。"
+
+ else:
+ # 若不符合免费取消条件,可根据需求设置取消费
+ cancel_fee = flight_price * 0.1 # 假设取消费为票价的10%
+ refund_amount = flight_price - cancel_fee
+ self.process_refund(user, refund_amount)
+ return f"距离出发时间不足24小时,已扣除取消费{cancel_fee}元,退款{refund_amount}元。"
+
+ def process_refund(self, user: dict, amount: float) -> str:
+ """将退款金额添加到用户的现金余额中。
+
+ Args:
+ user (dict): 用户信息字典。
+ amount (float): 退款金额。
+ """
+ user["cash_balance"] += amount
+ return f"已成功处理退款,{user['user_name']}的现金余额增加了{amount}元。"
+
+ def calculate_price_difference(
+ self,
+ flight: dict,
+ old_cabin: str,
+ new_cabin: str,
+ ) -> float:
+ """计算舱位价格差异。
+
+ Args:
+ flight (dict): 航班信息字典。
+ old_cabin (str): 原舱位等级。
+ new_cabin (str): 新舱位等级。
+
+ Returns:
+ float: 价格差异(正数表示需支付差价,负数表示退款)。
+ """
+ cabin_prices = {
+ "经济舱": flight["economy_price"],
+ "商务舱": flight["business_price"],
+ }
+ old_price = cabin_prices.get(old_cabin, 0)
+ new_price = cabin_prices.get(new_cabin, 0)
+ return new_price - old_price
diff --git a/src/agentscope/evaluate/_ace_benchmark/_ace_tools_zh.py b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_zh.py
new file mode 100644
index 000000000..963ab20b8
--- /dev/null
+++ b/src/agentscope/evaluate/_ace_benchmark/_ace_tools_zh.py
@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""The Chinese tools for ACEBench evaluation."""
+from functools import wraps
+from typing import Callable, Any
+
+from ._ace_tools_api import (
+ ReminderApi,
+ FoodPlatformApi,
+ TravelApi,
+ MessageApi,
+)
+from ...message import TextBlock
+from ...tool import ToolResponse
+
+
+def _tool_function_wrapper(get_tool_function: Callable) -> Callable:
+ """Wrap the tool function result to be ToolResponse."""
+
+ @wraps(get_tool_function)
+ def wrapper(self: "ACEPhone", name: str) -> Callable:
+ """Wrap the tool function to return ToolResponse."""
+ tool_function = get_tool_function(self, name)
+
+ @wraps(tool_function)
+ def wrapper_tool_function(*args: Any, **kwargs: Any) -> ToolResponse:
+ """The wrapped tool function"""
+ res = tool_function(*args, **kwargs)
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=str(res),
+ ),
+ ],
+ )
+
+ return wrapper_tool_function
+
+ return wrapper
+
+
+class ACEPhone:
+ """Simulate a user phone with various apps and functionalities in
+ ACEBench. The code is implemented with reference to the
+ `ACEBench <https://github.com/ACEBench/ACEBench>`_.
+ """
+
+ def __init__(self) -> None:
+ """Initialize the shared state and apps for the ACEPhone."""
+ self._state = {
+ "wifi": False,
+ "logged_in": False,
+ }
+ self._message_app = MessageApi(self._state)
+ self._reminder_app = ReminderApi(self._state)
+ self._food_platform_app = FoodPlatformApi(self._state)
+ self._travel = TravelApi()
+
+ def turn_on_wifi(self) -> dict[str, bool | str]:
+ """开启WiFi连接。"""
+ self._state["wifi"] = True
+ return {"status": True, "message": "wifi已经打开"}
+
+ def login_device(self) -> dict[str, bool | str]:
+ """登录设备。"""
+ self._state["logged_in"] = True
+ return {"status": True, "message": "设备已经登录"}
+
+ def load_initial_config(self, initial_config: dict) -> None:
+ """Load the initial config from the application configuration."""
+ # Empty initial config
+ if len(initial_config) == 0:
+ return
+
+ # Fix the typo in ACEBench by renaming "Baspi" to "BaseApi"
+ if "Baspi" in initial_config:
+ initial_config["BaseApi"] = initial_config.pop("Baspi")
+
+ # Verify state
+ assert (
+ "BaseApi" in initial_config
+ and "wifi" in initial_config["BaseApi"]
+ and "logged_in" in initial_config["BaseApi"]
+ ), f"Invalid initial config: {initial_config}"
+
+ self._state["wifi"] = initial_config["BaseApi"]["wifi"]
+ self._state["logged_in"] = initial_config["BaseApi"]["logged_in"]
+
+ def get_current_state(self) -> list[dict]:
+ """Follow ACEBench to get the current state of the ACEPhone."""
+ return [
+ {"BaseApi": self._state},
+ self._message_app.get_state_dict(),
+ self._reminder_app.get_state_dict(),
+ self._food_platform_app.get_state_dict(),
+ self._travel.get_state_dict(),
+ ]
+
+ @_tool_function_wrapper
+ def get_tool_function(self, name: str) -> Callable:
+ """Get a tool function by name."""
+ if name in [
+ "turn_on_wifi",
+ "login_device",
+ ]:
+ return getattr(self, name)
+
+ if name in self._message_app.tool_functions:
+ return getattr(self._message_app, name)
+
+ if name in self._food_platform_app.tool_functions:
+ return getattr(self._food_platform_app, name)
+
+ if name in self._reminder_app.tool_functions:
+ return getattr(self._reminder_app, name)
+
+ if name in self._travel.tool_functions:
+ return getattr(self._travel, name)
+
+ raise ValueError(
+ f"Tool function '{name}' not found in ACEPhone.",
+ )
diff --git a/src/agentscope/evaluate/_benchmark_base.py b/src/agentscope/evaluate/_benchmark_base.py
new file mode 100644
index 000000000..73b4262e9
--- /dev/null
+++ b/src/agentscope/evaluate/_benchmark_base.py
@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""The base class for benchmark evaluation."""
+from abc import ABC, abstractmethod
+from typing import Generator
+
+from ._task import Task
+
+
+class BenchmarkBase(ABC):
+ """The base class for benchmark evaluation."""
+
+ name: str
+ """The name of the benchmark."""
+
+ description: str
+ """The description of the benchmark."""
+
+ def __init__(self, name: str, description: str) -> None:
+ """Initialize the benchmark.
+
+ Args:
+ name (`str`):
+ The name of the benchmark.
+ description (`str`):
+ A brief description of the benchmark.
+ """
+ self.name = name
+ self.description = description
+
+ @abstractmethod
+ def __iter__(self) -> Generator[Task, None, None]:
+ """Iterate over the benchmark."""
+ raise NotImplementedError("Subclasses must implement this method.")
+
+ @abstractmethod
+ def __len__(self) -> int:
+ """Get the length of the benchmark."""
+ raise NotImplementedError("Subclasses must implement this method.")
+
+ @abstractmethod
+ def __getitem__(self, index: int) -> Task:
+ """Get the task at the given index."""
+ raise NotImplementedError("Subclasses must implement this method.")
diff --git a/src/agentscope/evaluate/_evaluator/__init__.py b/src/agentscope/evaluate/_evaluator/__init__.py
new file mode 100644
index 000000000..264e537c2
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""The evaluator module in AgentScope."""
+
+from ._evaluator_base import EvaluatorBase
+from ._ray_evaluator import RayEvaluator
+from ._general_evaluator import GeneralEvaluator
+
+__all__ = [
+ "EvaluatorBase",
+ "RayEvaluator",
+ "GeneralEvaluator",
+]
diff --git a/src/agentscope/evaluate/_evaluator/_evaluator_base.py b/src/agentscope/evaluate/_evaluator/_evaluator_base.py
new file mode 100644
index 000000000..055f80cb0
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator/_evaluator_base.py
@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""The base class for evaluator in evaluation."""
+import collections
+import json
+from abc import abstractmethod
+from typing import Callable, Coroutine, Any
+
+from .._solution import SolutionOutput
+from .._task import Task
+from .._benchmark_base import BenchmarkBase
+from .._evaluator_storage import EvaluatorStorageBase
+from .._metric_base import MetricType
+from ..._utils._common import _get_timestamp
+
+
+class EvaluatorBase:
+ """The class that runs the evaluation process."""
+
+ def __init__(
+ self,
+ name: str,
+ benchmark: BenchmarkBase,
+ n_repeat: int,
+ storage: EvaluatorStorageBase,
+ ) -> None:
+ """Initialize the evaluator.
+
+ Args:
+ name (`str`):
+ The name of this evaluator.
+ benchmark: (`BenchmarkBase`):
+ A benchmark instance inheriting from `BenchmarkBase` that
+ defines the evaluation dataset.
+ n_repeat (`int`):
+ How many times to repeat the evaluation for each task.
+ storage (`EvaluatorStorageBase`):
+ A instance inheriting from the child class of
+ `EvaluatorStorageBase` that supports storing and loading
+ solution output and evaluation results.
+ """
+ self.name = name
+ self.benchmark = benchmark
+ self.n_repeat = n_repeat
+ self.storage = storage
+
+ @abstractmethod
+ async def run(
+ self,
+ solution: Callable[
+ [Task, Callable],
+ Coroutine[Any, Any, SolutionOutput],
+ ],
+ ) -> None:
+ """Run the evaluation and return the results.
+
+ Args:
+ solution (`Callable[[Task, Callable], Coroutine[Any, Any, \
+ SolutionOutput]]`):
+ A async function that takes a `Task` instance and a pre-hook
+ as input and returns a `SolutionOutput` instance.
+ """
+
+ async def _save_evaluation_meta(self) -> None:
+ """Save the evaluation meta information."""
+ self.storage.save_evaluation_meta(
+ {
+ "evaluation_name": self.name,
+ "created_at": _get_timestamp(),
+ "total_repeats": self.n_repeat,
+ "benchmark": {
+ "name": self.benchmark.name,
+ "description": self.benchmark.description,
+ "total_tasks": len(self.benchmark),
+ },
+ "schema_version": 1,
+ },
+ )
+
+ async def aggregate(self) -> None: # pylint: disable=too-many-branches
+ """Aggregate the evaluation results and save an overall result."""
+ meta_info: dict = {
+ "total_tasks": len(self.benchmark),
+ "total_repeats": self.n_repeat,
+ "repeats": {},
+ "schema_version": 1,
+ }
+
+ for repeat_index in range(self.n_repeat):
+ repeat_id = str(repeat_index)
+ current_repeat: dict = {
+ "completed_tasks": 0,
+ "incomplete_tasks": 0,
+ "metrics": {},
+ "completed_ids": [],
+ "incomplete_ids": [],
+ }
+ for task in self.benchmark:
+ for metric in task.metrics:
+ # Create a new dict in aggregated_result
+ if metric.name not in current_repeat["metrics"]:
+ current_repeat["metrics"][metric.name] = {
+ "type": metric.metric_type,
+ "involved_tasks": 0,
+ "completed_tasks": 0,
+ "incomplete_tasks": 0,
+ "aggregation": {},
+ "distribution": collections.defaultdict(list),
+ }
+
+ # Record the submitted task
+ current_repeat["metrics"][metric.name][
+ "involved_tasks"
+ ] += 1
+
+ # Not finished
+ if not self.storage.evaluation_result_exists(
+ task.id,
+ repeat_id,
+ metric.name,
+ ):
+ if task.id not in current_repeat["incomplete_ids"]:
+ current_repeat["incomplete_tasks"] += 1
+ current_repeat["incomplete_ids"].append(task.id)
+ current_repeat["metrics"][metric.name][
+ "incomplete_tasks"
+ ] += 1
+ continue
+
+ if task.id not in current_repeat["completed_ids"]:
+ current_repeat["completed_tasks"] += 1
+ current_repeat["completed_ids"].append(task.id)
+ current_repeat["metrics"][metric.name][
+ "completed_tasks"
+ ] += 1
+
+ # Get the evaluation result
+ eval_result = self.storage.get_evaluation_result(
+ task.id,
+ repeat_id,
+ metric.name,
+ )
+
+ # Record the metric result
+ if metric.metric_type == MetricType.CATEGORY:
+ current_repeat["metrics"][metric.name]["distribution"][
+ eval_result.result
+ ].append(
+ task.id,
+ )
+
+ elif metric.metric_type == MetricType.NUMERICAL:
+ current_repeat["metrics"][metric.name]["distribution"][
+ task.id
+ ] = eval_result.result
+
+ print("Repeat ID:", repeat_id)
+
+ for metric, value in current_repeat["metrics"].items():
+ print("\tMetric:", metric)
+ print("\t\tType:", value["type"])
+ print("\t\tInvolved tasks:", value["involved_tasks"])
+ print("\t\tCompleted tasks:", value["completed_tasks"])
+ print("\t\tIncomplete tasks:", value["incomplete_tasks"])
+
+ if value["type"] == MetricType.CATEGORY:
+ # Count the distribution
+ for category, task_ids in value["distribution"].items():
+ value["aggregation"][category] = (
+ len(task_ids) * 1.0 / value["involved_tasks"]
+ )
+
+ elif value["type"] == MetricType.NUMERICAL:
+ scores = list(value["distribution"].values())
+ value["aggregation"] = {
+ "mean": sum(scores) / value["involved_tasks"],
+ "max": max(scores),
+ "min": min(scores),
+ }
+
+ print(
+ "\t\tAggregation:",
+ json.dumps(
+ value["aggregation"],
+ indent=4,
+ ensure_ascii=False,
+ ).replace("\n", "\n\t\t"),
+ )
+
+ meta_info["repeats"][repeat_id] = current_repeat
+
+ # save
+ self.storage.save_aggregation_result(meta_info)
diff --git a/src/agentscope/evaluate/_evaluator/_general_evaluator.py b/src/agentscope/evaluate/_evaluator/_general_evaluator.py
new file mode 100644
index 000000000..ce121c151
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator/_general_evaluator.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""General evaluator implementation in AgentScope, which is easy to debug
+compared to the RayEvaluator."""
+from typing import Callable, Awaitable, Coroutine, Any
+
+from ._evaluator_base import EvaluatorBase
+from .._evaluator_storage import EvaluatorStorageBase
+from .._task import Task
+from .._solution import SolutionOutput
+from .._benchmark_base import BenchmarkBase
+
+
+class GeneralEvaluator(EvaluatorBase):
+ """The general evaluator that support users to debug their evaluation"""
+
+ def __init__(
+ self,
+ name: str,
+ benchmark: BenchmarkBase,
+ n_repeat: int,
+ storage: EvaluatorStorageBase,
+ n_workers: int,
+ ) -> None:
+ """Initialize the evaluator."""
+ super().__init__(
+ name=name,
+ benchmark=benchmark,
+ n_repeat=n_repeat,
+ storage=storage,
+ )
+
+ assert isinstance(benchmark, BenchmarkBase)
+
+ assert n_repeat >= 1, "n_repeat must be at least 1"
+
+ assert n_workers >= 1, "n_workers must be at least 1"
+
+ self.benchmark = benchmark
+ self.n_repeat = n_repeat
+ self.n_workers = n_workers
+
+ def run_evaluation(
+ self,
+ task: Task,
+ repeat_id: str,
+ solution_output: SolutionOutput,
+ ) -> None:
+ """Run the evaluation for a task and solution result."""
+ evaluation_results = task.evaluate(solution_output)
+ # store the evaluation result
+ for result in evaluation_results:
+ self.storage.save_evaluation_result(
+ task_id=task.id,
+ repeat_id=repeat_id,
+ evaluation=result,
+ )
+
+ async def run_solution(
+ self,
+ repeat_id: str,
+ task: Task,
+ solution: Callable[[Task, Callable], Awaitable[SolutionOutput]],
+ ) -> None:
+ """Generate a solution to a task and evaluate."""
+ if self.storage.solution_result_exists(task.id, repeat_id):
+ # Obtain from storage
+ solution_result = self.storage.get_solution_result(
+ task.id,
+ repeat_id,
+ )
+
+ else:
+ # Run the solution
+ solution_result = await solution(
+ task,
+ self.storage.get_agent_pre_print_hook(
+ task.id,
+ repeat_id,
+ ),
+ )
+ self.storage.save_solution_result(
+ task.id,
+ repeat_id,
+ solution_result,
+ )
+
+ # Evaluate the solution with the
+ for metric in task.metrics:
+ if not self.storage.evaluation_result_exists(
+ task.id,
+ repeat_id,
+ metric.name,
+ ):
+ self.run_evaluation(
+ task,
+ repeat_id,
+ solution_result,
+ )
+
+ async def run(
+ self,
+ solution: Callable[
+ [Task, Callable],
+ Coroutine[Any, Any, SolutionOutput],
+ ],
+ ) -> None:
+ """Run the ray-based distributed and parallel evaluation, and get the
+ results.
+
+ Args:
+ solution (`Callable[[Task, Callable], Coroutine[Any, Any, \
+ SolutionOutput]]`):
+ A async function that takes a `Task` instance and a pre-print
+ hook function as input, returns a `SolutionOutput` instance.
+ """
+
+ await self._save_evaluation_meta()
+
+ for repeat_id in range(self.n_repeat):
+ for task in self.benchmark:
+ await self.run_solution(
+ str(repeat_id),
+ task,
+ solution,
+ )
+
+ await self.aggregate()
diff --git a/src/agentscope/evaluate/_evaluator/_ray_evaluator.py b/src/agentscope/evaluate/_evaluator/_ray_evaluator.py
new file mode 100644
index 000000000..a8f4a0147
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator/_ray_evaluator.py
@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""The evaluator base class in agentscope."""
+import asyncio
+from typing import Callable, Awaitable, Coroutine, Any
+
+try:
+ import ray
+except ImportError:
+ ray = None
+
+from .._benchmark_base import BenchmarkBase
+from .._evaluator._evaluator_base import EvaluatorBase
+from .._solution import SolutionOutput
+from .._task import Task
+from .._evaluator_storage import EvaluatorStorageBase
+
+
+def _lazy_ray_remote(func: Callable) -> Callable:
+ """Decorator to lazily initialize ray.remote."""
+ try:
+ import ray as lazy_ray
+
+ return lazy_ray.remote(func)
+
+ except ImportError:
+ return func
+
+
+class RayEvaluator(EvaluatorBase):
+ """The ray-based evaluator that supports distributed and parallel
+ evaluation."""
+
+ def __init__(
+ self,
+ name: str,
+ benchmark: BenchmarkBase,
+ n_repeat: int,
+ storage: EvaluatorStorageBase,
+ n_workers: int,
+ ) -> None:
+ """Initialize the evaluator."""
+ super().__init__(
+ name=name,
+ benchmark=benchmark,
+ n_repeat=n_repeat,
+ storage=storage,
+ )
+
+ assert isinstance(benchmark, BenchmarkBase)
+
+ assert n_repeat >= 1, "n_repeat must be at least 1"
+
+ assert n_workers >= 1, "n_workers must be at least 1"
+
+ self.benchmark = benchmark
+ self.n_repeat = n_repeat
+ self.n_workers = n_workers
+
+ @staticmethod
+ @_lazy_ray_remote
+ def run_evaluation(
+ storage: EvaluatorStorageBase,
+ task: Task,
+ repeat_id: str,
+ solution_output: SolutionOutput,
+ ) -> None:
+ """Run the evaluation for a task and solution result."""
+ evaluation_results = task.evaluate(solution_output)
+ # store the evaluation result
+ for result in evaluation_results:
+ storage.save_evaluation_result(
+ task_id=task.id,
+ repeat_id=repeat_id,
+ evaluation=result,
+ )
+
+ @staticmethod
+ @_lazy_ray_remote
+ def run_solution(
+ storage: EvaluatorStorageBase,
+ repeat_id: str,
+ task: Task,
+ solution: Callable[
+ [Task, Callable],
+ Coroutine[Any, Any, SolutionOutput],
+ ],
+ ) -> None:
+ """Generate a solution to a task and evaluate."""
+ if storage.solution_result_exists(task.id, repeat_id):
+ # Obtain from storage
+ solution_result = storage.get_solution_result(
+ task.id,
+ repeat_id,
+ )
+
+ else:
+ # Run the solution
+ solution_result = asyncio.run(
+ solution(
+ task,
+ storage.get_agent_pre_print_hook(
+ task.id,
+ repeat_id,
+ ),
+ ),
+ )
+ storage.save_solution_result(
+ task.id,
+ repeat_id,
+ solution_result,
+ )
+
+ # Evaluate the solution with the
+ futures = []
+ for metric in task.metrics:
+ if not storage.evaluation_result_exists(
+ task.id,
+ repeat_id,
+ metric.name,
+ ):
+ futures.append(
+ RayEvaluator.run_evaluation.remote(
+ storage,
+ task,
+ repeat_id,
+ solution_result,
+ ),
+ )
+ ray.get(futures)
+
+ async def run(
+ self,
+ solution: Callable[
+ [Task, Callable],
+ Awaitable[SolutionOutput] | SolutionOutput,
+ ],
+ ) -> None:
+ """Run the ray-based distributed and parallel evaluation, and get the
+ results.
+
+ Args:
+ solution (`Callable[[Task], SolutionOutput]`):
+ A sync or async function that takes a `Task` instance as input
+ and returns a `SolutionOutput` instance.
+ """
+
+ await self._save_evaluation_meta()
+
+ futures = []
+ for repeat_id in range(self.n_repeat):
+ for task in self.benchmark:
+ futures.append(
+ RayEvaluator.run_solution.remote(
+ self.storage,
+ str(repeat_id),
+ task,
+ solution,
+ ),
+ )
+ ray.get(futures)
+
+ await self.aggregate()
diff --git a/src/agentscope/evaluate/_evaluator_storage/__init__.py b/src/agentscope/evaluate/_evaluator_storage/__init__.py
new file mode 100644
index 000000000..0e90d7813
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator_storage/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""The evaluator storage module in AgentScope."""
+
+from ._evaluator_storage_base import EvaluatorStorageBase
+from ._file_evaluator_storage import FileEvaluatorStorage
+
+__all__ = [
+ "EvaluatorStorageBase",
+ "FileEvaluatorStorage",
+]
diff --git a/src/agentscope/evaluate/_evaluator_storage/_evaluator_storage_base.py b/src/agentscope/evaluate/_evaluator_storage/_evaluator_storage_base.py
new file mode 100644
index 000000000..74e398559
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator_storage/_evaluator_storage_base.py
@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+"""The evaluator storage base class for storing solution and evaluation
+results."""
+from abc import abstractmethod
+from typing import Any, Callable
+
+from .._metric_base import MetricResult
+from .._solution import SolutionOutput
+from ...agent import AgentBase
+
+
+class EvaluatorStorageBase:
+ """Used to store the solution results and evaluation results to support
+ resuming the evaluation process"""
+
+ @abstractmethod
+ def save_solution_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ output: SolutionOutput,
+ **kwargs: Any,
+ ) -> None:
+ """Save the solution result.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ output (`SolutionOutput`):
+ The solution output to be saved.
+ """
+
+ @abstractmethod
+ def get_evaluation_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ metric_name: str,
+ ) -> MetricResult:
+ """Get the evaluation result by the given task id and repeat id
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ metric_name (`str`):
+ The metric name.
+
+ Returns:
+ `MetricResult`:
+ The evaluation result for the given task and repeat ID.
+ """
+
+ @abstractmethod
+ def save_evaluation_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ evaluation: MetricResult,
+ **kwargs: Any,
+ ) -> None:
+ """Save the evaluation result.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ evaluation (`MetricResult`):
+ The evaluation result to be saved.
+ """
+
+ @abstractmethod
+ def get_solution_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ **kwargs: Any,
+ ) -> SolutionOutput:
+ """Get the solution result for the given task and repeat id.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Returns:
+ `SolutionOutput`:
+ The solution output for the given task and repeat ID.
+ """
+
+ @abstractmethod
+ def solution_result_exists(self, task_id: str, repeat_id: str) -> bool:
+ """Check if the solution for the given task and repeat is finished.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Returns:
+ `bool`:
+ True if the solution result file exists, False otherwise.
+ """
+
+ @abstractmethod
+ def evaluation_result_exists(
+ self,
+ task_id: str,
+ repeat_id: str,
+ metric_name: str,
+ ) -> bool:
+ """Check if the evaluation result for the given solution and metric
+ is finished.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ metric_name (`str`):
+ The name of the metric.
+
+ Returns:
+ `bool`:
+ True if the evaluation result file exists, False otherwise.
+ """
+
+ @abstractmethod
+ def save_aggregation_result(
+ self,
+ aggregation_result: dict,
+ **kwargs: Any,
+ ) -> None:
+ """Save the aggregation result.
+
+ Args:
+ aggregation_result (`dict`):
+ A dictionary containing the aggregation result.
+ """
+
+ @abstractmethod
+ def aggregation_result_exists(
+ self,
+ **kwargs: Any,
+ ) -> bool:
+ """Check if the aggregation result exists
+
+ Returns:
+ `bool`:
+ `True` if the aggregation result file exists.
+ """
+
+ @abstractmethod
+ def save_evaluation_meta(self, meta_info: dict) -> None:
+ """Save the evaluation meta information.
+
+ Args:
+ meta_info (`dict`):
+ A dictionary containing the meta information.
+ """
+
+ @abstractmethod
+ def get_agent_pre_print_hook(
+ self,
+ task_id: str,
+ repeat_id: str,
+ ) -> Callable[[AgentBase, dict], None]:
+ """Get a pre-print hook function for the agent to save the agent
+ printing in the evaluation storage.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Returns:
+ `Callable[[AgentBase, dict], None]`:
+ A hook function that takes an `AgentBase` instance and a
+ keyword arguments dictionary as input, saving the agent's
+ printing Msg into the evaluation storage.
+ """
diff --git a/src/agentscope/evaluate/_evaluator_storage/_file_evaluator_storage.py b/src/agentscope/evaluate/_evaluator_storage/_file_evaluator_storage.py
new file mode 100644
index 000000000..27c45835b
--- /dev/null
+++ b/src/agentscope/evaluate/_evaluator_storage/_file_evaluator_storage.py
@@ -0,0 +1,345 @@
+# -*- coding: utf-8 -*-
+"""A file system based evaluator storage."""
+import json
+import os
+from json import JSONDecodeError
+from typing import Any, Callable
+
+from ._evaluator_storage_base import EvaluatorStorageBase
+from .._solution import SolutionOutput
+from .._metric_base import MetricResult
+from ...agent import AgentBase
+from ...message import Msg
+
+
+class FileEvaluatorStorage(EvaluatorStorageBase):
+ """File system based evaluator storage, providing methods to save and
+ retrieve evaluation results. So that the evaluation process can be resumed
+ from the last saved state.
+
+ The files are organized in a directory structure:
+ - save_dir/
+ - evaluation_result.json
+ - evaluation_meta.json
+ - {task_id}/
+ - {repeat_id}/
+ - solution.json
+ - evaluation/
+ - {metric_name}.json
+ """
+
+ SOLUTION_FILE_NAME = "solution.json"
+ EVALUATION_DIR_NAME = "evaluation"
+ EVALUATION_RESULT_FILE = "evaluation_result.json"
+ EVALUATION_META_FILE = "evaluation_meta.json"
+ AGENT_PRINTING_LOG = "logging.txt"
+
+ def __init__(self, save_dir: str) -> None:
+ """Initialize the file evaluator storage."""
+ self.save_dir = save_dir
+
+ def _get_save_path(self, task_id: str, repeat_id: str, *args: str) -> str:
+ """Get the save path for a given task and repeat ID."""
+ return os.path.join(self.save_dir, repeat_id, task_id, *args)
+
+ def save_solution_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ output: SolutionOutput,
+ **kwargs: Any,
+ ) -> None:
+ """Save the solution result.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ output (`SolutionOutput`):
+ The solution output to be saved.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.SOLUTION_FILE_NAME,
+ )
+ os.makedirs(os.path.dirname(path_file), exist_ok=True)
+ with open(path_file, "w", encoding="utf-8") as f:
+ json.dump(output, f, ensure_ascii=False, indent=4)
+
+ def save_evaluation_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ evaluation: MetricResult,
+ **kwargs: Any,
+ ) -> None:
+ """Save the evaluation result.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ evaluation (`MetricResult`):
+ The evaluation result to be saved.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.EVALUATION_DIR_NAME,
+ f"{evaluation.name}.json",
+ )
+ os.makedirs(os.path.dirname(path_file), exist_ok=True)
+ with open(path_file, "w", encoding="utf-8") as f:
+ json.dump(evaluation, f, ensure_ascii=False, indent=4)
+
+ def get_evaluation_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ metric_name: str,
+ ) -> MetricResult:
+ """Get the evaluation result by the given task id and repeat id
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ metric_name (`str`):
+ The metric name.
+
+ Returns:
+ `MetricResult`:
+ The evaluation result for the given task and repeat ID.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.EVALUATION_DIR_NAME,
+ f"{metric_name}.json",
+ )
+ if not os.path.exists(path_file):
+ raise FileNotFoundError(path_file)
+ with open(path_file, "r", encoding="utf-8") as f:
+ evaluation = json.load(f)
+ return MetricResult(**evaluation)
+
+ def get_solution_result(
+ self,
+ task_id: str,
+ repeat_id: str,
+ **kwargs: Any,
+ ) -> SolutionOutput:
+ """Get the solution result for the given task and repeat id from the
+ file system.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Raises:
+ `FileNotFoundError`:
+ If the solution result file does not exist for the given task
+ and repeat ID.
+
+ Returns:
+ `SolutionOutput`:
+ The solution output for the given task and repeat ID.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.SOLUTION_FILE_NAME,
+ )
+ if not os.path.exists(path_file):
+ raise FileNotFoundError(
+ f"Solution result for task {task_id} and repeat {repeat_id} "
+ "not found.",
+ )
+
+ try:
+ with open(path_file, "r", encoding="utf-8") as f:
+ solution_data = json.load(f)
+ except JSONDecodeError as e:
+ raise JSONDecodeError(
+ f"Failed to load JSON from {path_file}: {e.msg}",
+ e.doc,
+ e.pos,
+ ) from e
+
+ return SolutionOutput(**solution_data)
+
+ def solution_result_exists(self, task_id: str, repeat_id: str) -> bool:
+ """Check if the solution for the given task and repeat is finished.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Returns:
+ `bool`:
+ True if the solution result file exists, False otherwise.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.SOLUTION_FILE_NAME,
+ )
+
+ return os.path.exists(path_file) and os.path.getsize(path_file) > 0
+
+ def evaluation_result_exists(
+ self,
+ task_id: str,
+ repeat_id: str,
+ metric_name: str,
+ ) -> bool:
+ """Check if the evaluation result for the given solution and metric
+ is finished.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+ metric_name (`str`):
+ The name of the metric.
+
+ Returns:
+ `bool`:
+ True if the evaluation result file exists, False otherwise.
+ """
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.EVALUATION_DIR_NAME,
+ f"{metric_name}.json",
+ )
+ return os.path.exists(path_file) and os.path.getsize(path_file) > 0
+
+ def save_aggregation_result(
+ self,
+ aggregation_result: dict,
+ **kwargs: Any,
+ ) -> None:
+ """Save the aggregation result.
+
+ Args:
+ aggregation_result (`dict`):
+ A dictionary containing the aggregation result.
+ """
+ path_file = os.path.join(
+ self.save_dir,
+ self.EVALUATION_RESULT_FILE,
+ )
+ os.makedirs(os.path.dirname(path_file), exist_ok=True)
+ with open(path_file, "w", encoding="utf-8") as f:
+ json.dump(aggregation_result, f, ensure_ascii=False, indent=4)
+
+ def aggregation_result_exists(
+ self,
+ **kwargs: Any,
+ ) -> bool:
+ """Check if the aggregation result exists
+
+ Returns:
+ `bool`:
+ `True` if the aggregation result file exists.
+ """
+ path_file = os.path.join(
+ self.save_dir,
+ self.EVALUATION_RESULT_FILE,
+ )
+ return os.path.exists(path_file) and os.path.getsize(path_file) > 0
+
+ def save_evaluation_meta(self, meta_info: dict) -> None:
+ """Save the evaluation meta information.
+
+ Args:
+ meta_info (`dict`):
+ A dictionary containing the meta information.
+ """
+ path_file = os.path.join(
+ self.save_dir,
+ self.EVALUATION_META_FILE,
+ )
+ os.makedirs(os.path.dirname(path_file), exist_ok=True)
+ with open(path_file, "w", encoding="utf-8") as f:
+ json.dump(meta_info, f, ensure_ascii=False, indent=4)
+
+ def get_agent_pre_print_hook(
+ self,
+ task_id: str,
+ repeat_id: str,
+ ) -> Callable[[AgentBase, dict], None]:
+ """Get a pre-print hook function for the agent to save the agent
+ printing in the evaluation storage.
+
+ Args:
+ task_id (`str`):
+ The task ID.
+ repeat_id (`str`):
+ The repeat ID for the task, usually the index of the repeat
+ evaluation.
+
+ Returns:
+ `Callable[[AgentBase, dict], None]`:
+ A hook function that takes an `AgentBase` instance and a
+ keyword arguments dictionary as input, saving the agent's
+ printing Msg into the evaluation storage.
+ """
+
+ def pre_print_hook(_agent: AgentBase, kwargs: dict) -> None:
+ """Hook function to save agent's printing."""
+ msg: Msg | None = kwargs.get("msg", None)
+ last: bool = kwargs.get("last", False)
+
+ if msg is None or not last:
+ return
+
+ # Only save the last message
+ printing_str = []
+ for block in msg.get_content_blocks():
+ match block["type"]:
+ case "text":
+ printing_str.append(
+ f"{msg.name}: {block['text']}",
+ )
+ case "thinking":
+ printing_str.append(
+ f"{msg.name} (thinking): {block['text']}",
+ )
+ case _:
+ block_str = json.dumps(
+ block,
+ ensure_ascii=False,
+ indent=4,
+ )
+ if printing_str:
+ printing_str.append(block_str)
+ else:
+ printing_str.append(f"{msg.name}: {block_str}")
+
+ path_file = self._get_save_path(
+ task_id,
+ repeat_id,
+ self.AGENT_PRINTING_LOG,
+ )
+ os.makedirs(os.path.dirname(path_file), exist_ok=True)
+ with open(path_file, "a", encoding="utf-8") as f:
+ f.write("\n".join(printing_str) + "\n")
+
+ return pre_print_hook
diff --git a/src/agentscope/evaluate/_metric_base.py b/src/agentscope/evaluate/_metric_base.py
new file mode 100644
index 000000000..649b48d22
--- /dev/null
+++ b/src/agentscope/evaluate/_metric_base.py
@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""The base class for _metric in evaluation."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .._utils._common import _get_timestamp
+from .._utils._mixin import DictMixin
+from ..types import JSONSerializableObject
+
+
+@dataclass
+class MetricResult(DictMixin):
+ """The result of a _metric."""
+
+ name: str
+ """The metric name."""
+
+ result: str | float | int
+ """The metric result."""
+
+ created_at: str = field(default_factory=_get_timestamp)
+ """The timestamp when the metric result was created."""
+
+ message: str | None = field(default_factory=lambda: None)
+ """An optional message for the metric result, can be used to provide
+ additional information or context about the result."""
+
+ metadata: dict[str, JSONSerializableObject] | None = field(default=None)
+ """Optional metadata for the metric result, can be used to store
+ additional information related to the metric result."""
+
+
+class MetricType(str, Enum):
+ """The metric type enum."""
+
+ CATEGORY = "category"
+ """The metric result is a category, e.g. "pass" or "fail"."""
+
+ NUMERICAL = "numerical"
+ """The metric result is a numerical value, e.g. 0.95 or 100."""
+
+
+class MetricBase(ABC):
+ """The base class for _metric in evaluation."""
+
+ def __init__(
+ self,
+ name: str,
+ metric_type: MetricType,
+ description: str | None = None,
+ categories: list[str] | None = None,
+ ) -> None:
+ """Initialize the _metric object.
+
+ Args:
+ name (`str`):
+ The name of the metric.
+ metric_type (`MetricType`):
+ The type of the metric, can be either "category" or
+ "numerical", which will determine how to display the result.
+ description (`str`):
+ The description of the metric.
+ categories (`list[str] | None`, optional):
+ The candidate categories. If `metric_type` is "category", the
+ categories must be provided, otherwise it should be `None`.
+ """
+ self.name = name
+ self.metric_type = metric_type
+ self.description = description
+
+ if metric_type == MetricType.CATEGORY and categories is None:
+ raise ValueError(
+ "Categories must be provided for category metrics.",
+ )
+
+ self.categories = categories
+
+ @abstractmethod
+ def __call__(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> MetricResult:
+ """The call function to calculate the _metric result"""
diff --git a/src/agentscope/evaluate/_solution.py b/src/agentscope/evaluate/_solution.py
new file mode 100644
index 000000000..1a01a242d
--- /dev/null
+++ b/src/agentscope/evaluate/_solution.py
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""Solution class for evaluation tasks."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..message import (
+ ToolResultBlock,
+ ToolUseBlock,
+ TextBlock,
+)
+from ..types._json import JSONSerializableObject
+from .._utils._mixin import DictMixin
+
+
+@dataclass
+class SolutionOutput(DictMixin):
+ """The output of a solution in evaluation task"""
+
+ success: bool
+ """Indicates whether the solution is executed successfully. When the
+ solution raise exception, this should be set to False."""
+ output: JSONSerializableObject
+ """The final output of the solution."""
+ trajectory: list[ToolUseBlock | ToolResultBlock | TextBlock]
+ """The tool calls and results trajectory"""
+ meta: dict[str, Any] | None = field(default_factory=lambda: None)
+ """Additional metadata for the solution"""
+
+ def __getstate__(self) -> dict[str, Any]:
+ """Custom pickling to handle dataclass + DictMixin inheritance."""
+ return self.__dict__.copy()
+
+ def __setstate__(self, state: dict[str, Any]) -> None:
+ """Custom unpickling to handle dataclass + DictMixin inheritance."""
+ self.__dict__.update(state)
diff --git a/src/agentscope/evaluate/_task.py b/src/agentscope/evaluate/_task.py
new file mode 100644
index 000000000..ed33ba304
--- /dev/null
+++ b/src/agentscope/evaluate/_task.py
@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""The base class for task in evaluation."""
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._solution import SolutionOutput
+from ._metric_base import MetricBase, MetricResult
+from ..types._json import JSONSerializableObject
+
+
+@dataclass
+class Task:
+ """The base class for task in evaluation."""
+
+ id: str
+ """The unique identifier for the task."""
+
+ input: JSONSerializableObject
+ """The task input, which should be a JSON serializable object."""
+
+ ground_truth: JSONSerializableObject
+ """The task ground truth if exists, which should be a JSON serializable
+ object."""
+
+ metrics: list[MetricBase]
+ """The metrics to evaluate the task, which should be a list of
+ `MetricBase` objects."""
+
+ tags: dict[str, str] | None = field(default_factory=lambda: None)
+ """Tags to categorize the task, e.g. `{"difficulty": "easy",
+ "cate": "math"}`."""
+
+ metadata: dict[str, Any] | None = field(
+ default_factory=lambda: None,
+ )
+ """Additional metadata for the task."""
+
+ def evaluate(self, solution: SolutionOutput) -> list[MetricResult]:
+ """Evaluate the task with the given solution.
+
+ Args:
+ solution (`SolutionOutput`):
+ The solution to evaluate the task with.
+
+ Returns:
+ `MetricResult`:
+ The result of the evaluation.
+ """
+ evaluations = []
+ for metric in self.metrics:
+ result = metric(solution)
+ evaluations.append(result)
+ return evaluations
diff --git a/src/agentscope/exception/__init__.py b/src/agentscope/exception/__init__.py
new file mode 100644
index 000000000..49f6670d3
--- /dev/null
+++ b/src/agentscope/exception/__init__.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The exception module in agentscope."""
+
+from ._exception_base import AgentOrientedExceptionBase
+from ._tool import (
+ ToolInterruptedError,
+ ToolNotFoundError,
+ ToolInvalidArgumentsError,
+)
+
+__all__ = [
+ "AgentOrientedExceptionBase",
+ "ToolInterruptedError",
+ "ToolNotFoundError",
+ "ToolInvalidArgumentsError",
+]
diff --git a/src/agentscope/exception/_exception_base.py b/src/agentscope/exception/_exception_base.py
new file mode 100644
index 000000000..c00481d18
--- /dev/null
+++ b/src/agentscope/exception/_exception_base.py
@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""The base exception class in agentscope."""
+
+
+class AgentOrientedExceptionBase(Exception):
+ """The base class for all agent-oriented exceptions. These exceptions are
+ expect to the captured and exposed to the agent during runtime, so that
+ agents can handle the error appropriately during the runtime.
+ """
+
+ def __init__(self, message: str):
+ """Initialize the exception with a message."""
+ super().__init__(message)
+ self.message = message
+
+ def __str__(self) -> str:
+ """Return the string representation of the exception."""
+ return f"{self.__class__.__name__}: {self.message}"
diff --git a/src/agentscope/exception/_tool.py b/src/agentscope/exception/_tool.py
new file mode 100644
index 000000000..ac313d028
--- /dev/null
+++ b/src/agentscope/exception/_tool.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The tool-related exceptions in agentscope."""
+
+from ._exception_base import AgentOrientedExceptionBase
+
+
+class ToolNotFoundError(AgentOrientedExceptionBase):
+ """Exception raised when a tool was not found."""
+
+
+class ToolInterruptedError(AgentOrientedExceptionBase):
+ """Exception raised when a tool calling was interrupted by the user."""
+
+
+class ToolInvalidArgumentsError(AgentOrientedExceptionBase):
+ """Exception raised when the arguments passed to a tool are invalid."""
diff --git a/src/agentscope/formatter/__init__.py b/src/agentscope/formatter/__init__.py
new file mode 100644
index 000000000..7a8f5b560
--- /dev/null
+++ b/src/agentscope/formatter/__init__.py
@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""The formatter module in agentscope."""
+
+from ._formatter_base import FormatterBase
+from ._truncated_formatter_base import TruncatedFormatterBase
+from ._dashscope_formatter import (
+ DashScopeChatFormatter,
+ DashScopeMultiAgentFormatter,
+)
+from ._anthropic_formatter import (
+ AnthropicChatFormatter,
+ AnthropicMultiAgentFormatter,
+)
+from ._openai_formatter import (
+ OpenAIChatFormatter,
+ OpenAIMultiAgentFormatter,
+)
+from ._gemini_formatter import (
+ GeminiChatFormatter,
+ GeminiMultiAgentFormatter,
+)
+from ._ollama_formatter import (
+ OllamaChatFormatter,
+ OllamaMultiAgentFormatter,
+)
+from ._deepseek_formatter import (
+ DeepSeekChatFormatter,
+ DeepSeekMultiAgentFormatter,
+)
+
+__all__ = [
+ "FormatterBase",
+ "TruncatedFormatterBase",
+ "DashScopeChatFormatter",
+ "DashScopeMultiAgentFormatter",
+ "OpenAIChatFormatter",
+ "OpenAIMultiAgentFormatter",
+ "AnthropicChatFormatter",
+ "AnthropicMultiAgentFormatter",
+ "GeminiChatFormatter",
+ "GeminiMultiAgentFormatter",
+ "OllamaChatFormatter",
+ "OllamaMultiAgentFormatter",
+ "DeepSeekChatFormatter",
+ "DeepSeekMultiAgentFormatter",
+]
diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.py
new file mode 100644
index 000000000..593b8b28d
--- /dev/null
+++ b/src/agentscope/formatter/_anthropic_formatter.py
@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The Anthropic formatter module."""
+
+from typing import Any
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._logging import logger
+from ..message import Msg, TextBlock, ImageBlock, ToolUseBlock, ToolResultBlock
+from ..token import TokenCounterBase
+
+
+class AnthropicChatFormatter(TruncatedFormatterBase):
+ """Formatter for Anthropic messages."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = False
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into Anthropic API format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+
+ .. note:: Anthropic suggests always passing all previous thinking
+ blocks back to the API in subsequent calls to maintain reasoning
+ continuity. For more details, please refer to
+ `Anthropic's documentation
+ <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ messages: list[dict] = []
+ for index, msg in enumerate(msgs):
+ content_blocks = []
+
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+ if typ in ["thinking", "text", "image"]:
+ content_blocks.append({**block})
+
+ elif typ == "tool_use":
+ content_blocks.append(
+ {
+ "id": block.get("id"),
+ "type": "tool_use",
+ "name": block.get("name"),
+ "input": block.get("input", {}),
+ },
+ )
+
+ elif typ == "tool_result":
+ output = block.get("output")
+ if output is None:
+ content_value = [{"type": "text", "text": None}]
+ elif isinstance(output, list):
+ content_value = output
+ else:
+ content_value = [{"type": "text", "text": str(output)}]
+ messages.append(
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": block.get("id"),
+ "content": content_value,
+ },
+ ],
+ },
+ )
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ typ,
+ )
+
+ # Claude only allow the first message to be system message
+ if msg.role == "system" and index != 0:
+ role = "user"
+ else:
+ role = msg.role
+
+ msg_anthropic = {
+ "role": role,
+ "content": content_blocks or None,
+ }
+
+ # When both content and tool_calls are None, skipped
+ if msg_anthropic["content"] or msg_anthropic.get("tool_calls"):
+ messages.append(msg_anthropic)
+
+ return messages
+
+
+class AnthropicMultiAgentFormatter(TruncatedFormatterBase):
+ """
+ Anthropic formatter for multi-agent conversations, where more than
+ a user and an agent are involved.
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the DashScope multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to use for the conversation history section.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the Anthropic API."""
+ return await AnthropicChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the Anthropic API."""
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into required Anthropic format
+ formatted_msgs: list[dict] = []
+
+ # Collect the multimodal files
+ conversation_blocks: list = []
+ accumulated_text = []
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ elif block["type"] == "image":
+ # Handle the accumulated text as a single block
+ if accumulated_text:
+ conversation_blocks.append(
+ {
+ "text": "\n".join(accumulated_text),
+ "type": "text",
+ },
+ )
+ accumulated_text.clear()
+
+ conversation_blocks.append({**block})
+
+ if accumulated_text:
+ conversation_blocks.append(
+ {
+ "text": "\n".join(accumulated_text),
+ "type": "text",
+ },
+ )
+
+ if conversation_blocks:
+ if conversation_blocks[0].get("text"):
+ conversation_blocks[0]["text"] = (
+ conversation_history_prompt
+ + "<history>\n"
+ + conversation_blocks[0]["text"]
+ )
+
+ else:
+ conversation_blocks.insert(
+ 0,
+ {
+ "type": "text",
+ "text": conversation_history_prompt + "<history>\n",
+ },
+ )
+
+ if conversation_blocks[-1].get("text"):
+ conversation_blocks[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_blocks.append(
+ {"type": "text", "text": "</history>"},
+ )
+
+ if conversation_blocks:
+ formatted_msgs.append(
+ {
+ "role": "user",
+ "content": conversation_blocks,
+ },
+ )
+
+ return formatted_msgs
diff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.py
new file mode 100644
index 000000000..d5fd7817c
--- /dev/null
+++ b/src/agentscope/formatter/_dashscope_formatter.py
@@ -0,0 +1,426 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The dashscope formatter module."""
+
+import json
+import os.path
+from typing import Any
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._logging import logger
+from .._utils._common import _is_accessible_local_file
+from ..message import (
+ Msg,
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+from ..token import TokenCounterBase
+
+
+def _reformat_messages(
+ messages: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ """Reformat the content to be compatible with HuggingFaceTokenCounter.
+
+ This function processes a list of messages and converts multi-part
+ text content into single string content when all parts are plain text.
+ This is necessary for compatibility with HuggingFaceTokenCounter which
+ expects simple string content rather than structured content with
+ multiple parts.
+
+ Args:
+ messages (list[dict[str, Any]]):
+ A list of message dictionaries where each message may contain a
+ "content" field. The content can be either:
+ - A string (unchanged)
+ - A list of content items, where each item is a dict that may
+ contain "text", "type", and other fields
+
+ Returns:
+ list[dict[str, Any]]:
+ A list of reformatted messages. For messages where all content
+ items are plain text (have "text" field and either no "type"
+ field or "type" == "text"), the content list is converted to a
+ single newline-joined string. Other messages remain unchanged.
+
+ Example:
+ .. code-block:: python
+
+ # Case 1: All text content - will be converted
+ messages = [
+ {
+ "role": "user",
+ "content": [
+ {"text": "Hello", "type": "text"},
+ {"text": "World", "type": "text"}
+ ]
+ }
+ ]
+ result = _reformat_messages(messages)
+ print(result[0]["content"])
+ # Output: "Hello\nWorld"
+
+ # Case 2: Mixed content - will remain unchanged
+ messages = [
+ {
+ "role": "user",
+ "content": [
+ {"text": "Hello", "type": "text"},
+ {"image_url": "...", "type": "image"}
+ ]
+ }
+ ]
+
+ result = _reformat_messages(messages) # remain unchanged
+ print(type(result[0]["content"]))
+ # Output: <class 'list'>
+
+ """
+ for message in messages:
+ content = message.get("content", [])
+
+ is_all_text = True
+ texts = []
+ for item in content:
+ if not isinstance(item, dict) or "text" not in item:
+ is_all_text = False
+ break
+ if "type" in item and item["type"] != "text":
+ is_all_text = False
+ break
+ if item["text"]:
+ texts.append(item["text"])
+
+ if is_all_text and texts:
+ message["content"] = "\n".join(texts)
+
+ return messages
+
+
+class DashScopeChatFormatter(TruncatedFormatterBase):
+ """Formatter for DashScope messages."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = False
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into DashScope API format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ formatted_msgs: list[dict] = []
+ for msg in msgs:
+ content_blocks = []
+ tool_calls = []
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+
+ if typ == "text":
+ content_blocks.append(
+ {
+ "text": block.get("text"),
+ },
+ )
+
+ elif typ in ["image", "audio"]:
+ source = block["source"]
+ if source["type"] == "url":
+ url = source["url"]
+ if _is_accessible_local_file(url):
+ content_blocks.append(
+ {typ: "file://" + os.path.abspath(url)},
+ )
+ else:
+ # treat as web url
+ content_blocks.append({typ: url})
+
+ elif source["type"] == "base64":
+ media_type = source["media_type"]
+ base64_data = source["data"]
+ content_blocks.append(
+ {typ: f"data:{media_type};base64,{base64_data}"},
+ )
+
+ else:
+ raise NotImplementedError(
+ f"Unsupported source type '{source.get('type')}' "
+ f"for {typ} block.",
+ )
+
+ elif typ == "tool_use":
+ tool_calls.append(
+ {
+ "id": block.get("id"),
+ "type": "function",
+ "function": {
+ "name": block.get("name"),
+ "arguments": json.dumps(
+ block.get("input", {}),
+ ensure_ascii=False,
+ ),
+ },
+ },
+ )
+
+ elif typ == "tool_result":
+ formatted_msgs.append(
+ {
+ "role": "tool",
+ "tool_call_id": block.get("id"),
+ "content": self.convert_tool_result_to_string(
+ block.get("output"), # type: ignore[arg-type]
+ ),
+ "name": block.get("name"),
+ },
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ typ,
+ )
+
+ msg_dashscope = {
+ "role": msg.role,
+ "content": content_blocks or [{"text": None}],
+ }
+
+ if tool_calls:
+ msg_dashscope["tool_calls"] = tool_calls
+
+ if msg_dashscope["content"] != [
+ {"text": None},
+ ] or msg_dashscope.get(
+ "tool_calls",
+ ):
+ formatted_msgs.append(msg_dashscope)
+
+ return _reformat_messages(formatted_msgs)
+
+
+class DashScopeMultiAgentFormatter(TruncatedFormatterBase):
+ """DashScope formatter for multi-agent conversations, where more than
+ a user and an agent are involved.
+
+ .. note:: This formatter will combine previous messages (except tool
+ calls/results) into a history section in the first system message with
+ the conversation history prompt.
+
+ .. note:: For tool calls/results, they will be presented as separate
+ messages as required by the DashScope API. Therefore, the tool calls/
+ results messages are expected to be placed at the end of the input
+ messages.
+
+ .. tip:: Telling the assistant's name in the system prompt is very
+ important in multi-agent conversations. So that LLM can know who it
+ is playing as.
+
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ AudioBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the DashScope multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to use for the conversation history section.
+ token_counter (`TokenCounterBase | None`, optional):
+ The token counter used for truncation.
+ max_tokens (`int | None`, optional):
+ The maximum number of tokens allowed in the formatted
+ messages. If `None`, no truncation will be applied.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the DashScope API.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of messages containing tool calls/results to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the DashScope API.
+ """
+ return await DashScopeChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into a user message with conversation history tags. For the
+ first agent message, it will include the conversation history prompt.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of Msg objects to be formatted.
+ is_first (`bool`, defaults to `True`):
+ Whether this is the first agent message in the conversation.
+ If `True`, the conversation history prompt will be included.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the DashScope API.
+ """
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into required DashScope format
+ formatted_msgs: list[dict] = []
+
+ # Collect the multimodal files
+ conversation_blocks = []
+ accumulated_text = []
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ elif block["type"] in ["image", "audio"]:
+ # Handle the accumulated text as a single block
+ if accumulated_text:
+ conversation_blocks.append(
+ {"text": "\n".join(accumulated_text)},
+ )
+ accumulated_text.clear()
+
+ if block["source"]["type"] == "url":
+ url = block["source"]["url"]
+ if _is_accessible_local_file(url):
+ conversation_blocks.append(
+ {
+ block["type"]: "file://"
+ + os.path.abspath(url),
+ },
+ )
+ else:
+ conversation_blocks.append({block["type"]: url})
+
+ elif block["source"]["type"] == "base64":
+ media_type = block["source"]["media_type"]
+ base64_data = block["source"]["data"]
+ conversation_blocks.append(
+ {
+ block[
+ "type"
+ ]: f"data:{media_type};base64,{base64_data}",
+ },
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, "
+ "skipped.",
+ block["type"],
+ )
+
+ if accumulated_text:
+ conversation_blocks.append({"text": "\n".join(accumulated_text)})
+
+ if conversation_blocks:
+ if conversation_blocks[0].get("text"):
+ conversation_blocks[0]["text"] = (
+ conversation_history_prompt
+ + "<history>\n"
+ + conversation_blocks[0]["text"]
+ )
+
+ else:
+ conversation_blocks.insert(
+ 0,
+ {
+ "text": conversation_history_prompt + "<history>\n",
+ },
+ )
+
+ if conversation_blocks[-1].get("text"):
+ conversation_blocks[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_blocks.append({"text": "</history>"})
+
+ formatted_msgs.append(
+ {
+ "role": "user",
+ "content": conversation_blocks,
+ },
+ )
+
+ return _reformat_messages(formatted_msgs)
+
+ async def _format_system_message(
+ self,
+ msg: Msg,
+ ) -> dict[str, Any]:
+ """Format system message for DashScope API."""
+ return {
+ "role": "system",
+ "content": msg.get_text_content(),
+ }
diff --git a/src/agentscope/formatter/_deepseek_formatter.py b/src/agentscope/formatter/_deepseek_formatter.py
new file mode 100644
index 000000000..602c61abc
--- /dev/null
+++ b/src/agentscope/formatter/_deepseek_formatter.py
@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The DeepSeek formatter module."""
+import json
+from typing import Any
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._logging import logger
+from ..message import Msg, TextBlock, ToolUseBlock, ToolResultBlock
+from ..token import TokenCounterBase
+
+
+class DeepSeekChatFormatter(TruncatedFormatterBase):
+ """Formatter for DeepSeek messages."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = False
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = False
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into DeepSeek API format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ messages: list[dict] = []
+ for msg in msgs:
+ content_blocks: list = []
+ tool_calls = []
+
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+ if typ == "text":
+ content_blocks.append({**block})
+
+ elif typ == "tool_use":
+ tool_calls.append(
+ {
+ "id": block.get("id"),
+ "type": "function",
+ "function": {
+ "name": block.get("name"),
+ "arguments": json.dumps(
+ block.get("input", {}),
+ ensure_ascii=False,
+ ),
+ },
+ },
+ )
+
+ elif typ == "tool_result":
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": block.get("id"),
+ "content": self.convert_tool_result_to_string(
+ block.get("output"), # type: ignore[arg-type]
+ ),
+ "name": block.get("name"),
+ },
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ typ,
+ )
+ content_msg = "\n".join(
+ content.get("text", "") for content in content_blocks
+ )
+ msg_deepseek = {
+ "role": msg.role,
+ "content": content_msg or None,
+ }
+
+ if tool_calls:
+ msg_deepseek["tool_calls"] = tool_calls
+
+ if msg_deepseek["content"] or msg_deepseek.get("tool_calls"):
+ messages.append(msg_deepseek)
+
+ return messages
+
+
+class DeepSeekMultiAgentFormatter(TruncatedFormatterBase):
+ """
+ DeepSeek formatter for multi-agent conversations, where more than
+ a user and an agent are involved.
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = False
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the DeepSeek multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to use for the conversation history section.
+ token_counter (`TokenCounterBase | None`, optional):
+ A token counter instance used to count tokens in the messages.
+ If not provided, the formatter will format the messages
+ without considering token limits.
+ max_tokens (`int | None`, optional):
+ The maximum number of tokens allowed in the formatted
+ messages. If not provided, the formatter will not truncate
+ the messages.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the DeepSeek API.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of messages containing tool calls/results to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the DeepSeek API.
+ """
+ return await DeepSeekChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the DeepSeek API.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of Msg objects to be formatted.
+ is_first (`bool`, defaults to `True`):
+ Whether this is the first agent message in the conversation.
+ If `True`, the conversation history prompt will be included.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the DeepSeek API.
+ """
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into required DeepSeek format
+ formatted_msgs: list[dict] = []
+
+ conversation_blocks: list = []
+ accumulated_text = []
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ if accumulated_text:
+ conversation_blocks.append(
+ {"text": "\n".join(accumulated_text)},
+ )
+
+ if conversation_blocks:
+ if conversation_blocks[0].get("text"):
+ conversation_blocks[0]["text"] = (
+ conversation_history_prompt
+ + "<history>\n"
+ + conversation_blocks[0]["text"]
+ )
+
+ else:
+ conversation_blocks.insert(
+ 0,
+ {
+ "text": conversation_history_prompt + "<history>\n",
+ },
+ )
+
+ if conversation_blocks[-1].get("text"):
+ conversation_blocks[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_blocks.append({"text": "</history>"})
+
+ conversation_blocks_text = "\n".join(
+ conversation_block.get("text", "")
+ for conversation_block in conversation_blocks
+ )
+
+ user_message = {
+ "role": "user",
+ "content": conversation_blocks_text,
+ }
+
+ if conversation_blocks:
+ formatted_msgs.append(user_message)
+
+ return formatted_msgs
diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.py
new file mode 100644
index 000000000..2e57b1064
--- /dev/null
+++ b/src/agentscope/formatter/_formatter_base.py
@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+"""The formatter module."""
+
+from abc import abstractmethod
+from typing import Any, List
+
+from .._utils._common import _save_base64_data
+from ..message import Msg, AudioBlock, ImageBlock, TextBlock
+
+
+class FormatterBase:
+ """The base class for formatters."""
+
+ @abstractmethod
+ async def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:
+ """Format the Msg objects to a list of dictionaries that satisfy the
+ API requirements."""
+
+ @staticmethod
+ def assert_list_of_msgs(msgs: list[Msg]) -> None:
+ """Assert that the input is a list of Msg objects.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of Msg objects to be validated.
+ """
+ if not isinstance(msgs, list):
+ raise TypeError("Input must be a list of Msg objects.")
+
+ for msg in msgs:
+ if not isinstance(msg, Msg):
+ raise TypeError(
+ f"Expected Msg object, got {type(msg)} instead.",
+ )
+
+ @staticmethod
+ def convert_tool_result_to_string(
+ output: List[TextBlock | ImageBlock | AudioBlock],
+ ) -> str:
+ """Turn the tool result list into a textual output to be compatible
+ with the LLM API that doesn't support multimodal data.
+
+ Args:
+ output (`List[TextBlock | ImageBlock | AudioBlock]`):
+ The output of the tool response, including text and multimodal
+ data like images and audio.
+
+ Returns:
+ `str`:
+ A string representation of the tool result, with text blocks
+ concatenated and multimodal data represented by file paths
+ or URLs.
+ """
+
+ textual_output = []
+ for block in output:
+ assert isinstance(block, dict) and "type" in block, (
+ f"Invalid block: {block}, a TextBlock, ImageBlock, or "
+ f"AudioBlock is expected."
+ )
+ if block["type"] == "text":
+ textual_output.append(block["text"])
+
+ elif block["type"] in ["image", "audio", "video"]:
+ assert "source" in block, (
+ f"Invalid {block['type']} block: {block}, 'source' key "
+ "is required."
+ )
+ source = block["source"]
+ # Save the image locally and return the file path
+ if source["type"] == "url":
+ textual_output.append(
+ f"The returned {block['type']} can be found "
+ f"at: {source['url']}",
+ )
+
+ elif source["type"] == "base64":
+ path_temp_file = _save_base64_data(
+ source["media_type"],
+ source["data"],
+ )
+ textual_output.append(
+ f"The returned {block['type']} can be found "
+ f"at: {path_temp_file}",
+ )
+
+ else:
+ raise ValueError(
+ f"Invalid image source: {block['source']}, "
+ "expected 'url' or 'base64'.",
+ )
+
+ else:
+ raise ValueError(
+ f"Unsupported block type: {block['type']}, "
+ "expected 'text', 'image', 'audio', or 'video'.",
+ )
+
+ if len(textual_output) == 1:
+ return textual_output[0]
+
+ else:
+ return "\n".join("- " + _ for _ in textual_output)
diff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.py
new file mode 100644
index 000000000..b3aaec809
--- /dev/null
+++ b/src/agentscope/formatter/_gemini_formatter.py
@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""Google gemini API formatter in agentscope."""
+import base64
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._utils._common import _get_bytes_from_web_url
+from ..message import (
+ Msg,
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ VideoBlock,
+)
+from .._logging import logger
+from ..token import TokenCounterBase
+
+
+def _to_gemini_inline_data(url: str) -> dict:
+ """Convert url into the Gemini API required format."""
+ parsed_url = urlparse(url)
+ extension = url.split(".")[-1].lower()
+
+ if not os.path.exists(url) and parsed_url.scheme != "":
+ # Web url
+ typ = None
+ for k, v in GeminiChatFormatter.supported_extensions.items():
+ if extension in v:
+ typ = k
+ break
+ if typ is None:
+ raise TypeError(
+ f"Unsupported file extension: {extension}, expected "
+ f"{GeminiChatFormatter.supported_extensions}",
+ )
+
+ data = _get_bytes_from_web_url(url)
+ return {
+ "data": data,
+ "mime_type": f"{typ}/{extension}",
+ }
+
+ elif os.path.exists(url):
+ # Local file
+ with open(url, "rb") as f:
+ data = base64.b64encode(f.read()).decode("utf-8")
+
+ return {
+ "data": data,
+ "mime_type": f"image/{extension}",
+ }
+
+ raise ValueError(
+ f"The URL `{url}` is not a valid image URL or local file.",
+ )
+
+
+class GeminiChatFormatter(TruncatedFormatterBase):
+ """The formatter for Google Gemini API."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = False
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ VideoBlock,
+ AudioBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ supported_extensions: list[str] = {
+ "image": ["png", "jpeg", "webp", "heic", "heif"],
+ "video": [
+ "mp4",
+ "mpeg",
+ "mov",
+ "avi",
+ "x-flv",
+ "mpg",
+ "webm",
+ "wmv",
+ "3gpp",
+ ],
+ "audio": ["mp3", "wav", "aiff", "aac", "ogg", "flac"],
+ }
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict]:
+ """Format message objects into Gemini API required format."""
+ self.assert_list_of_msgs(msgs)
+
+ messages: list = []
+ for msg in msgs:
+ parts = []
+
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+ if typ == "text":
+ parts.append(
+ {
+ "text": block.get("text"),
+ },
+ )
+
+ elif typ == "tool_use":
+ parts.append(
+ {
+ "function_call": {
+ "id": block["id"],
+ "name": block["name"],
+ "args": block["input"],
+ },
+ },
+ )
+
+ elif typ == "tool_result":
+ text_output = self.convert_tool_result_to_string(
+ block["output"], # type: ignore[arg-type]
+ )
+ messages.append(
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": block["id"],
+ "name": block["name"],
+ "response": {
+ "output": text_output,
+ },
+ },
+ },
+ ],
+ },
+ )
+
+ elif typ in ["image", "audio", "video"]:
+ if block["source"]["type"] == "base64":
+ media_type = block["source"]["media_type"]
+ base64_data = block["source"]["data"]
+
+ parts.append(
+ {
+ "inline_data": {
+ "data": base64_data,
+ "mime_type": media_type,
+ },
+ },
+ )
+
+ elif block["source"]["type"] == "url":
+ parts.append(
+ {
+ "inline_data": _to_gemini_inline_data(
+ block["source"]["url"],
+ ),
+ },
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type: %s in the message, skipped. ",
+ typ,
+ )
+
+ role = "model" if msg.role == "assistant" else "user"
+
+ if parts:
+ messages.append(
+ {
+ "role": role,
+ "parts": parts,
+ },
+ )
+
+ return messages
+
+
+class GeminiMultiAgentFormatter(TruncatedFormatterBase):
+ """The multi-agent formatter for Google Gemini API, where more than a
+ user and an agent are involved.
+
+ .. note:: This formatter will combine previous messages (except tool
+ calls/results) into a history section in the first system message with
+ the conversation history prompt.
+
+ .. note:: For tool calls/results, they will be presented as separate
+ messages as required by the Gemini API. Therefore, the tool calls/
+ results messages are expected to be placed at the end of the input
+ messages.
+
+ .. tip:: Telling the assistant's name in the system prompt is very
+ important in multi-agent conversations. So that LLM can know who it
+ is playing as.
+
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ VideoBlock,
+ AudioBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the Gemini multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to be used for the conversation history section.
+ token_counter (`TokenCounterBase | None`, optional):
+ The token counter used for truncation.
+ max_tokens (`int | None`, optional):
+ The maximum number of tokens allowed in the formatted
+ messages. If `None`, no truncation will be applied.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_system_message(
+ self,
+ msg: Msg,
+ ) -> dict[str, Any]:
+ """Format system message for the Gemini API."""
+ return {
+ "role": "user",
+ "parts": [
+ {
+ "text": msg.get_text_content(),
+ },
+ ],
+ }
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the Gemini API.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of messages containing tool calls/results to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the Gemini API.
+ """
+ return await GeminiChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the Gemini API.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of Msg objects to be formatted.
+ is_first (`bool`, defaults to `True`):
+ Whether this is the first agent message in the conversation.
+ If `True`, the conversation history prompt will be included.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the Gemini API.
+ """
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into Gemini API required format
+ formatted_msgs: list = []
+
+ # Collect the multimodal files
+ conversation_parts: list = []
+ accumulated_text = []
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ elif block["type"] in ["image", "video", "audio"]:
+ # handle the accumulated text as a single part if exists
+ if accumulated_text:
+ conversation_parts.append(
+ {
+ "text": "\n".join(accumulated_text),
+ },
+ )
+ accumulated_text.clear()
+
+ # handle the multimodal data
+ if block["source"]["type"] == "url":
+ conversation_parts.append(
+ {
+ "inline_data": _to_gemini_inline_data(
+ block["source"]["url"],
+ ),
+ },
+ )
+
+ elif block["source"]["type"] == "base64":
+ media_type = block["source"]["media_type"]
+ base64_data = block["source"]["data"]
+ conversation_parts.append(
+ {
+ "inline_data": {
+ "data": base64_data,
+ "mime_type": media_type,
+ },
+ },
+ )
+
+ if accumulated_text:
+ conversation_parts.append(
+ {
+ "text": "\n".join(accumulated_text),
+ },
+ )
+
+ # Add prompt and <history></history> tags around conversation history
+ if conversation_parts:
+ if conversation_parts[0].get("text"):
+ conversation_parts[0]["text"] = (
+ conversation_history_prompt
+ + "<history>"
+ + conversation_parts[0]["text"]
+ )
+
+ else:
+ conversation_parts.insert(
+ 0,
+ {"text": conversation_history_prompt + "<history>"},
+ )
+
+ if conversation_parts[-1].get("text"):
+ conversation_parts[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_parts.append(
+ {"text": "</history>"},
+ )
+
+ formatted_msgs.append(
+ {
+ "role": "user",
+ "parts": conversation_parts,
+ },
+ )
+
+ return formatted_msgs
diff --git a/src/agentscope/formatter/_ollama_formatter.py b/src/agentscope/formatter/_ollama_formatter.py
new file mode 100644
index 000000000..d12d8786a
--- /dev/null
+++ b/src/agentscope/formatter/_ollama_formatter.py
@@ -0,0 +1,320 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The Ollama formatter module."""
+import base64
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._logging import logger
+from .._utils._common import _get_bytes_from_web_url
+from ..message import Msg, TextBlock, ImageBlock, ToolUseBlock, ToolResultBlock
+from ..token import TokenCounterBase
+
+
+def _convert_ollama_image_url_to_base64_data(url: str) -> str:
+ """Convert image url to base64."""
+ parsed_url = urlparse(url)
+
+ if not os.path.exists(url) and parsed_url.scheme != "":
+ # Web url
+ data = _get_bytes_from_web_url(url)
+ return data
+ if os.path.exists(url):
+ # Local file
+ with open(url, "rb") as f:
+ data = base64.b64encode(f.read()).decode("utf-8")
+
+ return data
+
+ raise ValueError(
+ f"The URL `{url}` is not a valid image URL or local file.",
+ )
+
+
+class OllamaChatFormatter(TruncatedFormatterBase):
+ """Formatter for Ollama messages."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = False
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into Ollama API format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of message objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages as a list of dictionaries.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ messages: list[dict] = []
+ for msg in msgs:
+ content_blocks: list = []
+ tool_calls = []
+ images = []
+
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+ if typ == "text":
+ content_blocks.append({**block})
+
+ elif typ == "tool_use":
+ tool_calls.append(
+ {
+ "id": block.get("id"),
+ "type": "function",
+ "function": {
+ "name": block.get("name"),
+ "arguments": block.get("input", {}),
+ },
+ },
+ )
+
+ elif typ == "tool_result":
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": block.get("id"),
+ "content": self.convert_tool_result_to_string(
+ block.get("output"), # type: ignore[arg-type]
+ ),
+ "name": block.get("name"),
+ },
+ )
+
+ elif typ == "image":
+ source_type = block["source"]["type"]
+ if source_type == "url":
+ images.append(
+ _convert_ollama_image_url_to_base64_data(
+ block["source"]["url"],
+ ),
+ )
+ elif source_type == "base64":
+ images.append(block["source"]["data"])
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ typ,
+ )
+ content_msg = "\n".join(
+ content.get("text", "") for content in content_blocks
+ )
+ msg_ollama = {
+ "role": msg.role,
+ "content": content_msg or None,
+ }
+
+ if tool_calls:
+ msg_ollama["tool_calls"] = tool_calls
+
+ if images:
+ msg_ollama["images"] = images
+
+ if msg_ollama["content"] or msg_ollama.get("tool_calls"):
+ messages.append(msg_ollama)
+
+ return messages
+
+
+class OllamaMultiAgentFormatter(TruncatedFormatterBase):
+ """
+ Ollama formatter for multi-agent conversations, where more than
+ a user and an agent are involved.
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversations"""
+
+ support_vision: bool = True
+ """Whether support vision data"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ # Multimodal
+ ImageBlock,
+ # Tool use
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """The list of supported message blocks"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the Ollama multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to use for the conversation history section.
+ token_counter (`TokenCounterBase | None`, optional):
+ The token counter used for truncation.
+ max_tokens (`int | None`, optional):
+ The maximum number of tokens allowed in the formatted
+ messages. If `None`, no truncation will be applied.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_system_message(
+ self,
+ msg: Msg,
+ ) -> dict[str, Any]:
+ """Format system message for the Ollama API."""
+ return {
+ "role": "system",
+ "content": msg.get_text_content(),
+ }
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the Ollama API.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of messages containing tool calls/results to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the Ollama API.
+ """
+ return await OllamaChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the Ollama API.
+
+ Args:
+ msgs (`list[Msg]`):
+ A list of Msg objects to be formatted.
+ is_first (`bool`, defaults to `True`):
+ Whether this is the first agent message in the conversation.
+ If `True`, the conversation history prompt will be included.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries formatted for the ollama API.
+ """
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into required Ollama format
+ formatted_msgs: list[dict] = []
+
+ # Collect the multimodal files
+ conversation_blocks: list = []
+ accumulated_text = []
+ images = []
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ elif block["type"] == "image":
+ # Handle the accumulated text as a single block
+ source = block["source"]
+ if accumulated_text:
+ conversation_blocks.append(
+ {"text": "\n".join(accumulated_text)},
+ )
+ accumulated_text.clear()
+
+ if source["type"] == "url":
+ images.append(
+ _convert_ollama_image_url_to_base64_data(
+ source["url"],
+ ),
+ )
+
+ elif source["type"] == "base64":
+ images.append(source["data"])
+
+ conversation_blocks.append({**block})
+
+ if accumulated_text:
+ conversation_blocks.append(
+ {"text": "\n".join(accumulated_text)},
+ )
+
+ if conversation_blocks:
+ if conversation_blocks[0].get("text"):
+ conversation_blocks[0]["text"] = (
+ conversation_history_prompt
+ + "<history>\n"
+ + conversation_blocks[0]["text"]
+ )
+
+ else:
+ conversation_blocks.insert(
+ 0,
+ {
+ "text": conversation_history_prompt + "<history>\n",
+ },
+ )
+
+ if conversation_blocks[-1].get("text"):
+ conversation_blocks[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_blocks.append({"text": "</history>"})
+
+ conversation_blocks_text = "\n".join(
+ conversation_block.get("text", "")
+ for conversation_block in conversation_blocks
+ )
+
+ user_message = {
+ "role": "user",
+ "content": conversation_blocks_text,
+ }
+ if images:
+ user_message["images"] = images
+ if conversation_blocks:
+ formatted_msgs.append(user_message)
+
+ return formatted_msgs
diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.py
new file mode 100644
index 000000000..69c4ec782
--- /dev/null
+++ b/src/agentscope/formatter/_openai_formatter.py
@@ -0,0 +1,414 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The OpenAI formatter for agentscope."""
+import base64
+import json
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+
+from ._truncated_formatter_base import TruncatedFormatterBase
+from .._logging import logger
+from ..message import (
+ Msg,
+ URLSource,
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ Base64Source,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+from ..token import TokenCounterBase
+
+
+def _to_openai_image_url(url: str) -> str:
+ """Convert an image url to openai format. If the given url is a local
+ file, it will be converted to base64 format. Otherwise, it will be
+ returned directly.
+
+ Args:
+ url (`str`):
+ The local or public url of the image.
+ """
+ # See https://platform.openai.com/docs/guides/vision for details of
+ # support image extensions.
+ support_image_extensions = (
+ ".png",
+ ".jpg",
+ ".jpeg",
+ ".gif",
+ ".webp",
+ )
+
+ parsed_url = urlparse(url)
+
+ lower_url = url.lower()
+
+ # Web url
+ if not os.path.exists(url) and parsed_url.scheme != "":
+ if any(lower_url.endswith(_) for _ in support_image_extensions):
+ return url
+
+ # Check if it is a local file
+ elif os.path.exists(url) and os.path.isfile(url):
+ if any(lower_url.endswith(_) for _ in support_image_extensions):
+ with open(url, "rb") as image_file:
+ base64_image = base64.b64encode(image_file.read()).decode(
+ "utf-8",
+ )
+ extension = parsed_url.path.lower().split(".")[-1]
+ mime_type = f"image/{extension}"
+ return f"data:{mime_type};base64,{base64_image}"
+
+ raise TypeError(f'"{url}" should end with {support_image_extensions}.')
+
+
+def _to_openai_audio_data(source: URLSource | Base64Source) -> dict:
+ """Covert an audio source to OpenAI format."""
+ if source["type"] == "url":
+ extension = source["url"].split(".")[-1].lower()
+ if extension not in ["wav", "mp3"]:
+ raise TypeError(
+ f"Unsupported audio file extension: {extension}, "
+ "wav and mp3 are supported.",
+ )
+
+ parsed_url = urlparse(source["url"])
+
+ if os.path.exists(source["url"]):
+ with open(source["url"], "rb") as audio_file:
+ data = base64.b64encode(audio_file.read()).decode("utf-8")
+
+ # web url
+ elif parsed_url.scheme != "":
+ response = requests.get(source["url"])
+ response.raise_for_status()
+ data = base64.b64encode(response.content).decode("utf-8")
+
+ else:
+ raise ValueError(
+ f"Unsupported audio source: {source['url']}, "
+ "it should be a local file or a web URL.",
+ )
+
+ return {
+ "data": data,
+ "format": extension,
+ }
+
+ if source["type"] == "base64":
+ data = source["data"]
+ media_type = source["media_type"]
+
+ if media_type not in ["audio/wav", "audio/mp3"]:
+ raise TypeError(
+ f"Unsupported audio media type: {media_type}, "
+ "only audio/wav and audio/mp3 are supported.",
+ )
+
+ return {
+ "data": data,
+ "format": media_type.split("/")[-1],
+ }
+
+ raise TypeError(f"Unsupported audio source: {source['type']}.")
+
+
+class OpenAIChatFormatter(TruncatedFormatterBase):
+ """The class used to format message objects into the OpenAI API required
+ format."""
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversation"""
+
+ support_vision: bool = True
+ """Whether support vision models"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """Supported message blocks for OpenAI API"""
+
+ async def _format(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Format message objects into OpenAI API required format.
+
+ Args:
+ msgs (`list[Msg]`):
+ The list of Msg objects to format.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ A list of dictionaries, where each dictionary has "name",
+ "role", and "content" keys.
+ """
+ self.assert_list_of_msgs(msgs)
+
+ messages: list[dict] = []
+ for msg in msgs:
+ content_blocks = []
+ tool_calls = []
+
+ for block in msg.get_content_blocks():
+ typ = block.get("type")
+ if typ == "text":
+ content_blocks.append({**block})
+
+ elif typ == "tool_use":
+ tool_calls.append(
+ {
+ "id": block.get("id"),
+ "type": "function",
+ "function": {
+ "name": block.get("name"),
+ "arguments": json.dumps(
+ block.get("input", {}),
+ ensure_ascii=False,
+ ),
+ },
+ },
+ )
+
+ elif typ == "tool_result":
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": block.get("id"),
+ "content": self.convert_tool_result_to_string(
+ block.get("output"), # type: ignore[arg-type]
+ ),
+ "name": block.get("name"),
+ },
+ )
+
+ elif typ == "image":
+ source_type = block["source"]["type"]
+ if source_type == "url":
+ url = _to_openai_image_url(block["source"]["url"])
+
+ elif source_type == "base64":
+ data = block["source"]["data"]
+ media_type = block["source"]["media_type"]
+ url = f"data:{media_type};base64,{data}"
+
+ else:
+ raise ValueError(
+ f"Unsupported image source type: {source_type}",
+ )
+
+ content_blocks.append(
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": url,
+ },
+ },
+ )
+
+ elif typ == "audio":
+ input_audio = _to_openai_audio_data(block["source"])
+ content_blocks.append(
+ {
+ "type": "input_audio",
+ "input_audio": input_audio,
+ },
+ )
+
+ else:
+ logger.warning(
+ "Unsupported block type %s in the message, skipped.",
+ typ,
+ )
+
+ msg_openai = {
+ "role": msg.role,
+ "name": msg.name,
+ "content": content_blocks or None,
+ }
+
+ if tool_calls:
+ msg_openai["tool_calls"] = tool_calls
+
+ # When both content and tool_calls are None, skipped
+ if msg_openai["content"] or msg_openai.get("tool_calls"):
+ messages.append(msg_openai)
+
+ return messages
+
+
+class OpenAIMultiAgentFormatter(TruncatedFormatterBase):
+ """
+ OpenAI formatter for multi-agent conversations, where more than
+ a user and an agent are involved.
+ .. tip:: This formatter is compatible with OpenAI API and
+ OpenAI-compatible services like vLLM, Azure OpenAI, and others.
+ """
+
+ support_tools_api: bool = True
+ """Whether support tools API"""
+
+ support_multiagent: bool = True
+ """Whether support multi-agent conversation"""
+
+ support_vision: bool = True
+ """Whether support vision models"""
+
+ supported_blocks: list[type] = [
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ ]
+ """Supported message blocks for OpenAI API"""
+
+ def __init__(
+ self,
+ conversation_history_prompt: str = (
+ "# Conversation History\n"
+ "The content between <history></history> tags contains "
+ "your conversation history\n"
+ ),
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the OpenAI multi-agent formatter.
+
+ Args:
+ conversation_history_prompt (`str`):
+ The prompt to use for the conversation history section.
+ """
+ super().__init__(token_counter=token_counter, max_tokens=max_tokens)
+ self.conversation_history_prompt = conversation_history_prompt
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the OpenAI API."""
+ return await OpenAIChatFormatter().format(msgs)
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the OpenAI API."""
+
+ if is_first:
+ conversation_history_prompt = self.conversation_history_prompt
+ else:
+ conversation_history_prompt = ""
+
+ # Format into required OpenAI format
+ formatted_msgs: list[dict] = []
+
+ conversation_blocks: list = []
+ accumulated_text = []
+ images = []
+ audios = []
+
+ for msg in msgs:
+ for block in msg.get_content_blocks():
+ if block["type"] == "text":
+ accumulated_text.append(f"{msg.name}: {block['text']}")
+
+ elif block["type"] == "image":
+ source_type = block["source"]["type"]
+ if source_type == "url":
+ url = _to_openai_image_url(block["source"]["url"])
+
+ elif source_type == "base64":
+ data = block["source"]["data"]
+ media_type = block["source"]["media_type"]
+ url = f"data:{media_type};base64,{data}"
+
+ else:
+ raise ValueError(
+ f"Unsupported image source type: {source_type}",
+ )
+ images.append(
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": url,
+ },
+ },
+ )
+ elif block["type"] == "audio":
+ input_audio = _to_openai_audio_data(block["source"])
+ audios.append(
+ {
+ "type": "input_audio",
+ "input_audio": input_audio,
+ },
+ )
+
+ if accumulated_text:
+ conversation_blocks.append(
+ {"text": "\n".join(accumulated_text)},
+ )
+
+ if conversation_blocks:
+ if conversation_blocks[0].get("text"):
+ conversation_blocks[0]["text"] = (
+ conversation_history_prompt
+ + "<history>\n"
+ + conversation_blocks[0]["text"]
+ )
+
+ else:
+ conversation_blocks.insert(
+ 0,
+ {
+ "text": conversation_history_prompt + "<history>\n",
+ },
+ )
+
+ if conversation_blocks[-1].get("text"):
+ conversation_blocks[-1]["text"] += "\n</history>"
+
+ else:
+ conversation_blocks.append({"text": "</history>"})
+
+ conversation_blocks_text = "\n".join(
+ conversation_block.get("text", "")
+ for conversation_block in conversation_blocks
+ )
+
+ content_list: list[dict[str, Any]] = []
+ if conversation_blocks_text:
+ content_list.append(
+ {
+ "type": "text",
+ "text": conversation_blocks_text,
+ },
+ )
+ if images:
+ content_list.extend(images)
+ if audios:
+ content_list.extend(audios)
+
+ user_message = {
+ "role": "user",
+ "content": content_list,
+ }
+
+ if content_list:
+ formatted_msgs.append(user_message)
+
+ return formatted_msgs
diff --git a/src/agentscope/formatter/_truncated_formatter_base.py b/src/agentscope/formatter/_truncated_formatter_base.py
new file mode 100644
index 000000000..86d42ad41
--- /dev/null
+++ b/src/agentscope/formatter/_truncated_formatter_base.py
@@ -0,0 +1,297 @@
+# -*- coding: utf-8 -*-
+"""The truncated formatter base class, which allows to truncate the input
+messages."""
+from abc import ABC
+from copy import deepcopy
+from typing import (
+ Any,
+ Tuple,
+ Literal,
+ AsyncGenerator,
+)
+
+from ._formatter_base import FormatterBase
+from ..message import Msg
+from ..token import TokenCounterBase
+from ..tracing import trace_format
+
+
+class TruncatedFormatterBase(FormatterBase, ABC):
+ """Base class for truncated formatters, which formats input messages into
+ required formats with tokens under a specified limit."""
+
+ def __init__(
+ self,
+ token_counter: TokenCounterBase | None = None,
+ max_tokens: int | None = None,
+ ) -> None:
+ """Initialize the TruncatedFormatterBase.
+
+ Args:
+ token_counter (`TokenCounterBase | None`, optional):
+ A token counter instance used to count tokens in the messages.
+ If not provided, the formatter will format the messages
+ without considering token limits.
+ max_tokens (`int | None`, optional):
+ The maximum number of tokens allowed in the formatted
+ messages. If not provided, the formatter will not truncate
+ the messages.
+ """
+ self.token_counter = token_counter
+
+ assert (
+ max_tokens is None or 0 < max_tokens
+ ), "max_tokens must be greater than 0"
+ self.max_tokens = max_tokens
+
+ @trace_format
+ async def format(
+ self,
+ msgs: list[Msg],
+ **kwargs: Any,
+ ) -> list[dict[str, Any]]:
+ """Format the input messages into the required format. If token
+ counter and max token limit are provided, the messages will be
+ truncated to fit the limit.
+
+ Args:
+ msgs (`list[Msg]`):
+ The input messages to be formatted.
+
+ Returns:
+ `list[dict[str, Any]]`:
+ The formatted messages in the required format.
+ """
+
+ # Check if the input messages are valid
+ self.assert_list_of_msgs(msgs)
+
+ msgs = deepcopy(msgs)
+
+ while True:
+ formatted_msgs = await self._format(msgs)
+ n_tokens = await self._count(formatted_msgs)
+
+ if (
+ n_tokens is None
+ or self.max_tokens is None
+ or n_tokens <= self.max_tokens
+ ):
+ return formatted_msgs
+
+ # truncate the input messages
+ msgs = await self._truncate(msgs)
+
+ async def _format(self, msgs: list[Msg]) -> list[dict[str, Any]]:
+ """Format the input messages into the required format. This method
+ should be implemented by the subclasses."""
+
+ formatted_msgs = []
+ start_index = 0
+ if len(msgs) > 0 and msgs[0].role == "system":
+ formatted_msgs.append(
+ await self._format_system_message(msgs[0]),
+ )
+ start_index = 1
+
+ is_first_agent_message = True
+ async for typ, group in self._group_messages(msgs[start_index:]):
+ match typ:
+ case "tool_sequence":
+ formatted_msgs.extend(
+ await self._format_tool_sequence(group),
+ )
+ case "agent_message":
+ formatted_msgs.extend(
+ await self._format_agent_message(
+ group,
+ is_first_agent_message,
+ ),
+ )
+ is_first_agent_message = False
+
+ return formatted_msgs
+
+ async def _format_system_message(
+ self,
+ msg: Msg,
+ ) -> dict[str, Any]:
+ """Format system message for the LLM API.
+
+ .. note:: This is the default implementation. For certain LLM APIs
+ with specific requirements, you may need to implement a custom
+ formatting function to accommodate those particular needs.
+ """
+ return {
+ "role": "system",
+ "content": msg.get_content_blocks("text"),
+ }
+
+ async def _format_tool_sequence(
+ self,
+ msgs: list[Msg],
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of tool call/result messages, format them into
+ the required format for the LLM API."""
+ raise NotImplementedError(
+ "_format_tool_sequence is not implemented",
+ )
+
+ async def _format_agent_message(
+ self,
+ msgs: list[Msg],
+ is_first: bool = True,
+ ) -> list[dict[str, Any]]:
+ """Given a sequence of messages without tool calls/results, format
+ them into the required format for the LLM API."""
+ raise NotImplementedError(
+ "_format_agent_message is not implemented",
+ )
+
+ async def _truncate(self, msgs: list[Msg]) -> list[Msg]:
+ """Truncate the input messages, so that it can fit the token limit.
+ This function is called only when
+
+ - both `token_counter` and `max_tokens` are provided,
+ - the formatted output of the input messages exceeds the token limit.
+
+ .. tip:: This function only provides a simple strategy, and developers
+ can override this method to implement more sophisticated
+ truncation strategies.
+
+ .. note:: The tool call message should be truncated together with
+ its corresponding tool result message to satisfy the LLM API
+ requirements.
+
+ Args:
+ msgs (`list[Msg]`):
+ The input messages to be truncated.
+
+ Raises:
+ `ValueError`:
+ If the system prompt message already exceeds the token limit,
+ or if there are tool calls without corresponding tool results.
+
+ Returns:
+ `list[Msg]`:
+ The truncated messages.
+ """
+ start_index = 0
+ if len(msgs) > 0 and msgs[0].role == "system":
+ if len(msgs) == 1:
+ # If the system prompt already exceeds the token limit, we
+ # raise an error.
+ raise ValueError(
+ f"The system prompt message already exceeds the token "
+ f"limit ({self.max_tokens} tokens).",
+ )
+
+ start_index = 1
+
+ # Create a tool call IDs queues to delete the corresponding tool
+ # result message
+ tool_call_ids = set()
+ for i in range(start_index, len(msgs)):
+ msg = msgs[i]
+ for block in msg.get_content_blocks("tool_use"):
+ tool_call_ids.add(block["id"])
+
+ for block in msg.get_content_blocks("tool_result"):
+ try:
+ tool_call_ids.remove(block["id"])
+ except KeyError:
+ pass
+
+ # We can stop truncating if the queue is empty
+ if len(tool_call_ids) == 0:
+ return msgs[:start_index] + msgs[i + 1 :]
+
+ if len(tool_call_ids) > 0:
+ raise ValueError(
+ "The input messages contains tool call(s) that do not have "
+ f"the corresponding tool result(s): {tool_call_ids}. ",
+ )
+
+ return msgs[:start_index]
+
+ async def _count(self, msgs: list[dict[str, Any]]) -> int | None:
+ """Count the number of tokens in the input messages. If token counter
+ is not provided, `None` will be returned.
+
+ Args:
+ msgs (`list[Msg]`):
+ The input messages to count tokens for.
+ """
+ if self.token_counter is None:
+ return None
+
+ return await self.token_counter.count(msgs)
+
+ @staticmethod
+ async def _group_messages(
+ msgs: list[Msg],
+ ) -> AsyncGenerator[
+ Tuple[Literal["tool_sequence", "agent_message"], list[Msg]],
+ None,
+ ]:
+ """Group the input messages into two types and yield them as a
+ generator. The two types are:
+
+ - agent message that doesn't contain tool calls/results, and
+ - tool sequence that consisted of a sequence of tool calls/results
+
+ .. note:: The group operation is used in multi-agent scenario, where
+ multiple entities are involved in the input messages. So that to be
+ compatible with tools API, we have to group the messages and format
+ them with different strategies.
+
+ Args:
+ msgs (`list[Msg]`):
+ The input messages to be grouped, where the system prompt
+ message shouldn't be included.
+
+ Yields:
+ `AsyncGenerator[Tuple[str, list[Msg]], None]`:
+ A generator that yields tuples of group type and the list of
+ messages in that group. The group type can be either
+ "tool_sequence" or "agent_message".
+ """
+
+ group_type: Literal["tool_sequence", "agent_message"] | None = None
+ group = []
+ for msg in msgs:
+ if group_type is None:
+ if msg.has_content_blocks(
+ "tool_use",
+ ) or msg.has_content_blocks("tool_result"):
+ group_type = "tool_sequence"
+ else:
+ group_type = "agent_message"
+
+ group.append(msg)
+ continue
+
+ # determine if this msg has the same type as the current group
+ if group_type == "tool_sequence":
+ if msg.has_content_blocks(
+ "tool_use",
+ ) or msg.has_content_blocks("tool_result"):
+ group.append(msg)
+
+ else:
+ yield group_type, group
+ group = [msg]
+ group_type = "agent_message"
+
+ elif group_type == "agent_message":
+ if msg.has_content_blocks(
+ "tool_use",
+ ) or msg.has_content_blocks("tool_result"):
+ yield group_type, group
+ group = [msg]
+ group_type = "tool_sequence"
+
+ else:
+ group.append(msg)
+ if group_type:
+ yield group_type, group
diff --git a/src/agentscope/hooks/__init__.py b/src/agentscope/hooks/__init__.py
new file mode 100644
index 000000000..6893abc5b
--- /dev/null
+++ b/src/agentscope/hooks/__init__.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The built-in hook functions in agentscope."""
+from functools import partial
+
+from ._studio_hooks import (
+ as_studio_forward_message_pre_print_hook,
+)
+from .. import _config
+from ..agent import AgentBase
+
+
+__all__ = [
+ "as_studio_forward_message_pre_print_hook",
+]
+
+
+def _equip_as_studio_hooks(
+ studio_url: str,
+) -> None:
+ """Connect to the agentscope studio."""
+ AgentBase.register_class_hook(
+ "pre_print",
+ "as_studio_forward_message_pre_print_hook",
+ partial(
+ as_studio_forward_message_pre_print_hook,
+ studio_url=studio_url,
+ run_id=_config.run_id,
+ ),
+ )
diff --git a/src/agentscope/hooks/_studio_hooks.py b/src/agentscope/hooks/_studio_hooks.py
new file mode 100644
index 000000000..28f6dfcf3
--- /dev/null
+++ b/src/agentscope/hooks/_studio_hooks.py
@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+"""The studio related hook functions in agentscope."""
+from typing import Any
+
+import requests
+import shortuuid
+
+from ..agent import AgentBase
+
+
+def as_studio_forward_message_pre_print_hook(
+ self: AgentBase,
+ kwargs: dict[str, Any],
+ studio_url: str,
+ run_id: str,
+) -> None:
+ """The pre-speak hook to forward messages to the studio."""
+ msg = kwargs["msg"]
+
+ message_data = msg.to_dict()
+
+ if hasattr(self, "_reply_id"):
+ reply_id = getattr(self, "_reply_id")
+ else:
+ reply_id = shortuuid.uuid()
+
+ n_retry = 0
+ while True:
+ try:
+ res = requests.post(
+ f"{studio_url}/trpc/pushMessage",
+ json={
+ "runId": run_id,
+ "replyId": reply_id,
+ "name": reply_id,
+ "role": "assistant",
+ "msg": message_data,
+ },
+ )
+ res.raise_for_status()
+ break
+ except Exception as e:
+ if n_retry < 3:
+ n_retry += 1
+ continue
+
+ raise e from None
diff --git a/src/agentscope/mcp/__init__.py b/src/agentscope/mcp/__init__.py
new file mode 100644
index 000000000..1ede1344a
--- /dev/null
+++ b/src/agentscope/mcp/__init__.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The MCP module in AgentScope, that provides fine-grained control over
+the MCP servers."""
+
+from ._client_base import MCPClientBase
+from ._mcp_function import MCPToolFunction
+from ._stateful_client_base import StatefulClientBase
+from ._stdio_stateful_client import StdIOStatefulClient
+from ._http_stateless_client import HttpStatelessClient
+from ._http_stateful_client import HttpStatefulClient
+
+
+__all__ = [
+ "MCPToolFunction",
+ "MCPClientBase",
+ "StatefulClientBase",
+ "StdIOStatefulClient",
+ "HttpStatelessClient",
+ "HttpStatefulClient",
+]
diff --git a/src/agentscope/mcp/_client_base.py b/src/agentscope/mcp/_client_base.py
new file mode 100644
index 000000000..36013337b
--- /dev/null
+++ b/src/agentscope/mcp/_client_base.py
@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""The base class for MCP clients in AgentScope."""
+from abc import abstractmethod
+from typing import Callable, List
+
+import mcp.types
+
+from .._logging import logger
+from ..message import ImageBlock, Base64Source, AudioBlock, TextBlock
+
+
+class MCPClientBase:
+ """Base class for MCP clients."""
+
+ def __init__(self, name: str) -> None:
+ """Initialize the MCP client with a name.
+
+ Args:
+ name (`str`):
+ The name to identify the MCP server, which should be unique
+ across the MCP servers.
+ """
+ self.name = name
+
+ @abstractmethod
+ async def get_callable_function(
+ self,
+ func_name: str,
+ wrap_tool_result: bool = True,
+ ) -> Callable:
+ """Get a tool function by its name."""
+
+ @staticmethod
+ def _convert_mcp_content_to_as_blocks(
+ mcp_content_blocks: list,
+ ) -> List[TextBlock | ImageBlock | AudioBlock]:
+ """Convert MCP content to AgentScope blocks."""
+
+ as_content: list = []
+ for content in mcp_content_blocks:
+ if isinstance(content, mcp.types.TextContent):
+ as_content.append(
+ TextBlock(
+ type="text",
+ text=content.text,
+ ),
+ )
+ elif isinstance(content, mcp.types.ImageContent):
+ as_content.append(
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type=content.mimeType,
+ data=content.data,
+ ),
+ ),
+ )
+ elif isinstance(content, mcp.types.AudioContent):
+ as_content.append(
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type=content.mimeType,
+ data=content.data,
+ ),
+ ),
+ )
+ else:
+ logger.warning(
+ "Unsupported content type: %s. Skipping this content.",
+ type(content),
+ )
+ return as_content
diff --git a/src/agentscope/mcp/_http_stateful_client.py b/src/agentscope/mcp/_http_stateful_client.py
new file mode 100644
index 000000000..05f37438d
--- /dev/null
+++ b/src/agentscope/mcp/_http_stateful_client.py
@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""The MCP stateful HTTP client module in AgentScope."""
+from typing import Any, Literal
+
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
+
+from ._stateful_client_base import StatefulClientBase
+
+
+class HttpStatefulClient(StatefulClientBase):
+ """The stateful sse/streamable HTTP MCP client implementation in
+ AgentScope.
+
+ .. tip:: The stateful client is recommended for MCP servers that need to
+ maintain session states, e.g. web browsers or other interactive
+ MCP servers.
+
+ .. note:: The stateful client will maintain one session across multiple
+ tool calls, until the client is closed by explicitly calling the
+ `close()` method.
+ """
+
+ def __init__(
+ self,
+ name: str,
+ transport: Literal["streamable_http", "sse"],
+ url: str,
+ headers: dict[str, str] | None = None,
+ timeout: float = 30,
+ sse_read_timeout: float = 60 * 5,
+ **client_kwargs: Any,
+ ) -> None:
+ """Initialize the streamable HTTP MCP client.
+
+ Args:
+ name (`str`):
+ The name to identify the MCP server, which should be unique
+ across the MCP servers.
+ transport (`Literal["streamable_http", "sse"]`):
+ The transport type of MCP server. Generally, the URL of sse
+ transport should end with `/sse`, while the streamable HTTP
+ URL ends with `/mcp`.
+ url (`str`):
+ The URL to the MCP server.
+ headers (`dict[str, str] | None`, optional):
+ Additional headers to include in the HTTP request.
+ timeout (`float`, optional):
+ The timeout for the HTTP request in seconds. Defaults to 30.
+ sse_read_timeout (`float`, optional):
+ The timeout for reading Server-Sent Events (SSE) in seconds.
+ Defaults to 300 (5 minutes).
+ **client_kwargs (`Any`):
+ The additional keyword arguments to pass to the streamable
+ HTTP client.
+ """
+ super().__init__(name=name)
+
+ assert transport in ["streamable_http", "sse"]
+ self.transport = transport
+
+ if self.transport == "streamable_http":
+ self.client = streamablehttp_client(
+ url=url,
+ headers=headers,
+ timeout=timeout,
+ sse_read_timeout=sse_read_timeout,
+ **client_kwargs,
+ )
+ else:
+ self.client = sse_client(
+ url=url,
+ headers=headers,
+ timeout=timeout,
+ sse_read_timeout=sse_read_timeout,
+ **client_kwargs,
+ )
diff --git a/src/agentscope/mcp/_http_stateless_client.py b/src/agentscope/mcp/_http_stateless_client.py
new file mode 100644
index 000000000..0a0f3fc16
--- /dev/null
+++ b/src/agentscope/mcp/_http_stateless_client.py
@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+"""The MCP streamable HTTP server."""
+from contextlib import _AsyncGeneratorContextManager
+from typing import Any, Callable, Awaitable, Literal, List
+
+import mcp.types
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
+
+from . import MCPToolFunction
+from ._client_base import MCPClientBase
+from ..tool import ToolResponse
+
+
+class HttpStatelessClient(MCPClientBase):
+ """The sse/streamable HTTP MCP client implementation in AgentScope.
+
+ .. note:: Note this client is stateless, meaning it won't maintain the
+ session state across multiple tool calls. Each tool call will start a
+ new session and close it after the call is done.
+
+ """
+
+ stateful: bool = False
+ """Whether the MCP server is stateful, meaning it will maintain the
+ session state across multiple tool calls, or stateless, meaning it
+ will start a new session for each tool call."""
+
+ def __init__(
+ self,
+ name: str,
+ transport: Literal["streamable_http", "sse"],
+ url: str,
+ headers: dict[str, str] | None = None,
+ timeout: float = 30,
+ sse_read_timeout: float = 60 * 5,
+ **client_kwargs: Any,
+ ) -> None:
+ """Initialize the streamable HTTP MCP server.
+
+ Args:
+ name (`str`):
+ The name to identify the MCP server, which should be unique
+ across the MCP servers.
+ transport (`Literal["streamable_http", "sse"]`):
+ The transport type of MCP server. Generally, the URL of sse
+ transport should end with `/sse`, while the streamable HTTP
+ URL ends with `/mcp`.
+ url (`str`):
+ The URL of the MCP server.
+ headers (`dict[str, str] | None`, optional):
+ Additional headers to include in the HTTP request.
+ timeout (`float`, optional):
+ The timeout for the HTTP request in seconds. Defaults to 30.
+ sse_read_timeout (`float`, optional):
+ The timeout for reading Server-Sent Events (SSE) in seconds.
+ Defaults to 300 (5 minutes).
+ **client_kwargs (`Any`):
+ The additional keyword arguments to pass to the streamable
+ HTTP client.
+ """
+ super().__init__(name=name)
+
+ assert transport in ["streamable_http", "sse"]
+
+ self.transport = transport
+
+ self.client_config = {
+ "url": url,
+ "headers": headers or {},
+ "timeout": timeout,
+ "sse_read_timeout": sse_read_timeout,
+ **client_kwargs,
+ }
+
+ self._tools = None
+
+ def get_client(self) -> _AsyncGeneratorContextManager[Any]:
+ """The disposable MCP client object, which is a context manager."""
+ if self.transport == "sse":
+ return sse_client(**self.client_config)
+
+ if self.transport == "streamable_http":
+ return streamablehttp_client(**self.client_config)
+
+ raise ValueError(
+ f"Unsupported transport type: {self.transport}. "
+ "Supported types are 'sse' and 'streamable_http'.",
+ )
+
+ async def get_callable_function(
+ self,
+ func_name: str,
+ wrap_tool_result: bool = True,
+ ) -> Callable[..., Awaitable[mcp.types.CallToolResult | ToolResponse]]:
+ """Get a tool function by its name.
+
+ Args:
+ func_name (`str`):
+ The name of the tool function.
+ wrap_tool_result (`bool`, defaults to `True`):
+ Whether to wrap the tool result into agentscope's
+ `ToolResponse` object. If `False`, the raw result type
+ `mcp.types.CallToolResult` will be returned.
+
+ Returns:
+ `Callable[..., Awaitable[mcp.types.CallToolResult | \
+ ToolResponse]]`:
+ An async tool function that returns either
+ `mcp.types.CallToolResult` or `ToolResponse` when called.
+ """
+
+ if self._tools is None:
+ await self.list_tools()
+
+ target_tool = None
+ for tool in self._tools:
+ if tool.name == func_name:
+ target_tool = tool
+ break
+
+ if target_tool is None:
+ raise ValueError(
+ f"Tool '{func_name}' not found in the MCP server ",
+ )
+
+ return MCPToolFunction(
+ mcp_name=self.name,
+ tool=target_tool,
+ wrap_tool_result=wrap_tool_result,
+ client_gen=self.get_client,
+ )
+
+ async def list_tools(self) -> List[mcp.types.Tool]:
+ """List all tools available on the MCP server.
+
+ Returns:
+ `mcp.types.ListToolsResult`:
+ The result containing the list of tools.
+ """
+ async with self.get_client() as cli:
+ read_stream, write_stream = cli[0], cli[1]
+ async with ClientSession(read_stream, write_stream) as session:
+ await session.initialize()
+ res = await session.list_tools()
+ self._tools = res.tools
+ return res.tools
diff --git a/src/agentscope/mcp/_mcp_function.py b/src/agentscope/mcp/_mcp_function.py
new file mode 100644
index 000000000..a0bf1fefe
--- /dev/null
+++ b/src/agentscope/mcp/_mcp_function.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""The MCP tool function class in AgentScope."""
+from contextlib import _AsyncGeneratorContextManager
+from typing import Any, Callable
+
+import mcp
+from mcp import ClientSession
+
+from ._client_base import MCPClientBase
+from .._utils._common import _extract_json_schema_from_mcp_tool
+from ..tool import ToolResponse
+
+
+class MCPToolFunction:
+ """An MCP tool function class that can be called directly."""
+
+ name: str
+ """The name of the tool function."""
+
+ description: str
+ """The description of the tool function."""
+
+ json_schema: dict[str, Any]
+ """JSON schema of the tool function"""
+
+ def __init__(
+ self,
+ mcp_name: str,
+ tool: mcp.types.Tool,
+ wrap_tool_result: bool,
+ client_gen: Callable[..., _AsyncGeneratorContextManager[Any]]
+ | None = None,
+ session: ClientSession | None = None,
+ ) -> None:
+ """Initialize the MCP function."""
+ self.mcp_name = mcp_name
+ self.name = tool.name
+ self.description = tool.description
+ self.json_schema = _extract_json_schema_from_mcp_tool(tool)
+ self.wrap_tool_result = wrap_tool_result
+
+ # Cannot be None at the same time
+ if (
+ client_gen is None
+ and session is None
+ or (client_gen is not None and session is not None)
+ ):
+ raise ValueError(
+ "Either client or session must be provided, but not both.",
+ )
+
+ self.client_gen = client_gen
+ self.session = session
+
+ async def __call__(
+ self,
+ **kwargs: Any,
+ ) -> mcp.types.CallToolResult | ToolResponse:
+ """Call the MCP tool function with the given arguments, and return
+ the result."""
+ if self.client_gen:
+ async with self.client_gen() as cli:
+ read_stream, write_stream = cli[0], cli[1]
+ async with ClientSession(read_stream, write_stream) as session:
+ await session.initialize()
+ res = await session.call_tool(
+ self.name,
+ arguments=kwargs,
+ )
+
+ else:
+ res = await self.session.call_tool(
+ self.name,
+ arguments=kwargs,
+ )
+
+ if self.wrap_tool_result:
+ as_content = MCPClientBase._convert_mcp_content_to_as_blocks(
+ res.content,
+ )
+ return ToolResponse(
+ content=as_content,
+ metadata=res.meta,
+ )
+
+ return res
diff --git a/src/agentscope/mcp/_stateful_client_base.py b/src/agentscope/mcp/_stateful_client_base.py
new file mode 100644
index 000000000..8d94bc5d2
--- /dev/null
+++ b/src/agentscope/mcp/_stateful_client_base.py
@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+"""The base MCP stateful client class in AgentScope, that provides basic
+ functionality for stateful MCP clients."""
+from abc import ABC
+from contextlib import AsyncExitStack
+from typing import List
+
+import mcp
+from mcp import ClientSession
+
+from ._client_base import MCPClientBase
+from ._mcp_function import MCPToolFunction
+from .._logging import logger
+
+
+class StatefulClientBase(MCPClientBase, ABC):
+ """The base class for stateful MCP clients in AgentScope, which maintains
+ the session state across multiple tool calls.
+
+ The developers should use `connect()` and `close()` methods to manage
+ the client lifecycle.
+ """
+
+ is_connected: bool
+ """If connected to the MCP server"""
+
+ def __init__(self, name: str) -> None:
+ """Initialize the stateful MCP client.
+
+ Args:
+ name (`str`):
+ The name to identify the MCP server, which should be unique
+ across the MCP servers.
+ """
+
+ super().__init__(name=name)
+
+ self.client = None
+ self.stack = None
+ self.session = None
+ self.is_connected = False
+
+ # Cache the tools to avoid fetching them multiple times
+ self._cached_tools = None
+
+ async def connect(self) -> None:
+ """Connect to MCP server."""
+ if self.is_connected:
+ raise RuntimeError(
+ "The MCP server is already connected. Call close() "
+ "before connecting again.",
+ )
+
+ self.stack = AsyncExitStack()
+
+ try:
+ context = await self.stack.enter_async_context(
+ self.client,
+ )
+ read_stream, write_stream = context[0], context[1]
+ self.session = ClientSession(read_stream, write_stream)
+ await self.stack.enter_async_context(self.session)
+ await self.session.initialize()
+
+ self.is_connected = True
+ logger.info("MCP client connected.")
+ except Exception:
+ await self.stack.aclose()
+ self.stack = None
+ raise
+
+ async def close(self) -> None:
+ """Clean up the MCP client resources. You must call this method when
+ your application is done."""
+ if not self.is_connected:
+ raise RuntimeError(
+ "The MCP server is not connected. Call connect() before "
+ "closing.",
+ )
+
+ try:
+ if self.stack:
+ await self.stack.aclose()
+
+ logger.info("MCP client closed.")
+ finally:
+ self.stack = None
+ self.session = None
+ self.is_connected = False
+
+ async def list_tools(self) -> List[mcp.types.Tool]:
+ """Get all available tools from the server.
+
+ Returns:
+ `mcp.types.ListToolsResult`:
+ A list of available MCP tools.
+ """
+ self._validate_connection()
+
+ res = await self.session.list_tools()
+
+ # Cache the tools for later use
+ self._cached_tools = res.tools
+ return res.tools
+
+ async def get_callable_function(
+ self,
+ func_name: str,
+ wrap_tool_result: bool = True,
+ ) -> MCPToolFunction:
+ """Get an async tool function from the MCP server by its name, so
+ that you can call it directly, wrap it into your own function, or
+ anyway you like.
+
+ .. note:: Currently, only the text, image, and audio results are
+ supported in this function.
+
+ Args:
+ func_name (`str`):
+ The name of the tool function to get.
+ wrap_tool_result (`bool`):
+ Whether to wrap the tool result into agentscope's
+ `ToolResponse` object. If `False`, the raw result type
+ `mcp.types.CallToolResult` will be returned.
+
+ Returns:
+ `MCPToolFunction`:
+ A callable async function that returns either
+ `mcp.types.CallToolResult` or `ToolResponse` when called.
+ """
+ self._validate_connection()
+
+ if self._cached_tools is None:
+ await self.list_tools()
+
+ target_tool = None
+ for tool in self._cached_tools:
+ if tool.name == func_name:
+ target_tool = tool
+ break
+
+ if target_tool is None:
+ raise ValueError(
+ f"Tool '{func_name}' not found in the MCP server",
+ )
+
+ return MCPToolFunction(
+ mcp_name=self.name,
+ tool=target_tool,
+ wrap_tool_result=wrap_tool_result,
+ session=self.session,
+ )
+
+ def _validate_connection(self) -> None:
+ """Validate the connection to the MCP server."""
+ if not self.is_connected:
+ raise RuntimeError(
+ "The connection is not established. Call connect() "
+ "before using the client.",
+ )
+
+ if not self.session:
+ raise RuntimeError(
+ "The session is not initialized. Call connect() "
+ "before using the client.",
+ )
diff --git a/src/agentscope/mcp/_stdio_stateful_client.py b/src/agentscope/mcp/_stdio_stateful_client.py
new file mode 100644
index 000000000..71e13e33d
--- /dev/null
+++ b/src/agentscope/mcp/_stdio_stateful_client.py
@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+"""The StdIO MCP server implementation in AgentScope, which provides
+function-level fine-grained control over the MCP servers using standard IO."""
+from typing import Literal
+
+from mcp import stdio_client, StdioServerParameters
+
+from ._stateful_client_base import StatefulClientBase
+
+
+class StdIOStatefulClient(StatefulClientBase):
+ """A client class that sets up and manage StdIO MCP server connections, and
+ provides function-level fine-grained control over the MCP servers.
+
+ .. tip:: The stateful client is recommended for MCP servers that need to
+ maintain session states, e.g. web browsers or other interactive
+ MCP servers.
+
+ .. note:: The stateful client will maintain one session across multiple
+ tool calls, until the client is closed by explicitly calling the
+ `close()` method.
+ """
+
+ def __init__(
+ self,
+ name: str,
+ command: str,
+ args: list[str] | None = None,
+ env: dict[str, str] | None = None,
+ cwd: str | None = None,
+ encoding: str = "utf-8",
+ encoding_error_handler: Literal[
+ "strict",
+ "ignore",
+ "replace",
+ ] = "strict",
+ ) -> None:
+ """Initialize the MCP server with std IO.
+
+ Args:
+ name (`str`):
+ The name to identify the MCP server, which should be unique
+ across the MCP servers.
+ command (`str`):
+ The executable to run to start the server.
+ args (`list[str] | None`, optional):
+ Command line arguments to pass to the executable.
+ env (`dict[str, str] | None`, optional):
+ The environment to use when spawning the process.
+ cwd (`str | None`, optional):
+ The working directory to use when spawning the process.
+ encoding (`str`, optional):
+ The text encoding used when sending/receiving messages to the
+ server. Defaults to "utf-8".
+ encoding_error_handler (`Literal["strict", "ignore", "replace"]`,
+ defaults to "strict"):
+ The text encoding error handler.
+ """
+ super().__init__(name=name)
+
+ self.client = stdio_client(
+ StdioServerParameters(
+ command=command,
+ args=args or [],
+ env=env,
+ cwd=cwd,
+ encoding=encoding,
+ encoding_error_handler=encoding_error_handler,
+ ),
+ )
diff --git a/src/agentscope/memory/__init__.py b/src/agentscope/memory/__init__.py
new file mode 100644
index 000000000..696d4cb19
--- /dev/null
+++ b/src/agentscope/memory/__init__.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""The memory module."""
+
+from ._memory_base import MemoryBase
+from ._in_memory_memory import InMemoryMemory
+from ._long_term_memory_base import LongTermMemoryBase
+from ._mem0_long_term_memory import Mem0LongTermMemory
+
+
+__all__ = [
+ "MemoryBase",
+ "InMemoryMemory",
+ "LongTermMemoryBase",
+ "Mem0LongTermMemory",
+]
diff --git a/src/agentscope/memory/_in_memory_memory.py b/src/agentscope/memory/_in_memory_memory.py
new file mode 100644
index 000000000..0d4e0f956
--- /dev/null
+++ b/src/agentscope/memory/_in_memory_memory.py
@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""The dialogue memory class"""
+
+from typing import Union, Iterable, Any
+
+from ._memory_base import MemoryBase
+from ..message import Msg
+
+
+class InMemoryMemory(MemoryBase):
+ """The in-memory memory class for storing messages."""
+
+ def __init__(
+ self,
+ ) -> None:
+ """Initialize the in-memory memory object."""
+ super().__init__()
+ self.content: list[Msg] = []
+
+ def state_dict(self) -> dict:
+ """Convert the current memory into JSON data format."""
+ return {
+ "content": [_.to_dict() for _ in self.content],
+ }
+
+ def load_state_dict(
+ self,
+ state_dict: dict,
+ strict: bool = True,
+ ) -> None:
+ """Load the memory from JSON data.
+
+ Args:
+ state_dict (`dict`):
+ The state dictionary to load, which should have a "content"
+ field.
+ strict (`bool`, defaults to `True`):
+ If `True`, raises an error if any key in the module is not
+ found in the state_dict. If `False`, skips missing keys.
+ """
+ self.content = []
+ for data in state_dict["content"]:
+ data.pop("type", None)
+ self.content.append(Msg.from_dict(data))
+
+ async def size(self) -> int:
+ """The size of the memory."""
+ return len(self.content)
+
+ async def retrieve(self, *args: Any, **kwargs: Any) -> None:
+ """Retrieve items from the memory."""
+ raise NotImplementedError(
+ "The retrieve method is not implemented in "
+ f"{self.__class__.__name__} class.",
+ )
+
+ async def delete(self, index: Union[Iterable, int]) -> None:
+ """Delete the specified item by index(es).
+
+ Args:
+ index (`Union[Iterable, int]`):
+ The index to delete.
+ """
+ if isinstance(index, int):
+ index = [index]
+
+ invalid_index = [_ for _ in index if 0 > _ or _ >= len(self.content)]
+
+ if invalid_index:
+ raise IndexError(
+ f"The index {invalid_index} does not exist.",
+ )
+
+ self.content = [
+ _ for idx, _ in enumerate(self.content) if idx not in index
+ ]
+
+ async def add(
+ self,
+ memories: Union[list[Msg], Msg, None],
+ allow_duplicates: bool = False,
+ ) -> None:
+ """Add message into the memory.
+
+ Args:
+ memories (`Union[list[Msg], Msg, None]`):
+ The message to add.
+ allow_duplicates (`bool`, defaults to `False`):
+ If allow adding duplicate messages (with the same id) into
+ the memory.
+ """
+ if memories is None:
+ return
+
+ if isinstance(memories, Msg):
+ memories = [memories]
+
+ if not isinstance(memories, list):
+ raise TypeError(
+ f"The memories should be a list of Msg or a single Msg, "
+ f"but got {type(memories)}.",
+ )
+
+ for msg in memories:
+ if not isinstance(msg, Msg):
+ raise TypeError(
+ f"The memories should be a list of Msg or a single Msg, "
+ f"but got {type(msg)}.",
+ )
+
+ if not allow_duplicates:
+ existing_ids = [_.id for _ in self.content]
+ memories = [_ for _ in memories if _.id not in existing_ids]
+ self.content.extend(memories)
+
+ async def get_memory(self) -> list[Msg]:
+ """Get the memory content."""
+ return self.content
+
+ async def clear(self) -> None:
+ """Clear the memory content."""
+ self.content = []
diff --git a/src/agentscope/memory/_long_term_memory_base.py b/src/agentscope/memory/_long_term_memory_base.py
new file mode 100644
index 000000000..269c0c56d
--- /dev/null
+++ b/src/agentscope/memory/_long_term_memory_base.py
@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""The long-term memory base class."""
+
+from typing import Any
+
+from ..message import Msg
+from ..module import StateModule
+from ..tool import ToolResponse
+
+
+class LongTermMemoryBase(StateModule):
+ """The long-term memory base class, which should be a time-series
+ memory management system.
+
+ The `record_to_memory` and `retrieve_from_memory` methods are two tool
+ functions for agent to manage the long-term memory voluntarily. You can
+ choose not to implement these two functions.
+
+ The `record` and `retrieve` methods are for developers to use. For example,
+ retrieving/recording memory at the beginning of each reply, and adding
+ the retrieved memory to the system prompt.
+ """
+
+ async def record(
+ self,
+ msgs: list[Msg | None],
+ **kwargs: Any,
+ ) -> None:
+ """A developer-designed method to record information from the given
+ input message(s) to the long-term memory."""
+ raise NotImplementedError(
+ "The `record` method is not implemented. ",
+ )
+
+ async def retrieve(
+ self,
+ msg: Msg | list[Msg] | None,
+ **kwargs: Any,
+ ) -> str:
+ """A developer-designed method to retrieve information from the
+ long-term memory based on the given input message(s). The retrieved
+ information will be added to the system prompt of the agent."""
+ raise NotImplementedError(
+ "The `retrieve` method is not implemented. ",
+ )
+
+ async def record_to_memory(
+ self,
+ thinking: str,
+ content: list[str],
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """Use this function to record important information that you may
+ need later. The target content should be specific and concise, e.g.
+ who, when, where, do what, why, how, etc.
+
+ Args:
+ thinking (`str`):
+ Your thinking and reasoning about what to record
+ content (`list[str]`):
+ The content to remember, which is a list of strings.
+ """
+ raise NotImplementedError(
+ "The `record_to_memory` method is not implemented. "
+ "You can implement it in your own long-term memory class.",
+ )
+
+ async def retrieve_from_memory(
+ self,
+ keywords: list[str],
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """Retrieve the memory based on the given keywords.
+
+ Args:
+ keywords (`list[str]`):
+ The keywords to search for in the memory, which should be
+ specific and concise, e.g. the person's name, the date, the
+ location, etc.
+
+ Returns:
+ `list[Msg]`:
+ A list of messages that match the keywords.
+ """
+ raise NotImplementedError(
+ "The `retrieve_from_memory` method is not implemented. "
+ "You can implement it in your own long-term memory class.",
+ )
diff --git a/src/agentscope/memory/_mem0_long_term_memory.py b/src/agentscope/memory/_mem0_long_term_memory.py
new file mode 100644
index 000000000..d5031c6ce
--- /dev/null
+++ b/src/agentscope/memory/_mem0_long_term_memory.py
@@ -0,0 +1,492 @@
+# -*- coding: utf-8 -*-
+"""Long-term memory implementation using mem0 library.
+
+This module provides a long-term memory implementation that integrates
+with the mem0 library to provide persistent memory storage and retrieval
+capabilities for AgentScope agents.
+"""
+import json
+from typing import Any, TYPE_CHECKING
+from importlib import metadata
+from packaging import version
+
+
+from pydantic import field_validator
+
+from ..embedding import EmbeddingModelBase
+from ._long_term_memory_base import LongTermMemoryBase
+from ..message import Msg, TextBlock
+from ..model import ChatModelBase
+from ..tool import ToolResponse
+
+
+if TYPE_CHECKING:
+ from mem0.configs.base import MemoryConfig
+ from mem0.vector_stores.configs import VectorStoreConfig
+else:
+ MemoryConfig = Any
+ VectorStoreConfig = Any
+
+
+def _create_agentscope_config_classes() -> tuple:
+ """Create custom config classes for agentscope providers."""
+ from mem0.embeddings.configs import EmbedderConfig
+ from mem0.llms.configs import LlmConfig
+
+ class _ASLlmConfig(LlmConfig):
+ """Custom LLM config class that updates the validate_config method.
+
+ Attention: in mem0, the validate_config hardcodes the provider, so we
+ need to override the validate_config method to support the agentscope
+ providers. We will follow up with the mem0 to improve this.
+ """
+
+ @field_validator("config")
+ @classmethod
+ def validate_config(cls, v: Any, values: Any) -> Any:
+ """Validate the LLM configuration."""
+ from mem0.utils.factory import LlmFactory
+
+ provider = values.data.get("provider")
+ if provider in LlmFactory.provider_to_class:
+ return v
+ raise ValueError(f"Unsupported LLM provider: {provider}")
+
+ class _ASEmbedderConfig(EmbedderConfig):
+ """Custom embedder config class that updates the validate_config
+ method."""
+
+ @field_validator("config")
+ @classmethod
+ def validate_config(cls, v: Any, values: Any) -> Any:
+ """Validate the embedder configuration."""
+ from mem0.utils.factory import EmbedderFactory
+
+ provider = values.data.get("provider")
+ if provider in EmbedderFactory.provider_to_class:
+ return v
+ raise ValueError(f"Unsupported Embedder provider: {provider}")
+
+ return _ASLlmConfig, _ASEmbedderConfig
+
+
+class Mem0LongTermMemory(LongTermMemoryBase):
+ """A class that implements the LongTermMemoryBase interface using mem0."""
+
+ def __init__(
+ self,
+ agent_name: str | None = None,
+ user_name: str | None = None,
+ run_name: str | None = None,
+ model: ChatModelBase | None = None,
+ embedding_model: EmbeddingModelBase | None = None,
+ vector_store_config: VectorStoreConfig | None = None,
+ mem0_config: MemoryConfig | None = None,
+ default_memory_type: str | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the Mem0LongTermMemory instance
+
+ Args:
+ agent_name (`str | None`, optional):
+ The name of the agent. Default is None.
+ user_name (`str | None`, optional):
+ The name of the user. Default is None.
+ run_name (`str | None`, optional):
+ The name of the run/session. Default is None.
+
+ .. note::
+ 1. At least one of `agent_name`, `user_name`, or `run_name` is
+ required.
+ 2. During memory recording, these parameters become metadata
+ for the stored memories.
+ 3. During memory retrieval, only memories with matching
+ metadata values will be returned.
+
+ model (`ChatModelBase | None`, optional):
+ The chat model to use for the long-term memory. If
+ mem0_config is provided, this will override the LLM
+ configuration. If mem0_config is None, this is required.
+ embedding_model (`EmbeddingModelBase | None`, optional):
+ The embedding model to use for the long-term memory. If
+ mem0_config is provided, this will override the embedder
+ configuration. If mem0_config is None, this is required.
+ vector_store_config (`VectorStoreConfig | None`, optional):
+ The vector store config to use for the long-term memory.
+ If mem0_config is provided, this will override the vector store
+ configuration. If mem0_config is None and this is not
+ provided, defaults to Qdrant with on_disk=True.
+ mem0_config (`MemoryConfig | None`, optional):
+ The mem0 config to use for the long-term memory.
+ If provided, individual
+ model/embedding_model/vector_store_config parameters will
+ override the corresponding configurations in mem0_config. If
+ None, a new MemoryConfig will be created using the provided
+ parameters.
+ default_memory_type (`str | None`, optional):
+ The type of memory to use. Default is None, to create a
+ semantic memory.
+
+ Raises:
+ `ValueError`:
+ If `mem0_config` is None and either `model` or
+ `embedding_model` is None.
+ """
+ super().__init__()
+
+ try:
+ import mem0
+ from mem0.configs.llms.base import BaseLlmConfig
+ from mem0.utils.factory import LlmFactory, EmbedderFactory
+
+ # Check mem0 version
+ current_version = metadata.version("mem0ai")
+ is_mem0_version_low = version.parse(
+ current_version,
+ ) <= version.parse("0.1.115")
+
+ # Register the agentscope providers with mem0
+
+ EmbedderFactory.provider_to_class[
+ "agentscope"
+ ] = "agentscope.memory._mem0_utils.AgentScopeEmbedding"
+ if is_mem0_version_low:
+ # For mem0 version <= 0.1.115, use the old style
+ LlmFactory.provider_to_class[
+ "agentscope"
+ ] = "agentscope.memory._mem0_utils.AgentScopeLLM"
+ else:
+ # For mem0 version > 0.1.115, use the new style
+ LlmFactory.provider_to_class["agentscope"] = (
+ "agentscope.memory._mem0_utils.AgentScopeLLM",
+ BaseLlmConfig,
+ )
+
+ except ImportError as e:
+ raise ImportError(
+ "Please install the mem0 library by `pip install mem0ai`",
+ ) from e
+
+ # Create the custom config classes for agentscope providers dynamically
+ _ASLlmConfig, _ASEmbedderConfig = _create_agentscope_config_classes()
+
+ if agent_name is None and user_name is None and run_name is None:
+ raise ValueError(
+ "at least one of agent_name, user_name, and run_name is "
+ "required",
+ )
+
+ # Store agent and user identifiers for memory management
+ self.agent_id = agent_name
+ self.user_id = user_name
+ self.run_id = run_name
+
+ # Configuration logic: Handle mem0_config parameter
+ if mem0_config is not None:
+ # Case 1: mem0_config is provided - override specific
+ # configurations if individual params are given
+
+ # Override LLM configuration if model is provided
+ if model is not None:
+ mem0_config.llm = _ASLlmConfig(
+ provider="agentscope",
+ config={"model": model},
+ )
+
+ # Override embedder configuration if embedding_model is provided
+ if embedding_model is not None:
+ mem0_config.embedder = _ASEmbedderConfig(
+ provider="agentscope",
+ config={"model": embedding_model},
+ )
+
+ # Override vector store configuration if vector_store_config is
+ # provided
+ if vector_store_config is not None:
+ mem0_config.vector_store = vector_store_config
+
+ else:
+ # Case 2: mem0_config is not provided - create new configuration
+ # from individual parameters
+
+ # Validate that required parameters are provided
+ if model is None or embedding_model is None:
+ raise ValueError(
+ "model and embedding_model are required if mem0_config "
+ "is not provided",
+ )
+
+ # Create new MemoryConfig with provided LLM and embedder
+ mem0_config = mem0.configs.base.MemoryConfig(
+ llm=_ASLlmConfig(
+ provider="agentscope",
+ config={"model": model},
+ ),
+ embedder=_ASEmbedderConfig(
+ provider="agentscope",
+ config={"model": embedding_model},
+ ),
+ )
+
+ # Set vector store configuration
+ if vector_store_config is not None:
+ # Use provided vector store configuration
+ mem0_config.vector_store = vector_store_config
+ else:
+ # Use default Qdrant configuration with on-disk storage for
+ # persistence set on_disk to True to enable persistence,
+ # otherwise it will be in memory only
+ on_disk = kwargs.get("on_disk", True)
+ mem0_config.vector_store = (
+ mem0.vector_stores.configs.VectorStoreConfig(
+ config={"on_disk": on_disk},
+ )
+ )
+
+ # Initialize the async memory instance with the configured settings
+ self.long_term_working_memory = mem0.AsyncMemory(mem0_config)
+
+ # Store the default memory type for future use
+ self.default_memory_type = default_memory_type
+
+ async def record_to_memory(
+ self,
+ thinking: str,
+ content: list[str],
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """Use this function to record important information that you may
+ need later. The target content should be specific and concise, e.g.
+ who, when, where, do what, why, how, etc.
+
+ Args:
+ thinking (`str`):
+ Your thinking and reasoning about what to record.
+ content (`list[str]`):
+ The content to remember, which is a list of strings.
+ """
+ try:
+ if thinking:
+ content = [thinking] + content
+
+ results = await self._mem0_record(
+ [
+ {
+ "role": "assistant",
+ "content": "\n".join(content),
+ "name": "assistant",
+ },
+ ],
+ **kwargs,
+ )
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Successfully recorded content to memory "
+ f"{results}",
+ ),
+ ],
+ )
+
+ except Exception as e:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error recording memory: {str(e)}",
+ ),
+ ],
+ )
+
+ async def retrieve_from_memory(
+ self,
+ keywords: list[str],
+ limit: int = 5,
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """Retrieve the memory based on the given keywords.
+
+ Args:
+ keywords (`list[str]`):
+ The keywords to search for in the memory, which should be
+ specific and concise, e.g. the person's name, the date, the
+ location, etc.
+ limit (`int`, optional):
+ The maximum number of memories to retrieve per search.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the retrieved memories as JSON text.
+ """
+
+ try:
+ results = []
+ for keyword in keywords:
+ result = await self.long_term_working_memory.search(
+ query=keyword,
+ agent_id=self.agent_id,
+ user_id=self.user_id,
+ run_id=self.run_id,
+ limit=limit,
+ )
+ if result:
+ results.extend(
+ [item["memory"] for item in result["results"]],
+ )
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="\n".join(results),
+ ),
+ ],
+ )
+
+ except Exception as e:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error retrieving memory: {str(e)}",
+ ),
+ ],
+ )
+
+ async def record(
+ self,
+ msgs: list[Msg | None],
+ memory_type: str | None = None,
+ infer: bool = True,
+ **kwargs: Any,
+ ) -> None:
+ """Record the content to the long-term memory.
+
+ Args:
+ msgs (`list[Msg | None]`):
+ The messages to record to memory.
+ memory_type (`str | None`, optional):
+ The type of memory to use. Default is None, to create a
+ semantic memory. "procedural_memory" is explicitly used for
+ procedural memories.
+ infer (`bool`, optional):
+ Whether to infer memory from the content. Default is True.
+ **kwargs (`Any`):
+ Additional keyword arguments for the mem0 recording.
+ """
+ if isinstance(msgs, Msg):
+ msgs = [msgs]
+
+ # Filter out None
+ msg_list = [_ for _ in msgs if _]
+ if not all(isinstance(_, Msg) for _ in msg_list):
+ raise TypeError(
+ "The input messages must be a list of Msg objects.",
+ )
+
+ messages = [
+ {
+ "role": "assistant",
+ "content": "\n".join([str(_.content) for _ in msg_list]),
+ "name": "assistant",
+ },
+ ]
+
+ await self._mem0_record(
+ messages,
+ memory_type=memory_type,
+ infer=infer,
+ **kwargs,
+ )
+
+ async def _mem0_record(
+ self,
+ messages: str | list[dict],
+ memory_type: str | None,
+ infer: bool = True,
+ **kwargs: Any,
+ ) -> dict:
+ """Record the content to the long-term memory.
+
+ Args:
+ messages (`str`):
+ The content to remember, which is a string or a list of
+ dictionaries representing messages.
+ memory_type (`str | None`, optional):
+ The type of memory to use. Default is None, to create a
+ semantic memory. "procedural_memory" is explicitly used for
+ procedural memories.
+ infer (`bool`, optional):
+ Whether to infer memory from the content. Default is True.
+ **kwargs (`Any`):
+ Additional keyword arguments.
+
+ Returns:
+ `dict`:
+ The result from the memory recording operation.
+ """
+ results = await self.long_term_working_memory.add(
+ messages=messages,
+ agent_id=self.agent_id,
+ user_id=self.user_id,
+ run_id=self.run_id,
+ memory_type=(
+ memory_type
+ if memory_type is not None
+ else self.default_memory_type
+ ),
+ infer=infer,
+ **kwargs,
+ )
+ return results
+
+ async def retrieve(
+ self,
+ msg: Msg | list[Msg] | None,
+ limit: int = 5,
+ **kwargs: Any,
+ ) -> str:
+ """Retrieve the content from the long-term memory.
+
+ Args:
+ msg (`Msg | list[Msg] | None`):
+ The message to search for in the memory, which should be
+ specific and concise, e.g. the person's name, the date, the
+ location, etc.
+ limit (`int`, optional):
+ The maximum number of memories to retrieve per search.
+ **kwargs (`Any`):
+ Additional keyword arguments.
+
+ Returns:
+ `str`:
+ The retrieved memory
+ """
+ if isinstance(msg, Msg):
+ msg = [msg]
+
+ if not isinstance(msg, list) or not all(
+ isinstance(_, Msg) for _ in msg
+ ):
+ raise TypeError(
+ "The input message must be a Msg or a list of Msg objects.",
+ )
+
+ msg_strs = [
+ json.dumps(_.to_dict()["content"], ensure_ascii=False) for _ in msg
+ ]
+
+ results = []
+ for item in msg_strs:
+ result = await self.long_term_working_memory.search(
+ query=item,
+ agent_id=self.agent_id,
+ user_id=self.user_id,
+ run_id=self.run_id,
+ limit=limit,
+ )
+ if result:
+ results.extend([item["memory"] for item in result["results"]])
+
+ return "\n".join(results)
diff --git a/src/agentscope/memory/_mem0_utils.py b/src/agentscope/memory/_mem0_utils.py
new file mode 100644
index 000000000..72b36048b
--- /dev/null
+++ b/src/agentscope/memory/_mem0_utils.py
@@ -0,0 +1,217 @@
+# -*- coding: utf-8 -*-
+"""Utility classes for integrating AgentScope with mem0 library.
+
+This module provides wrapper classes that allow AgentScope models to be used
+with the mem0 library for long-term memory functionality.
+"""
+import asyncio
+from typing import Any, Dict, List, Literal
+
+from mem0.configs.embeddings.base import BaseEmbedderConfig
+from mem0.configs.llms.base import BaseLlmConfig
+from mem0.embeddings.base import EmbeddingBase
+from mem0.llms.base import LLMBase
+
+
+from ..embedding import EmbeddingModelBase
+from ..model import ChatModelBase, ChatResponse
+
+
+class AgentScopeLLM(LLMBase):
+ """Wrapper for the AgentScope LLM.
+
+ This class is a wrapper for the AgentScope LLM. It is used to generate
+ responses using the AgentScope LLM in mem0.
+ """
+
+ def __init__(self, config: BaseLlmConfig | None = None):
+ """Initialize the AgentScopeLLM wrapper.
+
+ Args:
+ config (`BaseLlmConfig | None`, optional):
+ Configuration object for the LLM. Default is None.
+ """
+ super().__init__(config)
+
+ if self.config.model is None:
+ raise ValueError("`model` parameter is required")
+
+ if not isinstance(self.config.model, ChatModelBase):
+ raise ValueError("`model` must be an instance of ChatModelBase")
+
+ self.agentscope_model = self.config.model
+
+ def generate_response(
+ self,
+ messages: List[Dict[str, str]],
+ response_format: Any | None = None,
+ tools: List[Dict] | None = None,
+ tool_choice: str = "auto",
+ ) -> str:
+ """Generate a response based on the given messages using agentscope.
+
+ Args:
+ messages (`List[Dict[str, str]]`):
+ List of message dicts containing 'role' and 'content'.
+ response_format (`Any | None`, optional):
+ Format of the response. Not used in AgentScope.
+ tools (`List[Dict] | None`, optional):
+ List of tools that the model can call. Not used in AgentScope.
+ tool_choice (`str`, optional):
+ Tool choice method. Not used in AgentScope.
+
+ Returns:
+ `str`:
+ The generated response.
+ """
+ # pylint: disable=unused-argument
+ try:
+ # Convert the messages to AgentScope's format
+ agentscope_messages = []
+ for message in messages:
+ role = message["role"]
+ content = message["content"]
+
+ if role in ["system", "user", "assistant"]:
+ agentscope_messages.append(
+ {"role": role, "content": content},
+ )
+
+ if not agentscope_messages:
+ raise ValueError(
+ "No valid messages found in the messages list",
+ )
+
+ # Use the agentscope model to generate response (async call)
+ async def _async_call() -> ChatResponse:
+ # TODO: handle the streaming response or forbidden streaming
+ # mode
+ return await self.agentscope_model( # type: ignore
+ agentscope_messages,
+ tools=tools,
+ )
+
+ response = asyncio.run(_async_call())
+
+ # Extract text from the response content blocks
+ if not response.content:
+ return ""
+
+ # Collect all text from different block types
+ text_parts = []
+ thinking_parts = []
+ tool_parts = []
+
+ for block in response.content:
+ # Handle TextBlock
+ if isinstance(block, dict) and block.get("type") == "text":
+ text_parts.append(block.get("text", ""))
+
+ # Handle ThinkingBlock
+ elif (
+ isinstance(block, dict) and block.get("type") == "thinking"
+ ):
+ thinking_parts.append(
+ f"[Thinking: {block.get('thinking', '')}]",
+ )
+
+ # Handle ToolUseBlock
+ elif (
+ isinstance(block, dict) and block.get("type") == "tool_use"
+ ):
+ tool_name = block.get("name")
+ tool_input = block.get("input", {})
+ tool_parts.append(
+ f"[Tool: {tool_name} - {str(tool_input)}]",
+ )
+
+ # Combine all parts in order: thinking, text, tools
+ all_parts: list[str] = thinking_parts + text_parts + tool_parts
+
+ if all_parts:
+ return "\n".join(all_parts)
+ # If no recognized blocks found, try to convert the entire
+ # content to string
+ return str(response.content)
+
+ except Exception as e:
+ raise RuntimeError(
+ f"Error generating response using agentscope model: {str(e)}",
+ ) from e
+
+
+class AgentScopeEmbedding(EmbeddingBase):
+ """Wrapper for the AgentScope Embedding model.
+
+ This class is a wrapper for the AgentScope Embedding model. It is used
+ to generate embeddings using the AgentScope Embedding model in mem0.
+ """
+
+ def __init__(self, config: BaseEmbedderConfig | None = None):
+ """Initialize the AgentScopeEmbedding wrapper.
+
+ Args:
+ config (`BaseEmbedderConfig | None`, optional):
+ Configuration object for the embedder. Default is None.
+ """
+ super().__init__(config)
+
+ if self.config.model is None:
+ raise ValueError("`model` parameter is required")
+
+ if not isinstance(self.config.model, EmbeddingModelBase):
+ raise ValueError(
+ "`model` must be an instance of EmbeddingModelBase",
+ )
+
+ self.agentscope_model = self.config.model
+
+ def embed(
+ self,
+ text: str | List[str],
+ memory_action: Literal[ # pylint: disable=unused-argument
+ "add",
+ "search",
+ "update",
+ ]
+ | None = None,
+ ) -> List[float]:
+ """Get the embedding for the given text using AgentScope.
+
+ Args:
+ text (`str | List[str]`):
+ The text to embed.
+ memory_action (`Literal["add", "search", "update"] | None`, \
+ optional):
+ The type of embedding to use. Must be one of "add", "search",
+ or "update". Defaults to None.
+
+ Returns:
+ `List[float]`:
+ The embedding vector.
+ """
+ try:
+ # Convert single text to list for AgentScope embedding model
+ text_list = [text] if isinstance(text, str) else text
+
+ # Use the agentscope model to generate embedding (async call)
+ async def _async_call() -> Any:
+ response = await self.agentscope_model(text_list)
+ return response
+
+ response = asyncio.run(_async_call())
+
+ # Extract the embedding vector from the first Embedding object
+ # response.embeddings is a list of Embedding objects
+ # Each Embedding object has an 'embedding' attribute containing
+ # the vector
+ embedding = response.embeddings[0]
+
+ if embedding is None:
+ raise ValueError("Failed to extract embedding from response")
+ return embedding
+
+ except Exception as e:
+ raise RuntimeError(
+ f"Error generating embedding using agentscope model: {str(e)}",
+ ) from e
diff --git a/src/agentscope/memory/_memory_base.py b/src/agentscope/memory/_memory_base.py
new file mode 100644
index 000000000..8173d9fd7
--- /dev/null
+++ b/src/agentscope/memory/_memory_base.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""The memory base class."""
+
+from abc import abstractmethod
+from typing import Any
+
+from ..message import Msg
+from ..module import StateModule
+
+
+class MemoryBase(StateModule):
+ """The base class for memory in agentscope."""
+
+ @abstractmethod
+ async def add(self, *args: Any, **kwargs: Any) -> None:
+ """Add items to the memory."""
+
+ @abstractmethod
+ async def delete(self, *args: Any, **kwargs: Any) -> None:
+ """Delete items from the memory."""
+
+ @abstractmethod
+ async def retrieve(self, *args: Any, **kwargs: Any) -> None:
+ """Retrieve items from the memory."""
+
+ @abstractmethod
+ async def size(self) -> int:
+ """Get the size of the memory."""
+
+ @abstractmethod
+ async def clear(self) -> None:
+ """Clear the memory content."""
+
+ @abstractmethod
+ async def get_memory(self, *args: Any, **kwargs: Any) -> list[Msg]:
+ """Get the memory content."""
+
+ @abstractmethod
+ def state_dict(self) -> dict:
+ """Get the state dictionary of the memory."""
+
+ @abstractmethod
+ def load_state_dict(self, state_dict: dict, strict: bool = True) -> None:
+ """Load the state dictionary of the memory."""
diff --git a/src/agentscope/message/__init__.py b/src/agentscope/message/__init__.py
new file mode 100644
index 000000000..1dfe69f5b
--- /dev/null
+++ b/src/agentscope/message/__init__.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+"""The message module in agentscope."""
+
+from ._message_block import (
+ ContentBlock,
+ TextBlock,
+ ThinkingBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ ImageBlock,
+ AudioBlock,
+ VideoBlock,
+ Base64Source,
+ URLSource,
+)
+from ._message_base import Msg
+
+
+__all__ = [
+ "TextBlock",
+ "ThinkingBlock",
+ "Base64Source",
+ "URLSource",
+ "ImageBlock",
+ "AudioBlock",
+ "VideoBlock",
+ "ToolUseBlock",
+ "ToolResultBlock",
+ "ContentBlock",
+ "Msg",
+]
diff --git a/src/agentscope/message/_message_base.py b/src/agentscope/message/_message_base.py
new file mode 100644
index 000000000..445b140c2
--- /dev/null
+++ b/src/agentscope/message/_message_base.py
@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+"""The message class in agentscope."""
+from datetime import datetime
+from typing import Literal, List, overload, Sequence
+
+import shortuuid
+
+from . import ToolResultBlock
+from ._message_block import (
+ TextBlock,
+ ToolUseBlock,
+ ImageBlock,
+ AudioBlock,
+ ContentBlock,
+ VideoBlock,
+ ThinkingBlock,
+)
+from ..types import JSONSerializableObject
+
+
+class Msg:
+ """The message class in agentscope."""
+
+ def __init__(
+ self,
+ name: str,
+ content: str | Sequence[ContentBlock],
+ role: Literal["user", "assistant", "system"],
+ metadata: dict[str, JSONSerializableObject] | None = None,
+ timestamp: str | None = None,
+ invocation_id: str | None = None,
+ ) -> None:
+ """Initialize the Msg object.
+
+ Args:
+ name (`str`):
+ The name of the message sender.
+ content (`str | list[ContentBlock]`):
+ The content of the message.
+ role (`Literal["user", "assistant", "system"]`):
+ The role of the message sender.
+ metadata (`dict[str, JSONSerializableObject] | None`, optional):
+ The metadata of the message, e.g. structured output.
+ timestamp (`str | None`, optional):
+ The created timestamp of the message. If not given, the
+ timestamp will be set automatically.
+ invocation_id (`str | None`, optional):
+ The related API invocation id, if any. This is useful for
+ tracking the message in the context of an API call.
+ """
+
+ self.name = name
+ self.content = content
+
+ assert role in ["user", "assistant", "system"]
+ self.role = role
+
+ self.metadata = metadata
+
+ self.id = shortuuid.uuid()
+ self.timestamp = (
+ timestamp
+ or datetime.now().strftime(
+ "%Y-%m-%d %H:%M:%S.%f",
+ )[:-3]
+ )
+ self.invocation_id = invocation_id
+
+ def to_dict(self) -> dict:
+ """Convert the message into JSON dict data."""
+ return {
+ "id": self.id,
+ "name": self.name,
+ "role": self.role,
+ "content": self.content,
+ "metadata": self.metadata,
+ "timestamp": self.timestamp,
+ }
+
+ @classmethod
+ def from_dict(cls, json_data: dict) -> "Msg":
+ """Load a message object from the given JSON data."""
+ new_obj = cls(
+ name=json_data["name"],
+ content=json_data["content"],
+ role=json_data["role"],
+ metadata=json_data.get("metadata", None),
+ timestamp=json_data.get("timestamp", None),
+ invocation_id=json_data.get("invocation_id", None),
+ )
+
+ new_obj.id = json_data.get("id", new_obj.id)
+ return new_obj
+
+ def has_content_blocks(
+ self,
+ block_type: Literal[
+ "text",
+ "tool_use",
+ "tool_result",
+ "image",
+ "audio",
+ "video",
+ ]
+ | None = None,
+ ) -> bool:
+ """Check if the message has content blocks of the given type.
+
+ Args:
+ block_type (Literal["text", "tool_use", "tool_result", "image", \
+ "audio", "video"] | None, defaults to None):
+ The type of the block to be checked. If `None`, it will
+ check if there are any content blocks.
+ """
+ return len(self.get_content_blocks(block_type)) > 0
+
+ def get_text_content(self) -> str | None:
+ """Get the pure text blocks from the message content."""
+ if isinstance(self.content, str):
+ return self.content
+
+ gathered_text = None
+ for block in self.content:
+ if block.get("type") == "text":
+ if gathered_text is None:
+ gathered_text = str(block.get("text"))
+ else:
+ gathered_text += block.get("text")
+ return gathered_text
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["text"],
+ ) -> List[TextBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["tool_use"],
+ ) -> List[ToolUseBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["tool_result"],
+ ) -> List[ToolUseBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["image"],
+ ) -> List[ImageBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["audio"],
+ ) -> List[AudioBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: Literal["video"],
+ ) -> List[VideoBlock]:
+ ...
+
+ @overload
+ def get_content_blocks(
+ self,
+ block_type: None = None,
+ ) -> List[ContentBlock]:
+ ...
+
+ def get_content_blocks(
+ self,
+ block_type: Literal[
+ "text",
+ "thinking",
+ "tool_use",
+ "tool_result",
+ "image",
+ "audio",
+ "video",
+ ]
+ | None = None,
+ ) -> (
+ List[ContentBlock]
+ | List[TextBlock]
+ | List[ThinkingBlock]
+ | List[ToolUseBlock]
+ | List[ToolResultBlock]
+ | List[ImageBlock]
+ | List[AudioBlock]
+ | List[VideoBlock]
+ ):
+ """Get the content in block format. If the content is a string,
+ it will be converted to a text block.
+
+ Args:
+ block_type (`Literal["text", "thinking", "tool_use", \
+ "tool_result", "image", "audio", "video"] | None`, optional):
+ The type of the block to be extracted. If `None`, all blocks
+ will be returned.
+
+ Returns:
+ `List[ContentBlock]`:
+ The content blocks.
+ """
+ blocks = []
+ if isinstance(self.content, str):
+ blocks.append(
+ TextBlock(type="text", text=self.content),
+ )
+ else:
+ blocks = self.content
+
+ if block_type is not None:
+ blocks = [_ for _ in blocks if _["type"] == block_type]
+
+ return blocks
+
+ def __repr__(self) -> str:
+ """Get the string representation of the message."""
+ return (
+ f"Msg(id='{self.id}', "
+ f"name='{self.name}', "
+ f"content={repr(self.content)}, "
+ f"role='{self.role}', "
+ f"metadata={repr(self.metadata)}, "
+ f"timestamp='{self.timestamp}', "
+ f"invocation_id='{self.invocation_id}')"
+ )
diff --git a/src/agentscope/message/_message_block.py b/src/agentscope/message/_message_block.py
new file mode 100644
index 000000000..792688565
--- /dev/null
+++ b/src/agentscope/message/_message_block.py
@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=R0901
+"""The content blocks of messages"""
+
+from typing import Literal, List
+from typing_extensions import TypedDict, Required
+
+
+class TextBlock(TypedDict, total=False):
+ """The text block."""
+
+ type: Required[Literal["text"]]
+ """The type of the block"""
+ text: str
+ """The text content"""
+
+
+class ThinkingBlock(TypedDict, total=False):
+ """The thinking block."""
+
+ type: Required[Literal["thinking"]]
+ """The type of the block"""
+ thinking: str
+
+
+class Base64Source(TypedDict, total=False):
+ """The base64 source"""
+
+ type: Required[Literal["base64"]]
+ """The type of the src, must be `base64`"""
+
+ media_type: Required[str]
+ """The media type of the data, e.g. `image/jpeg` or `audio/mpeg`"""
+
+ data: Required[str]
+ """The base64 data, in format of RFC 2397"""
+
+
+class URLSource(TypedDict, total=False):
+ """The URL source"""
+
+ type: Required[Literal["url"]]
+ """The type of the src, must be `url`"""
+
+ url: Required[str]
+ """The URL of the image or audio"""
+
+
+class ImageBlock(TypedDict, total=False):
+ """The image block"""
+
+ type: Required[Literal["image"]]
+ """The type of the block"""
+
+ source: Required[Base64Source | URLSource]
+ """The src of the image"""
+
+
+class AudioBlock(TypedDict, total=False):
+ """The audio block"""
+
+ type: Required[Literal["audio"]]
+ """The type of the block"""
+
+ source: Required[Base64Source | URLSource]
+ """The src of the audio"""
+
+
+class VideoBlock(TypedDict, total=False):
+ """The video block"""
+
+ type: Required[Literal["video"]]
+ """The type of the block"""
+
+ source: Required[Base64Source | URLSource]
+ """The src of the audio"""
+
+
+class ToolUseBlock(TypedDict, total=False):
+ """The tool use block."""
+
+ type: Required[Literal["tool_use"]]
+ """The type of the block, must be `tool_use`"""
+ id: Required[str]
+ """The identity of the tool call"""
+ name: Required[str]
+ """The name of the tool"""
+ input: Required[dict[str, object]]
+ """The input of the tool"""
+
+
+class ToolResultBlock(TypedDict, total=False):
+ """The tool result block."""
+
+ type: Required[Literal["tool_result"]]
+ """The type of the block"""
+ id: Required[str]
+ """The identity of the tool call result"""
+ output: Required[str | List[TextBlock | ImageBlock | AudioBlock]]
+ """The output of the tool function"""
+ name: Required[str]
+ """The name of the tool function"""
+
+
+# The content block
+ContentBlock = (
+ ToolUseBlock
+ | ToolResultBlock
+ | TextBlock
+ | ThinkingBlock
+ | ImageBlock
+ | AudioBlock
+ | VideoBlock
+)
diff --git a/src/agentscope/model/__init__.py b/src/agentscope/model/__init__.py
new file mode 100644
index 000000000..6f3a729fc
--- /dev/null
+++ b/src/agentscope/model/__init__.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""The model module."""
+
+from ._model_base import ChatModelBase
+from ._model_response import ChatResponse
+from ._dashscope_model import DashScopeChatModel
+from ._openai_model import OpenAIChatModel
+from ._anthropic_model import AnthropicChatModel
+from ._ollama_model import OllamaChatModel
+from ._gemini_model import GeminiChatModel
+
+__all__ = [
+ "ChatModelBase",
+ "ChatResponse",
+ "DashScopeChatModel",
+ "OpenAIChatModel",
+ "AnthropicChatModel",
+ "OllamaChatModel",
+ "GeminiChatModel",
+]
diff --git a/src/agentscope/model/_anthropic_model.py b/src/agentscope/model/_anthropic_model.py
new file mode 100644
index 000000000..2267c23ac
--- /dev/null
+++ b/src/agentscope/model/_anthropic_model.py
@@ -0,0 +1,419 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches, too-many-statements
+"""The Anthropic API model classes."""
+
+from datetime import datetime
+from typing import (
+ Any,
+ AsyncGenerator,
+ TYPE_CHECKING,
+ List,
+ Literal,
+)
+from collections import OrderedDict
+
+from ._model_base import ChatModelBase
+from ._model_response import ChatResponse
+from ._model_usage import ChatUsage
+from .._utils._common import _json_loads_with_repair
+from ..message import TextBlock, ToolUseBlock, ThinkingBlock
+from ..tracing import trace_llm
+from ..types._json import JSONSerializableObject
+
+if TYPE_CHECKING:
+ from anthropic.types.message import Message
+ from anthropic import AsyncStream
+else:
+ Message = "anthropic.types.message.Message"
+ AsyncStream = "anthropic.AsyncStream"
+
+
+class AnthropicChatModel(ChatModelBase):
+ """The Anthropic model wrapper for AgentScope."""
+
+ def __init__(
+ self,
+ model_name: str,
+ api_key: str | None = None,
+ max_tokens: int = 2048,
+ stream: bool = True,
+ thinking: dict | None = None,
+ client_args: dict | None = None,
+ generate_kwargs: dict[str, JSONSerializableObject] | None = None,
+ ) -> None:
+ """Initialize the Anthropic chat model.
+
+ Args:
+ model_name (`str`):
+ The model names.
+ api_key (`str`):
+ The anthropic API key.
+ stream (`bool`):
+ The streaming output or not
+ max_tokens (`int`):
+ Limit the maximum token count the model can generate.
+ thinking (`dict | None`, default `None`):
+ Configuration for Claude's internal reasoning process.
+
+ .. code-block:: python
+ :caption: Example of thinking
+
+ {
+ "type": "enabled" | "disabled",
+ "budget_tokens": 1024
+ }
+
+ client_args (`dict | None`, optional):
+ The extra keyword arguments to initialize the Anthropic client.
+ generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
+ optional):
+ The extra keyword arguments used in Gemini API generation,
+ e.g. `temperature`, `seed`.
+ """
+
+ try:
+ import anthropic
+ except ImportError as e:
+ raise ImportError(
+ "Please install the `anthropic` package by running "
+ "`pip install anthropic`.",
+ ) from e
+
+ super().__init__(model_name, stream)
+
+ self.client = anthropic.AsyncAnthropic(
+ api_key=api_key,
+ **(client_args or {}),
+ )
+ self.max_tokens = max_tokens
+ self.thinking = thinking
+ self.generate_kwargs = generate_kwargs or {}
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict] | None = None,
+ tool_choice: Literal["auto", "none", "any", "required"]
+ | str
+ | None = None,
+ **generate_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Get the response from Anthropic chat completions API by the given
+ arguments.
+
+ Args:
+ messages (`list[dict]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required, and `name` field is optional.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas that in format of:
+
+ .. code-block:: python
+ :caption: Example of tools JSON schemas
+
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "xxx",
+ "description": "xxx",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "param1": {
+ "type": "string",
+ "description": "..."
+ },
+ # Add more parameters as needed
+ },
+ "required": ["param1"]
+ }
+ },
+ # More schemas here
+ ]
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name. For more details, please refer to
+ https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use
+ **generate_kwargs (`Any`):
+ The keyword arguments for Anthropic chat completions API,
+ e.g. `temperature`, `top_p`, etc. Please
+ refer to the Anthropic API documentation for more details.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ The response from the Anthropic chat completions API."""
+
+ kwargs: dict[str, Any] = {
+ "model": self.model_name,
+ "max_tokens": self.max_tokens,
+ "stream": self.stream,
+ **self.generate_kwargs,
+ **generate_kwargs,
+ }
+ if self.thinking and "thinking" not in kwargs:
+ kwargs["thinking"] = self.thinking
+
+ if tools:
+ kwargs["tools"] = self._format_tools_json_schemas(tools)
+
+ if tool_choice:
+ self._validate_tool_choice(tool_choice, tools)
+ kwargs["tool_choice"] = self._format_tool_choice(tool_choice)
+
+ # Extract the system message
+ if messages[0]["role"] == "system":
+ kwargs["system"] = messages[0]["content"]
+ messages = messages[1:]
+
+ kwargs["messages"] = messages
+
+ start_datetime = datetime.now()
+
+ response = await self.client.messages.create(**kwargs)
+
+ if self.stream:
+ return self._parse_anthropic_stream_completion_response(
+ start_datetime,
+ response,
+ )
+
+ # Non-streaming response
+ parsed_response = await self._parse_anthropic_completion_response(
+ start_datetime,
+ response,
+ )
+
+ return parsed_response
+
+ async def _parse_anthropic_completion_response(
+ self,
+ start_datetime: datetime,
+ response: Message,
+ ) -> ChatResponse:
+ """Parse the Anthropic chat completion response into a `ChatResponse`
+ object."""
+ content_blocks: List[ThinkingBlock | TextBlock | ToolUseBlock] = []
+
+ if hasattr(response, "content") and response.content:
+ for content_block in response.content:
+ if (
+ hasattr(content_block, "type")
+ and content_block.type == "thinking"
+ ):
+ thinking_block = ThinkingBlock(
+ type="thinking",
+ thinking=content_block.thinking,
+ )
+ thinking_block["signature"] = content_block.signature
+ content_blocks.append(thinking_block)
+
+ elif hasattr(content_block, "text"):
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=content_block.text,
+ ),
+ )
+
+ elif (
+ hasattr(content_block, "type")
+ and content_block.type == "tool_use"
+ ):
+ content_blocks.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=content_block.id,
+ name=content_block.name,
+ input=content_block.input,
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.input_tokens,
+ output_tokens=response.usage.output_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ parsed_response = ChatResponse(
+ content=content_blocks,
+ usage=usage,
+ )
+
+ return parsed_response
+
+ async def _parse_anthropic_stream_completion_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncStream,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Anthropic chat completion response stream into an async
+ generator of `ChatResponse` objects."""
+
+ usage = None
+ text_buffer = ""
+ thinking_buffer = ""
+ thinking_signature = ""
+ tool_calls = OrderedDict()
+ tool_call_buffers = {}
+ res = None
+
+ async for event in response:
+ content_changed = False
+ thinking_changed = False
+
+ if event.type == "message_start":
+ message = event.message
+ if message.usage:
+ usage = ChatUsage(
+ input_tokens=message.usage.input_tokens,
+ output_tokens=getattr(
+ message.usage,
+ "output_tokens",
+ 0,
+ ),
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ elif event.type == "content_block_start":
+ if event.content_block.type == "tool_use":
+ block_index = event.index
+ tool_block = event.content_block
+ tool_calls[block_index] = {
+ "type": "tool_use",
+ "id": tool_block.id,
+ "name": tool_block.name,
+ "input": "",
+ }
+ tool_call_buffers[block_index] = ""
+ content_changed = True
+
+ elif event.type == "content_block_delta":
+ block_index = event.index
+ delta = event.delta
+ if delta.type == "text_delta":
+ text_buffer += delta.text
+ content_changed = True
+ elif delta.type == "thinking_delta":
+ thinking_buffer += delta.thinking
+ thinking_changed = True
+ elif delta.type == "signature_delta":
+ thinking_signature = delta.signature
+ elif (
+ delta.type == "input_json_delta"
+ and block_index in tool_calls
+ ):
+ tool_call_buffers[block_index] += delta.partial_json or ""
+ tool_calls[block_index]["input"] = tool_call_buffers[
+ block_index
+ ]
+ content_changed = True
+
+ elif event.type == "message_delta":
+ if event.usage and usage:
+ usage.output_tokens = event.usage.output_tokens
+
+ if (thinking_changed or content_changed) and usage:
+ contents: list = []
+ if thinking_buffer:
+ thinking_block = ThinkingBlock(
+ type="thinking",
+ thinking=thinking_buffer,
+ )
+ thinking_block["signature"] = thinking_signature
+ contents.append(thinking_block)
+ if text_buffer:
+ contents.append(
+ TextBlock(
+ type="text",
+ text=text_buffer,
+ ),
+ )
+ for block_index, tool_call in tool_calls.items():
+ input_str = tool_call["input"]
+ try:
+ input_obj = _json_loads_with_repair(input_str or "{}")
+ if not isinstance(input_obj, dict):
+ input_obj = {}
+
+ except Exception:
+ input_obj = {}
+
+ contents.append(
+ ToolUseBlock(
+ type=tool_call["type"],
+ id=tool_call["id"],
+ name=tool_call["name"],
+ input=input_obj,
+ ),
+ )
+ if contents:
+ res = ChatResponse(
+ content=contents,
+ usage=usage,
+ )
+ yield res
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format the JSON schemas of the tool functions to the format that
+ Anthropic API expects."""
+ formatted_schemas = []
+ for schema in schemas:
+ assert (
+ "function" in schema
+ ), f"Invalid schema: {schema}, expect key 'function'."
+
+ assert "name" in schema["function"], (
+ f"Invalid schema: {schema}, "
+ "expect key 'name' in 'function' field."
+ )
+
+ formatted_schemas.append(
+ {
+ "name": schema["function"]["name"],
+ "description": schema["function"].get("description", ""),
+ "input_schema": schema["function"].get("parameters", {}),
+ },
+ )
+
+ return formatted_schemas
+
+ def _format_tool_choice(
+ self,
+ tool_choice: Literal["auto", "none", "any", "required"] | str | None,
+ ) -> dict | None:
+ """Format tool_choice parameter for API compatibility.
+
+ Args:
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name. For more details, please refer to
+ https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use
+ Returns:
+ `dict | None`:
+ The formatted tool choice configuration dict, or None if
+ tool_choice is None.
+ """
+ if tool_choice is None:
+ return None
+
+ type_mapping = {
+ "auto": {"type": "auto"},
+ "none": {"type": "none"},
+ "any": {"type": "any"},
+ "required": {"type": "any"},
+ }
+ if tool_choice in type_mapping:
+ return type_mapping[tool_choice]
+
+ return {"type": "tool", "name": tool_choice}
diff --git a/src/agentscope/model/_dashscope_model.py b/src/agentscope/model/_dashscope_model.py
new file mode 100644
index 000000000..9b3c2639a
--- /dev/null
+++ b/src/agentscope/model/_dashscope_model.py
@@ -0,0 +1,430 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""The dashscope API model classes."""
+import collections
+from datetime import datetime
+from http import HTTPStatus
+from typing import (
+ Any,
+ AsyncGenerator,
+ Generator,
+ Union,
+ TYPE_CHECKING,
+ List,
+ Literal,
+)
+from aioitertools import iter as giter
+
+from ._model_base import ChatModelBase
+from ._model_response import ChatResponse
+from ._model_usage import ChatUsage
+from .._utils._common import _json_loads_with_repair
+from ..message import TextBlock, ToolUseBlock, ThinkingBlock
+from ..tracing import trace_llm
+from ..types import JSONSerializableObject
+from .._logging import logger
+
+if TYPE_CHECKING:
+ from dashscope.api_entities.dashscope_response import GenerationResponse
+ from dashscope.api_entities.dashscope_response import (
+ MultiModalConversationResponse,
+ )
+else:
+ GenerationResponse = (
+ "dashscope.api_entities.dashscope_response.GenerationResponse"
+ )
+ MultiModalConversationResponse = (
+ "dashscope.api_entities.dashscope_response."
+ "MultiModalConversationResponse"
+ )
+
+
+class DashScopeChatModel(ChatModelBase):
+ """The DashScope chat model class, which unifies the Generation and
+ MultimodalConversation APIs into one method."""
+
+ def __init__(
+ self,
+ model_name: str,
+ api_key: str,
+ stream: bool = True,
+ enable_thinking: bool | None = None,
+ generate_kwargs: dict[str, JSONSerializableObject] | None = None,
+ ) -> None:
+ """Initialize the DashScope chat model.
+
+ Args:
+ model_name (`str`):
+ The model names.
+ api_key (`str`):
+ The dashscope API key.
+ stream (`bool`):
+ The streaming output or not
+ enable_thinking (`bool | None`, optional):
+ Enable thinking or not, only support Qwen3, QwQ, DeepSeek-R1.
+ Refer to `DashScope documentation
+ <https://help.aliyun.com/zh/model-studio/deep-thinking>`_
+ for more details.
+ generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
+ optional):
+ The extra keyword arguments used in DashScope API generation,
+ e.g. `temperature`, `seed`.
+ """
+ if enable_thinking and not stream:
+ logger.info(
+ "In DashScope API, `stream` must be True when "
+ "`enable_thinking` is True. ",
+ )
+ stream = True
+
+ super().__init__(model_name, stream)
+
+ self.api_key = api_key
+ self.enable_thinking = enable_thinking
+ self.incremental_output = self.stream
+ self.generate_kwargs = generate_kwargs or {}
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict] | None = None,
+ tool_choice: Literal["auto", "none", "any", "required"]
+ | str
+ | None = None,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Get the response from the dashscope
+ Generation/MultimodalConversation API by the given arguments.
+
+ .. note:: We unify the dashscope generation and multimodal conversation
+ APIs into one method, since they support similar arguments and share
+ the same functionality.
+
+ Args:
+ messages (`list[dict[str, Any]]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required.
+ tools (`list[dict] | None`, default `None`):
+ The tools JSON schemas that the model can use.
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", or specific tool name.
+ For more details, please refer to
+ https://help.aliyun.com/zh/model-studio/qwen-function-calling
+ **kwargs (`Any`):
+ The keyword arguments for DashScope chat completions API,
+ e.g. `temperature`, `max_tokens`, `top_p`, etc. Please
+ refer to `DashScope documentation
+ <https://help.aliyun.com/zh/dashscope/developer-reference/api-details>`_
+ for more detailed arguments.
+ """
+ import dashscope
+
+ # For qvq and qwen-vl models, the content field cannot be `None` or
+ # `[{"text": None}]`, so we need to convert it to an empty list.
+ if self.model_name.startswith("qvq") or "-vl" in self.model_name:
+ for msg in messages:
+ if msg["content"] is None or msg["content"] == [
+ {"text": None},
+ ]:
+ msg["content"] = []
+
+ kwargs = {
+ "messages": messages,
+ "model": self.model_name,
+ "stream": self.stream,
+ **self.generate_kwargs,
+ **kwargs,
+ "result_format": "message",
+ # In agentscope, the `incremental_output` must be `True`
+ "incremental_output": self.incremental_output,
+ }
+
+ if tools:
+ kwargs["tools"] = self._format_tools_json_schemas(tools)
+
+ if tool_choice:
+ self._validate_tool_choice(tool_choice, tools)
+ kwargs["tool_choice"] = self._format_tool_choice(tool_choice)
+
+ if self.enable_thinking and "enable_thinking" not in kwargs:
+ kwargs["enable_thinking"] = self.enable_thinking
+
+ start_datetime = datetime.now()
+ if self.model_name.startswith("qvq") or "-vl" in self.model_name:
+ response = dashscope.MultiModalConversation.call(
+ api_key=self.api_key,
+ **kwargs,
+ )
+
+ else:
+ response = await dashscope.aigc.generation.AioGeneration.call(
+ api_key=self.api_key,
+ **kwargs,
+ )
+
+ if self.stream:
+ return self._parse_dashscope_stream_response(
+ start_datetime,
+ response,
+ )
+
+ parsed_response = await self._parse_dashscope_generation_response(
+ used_time=(datetime.now() - start_datetime).total_seconds(),
+ response=response,
+ )
+
+ return parsed_response
+
+ async def _parse_dashscope_stream_response(
+ self,
+ start_datetime: datetime,
+ response: Union[
+ AsyncGenerator[GenerationResponse, None],
+ Generator[MultiModalConversationResponse, None, None],
+ ],
+ ) -> AsyncGenerator[ChatResponse, Any]:
+ """Parse the DashScope GenerationResponse object and return a
+ ChatResponse object."""
+ acc_content, acc_thinking_content = "", ""
+ acc_tool_calls = collections.defaultdict(dict)
+ parsed_chunk = None
+
+ async for chunk in giter(response):
+ if chunk.status_code != HTTPStatus.OK:
+ raise RuntimeError(
+ f"Failed to get response from _ API: {chunk}",
+ )
+
+ message = chunk.output.choices[0].message
+
+ # Update reasoning content
+ if isinstance(message.get("reasoning_content"), str):
+ acc_thinking_content += message["reasoning_content"]
+
+ # Update text content
+ if isinstance(message.content, str):
+ acc_content += message.content
+ elif isinstance(message.content, list):
+ for item in message.content:
+ if isinstance(item, dict) and "text" in item:
+ acc_content += item["text"]
+
+ # Update tool calls
+ for tool_call in message.get("tool_calls", []):
+ index = tool_call.get("index", 0)
+
+ if "id" in tool_call and tool_call["id"] != acc_tool_calls[
+ index
+ ].get("id"):
+ acc_tool_calls[index]["id"] = (
+ acc_tool_calls[index].get("id", "") + tool_call["id"]
+ )
+
+ if "function" in tool_call:
+ func = tool_call["function"]
+ if "name" in func:
+ acc_tool_calls[index]["name"] = (
+ acc_tool_calls[index].get("name", "")
+ + func["name"]
+ )
+
+ if "arguments" in func:
+ acc_tool_calls[index]["arguments"] = (
+ acc_tool_calls[index].get("arguments", "")
+ + func["arguments"]
+ )
+
+ # to content blocks
+ content_blocks: list[TextBlock | ToolUseBlock | ThinkingBlock] = []
+ if acc_thinking_content:
+ content_blocks.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=acc_thinking_content,
+ ),
+ )
+
+ if acc_content:
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=acc_content,
+ ),
+ )
+
+ for tool_call in acc_tool_calls.values():
+ repaired_input = _json_loads_with_repair(
+ tool_call.get("arguments", "{}") or "{}",
+ )
+
+ if not isinstance(repaired_input, dict):
+ repaired_input = {}
+
+ content_blocks.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=tool_call.get("id", ""),
+ name=tool_call.get("name", ""),
+ input=repaired_input,
+ ),
+ )
+
+ usage = None
+ if chunk.usage:
+ usage = ChatUsage(
+ input_tokens=chunk.usage.input_tokens,
+ output_tokens=chunk.usage.output_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ parsed_chunk = ChatResponse(
+ content=content_blocks,
+ usage=usage,
+ )
+ yield parsed_chunk
+
+ async def _parse_dashscope_generation_response(
+ self,
+ used_time: float,
+ response: Union[
+ GenerationResponse,
+ MultiModalConversationResponse,
+ ],
+ ) -> ChatResponse:
+ """Given a DashScope GenerationResponse object, extract the content
+ blocks and usages from it.
+
+ Args:
+ used_time (`float`):
+ The time used for the response in seconds.
+ response (
+ `Union[GenerationResponse, MultiModalConversationResponse]`
+ ):
+ Dashscope GenerationResponse | MultiModalConversationResponse
+ object to parse.
+
+ Returns:
+ `ChatResponse`:
+ A ChatResponse object containing the content blocks and usage.
+ """
+ # Collect the content blocks from the response.
+ if response.status_code != 200:
+ raise RuntimeError(response)
+
+ content_blocks: List[TextBlock | ToolUseBlock] = []
+
+ message = response.output.choices[0].message
+ content = message.get("content")
+
+ if response.output.choices[0].message.get("content") not in [
+ None,
+ "",
+ [],
+ ]:
+ if isinstance(content, list):
+ for item in content:
+ if isinstance(item, dict) and "text" in item:
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=item["text"],
+ ),
+ )
+ else:
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=content,
+ ),
+ )
+
+ if message.get("tool_calls"):
+ for tool_call in message["tool_calls"]:
+ content_blocks.append(
+ ToolUseBlock(
+ type="tool_use",
+ name=tool_call["function"]["name"],
+ input=_json_loads_with_repair(
+ tool_call["function"].get(
+ "arguments",
+ "{}",
+ )
+ or "{}",
+ ),
+ id=tool_call["id"],
+ ),
+ )
+
+ # Usage information
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.input_tokens,
+ output_tokens=response.usage.output_tokens,
+ time=used_time,
+ )
+
+ return ChatResponse(
+ content=content_blocks,
+ usage=usage,
+ )
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format the tools JSON schema into required format for DashScope API.
+
+ Args:
+ schemas (`dict[str, dict[str, Any]]`):
+ The tools JSON schemas.
+ """
+ # Check schemas format
+ for value in schemas:
+ if (
+ not isinstance(value, dict)
+ or "type" not in value
+ or value["type"] != "function"
+ or "function" not in value
+ ):
+ raise ValueError(
+ f"Each schema must be a dict with 'type' as 'function' "
+ f"and 'function' key, got {value}",
+ )
+
+ return schemas
+
+ def _format_tool_choice(
+ self,
+ tool_choice: Literal["auto", "none", "any", "required"] | str | None,
+ ) -> str | dict | None:
+ """Format tool_choice parameter for API compatibility.
+
+ Args:
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", or specific tool name.
+ For more details, please refer to
+ https://help.aliyun.com/zh/model-studio/qwen-function-calling
+ Returns:
+ `dict | None`:
+ The formatted tool choice configuration dict, or None if
+ tool_choice is None.
+ """
+ if tool_choice is None:
+ return None
+ if tool_choice in ["auto", "none"]:
+ return tool_choice
+ if tool_choice in ["any", "required"]:
+ logger.warning(
+ "tool_choice '%s' is not supported by DashScope API. "
+ "Supported options are 'auto', 'none', or specific function "
+ "name. Automatically using 'auto' instead.",
+ tool_choice,
+ )
+ return "auto"
+ return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/model/_gemini_model.py b/src/agentscope/model/_gemini_model.py
new file mode 100644
index 000000000..aa4f64b58
--- /dev/null
+++ b/src/agentscope/model/_gemini_model.py
@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+# mypy: disable-error-code="dict-item"
+"""The Google Gemini model in agentscope."""
+from datetime import datetime
+from typing import AsyncGenerator, Any, TYPE_CHECKING, AsyncIterator, Literal
+
+from ..message import ToolUseBlock, TextBlock, ThinkingBlock
+from ._model_usage import ChatUsage
+from ._model_base import ChatModelBase
+from ._model_response import ChatResponse
+from ..tracing import trace_llm
+from ..types import JSONSerializableObject
+
+if TYPE_CHECKING:
+ from google.genai.types import GenerateContentResponse
+else:
+ GenerateContentResponse = "google.genai.types.GenerateContentResponse"
+
+
+class GeminiChatModel(ChatModelBase):
+ """The Google Gemini chat model class in agentscope."""
+
+ def __init__(
+ self,
+ model_name: str,
+ api_key: str,
+ stream: bool = True,
+ thinking_config: dict | None = None,
+ client_args: dict = None,
+ generate_kwargs: dict[str, JSONSerializableObject] | None = None,
+ ) -> None:
+ """Initialize the Gemini chat model.
+
+ Args:
+ model_name (`str`):
+ The name of the Gemini model to use, e.g. "gemini-2.5-flash".
+ api_key (`str`):
+ The API key for Google Gemini.
+ stream (`bool`, default `True`):
+ Whether to use streaming output or not.
+ thinking_config (`dict | None`, optional):
+ Thinking config, supported models are 2.5 Pro, 2.5 Flash, etc.
+ Refer to https://ai.google.dev/gemini-api/docs/thinking for
+ more details.
+
+ .. code-block:: python
+ :caption: Example of thinking_config
+
+ {
+ "include_thoughts": True, # enable thoughts or not
+ "thinking_budget": 1024 # Max tokens for reasoning
+ }
+
+ client_args (`dict`, default `None`):
+ The extra keyword arguments to initialize the OpenAI client.
+ generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
+ optional):
+ The extra keyword arguments used in Gemini API generation,
+ e.g. `temperature`, `seed`.
+ """
+ try:
+ from google import genai
+ except ImportError as e:
+ raise ImportError(
+ "Please install gemini Python sdk with "
+ "`pip install -q -U google-genai`",
+ ) from e
+
+ super().__init__(model_name, stream)
+
+ self.client = genai.Client(
+ api_key=api_key,
+ **(client_args or {}),
+ )
+ self.thinking_config = thinking_config
+ self.generate_kwargs = generate_kwargs or {}
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict],
+ tools: list[dict] | None = None,
+ tool_choice: Literal["auto", "none", "any", "required"]
+ | str
+ | None = None,
+ **config_kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Call the Gemini model with the provided arguments.
+
+ Args:
+ messages (`list[dict[str, Any]]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required.
+ tools (`list[dict] | None`, default `None`):
+ The tools JSON schemas that the model can use.
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name. For more details, please refer to
+ https://ai.google.dev/gemini-api/docs/function-calling?hl=en&example=meeting#function_calling_modes
+ **config_kwargs (`Any`):
+ The keyword arguments for Gemini chat completions API.
+ """
+
+ config: dict = {
+ "thinking_config": self.thinking_config,
+ **self.generate_kwargs,
+ **config_kwargs,
+ }
+
+ if tools:
+ config["tools"] = self._format_tools_json_schemas(tools)
+ if tool_choice:
+ self._validate_tool_choice(tool_choice, tools)
+ config["tool_config"] = self._format_tool_choice(tool_choice)
+
+ # Prepare the arguments for the Gemini API call
+ kwargs: dict[str, JSONSerializableObject] = {
+ "model": self.model_name,
+ "contents": messages,
+ "config": config,
+ }
+
+ start_datetime = datetime.now()
+ if self.stream:
+ response = await self.client.aio.models.generate_content_stream(
+ **kwargs,
+ )
+
+ return self._parse_gemini_stream_generation_response(
+ start_datetime,
+ response,
+ )
+
+ # non-streaming
+ response = await self.client.aio.models.generate_content(
+ **kwargs,
+ )
+
+ parsed_response = self._parse_gemini_generation_response(
+ used_time=(datetime.now() - start_datetime).total_seconds(),
+ response=response,
+ )
+
+ return parsed_response
+
+ async def _parse_gemini_stream_generation_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncIterator[GenerateContentResponse],
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Gemini streaming generation response into ChatResponse"""
+
+ parsed_chunk = None
+ text = ""
+ thinking = ""
+ async for chunk in response:
+ content_block: list = []
+
+ # Thinking parts
+ if (
+ chunk.candidates
+ and chunk.candidates[0].content
+ and chunk.candidates[0].content.parts
+ ):
+ for part in chunk.candidates[0].content.parts:
+ if part.thought and part.text:
+ thinking += part.text
+
+ # Text parts
+ if chunk.text:
+ text += chunk.text
+
+ # Function calls
+ tool_calls = []
+ if chunk.function_calls:
+ for function_call in chunk.function_calls:
+ tool_calls.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=function_call.id,
+ name=function_call.name,
+ input=function_call.args or {},
+ ),
+ )
+
+ usage = None
+ if chunk.usage_metadata:
+ usage = ChatUsage(
+ input_tokens=chunk.usage_metadata.prompt_token_count,
+ output_tokens=chunk.usage_metadata.total_token_count
+ - chunk.usage_metadata.prompt_token_count,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ if thinking:
+ content_block.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=thinking,
+ ),
+ )
+
+ if text:
+ content_block.append(
+ TextBlock(
+ type="text",
+ text=text,
+ ),
+ )
+
+ content_block.extend(
+ [
+ *tool_calls,
+ ],
+ )
+
+ parsed_chunk = ChatResponse(
+ content=content_block,
+ usage=usage,
+ )
+ yield parsed_chunk
+
+ def _parse_gemini_generation_response(
+ self,
+ used_time: float,
+ response: GenerateContentResponse,
+ ) -> ChatResponse:
+ """Parse the Gemini generation response into ChatResponse"""
+ content: list = []
+
+ if (
+ response.candidates
+ and response.candidates[0].content
+ and response.candidates[0].content.parts
+ ):
+ for part in response.candidates[0].content.parts:
+ if part.thought and part.text:
+ content.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=part.text,
+ ),
+ )
+
+ if response.text:
+ content.append(
+ TextBlock(
+ type="text",
+ text=response.text,
+ ),
+ )
+
+ if response.function_calls:
+ for tool_call in response.function_calls:
+ content.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=tool_call.id,
+ name=tool_call.name,
+ input=tool_call.args or {},
+ ),
+ )
+
+ if response.usage_metadata:
+ usage = ChatUsage(
+ input_tokens=response.usage_metadata.prompt_token_count,
+ output_tokens=response.usage_metadata.total_token_count
+ - response.usage_metadata.prompt_token_count,
+ time=used_time,
+ )
+
+ else:
+ usage = None
+
+ return ChatResponse(
+ content=content,
+ usage=usage,
+ )
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format the tools JSON schema into required format for Gemini API.
+
+ Args:
+ schemas (`dict[str, Any]`):
+ The tools JSON schemas.
+
+ Returns:
+ List[Dict[str, Any]]:
+ A list containing a dictionary with the
+ "function_declarations" key, which maps to a list of
+ function definitions.
+
+ Example:
+ .. code-block:: python
+ :caption: Example tool schemas of Gemini API
+
+ # Input JSON schema
+ schemas = [
+ {
+ 'type': 'function',
+ 'function': {
+ 'name': 'execute_shell_command',
+ 'description': 'xxx',
+ 'parameters': {
+ 'type': 'object',
+ 'properties': {
+ 'command': {
+ 'type': 'string',
+ 'description': 'xxx.'
+ },
+ 'timeout': {
+ 'type': 'integer',
+ 'default': 300
+ }
+ },
+ 'required': ['command']
+ }
+ }
+ }
+ ]
+
+ # Output format (Gemini API expected):
+ [
+ {
+ 'function_declarations': [
+ {
+ 'name': 'execute_shell_command',
+ 'description': 'xxx.',
+ 'parameters': {
+ 'type': 'object',
+ 'properties': {
+ 'command': {
+ 'type': 'string',
+ 'description': 'xxx.'
+ },
+ 'timeout': {
+ 'type': 'integer',
+ 'default': 300
+ }
+ },
+ 'required': ['command']
+ }
+ }
+ ]
+ }
+ ]
+ """
+ return [
+ {
+ "function_declarations": [
+ _["function"] for _ in schemas if "function" in _
+ ],
+ },
+ ]
+
+ def _format_tool_choice(
+ self,
+ tool_choice: Literal["auto", "none", "any", "required"] | str | None,
+ ) -> dict | None:
+ """Format tool_choice parameter for API compatibility.
+
+ Args:
+ tool_choice (`Literal["auto", "none"] | str | None`, default \
+ `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name.
+ For more details, please refer to
+ https://ai.google.dev/gemini-api/docs/function-calling?hl=en&example=meeting#function_calling_modes
+ Returns:
+ `dict | None`:
+ The formatted tool choice configuration dict, or None if
+ tool_choice is None.
+ """
+ if tool_choice is None:
+ return None
+
+ mode_mapping = {
+ "auto": "AUTO",
+ "none": "NONE",
+ "any": "ANY",
+ "required": "ANY",
+ }
+ mode = mode_mapping.get(tool_choice)
+ if mode:
+ return {"function_calling_config": {"mode": mode}}
+ return {
+ "function_calling_config": {
+ "mode": "ANY",
+ "allowed_function_names": [tool_choice],
+ },
+ }
diff --git a/src/agentscope/model/_model_base.py b/src/agentscope/model/_model_base.py
new file mode 100644
index 000000000..d615dc3dc
--- /dev/null
+++ b/src/agentscope/model/_model_base.py
@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""The chat model base class."""
+
+from abc import abstractmethod
+from typing import AsyncGenerator, Any
+
+from ._model_response import ChatResponse
+
+TOOL_CHOICE_MODES = ["auto", "none", "any", "required"]
+
+
+class ChatModelBase:
+ """Base class for chat models."""
+
+ model_name: str
+ """The model name"""
+
+ stream: bool
+ """Is the model output streaming or not"""
+
+ def __init__(
+ self,
+ model_name: str,
+ stream: bool,
+ ) -> None:
+ """Initialize the chat model base class.
+
+ Args:
+ model_name (`str`):
+ The name of the model
+ stream (`bool`):
+ Whether the model output is streaming or not
+ """
+ self.model_name = model_name
+ self.stream = stream
+
+ @abstractmethod
+ async def __call__(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ pass
+
+ def _validate_tool_choice(
+ self,
+ tool_choice: str,
+ tools: list[dict] | None,
+ ) -> None:
+ """
+ Validate tool_choice parameter.
+
+ Args:
+ tool_choice (`str`):
+ Tool choice mode or function name
+ tools (`list[dict] | None`):
+ Available tools list
+ Raises:
+ TypeError: If tool_choice is not string
+ ValueError: If tool_choice is invalid
+ """
+ if not isinstance(tool_choice, str):
+ raise TypeError(
+ f"tool_choice must be str, got {type(tool_choice)}",
+ )
+ if tool_choice in TOOL_CHOICE_MODES:
+ return
+
+ available_functions = [tool["function"]["name"] for tool in tools]
+
+ if tool_choice not in available_functions:
+ all_options = TOOL_CHOICE_MODES + available_functions
+ raise ValueError(
+ f"Invalid tool_choice '{tool_choice}'. "
+ f"Available options: {', '.join(sorted(all_options))}",
+ )
diff --git a/src/agentscope/model/_model_response.py b/src/agentscope/model/_model_response.py
new file mode 100644
index 000000000..87c00d9f8
--- /dev/null
+++ b/src/agentscope/model/_model_response.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""The model response module."""
+
+from dataclasses import dataclass, field
+from typing import Literal, Sequence
+
+from anthropic.types import ThinkingBlock
+
+from ._model_usage import ChatUsage
+from .._utils._common import _get_timestamp
+from .._utils._mixin import DictMixin
+from ..message import TextBlock, ToolUseBlock
+
+
+@dataclass
+class ChatResponse(DictMixin):
+ """The response of chat models."""
+
+ content: Sequence[TextBlock | ToolUseBlock | ThinkingBlock]
+ """The content of the chat response, which can include text blocks,
+ tool use blocks, or thinking blocks."""
+
+ id: str = field(default_factory=lambda: _get_timestamp(True))
+ """The unique identifier formatter """
+
+ created_at: str = field(default_factory=_get_timestamp)
+ """When the response was created"""
+
+ type: Literal["chat"] = field(default_factory=lambda: "chat")
+ """The type of the response, which is always 'chat'."""
+
+ usage: ChatUsage | None = field(default_factory=lambda: None)
+ """The usage information of the chat response, if available."""
diff --git a/src/agentscope/model/_model_usage.py b/src/agentscope/model/_model_usage.py
new file mode 100644
index 000000000..fcc76120f
--- /dev/null
+++ b/src/agentscope/model/_model_usage.py
@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""The model usage class in agentscope."""
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .._utils._mixin import DictMixin
+
+
+@dataclass
+class ChatUsage(DictMixin):
+ """The usage of a chat model API invocation."""
+
+ input_tokens: int
+ """The number of input tokens."""
+
+ output_tokens: int
+ """The number of output tokens."""
+
+ time: float
+ """The time used in seconds."""
+
+ type: Literal["chat"] = field(default_factory=lambda: "chat")
+ """The type of the usage, must be `chat`."""
diff --git a/src/agentscope/model/_ollama_model.py b/src/agentscope/model/_ollama_model.py
new file mode 100644
index 000000000..80d45d94b
--- /dev/null
+++ b/src/agentscope/model/_ollama_model.py
@@ -0,0 +1,321 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""Model wrapper for Ollama models."""
+from datetime import datetime
+from typing import (
+ Any,
+ TYPE_CHECKING,
+ List,
+ AsyncGenerator,
+ AsyncIterator,
+ Literal,
+)
+from collections import OrderedDict
+
+from . import ChatResponse
+from ._model_base import ChatModelBase
+from ._model_usage import ChatUsage
+from .._logging import logger
+from .._utils._common import _json_loads_with_repair
+from ..message import ToolUseBlock, TextBlock, ThinkingBlock
+from ..tracing import trace_llm
+
+
+if TYPE_CHECKING:
+ from ollama._types import OllamaChatResponse
+else:
+ OllamaChatResponse = "ollama._types.ChatResponse"
+
+
+class OllamaChatModel(ChatModelBase):
+ """The Ollama chat model class in agentscope."""
+
+ def __init__(
+ self,
+ model_name: str,
+ stream: bool = False,
+ options: dict = None,
+ keep_alive: str = "5m",
+ enable_thinking: bool | None = None,
+ host: str | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the Ollama chat model.
+
+ Args:
+ model_name (`str`):
+ The name of the model.
+ stream (`bool`, default `True`):
+ Streaming mode or not.
+ options (`dict`, default `None`):
+ Additional parameters to pass to the Ollama API. These can
+ include temperature etc.
+ keep_alive (`str`, default `"5m"`):
+ Duration to keep the model loaded in memory. The format is a
+ number followed by a unit suffix (s for seconds, m for minutes
+ , h for hours).
+ enable_thinking (`bool | None`, default `None`)
+ Whether enable thinking or not, only for models such as qwen3,
+ deepseek-r1, etc. For more details, please refer to
+ https://ollama.com/search?c=thinking
+ host (`str | None`, default `None`):
+ The host address of the Ollama server. If None, uses the
+ default address (typically http://localhost:11434).
+ **kwargs (`Any`):
+ Additional keyword arguments to pass to the base chat model
+ class.
+ """
+
+ try:
+ import ollama
+ except ImportError as e:
+ raise ImportError(
+ "The package ollama is not found. Please install it by "
+ 'running command `pip install "ollama>=0.1.7"`',
+ ) from e
+
+ super().__init__(model_name, stream)
+
+ self.client = ollama.AsyncClient(
+ host=host,
+ **kwargs,
+ )
+ self.options = options
+ self.keep_alive = keep_alive
+ self.think = enable_thinking
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict] | None = None,
+ tool_choice: Literal["auto", "none", "any", "required"]
+ | str
+ | None = None,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Get the response from Ollama chat completions API by the given
+ arguments.
+
+ Args:
+ messages (`list[dict]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required, and `name` field is optional.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas that the model can use.
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name.
+ **kwargs (`Any`):
+ The keyword arguments for Ollama chat completions API,
+ e.g. `think`etc. Please refer to the Ollama API
+ documentation for more details.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ The response from the Ollama chat completions API.
+ """
+
+ kwargs = {
+ "model": self.model_name,
+ "messages": messages,
+ "stream": self.stream,
+ "options": self.options,
+ "keep_alive": self.keep_alive,
+ **kwargs,
+ }
+
+ if self.think is not None and "think" not in kwargs:
+ kwargs["think"] = self.think
+
+ if tools:
+ kwargs["tools"] = self._format_tools_json_schemas(tools)
+
+ if tool_choice:
+ logger.warning("Ollama does not support tool_choice yet, ignored.")
+
+ start_datetime = datetime.now()
+ response = await self.client.chat(**kwargs)
+
+ if self.stream:
+ return self._parse_ollama_stream_completion_response(
+ start_datetime,
+ response,
+ )
+
+ parsed_response = await self._parse_ollama_completion_response(
+ start_datetime,
+ response,
+ )
+
+ return parsed_response
+
+ async def _parse_ollama_stream_completion_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncIterator[Any],
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the Ollama chat completion response stream into an async
+ generator of `ChatResponse` objects."""
+ accumulated_text = ""
+ acc_thinking_content = ""
+ tool_calls = OrderedDict() # Store tool calls
+
+ async for chunk in response:
+ has_new_content = False
+ has_new_thinking = False
+
+ # Handle text content
+ if hasattr(chunk, "message"):
+ msg = chunk.message
+
+ if getattr(msg, "thinking", None):
+ acc_thinking_content += msg.thinking
+ has_new_thinking = True
+
+ if getattr(msg, "content", None):
+ accumulated_text += msg.content
+ has_new_content = True
+
+ # Handle tool calls
+ if getattr(msg, "tool_calls", None):
+ has_new_content = True
+ for idx, tool_call in enumerate(msg.tool_calls):
+ function_name = (
+ getattr(
+ tool_call,
+ "function",
+ None,
+ )
+ and tool_call.function.name
+ or "tool"
+ )
+ tool_id = getattr(
+ tool_call,
+ "id",
+ f"{function_name}_{idx}",
+ )
+ if hasattr(tool_call, "function"):
+ function = tool_call.function
+ tool_calls[tool_id] = {
+ "type": "tool_use",
+ "id": tool_id,
+ "name": function.name,
+ "input": function.arguments,
+ }
+ # Calculate usage statistics
+ current_time = (datetime.now() - start_datetime).total_seconds()
+ usage = ChatUsage(
+ input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,
+ output_tokens=getattr(chunk, "eval_count", 0) or 0,
+ time=current_time,
+ )
+ # Create content blocks
+ contents: list = []
+
+ if acc_thinking_content:
+ contents.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=acc_thinking_content,
+ ),
+ )
+
+ if accumulated_text:
+ contents.append(TextBlock(type="text", text=accumulated_text))
+
+ # Add tool call blocks
+ if tool_calls:
+ for tool_call in tool_calls.values():
+ try:
+ input_data = tool_call["input"]
+ if isinstance(input_data, str):
+ input_data = _json_loads_with_repair(input_data)
+ contents.append(
+ ToolUseBlock(
+ type=tool_call["type"],
+ id=tool_call["id"],
+ name=tool_call["name"],
+ input=input_data,
+ ),
+ )
+ except Exception as e:
+ print(f"Error parsing tool call input: {e}")
+
+ # Generate response when there's new content or at final chunk
+ is_final = getattr(chunk, "done", False)
+ if (has_new_thinking or has_new_content or is_final) and contents:
+ res = ChatResponse(content=contents, usage=usage)
+ yield res
+
+ async def _parse_ollama_completion_response(
+ self,
+ start_datetime: datetime,
+ response: OllamaChatResponse,
+ ) -> ChatResponse:
+ """Parse the Ollama chat completion response into a `ChatResponse`
+ object.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`OllamaChatResponse`):
+ The Ollama chat response object to parse.
+
+ Returns:
+ `ChatResponse`:
+ The content blocks and usage information extracted from the
+ response.
+ """
+ content_blocks: List[TextBlock | ToolUseBlock | ThinkingBlock] = []
+
+ if response.message.thinking:
+ content_blocks.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=response.message.thinking,
+ ),
+ )
+
+ if response.message.content:
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=response.message.content,
+ ),
+ )
+
+ if response.message.tool_calls:
+ for tool_call in response.message.tool_calls:
+ content_blocks.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=tool_call.function.name,
+ name=tool_call.function.name,
+ input=tool_call.function.arguments,
+ ),
+ )
+
+ usage = None
+ if "prompt_eval_count" in response and "eval_count" in response:
+ usage = ChatUsage(
+ input_tokens=response.get("prompt_eval_count", 0),
+ output_tokens=response.get("eval_count", 0),
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ parsed_response = ChatResponse(
+ content=content_blocks,
+ usage=usage,
+ )
+
+ return parsed_response
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format the tools JSON schemas to the Ollama format."""
+ return schemas
diff --git a/src/agentscope/model/_openai_model.py b/src/agentscope/model/_openai_model.py
new file mode 100644
index 000000000..fa034e17b
--- /dev/null
+++ b/src/agentscope/model/_openai_model.py
@@ -0,0 +1,356 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-branches
+"""OpenAI Chat model class."""
+from datetime import datetime
+from typing import (
+ Any,
+ TYPE_CHECKING,
+ List,
+ AsyncGenerator,
+ Literal,
+)
+from collections import OrderedDict
+
+from . import ChatResponse
+from ._model_base import ChatModelBase
+from ._model_usage import ChatUsage
+from .._utils._common import _json_loads_with_repair
+from ..message import ToolUseBlock, TextBlock, ThinkingBlock
+from ..tracing import trace_llm
+from ..types import JSONSerializableObject
+
+if TYPE_CHECKING:
+ from openai.types.chat import ChatCompletion
+ from openai import AsyncStream
+else:
+ ChatCompletion = "openai.types.chat.ChatCompletion"
+ AsyncStream = "openai.types.chat.AsyncStream"
+
+
+class OpenAIChatModel(ChatModelBase):
+ """The OpenAI chat model class."""
+
+ def __init__(
+ self,
+ model_name: str,
+ api_key: str | None = None,
+ stream: bool = True,
+ reasoning_effort: Literal["low", "medium", "high"] | None = None,
+ organization: str = None,
+ client_args: dict = None,
+ generate_kwargs: dict[str, JSONSerializableObject] | None = None,
+ ) -> None:
+ """Initialize the openai client.
+
+ Args:
+ model_name (`str`, default `None`):
+ The name of the model to use in OpenAI API.
+ api_key (`str`, default `None`):
+ The API key for OpenAI API. If not specified, it will
+ be read from the environment variable `OPENAI_API_KEY`.
+ stream (`bool`, default `True`):
+ Whether to use streaming output or not.
+ reasoning_effort (`Literal["low", "medium", "high"] | None`, \
+ optional):
+ Reasoning effort, supported for o3, o4, etc. Please refer to
+ `OpenAI documentation
+ <https://platform.openai.com/docs/guides/reasoning?api-mode=chat>`_
+ for more details.
+ organization (`str`, default `None`):
+ The organization ID for OpenAI API. If not specified, it will
+ be read from the environment variable `OPENAI_ORGANIZATION`.
+ client_args (`dict`, default `None`):
+ The extra keyword arguments to initialize the OpenAI client.
+ generate_kwargs (`dict[str, JSONSerializableObject] | None`, \
+ optional):
+ The extra keyword arguments used in OpenAI API generation,
+ e.g. `temperature`, `seed`.
+ """
+
+ super().__init__(model_name, stream)
+
+ import openai
+
+ self.client = openai.AsyncClient(
+ api_key=api_key,
+ organization=organization,
+ **(client_args or {}),
+ )
+
+ self.reasoning_effort = reasoning_effort
+ self.generate_kwargs = generate_kwargs or {}
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict],
+ tools: list[dict] | None = None,
+ tool_choice: Literal["auto", "none", "any", "required"]
+ | str
+ | None = None,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """Get the response from OpenAI chat completions API by the given
+ arguments.
+
+ Args:
+ messages (`list[dict]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required, and `name` field is optional.
+ tools (`list[dict]`, default `None`):
+ The tools JSON schemas that the model can use.
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name. For more details, please refer to
+ https://platform.openai.com/docs/api-reference/responses/create#responses_create-tool_choice
+ **kwargs (`Any`):
+ The keyword arguments for OpenAI chat completions API,
+ e.g. `temperature`, `max_tokens`, `top_p`, etc. Please
+ refer to the OpenAI API documentation for more details.
+
+ Returns:
+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:
+ The response from the OpenAI chat completions API.
+ """
+
+ # checking messages
+ if not isinstance(messages, list):
+ raise ValueError(
+ "OpenAI `messages` field expected type `list`, "
+ f"got `{type(messages)}` instead.",
+ )
+ if not all("role" in msg and "content" in msg for msg in messages):
+ raise ValueError(
+ "Each message in the 'messages' list must contain a 'role' "
+ "and 'content' key for OpenAI API.",
+ )
+
+ kwargs = {
+ "model": self.model_name,
+ "messages": messages,
+ "stream": self.stream,
+ **self.generate_kwargs,
+ **kwargs,
+ }
+ if self.reasoning_effort and "reasoning_effort" not in kwargs:
+ kwargs["reasoning_effort"] = self.reasoning_effort
+
+ if tools:
+ kwargs["tools"] = self._format_tools_json_schemas(tools)
+
+ if tool_choice:
+ self._validate_tool_choice(tool_choice, tools)
+ kwargs["tool_choice"] = self._format_tool_choice(tool_choice)
+
+ if self.stream:
+ kwargs["stream_options"] = {"include_usage": True}
+
+ start_datetime = datetime.now()
+ response = await self.client.chat.completions.create(**kwargs)
+
+ if self.stream:
+ return self._parse_openai_stream_completion_response(
+ start_datetime,
+ response,
+ )
+
+ # Non-streaming response
+ parsed_response = self._parse_openai_completion_response(
+ start_datetime,
+ response,
+ )
+
+ return parsed_response
+
+ async def _parse_openai_stream_completion_response(
+ self,
+ start_datetime: datetime,
+ response: AsyncStream,
+ ) -> AsyncGenerator[ChatResponse, None]:
+ """Parse the OpenAI chat completion response stream into an async
+ generator of `ChatResponse` objects."""
+ usage, res = None, None
+ text = ""
+ thinking = ""
+ tool_calls = OrderedDict()
+ async for chunk in response:
+ if chunk.usage:
+ usage = ChatUsage(
+ input_tokens=chunk.usage.prompt_tokens,
+ output_tokens=chunk.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ if chunk.choices:
+ choice = chunk.choices[0]
+ if (
+ hasattr(choice.delta, "reasoning_content")
+ and choice.delta.reasoning_content is not None
+ ):
+ thinking += choice.delta.reasoning_content
+
+ if choice.delta.content:
+ text += choice.delta.content
+
+ if choice.delta.tool_calls:
+ for tool_call in choice.delta.tool_calls:
+ if tool_call.index in tool_calls:
+ if tool_call.function.arguments is not None:
+ tool_calls[tool_call.index][
+ "input"
+ ] += tool_call.function.arguments
+
+ else:
+ tool_calls[tool_call.index] = {
+ "type": "tool_use",
+ "id": tool_call.id,
+ "name": tool_call.function.name,
+ "input": tool_call.function.arguments or "",
+ }
+
+ contents: List[TextBlock | ToolUseBlock | ThinkingBlock] = []
+
+ if thinking:
+ contents.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=thinking,
+ ),
+ )
+
+ if text:
+ contents.append(
+ TextBlock(
+ type="text",
+ text=text,
+ ),
+ )
+
+ if tool_calls:
+ for tool_call in tool_calls.values():
+ contents.append(
+ ToolUseBlock(
+ type=tool_call["type"],
+ id=tool_call["id"],
+ name=tool_call["name"],
+ input=_json_loads_with_repair(
+ tool_call["input"] or "{}",
+ ),
+ ),
+ )
+
+ if contents:
+ res = ChatResponse(
+ content=contents,
+ usage=usage,
+ )
+ yield res
+
+ def _parse_openai_completion_response(
+ self,
+ start_datetime: datetime,
+ response: ChatCompletion,
+ ) -> ChatResponse:
+ """Parse the OpenAI chat completion response into a `ChatResponse`
+ object.
+
+ Args:
+ start_datetime (`datetime`):
+ The start datetime of the response generation.
+ response (`ChatCompletion`):
+ The OpenAI chat completion response object to parse.
+
+ Returns:
+ `Tuple[List[TextBlock | ToolUseBlock] | None, ChatUsage | None]`:
+ The content blocks and usage information extracted from the
+ response.
+ """
+ content_blocks: List[TextBlock | ToolUseBlock | ThinkingBlock] = []
+
+ if response.choices:
+ choice = response.choices[0]
+ if (
+ hasattr(choice.message, "reasoning_content")
+ and choice.message.reasoning_content is not None
+ ):
+ content_blocks.append(
+ ThinkingBlock(
+ type="thinking",
+ thinking=response.choices[0].message.reasoning_content,
+ ),
+ )
+
+ if choice.message.content:
+ content_blocks.append(
+ TextBlock(
+ type="text",
+ text=response.choices[0].message.content,
+ ),
+ )
+
+ if choice.message.tool_calls:
+ for tool_call in choice.message.tool_calls:
+ content_blocks.append(
+ ToolUseBlock(
+ type="tool_use",
+ id=tool_call.id,
+ name=tool_call.function.name,
+ input=_json_loads_with_repair(
+ tool_call.function.arguments,
+ ),
+ ),
+ )
+
+ usage = None
+ if response.usage:
+ usage = ChatUsage(
+ input_tokens=response.usage.prompt_tokens,
+ output_tokens=response.usage.completion_tokens,
+ time=(datetime.now() - start_datetime).total_seconds(),
+ )
+
+ parsed_response = ChatResponse(
+ content=content_blocks,
+ usage=usage,
+ )
+
+ return parsed_response
+
+ def _format_tools_json_schemas(
+ self,
+ schemas: list[dict[str, Any]],
+ ) -> list[dict[str, Any]]:
+ """Format the tools JSON schemas to the OpenAI format."""
+ return schemas
+
+ def _format_tool_choice(
+ self,
+ tool_choice: Literal["auto", "none", "any", "required"] | str | None,
+ ) -> str | dict | None:
+ """Format tool_choice parameter for API compatibility.
+
+ Args:
+ tool_choice (`Literal["auto", "none", "any", "required"] | str \
+ | None`, default `None`):
+ Controls which (if any) tool is called by the model.
+ Can be "auto", "none", "any", "required", or specific tool
+ name. For more details, please refer to
+ https://platform.openai.com/docs/api-reference/responses/create#responses_create-tool_choice
+ Returns:
+ `dict | None`:
+ The formatted tool choice configuration dict, or None if
+ tool_choice is None.
+ """
+ if tool_choice is None:
+ return None
+ mode_mapping = {
+ "auto": "auto",
+ "none": "none",
+ "any": "required",
+ "required": "required",
+ }
+ if tool_choice in mode_mapping:
+ return mode_mapping[tool_choice]
+ return {"type": "function", "function": {"name": tool_choice}}
diff --git a/src/agentscope/module/__init__.py b/src/agentscope/module/__init__.py
new file mode 100644
index 000000000..9ef34be48
--- /dev/null
+++ b/src/agentscope/module/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The module in agentscope."""
+
+from ._state_module import StateModule
+
+__all__ = [
+ "StateModule",
+]
diff --git a/src/agentscope/module/_state_module.py b/src/agentscope/module/_state_module.py
new file mode 100644
index 000000000..20bf3625f
--- /dev/null
+++ b/src/agentscope/module/_state_module.py
@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""The state module in agentscope."""
+
+import json
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Callable, Any, Optional
+
+from ..types import JSONSerializableObject
+
+
+@dataclass
+class _JSONSerializeFunction:
+ to_json: Optional[Callable[[Any], Any]] = None
+ """The function converting the original data to JSON data."""
+ load_json: Optional[Callable[[Any], Any]] = None
+ """The function converting the JSON data to original data."""
+
+
+class StateModule:
+ """The state module class in agentscope to support nested state
+ serialization and deserialization."""
+
+ def __init__(self) -> None:
+ """Initialize the state module."""
+ self._module_dict = OrderedDict()
+ self._attribute_dict = OrderedDict()
+
+ def __setattr__(self, key: str, value: Any) -> None:
+ """Set attributes and record state modules."""
+ if isinstance(value, StateModule):
+ if not hasattr(self, "_module_dict"):
+ raise AttributeError(
+ f"Call the super().__init__() method within the "
+ f"constructor of {self.__class__.__name__} before setting "
+ f"any attributes.",
+ )
+ self._module_dict[key] = value
+ super().__setattr__(key, value)
+
+ def __delattr__(self, key: str) -> None:
+ """Delete attributes and remove from state modules."""
+ if key in self._module_dict:
+ self._module_dict.pop(key)
+ if key in self._attribute_dict:
+ self._attribute_dict.pop(key)
+ super().__delattr__(key)
+
+ def state_dict(self) -> dict:
+ """Get the state dictionary of the module, including the nested
+ state modules and registered attributes.
+
+ Returns:
+ `dict`:
+ A dictionary that keys are attribute names and values are
+ the state of the attribute.
+ """
+ state = {}
+ for key in self._module_dict:
+ attr = getattr(self, key, None)
+ if isinstance(attr, StateModule):
+ state[key] = attr.state_dict()
+
+ for key in self._attribute_dict:
+ attr = getattr(self, key)
+ to_json_function = self._attribute_dict[key].to_json
+ if to_json_function is not None:
+ state[key] = to_json_function(attr)
+ else:
+ state[key] = attr
+
+ return state
+
+ def load_state_dict(self, state_dict: dict, strict: bool = True) -> None:
+ """Load the state dictionary into the module.
+
+ Args:
+ state_dict (`dict`):
+ The state dictionary to load.
+ strict (`bool`, defaults to `True`):
+ If `True`, raises an error if any key in the module is not
+ found in the state_dict. If `False`, skips missing keys.
+ """
+ for key in self._module_dict:
+ if key not in state_dict:
+ if strict:
+ raise KeyError(
+ f"Key '{key}' not found in state_dict. Ensure that "
+ f"the state_dict contains all required keys.",
+ )
+ continue
+ self._module_dict[key].load_state_dict(state_dict[key])
+
+ for key in self._attribute_dict:
+ if key not in state_dict:
+ if strict:
+ raise KeyError(
+ f"Key '{key}' not found in state_dict. Ensure that "
+ f"the state_dict contains all required keys.",
+ )
+ continue
+ from_json_func = self._attribute_dict[key].load_json
+ if from_json_func is not None:
+ setattr(self, key, from_json_func(state_dict[key]))
+ else:
+ setattr(self, key, state_dict[key])
+
+ def register_state(
+ self,
+ attr_name: str,
+ custom_to_json: Callable[[Any], JSONSerializableObject] | None = None,
+ custom_from_json: Callable[[JSONSerializableObject], Any]
+ | None = None,
+ ) -> None:
+ """Register an attribute to be tracked as a state variable.
+
+ Args:
+ attr_name (`str`):
+ The name of the attribute to register.
+ custom_to_json (`Callable[[Any], JSONSerializableObject] | None`, \
+ optional):
+ A custom function to convert the attribute to a
+ JSON-serializable format. If not provided, `json.dumps` will
+ be used.
+ custom_from_json (`Callable[[JSONSerializableObject], Any] | None`\
+ , defaults to `None`):
+ A custom function to convert the JSON dictionary back to the
+ original attribute format.
+ """
+ attr = getattr(self, attr_name)
+
+ if custom_to_json is None:
+ # Make sure the attribute is JSON serializable natively
+ try:
+ json.dumps(attr)
+ except Exception as e:
+ raise TypeError(
+ f"Attribute '{attr_name}' is not JSON serializable. "
+ "Please provide a custom function to convert the "
+ "attribute to a JSON-serializable format.",
+ ) from e
+
+ if attr_name in self._module_dict:
+ raise ValueError(
+ f"Attribute `{attr_name}` is already registered as a module. ",
+ )
+
+ self._attribute_dict[attr_name] = _JSONSerializeFunction(
+ to_json=custom_to_json,
+ load_json=custom_from_json,
+ )
diff --git a/src/agentscope/pipeline/__init__.py b/src/agentscope/pipeline/__init__.py
new file mode 100644
index 000000000..c7cdf7229
--- /dev/null
+++ b/src/agentscope/pipeline/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""The pipeline module in AgentScope, that provides syntactic sugar for
+complex workflows and multi-agent conversations."""
+
+from ._msghub import MsgHub
+from ._class import SequentialPipeline
+from ._functional import sequential_pipeline
+
+__all__ = [
+ "MsgHub",
+ "SequentialPipeline",
+ "sequential_pipeline",
+]
diff --git a/src/agentscope/pipeline/_class.py b/src/agentscope/pipeline/_class.py
new file mode 100644
index 000000000..39f6fd799
--- /dev/null
+++ b/src/agentscope/pipeline/_class.py
@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""Pipeline classes."""
+from ._functional import sequential_pipeline
+from ..agent import AgentBase
+from ..message import Msg
+
+
+class SequentialPipeline:
+ """An async sequential pipeline class, which executes a sequence of
+ agents sequentially. Compared with functional pipeline, this class
+ can be re-used."""
+
+ def __init__(
+ self,
+ agents: list[AgentBase],
+ ) -> None:
+ """Initialize a sequential pipeline class
+
+ Args:
+ agents (`list[AgentBase]`):
+ A list of agents.
+ """
+ self.agents = agents
+
+ async def __call__(
+ self,
+ msg: Msg | list[Msg] | None = None,
+ ) -> Msg | list[Msg] | None:
+ """Execute the sequential pipeline
+
+ Args:
+ msg (`Msg | list[Msg] | None`, defaults to `None`):
+ The initial input that will be passed to the first agent.
+ """
+ return await sequential_pipeline(agents=self.agents, msg=msg)
diff --git a/src/agentscope/pipeline/_functional.py b/src/agentscope/pipeline/_functional.py
new file mode 100644
index 000000000..590f44c77
--- /dev/null
+++ b/src/agentscope/pipeline/_functional.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Functional counterpart for Pipeline"""
+from ..agent import AgentBase
+from ..message import Msg
+
+
+async def sequential_pipeline(
+ agents: list[AgentBase],
+ msg: Msg | list[Msg] | None = None,
+) -> Msg | list[Msg] | None:
+ """An async syntactic sugar pipeline that executes a sequence of agents
+ sequentially. The output of the previous agent will be passed as the
+ input to the next agent. The final output will be the output of the
+ last agent.
+
+ Example:
+ .. code-block:: python
+
+ agent1 = ReActAgent(...)
+ agent2 = ReActAgent(...)
+ agent3 = ReActAgent(...)
+
+ msg_input = Msg("user", "Hello", "user")
+
+ msg_output = await sequential_pipeline(
+ [agent1, agent2, agent3],
+ msg_input
+ )
+
+ Args:
+ agents (`list[AgentBase]`):
+ A list of agents.
+ msg (`Msg | list[Msg] | None`, defaults to `None`):
+ The initial input that will be passed to the first agent.
+
+ Returns:
+ `Msg | list[Msg] | None`:
+ The output of the last agent in the sequence.
+ """
+ for agent in agents:
+ msg = await agent(msg)
+ return msg
diff --git a/src/agentscope/pipeline/_msghub.py b/src/agentscope/pipeline/_msghub.py
new file mode 100644
index 000000000..3d8a1ceed
--- /dev/null
+++ b/src/agentscope/pipeline/_msghub.py
@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""MsgHub is designed to share messages among a group of agents."""
+from typing import Any
+
+from .._logging import logger
+
+from ..agent import AgentBase
+from ..message import Msg
+
+
+class MsgHub:
+ """MsgHub class that controls the subscription of the participated agents.
+
+ Example:
+ In the following example, the reply message from `agent1`, `agent2`,
+ and `agent3` will be broadcasted to all the other agents in the MsgHub.
+
+ .. code-block:: python
+
+ with MsgHub(participant=[agent1, agent2, agent3]):
+ agent1()
+ agent2()
+
+ Actually, it has the same effect as the following code, but much more
+ easy and elegant!
+
+ .. code-block:: python
+
+ x1 = agent1()
+ agent2.observe(x1)
+ agent3.observe(x1)
+
+ x2 = agent2()
+ agent1.observe(x2)
+ agent3.observe(x2)
+
+ """
+
+ def __init__(
+ self,
+ participants: list[AgentBase],
+ announcement: list[Msg] | Msg | None = None,
+ ) -> None:
+ """Initialize a MsgHub context manager.
+
+ Args:
+ participants (`list[AgentBase]`):
+ A list of agents that participate in the MsgHub.
+ announcement (`list[Msg] | Msg | None`):
+ The message that will be broadcast to all participants when
+ entering the MsgHub.
+ """
+ self.participants = participants
+ self.announcement = announcement
+
+ async def __aenter__(self) -> "MsgHub":
+ """Will be called when entering the MsgHub."""
+ self._reset_subscriber()
+
+ # broadcast the input message to all participants
+ if self.announcement is not None:
+ for agent in self.participants:
+ await agent.observe(self.announcement)
+
+ return self
+
+ async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
+ """Will be called when exiting the MsgHub."""
+ for agent in self.participants:
+ agent.reset_subscribers([])
+
+ def _reset_subscriber(self) -> None:
+ """Reset the subscriber for agent in `self.participant`"""
+ for agent in self.participants:
+ agent.reset_subscribers(self.participants)
+
+ def add(
+ self,
+ new_participant: list[AgentBase] | AgentBase,
+ ) -> None:
+ """Add new participant into this hub"""
+ if isinstance(new_participant, AgentBase):
+ new_participant = [new_participant]
+
+ for agent in new_participant:
+ if agent not in self.participants:
+ self.participants.append(agent)
+
+ self._reset_subscriber()
+
+ def delete(
+ self,
+ participant: list[AgentBase] | AgentBase,
+ ) -> None:
+ """Delete agents from participant."""
+ if isinstance(participant, AgentBase):
+ participant = [participant]
+
+ for agent in participant:
+ if agent in self.participants:
+ # Clear the subscriber of the deleted agent firstly
+ agent.reset_subscribers([])
+
+ # remove agent from self.participant
+ self.participants.pop(self.participants.index(agent))
+ else:
+ logger.warning(
+ "Cannot find the agent with ID %s, skip its deletion.",
+ agent.id,
+ )
+
+ # Remove this agent from the subscriber of other agents
+ self._reset_subscriber()
+
+ async def broadcast(self, msg: list[Msg] | Msg) -> None:
+ """Broadcast the message to all participants.
+
+ Args:
+ msg (`list[Msg] | Msg`):
+ Message(s) to be broadcast among all participants.
+ """
+ for agent in self.participants:
+ await agent.observe(msg)
diff --git a/src/agentscope/session/__init__.py b/src/agentscope/session/__init__.py
new file mode 100644
index 000000000..3937b9e9f
--- /dev/null
+++ b/src/agentscope/session/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""The session module in agentscope."""
+
+from ._session_base import SessionBase
+from ._json_session import JSONSession
+
+__all__ = [
+ "SessionBase",
+ "JSONSession",
+]
diff --git a/src/agentscope/session/_json_session.py b/src/agentscope/session/_json_session.py
new file mode 100644
index 000000000..caba6a06f
--- /dev/null
+++ b/src/agentscope/session/_json_session.py
@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""The JSON session class."""
+import json
+import os
+
+from ._session_base import SessionBase
+from ..module import StateModule
+
+
+class JSONSession(SessionBase):
+ """The JSON session class."""
+
+ def __init__(self, session_id: str, save_dir: str) -> None:
+ """Initialize the JSON session class.
+
+ Args:
+ session_id (`str`):
+ The session id.
+ save_dir (`str`):
+ The directory to save the session state.
+ """
+ super().__init__(session_id=session_id)
+ self.save_dir = save_dir
+
+ @property
+ def save_path(self) -> str:
+ """The path to save the session state."""
+ os.makedirs(self.save_dir, exist_ok=True)
+ return os.path.join(self.save_dir, f"{self.session_id}.json")
+
+ async def save_session_state(
+ self,
+ **state_modules_mapping: StateModule,
+ ) -> None:
+ """Load the state dictionary from a JSON file.
+
+ Args:
+ **state_modules_mapping (`dict[str, StateModule]`):
+ A dictionary mapping of state module names to their instances.
+ """
+ state_dicts = {
+ name: state_module.state_dict()
+ for name, state_module in state_modules_mapping.items()
+ }
+ with open(self.save_path, "w", encoding="utf-8") as file:
+ json.dump(state_dicts, file, ensure_ascii=False)
+
+ async def load_session_state(
+ self,
+ **state_modules_mapping: StateModule,
+ ) -> None:
+ """Get the state dictionary to be saved to a JSON file.
+
+ Args:
+ state_modules_mapping (`list[StateModule]`):
+ The list of state modules to be loaded.
+ """
+ if os.path.exists(self.save_path):
+ with open(self.save_path, "r", encoding="utf-8") as file:
+ states = json.load(file)
+
+ for name, state_module in state_modules_mapping.items():
+ if name in states:
+ state_module.load_state_dict(states[name])
+ else:
+ raise ValueError(
+ f"Failed to load session state for file {self.save_path} "
+ "does not exist.",
+ )
diff --git a/src/agentscope/session/_session_base.py b/src/agentscope/session/_session_base.py
new file mode 100644
index 000000000..09193ef46
--- /dev/null
+++ b/src/agentscope/session/_session_base.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The session base class in agentscope."""
+from abc import abstractmethod
+from typing import Any
+
+from ..module import StateModule
+
+
+class SessionBase:
+ """The base class for session in agentscope."""
+
+ session_id: str
+ """The session id"""
+
+ def __init__(self, session_id: str) -> None:
+ """Initialize the session base class"""
+
+ self.session_id = session_id
+
+ @abstractmethod
+ async def save_session_state(
+ self,
+ **state_modules_mapping: StateModule,
+ ) -> None:
+ """Save the session state"""
+
+ @abstractmethod
+ async def load_session_state(self, *args: Any, **kwargs: Any) -> None:
+ """Load the session state"""
diff --git a/src/agentscope/token/__init__.py b/src/agentscope/token/__init__.py
new file mode 100644
index 000000000..6c0397fd6
--- /dev/null
+++ b/src/agentscope/token/__init__.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The token module in agentscope"""
+
+from ._token_base import TokenCounterBase
+from ._gemini_token_counter import GeminiTokenCounter
+from ._openai_token_counter import OpenAITokenCounter
+from ._anthropic_token_counter import AnthropicTokenCounter
+from ._huggingface_token_counter import HuggingFaceTokenCounter
+
+__all__ = [
+ "TokenCounterBase",
+ "GeminiTokenCounter",
+ "OpenAITokenCounter",
+ "AnthropicTokenCounter",
+ "HuggingFaceTokenCounter",
+]
diff --git a/src/agentscope/token/_anthropic_token_counter.py b/src/agentscope/token/_anthropic_token_counter.py
new file mode 100644
index 000000000..584b667af
--- /dev/null
+++ b/src/agentscope/token/_anthropic_token_counter.py
@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic token counter class."""
+from typing import Any
+
+
+class AnthropicTokenCounter:
+ """The Anthropic token counter class."""
+
+ def __init__(self, model_name: str, api_key: str, **kwargs: Any) -> None:
+ """Initialize the Anthropic token counter.
+
+ Args:
+ model_name (`str`):
+ The name of the Anthropic model to use, e.g. "claude-2".
+ api_key (`str`):
+ The API key for Anthropic.
+ """
+ import anthropic
+
+ self.client = anthropic.AsyncAnthropic(api_key=api_key, **kwargs)
+ self.model_name = model_name
+
+ async def count(
+ self,
+ messages: list[dict],
+ tools: list[dict] | None = None,
+ **kwargs: Any,
+ ) -> int:
+ """Count the number of tokens for the given messages
+
+ .. note:: The Anthropic token counting API requires the multimodal
+ data to be in base64 format,
+
+ Args:
+ messages (`list[dict]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required.
+ tools (`list[dict] | None`, defaults to `None`):
+ The tools JSON schemas that the model can use.
+ **kwargs (`Any`):
+ Additional keyword arguments for the token counting API.
+ """
+ system_message = None
+ if messages[0].get("role") == "system":
+ system_message = messages.pop(0)
+
+ extra_kwargs: dict = {
+ "model": self.model_name,
+ "messages": messages,
+ **kwargs,
+ }
+
+ if tools:
+ extra_kwargs["tools"] = tools
+
+ if system_message:
+ extra_kwargs["system"] = system_message
+
+ res = await self.client.messages.count_tokens(**extra_kwargs)
+
+ return res.input_tokens
diff --git a/src/agentscope/token/_gemini_token_counter.py b/src/agentscope/token/_gemini_token_counter.py
new file mode 100644
index 000000000..807cab197
--- /dev/null
+++ b/src/agentscope/token/_gemini_token_counter.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""The gemini token counter class in agentscope."""
+from typing import Any
+
+from agentscope.token._token_base import TokenCounterBase
+
+
+class GeminiTokenCounter(TokenCounterBase):
+ """The Gemini token counter class."""
+
+ def __init__(self, model_name: str, api_key: str, **kwargs: Any) -> None:
+ """Initialize the Gemini token counter.
+
+ Args:
+ model_name (`str`):
+ The name of the Gemini model to use, e.g. "gemini-2.5-flash".
+ api_key (`str`):
+ The API key for Google Gemini.
+ **kwargs:
+ Additional keyword arguments that will be passed to the
+ Gemini client.
+ """
+ from google import genai
+
+ self.client = genai.Client(
+ api_key=api_key,
+ **kwargs,
+ )
+ self.model_name = model_name
+
+ async def count(
+ self,
+ messages: list[dict],
+ tools: list[dict] | None = None,
+ **config_kwargs: Any,
+ ) -> int:
+ """Count the number of tokens of gemini models."""
+
+ kwargs = {
+ "model": self.model_name,
+ "contents": messages,
+ "config": {
+ "tools": tools,
+ **config_kwargs,
+ },
+ }
+
+ res = self.client.models.count_tokens(**kwargs)
+
+ return res.total_tokens
diff --git a/src/agentscope/token/_huggingface_token_counter.py b/src/agentscope/token/_huggingface_token_counter.py
new file mode 100644
index 000000000..74350400a
--- /dev/null
+++ b/src/agentscope/token/_huggingface_token_counter.py
@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""The huggingface token counter class."""
+import os
+from typing import Any
+
+from agentscope.token._token_base import TokenCounterBase
+
+
+class HuggingFaceTokenCounter(TokenCounterBase):
+ """The token counter for Huggingface models."""
+
+ def __init__(
+ self,
+ pretrained_model_name_or_path: str,
+ use_mirror: bool = False,
+ use_fast: bool = False,
+ trust_remote_code: bool = False,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the huggingface token counter.
+
+ Args:
+ pretrained_model_name_or_path (`str`):
+ The name or path of the pretrained model, which will be used
+ to download the tokenizer from Huggingface Hub.
+ use_mirror (`bool`, defaults to `False`):
+ Whether to enable the HuggingFace mirror, which is useful for
+ users in China.
+ use_fast (`bool`, defaults to `False`):
+ The argument that will be passed to the tokenizer.
+ trust_remote_code (`bool`, defaults to `False`):
+ The argument that will be passed to the tokenizer.
+ **kwargs:
+ Additional keyword arguments that will be passed to the
+ tokenizer.
+ """
+ if use_mirror:
+ os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
+
+ from transformers import AutoTokenizer
+
+ self.tokenizer = AutoTokenizer.from_pretrained(
+ pretrained_model_name_or_path,
+ use_fast=use_fast,
+ trust_remote_code=trust_remote_code,
+ **kwargs,
+ )
+
+ if self.tokenizer.chat_template is None:
+ raise ValueError(
+ f"The tokenizer for model {pretrained_model_name_or_path} in "
+ f"transformers does not have chat template.",
+ )
+
+ async def count(
+ self,
+ messages: list[dict],
+ tools: list[dict] | None = None,
+ **kwargs: Any,
+ ) -> int:
+ """Count the number of tokens with the tokenizer download from
+ HuggingFace hub.
+
+ Args:
+ messages (`list[dict]`):
+ A list of message dictionaries
+ tools (`list[dict] | None`, defaults to `None`):
+ The JSON schema of the tools, which will also be involved in
+ the token counting.
+ **kwargs (`Any`):
+ The additional keyword arguments that will be passed to the
+ tokenizer, e.g. `chat_template`, `padding`, etc.
+ """
+ tokenized_msgs = self.tokenizer.apply_chat_template(
+ messages,
+ add_generation_prompt=False,
+ tokenize=True,
+ return_tensors="np",
+ tools=tools,
+ **kwargs,
+ )[0]
+
+ return len(tokenized_msgs)
diff --git a/src/agentscope/token/_openai_token_counter.py b/src/agentscope/token/_openai_token_counter.py
new file mode 100644
index 000000000..8fcf4e6f7
--- /dev/null
+++ b/src/agentscope/token/_openai_token_counter.py
@@ -0,0 +1,384 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI token counting class. The token calculation of vision models
+follows
+https://platform.openai.com/docs/guides/images-vision?api-mode=chat#calculating-costs
+"""
+import base64
+import io
+import json
+import math
+from http import HTTPStatus
+from typing import Any
+
+import requests
+
+from ._token_base import TokenCounterBase
+
+
+def _calculate_tokens_for_high_quality_image(
+ base_tokens: int,
+ tile_tokens: int,
+ width: int,
+ height: int,
+) -> int:
+ """Calculate the number of tokens for a high-quality image, which follows
+ https://platform.openai.com/docs/guides/images-vision?api-mode=chat#calculating-costs
+ """
+ # Step1: scale to fit within a 2048x2048 box
+ if width > 2048 or height > 2048:
+ ratio = min(2048 / width, 2048 / height)
+ width = int(width * ratio)
+ height = int(height * ratio)
+
+ # Step2: Scale to make the shortest side 768 pixels
+ shortest_side = min(width, height)
+ if shortest_side != 768:
+ ratio = 768 / shortest_side
+ width = int(width * ratio)
+ height = int(height * ratio)
+
+ # Step3: Calculate how many 512px tiles are needed
+ tiles_width = (width + 511) // 512
+ tiles_height = (height + 511) // 512
+ total_tiles = tiles_width * tiles_height
+
+ # Step4: Calculate the total tokens
+ total_tokens = (total_tiles * tile_tokens) + base_tokens
+
+ return total_tokens
+
+
+def _get_size_of_image_url(url: str) -> tuple[int, int]:
+ """Get the size of an image from the given URL.
+
+ Args:
+ url (`str`):
+ A web URL or base64 encoded image URL.
+
+ Returns:
+ `tuple[int, int]`:
+ A tuple containing the width and height of the image.
+ """
+ if url.startswith("data:image/"):
+ base64_data = url.split("base64,")[1]
+ image_data = base64.b64decode(base64_data)
+
+ else:
+ response = None
+ for _ in range(3):
+ response = requests.get(url)
+ if response.status_code == HTTPStatus.OK:
+ break
+ response.raise_for_status()
+ image_data = response.content
+
+ from PIL import Image
+
+ image = Image.open(io.BytesIO(image_data))
+ width, height = image.size
+ return width, height
+
+
+def _get_base_and_tile_tokens(model_name: str) -> tuple[int, int]:
+ """Get the base and tile tokens for the given OpenAI model.
+
+ Args:
+ model_name (`str`):
+ The name of the model.
+
+ Returns:
+ `tuple[int, int]`:
+ A tuple containing the base tokens and tile tokens.
+ """
+ if any(
+ model_name.startswith(_)
+ for _ in [
+ "gpt-4o",
+ "gpt-4.1",
+ "gpt-4.5",
+ ]
+ ):
+ return 85, 170
+
+ if any(
+ model_name.startswith(_)
+ for _ in [
+ "o1",
+ "o1-pro",
+ "o3",
+ ]
+ ):
+ return 75, 150
+
+ if model_name.startswith("4o-mini"):
+ return 2833, 5667
+
+ raise ValueError(
+ f"Unsupported OpenAI model {model_name} for token counting. ",
+ )
+
+
+def _calculate_tokens_for_tools(
+ model_name: str,
+ tools: list[dict],
+ encoding: Any,
+) -> int:
+ """Calculate the tokens for the given tools JSON schema, which follows the
+ OpenAI cookbook
+ https://github.com/openai/openai-cookbook/blob/6dfb7920b59a45291f7df4ea41338d1faf9ef1e8/examples/How_to_count_tokens_with_tiktoken.ipynb
+ """
+ if not tools:
+ return 0
+
+ func_init = 10
+ prop_init = 3
+ prop_key = 3
+ enum_init = -3
+ enum_item = 3
+ func_end = 12
+
+ if model_name.startswith("gpt-4o"):
+ func_init = 7
+
+ func_token_count = 0
+ for f in tools:
+ func_token_count += func_init
+ function = f["function"]
+ f_name = function["name"]
+ f_desc = function.get("description", "").removesuffix(".")
+ func_token_count += len(encoding.encode(f"{f_name}:{f_desc}"))
+
+ properties = function["parameters"]["properties"]
+
+ if len(properties) > 0:
+ func_token_count += prop_init
+ for key in properties.keys():
+ func_token_count += prop_key
+ p_name = key
+ p_type = properties[key]["type"]
+ p_desc = (
+ properties[key].get("description", "").removesuffix(".")
+ )
+
+ if "enum" in properties[key].keys():
+ func_token_count += enum_init
+ for item in properties[key]["enum"]:
+ func_token_count += enum_item
+ func_token_count += len(encoding.encode(item))
+
+ func_token_count += len(
+ encoding.encode(f"{p_name}:{p_type}:{p_desc}"),
+ )
+ func_token_count += func_end
+
+ return func_token_count
+
+
+def _count_content_tokens_for_openai_vision_model(
+ model_name: str,
+ content: list[dict],
+ encoding: Any,
+) -> int:
+ """Yield the number of tokens for the content of an OpenAI vision model.
+ Implemented according to https://platform.openai.com/docs/guides/vision.
+
+ Args:
+ model_name (`str`):
+ The name of the model.
+ content (`list[dict]`):
+ A list of dictionaries.
+ encoding (`Any`):
+ The encoding object.
+
+ Example:
+ .. code-block:: python
+
+ _yield_tokens_for_openai_vision_model(
+ [
+ {
+ "type": "text",
+ "text": "xxx",
+ },
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": "xxx",
+ "detail": "auto",
+ }
+ },
+ # ...
+ ]
+ )
+
+ Returns:
+ `Generator[int, None, None]`: Generate the number of tokens in a
+ generator.
+ """
+
+ num_tokens = 0
+ for item in content:
+ assert isinstance(item, dict), (
+ "The content field should be a list of dictionaries, but got "
+ f"{type(item)}."
+ )
+
+ typ = item.get("type", None)
+ if typ == "text":
+ num_tokens += len(
+ encoding.encode(item["text"]),
+ )
+
+ elif typ == "image_url":
+ width, height = _get_size_of_image_url(item["image_url"]["url"])
+
+ # Different counting logic for different models
+ if any(
+ model_name.startswith(_)
+ for _ in [
+ "gpt-4.1-mini",
+ "gpt-4.1-nano",
+ "o4-mini",
+ ]
+ ):
+ patches = min(
+ math.ceil(width / 32) * math.ceil(height / 32),
+ 1536,
+ )
+ if model_name.startswith("gpt-4.1-mini"):
+ num_tokens += math.ceil(patches * 1.62)
+
+ elif model_name.startswith("gpt-4.1-nano"):
+ num_tokens += math.ceil(patches * 2.46)
+
+ else:
+ num_tokens += math.ceil(patches * 1.72)
+
+ elif any(
+ model_name.startswith(_)
+ for _ in [
+ "gpt-4o",
+ "gpt-4.1",
+ "gpt-4o-mini",
+ "o",
+ ]
+ ):
+ base_tokens, tile_tokens = _get_base_and_tile_tokens(
+ model_name,
+ )
+
+ # By default, we use high here to avoid undercounting tokens
+ detail = item.get("image_url").get("detail", "high")
+ if detail == "low":
+ num_tokens += base_tokens
+
+ elif detail in ["auto", "high"]:
+ num_tokens += _calculate_tokens_for_high_quality_image(
+ base_tokens,
+ tile_tokens,
+ width,
+ height,
+ )
+
+ else:
+ raise ValueError(
+ f"Unsupported image detail {detail}, expected "
+ f"one of ['low', 'auto', 'high'].",
+ )
+
+ else:
+ raise ValueError(
+ "The type field currently only supports 'text' "
+ f"and 'image_url', but got {typ}.",
+ )
+
+ return num_tokens
+
+
+class OpenAITokenCounter(TokenCounterBase):
+ """The OpenAI token counting class."""
+
+ def __init__(self, model_name: str) -> None:
+ """Initialize the OpenAI token counter.
+
+ Args:
+ model_name (`str`):
+ The name of the OpenAI model to use for token counting.
+ """
+ self.model_name = model_name
+
+ async def count(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict] = None,
+ **kwargs: Any,
+ ) -> int:
+ """Count the token numbers of the given messages.
+
+ .. note:: OpenAI hasn't provided an official guide for counting tokens
+ with tools. If you have any ideas, please open an issue on
+ our GitHub repository.
+
+ Args:
+ messages (`list[dict[str, Any]]`):
+ A list of dictionaries, where `role` and `content` fields are
+ required.
+ tools (`list[dict]`, defaults to `None`):
+ """
+ import tiktoken
+
+ try:
+ encoding = tiktoken.encoding_for_model(self.model_name)
+ except KeyError:
+ encoding = tiktoken.get_encoding("o200k_base")
+
+ tokens_per_message = 3
+ tokens_per_name = 1
+
+ # every reply is primed with <|start|>assistant<|message|>
+ num_tokens = 3
+ for message in messages:
+ num_tokens += tokens_per_message
+ for key, value in message.items():
+ # Considering vision models
+ if key == "content" and isinstance(value, list):
+ num_tokens += (
+ _count_content_tokens_for_openai_vision_model(
+ self.model_name,
+ value,
+ encoding,
+ )
+ )
+
+ elif isinstance(value, str):
+ num_tokens += len(encoding.encode(value))
+
+ elif value is None:
+ continue
+
+ elif key == "tool_calls":
+ # TODO: This is only a temporary solution, since OpenAI
+ # hasn't provided an official guide for counting tokens
+ # with tool results.
+ num_tokens += len(
+ encoding.encode(
+ json.dumps(value, ensure_ascii=False),
+ ),
+ )
+
+ else:
+ raise TypeError(
+ f"Invalid type {type(value)} in the {key} field: "
+ f"{value}",
+ )
+
+ if key == "name":
+ num_tokens += tokens_per_name
+
+ if tools:
+ num_tokens += _calculate_tokens_for_tools(
+ self.model_name,
+ tools,
+ encoding,
+ )
+
+ return num_tokens
diff --git a/src/agentscope/token/_token_base.py b/src/agentscope/token/_token_base.py
new file mode 100644
index 000000000..1718c2892
--- /dev/null
+++ b/src/agentscope/token/_token_base.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""The token base class in agentscope."""
+from abc import abstractmethod
+from typing import Any
+
+
+class TokenCounterBase:
+ """The base class for token counting."""
+
+ @abstractmethod
+ async def count(
+ self,
+ messages: list[dict],
+ **kwargs: Any,
+ ) -> int:
+ """Count the number of tokens by the given model and messages."""
diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.py
new file mode 100644
index 000000000..a77ff2747
--- /dev/null
+++ b/src/agentscope/tool/__init__.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""The tool module in agentscope."""
+
+from ._response import ToolResponse
+from ._coding import (
+ execute_python_code,
+ execute_shell_command,
+)
+from ._text_file import (
+ view_text_file,
+ write_text_file,
+ insert_text_file,
+)
+from ._multi_modality import (
+ dashscope_text_to_image,
+ dashscope_text_to_audio,
+ dashscope_image_to_text,
+ openai_text_to_image,
+ openai_text_to_audio,
+ openai_edit_image,
+ openai_create_image_variation,
+ openai_image_to_text,
+ openai_audio_to_text,
+)
+from ._toolkit import Toolkit
+
+__all__ = [
+ "Toolkit",
+ "ToolResponse",
+ "execute_python_code",
+ "execute_shell_command",
+ "view_text_file",
+ "write_text_file",
+ "insert_text_file",
+ "dashscope_text_to_image",
+ "dashscope_text_to_audio",
+ "dashscope_image_to_text",
+ "openai_text_to_image",
+ "openai_text_to_audio",
+ "openai_edit_image",
+ "openai_create_image_variation",
+ "openai_image_to_text",
+ "openai_audio_to_text",
+]
diff --git a/src/agentscope/tool/_async_wrapper.py b/src/agentscope/tool/_async_wrapper.py
new file mode 100644
index 000000000..1f127bf80
--- /dev/null
+++ b/src/agentscope/tool/_async_wrapper.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""The functions that wrap object, sync generator, and async generator
+into async generators.
+
+TODO: handle the exception raised when yielding from async generator
+ into a normal ToolResponse instance.
+"""
+import asyncio
+from typing import AsyncGenerator, Generator, Callable
+
+from ._response import ToolResponse
+from ..message import TextBlock
+
+
+async def _postprocess_tool_response(
+ tool_response: ToolResponse,
+ postprocess_func: Callable[[ToolResponse], ToolResponse | None] | None,
+) -> ToolResponse:
+ """Post-process a ToolResponse object with the given function."""
+ if postprocess_func:
+ processed_response = postprocess_func(tool_response)
+ if processed_response:
+ return processed_response
+ return tool_response
+
+
+async def _object_wrapper(
+ obj: ToolResponse,
+ postprocess_func: Callable[[ToolResponse], ToolResponse | None] | None,
+) -> AsyncGenerator[ToolResponse, None]:
+ """Wrap a ToolResponse object to an async generator."""
+ yield await _postprocess_tool_response(obj, postprocess_func)
+
+
+async def _sync_generator_wrapper(
+ sync_generator: Generator[ToolResponse, None, None],
+ postprocess_func: Callable[[ToolResponse], ToolResponse | None] | None,
+) -> AsyncGenerator[ToolResponse, None]:
+ """Wrap a sync generator to an async generator."""
+ for chunk in sync_generator:
+ yield await _postprocess_tool_response(chunk, postprocess_func)
+
+
+async def _async_generator_wrapper(
+ async_func: AsyncGenerator[ToolResponse, None],
+ postprocess_func: Callable[[ToolResponse], ToolResponse | None] | None,
+) -> AsyncGenerator[ToolResponse, None]:
+ """When the function is interrupted during generating the tool
+ response, add an interrupted message to the response, and postpone
+ the CancelledError to the caller."""
+
+ last_chunk = None
+ try:
+ async for chunk in async_func:
+ processed_chunk = await _postprocess_tool_response(
+ chunk,
+ postprocess_func,
+ )
+ yield processed_chunk
+ last_chunk = processed_chunk
+
+ except asyncio.CancelledError:
+ interrupted_info = TextBlock(
+ type="text",
+ text="<system-info>"
+ "The tool call has been interrupted by the user."
+ "</system-info>",
+ )
+ if last_chunk:
+ last_chunk.content.append(interrupted_info)
+ last_chunk.is_interrupted = True
+ last_chunk.is_last = True
+ yield await _postprocess_tool_response(
+ last_chunk,
+ postprocess_func,
+ )
+
+ else:
+ yield await _postprocess_tool_response(
+ ToolResponse(
+ content=[interrupted_info],
+ is_interrupted=True,
+ is_last=True,
+ ),
+ postprocess_func,
+ )
diff --git a/src/agentscope/tool/_coding/__init__.py b/src/agentscope/tool/_coding/__init__.py
new file mode 100644
index 000000000..acad79d70
--- /dev/null
+++ b/src/agentscope/tool/_coding/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""The coding-related tools module in agentscope."""
+
+from ._python import execute_python_code
+from ._shell import execute_shell_command
+
+__all__ = [
+ "execute_python_code",
+ "execute_shell_command",
+]
diff --git a/src/agentscope/tool/_coding/_python.py b/src/agentscope/tool/_coding/_python.py
new file mode 100644
index 000000000..0a6d5581e
--- /dev/null
+++ b/src/agentscope/tool/_coding/_python.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""The Python code execution tool in agentscope."""
+
+import asyncio
+import os
+import sys
+import tempfile
+from typing import Any
+
+import shortuuid
+
+from ...message import TextBlock
+from .._response import ToolResponse
+
+
+async def execute_python_code(
+ code: str,
+ timeout: float = 300,
+ **kwargs: Any,
+) -> ToolResponse:
+ """Execute the given python code in a temp file and capture the return
+ code, standard output and error. Note you must `print` the output to get
+ the result, and the tmp file will be removed right after the execution.
+
+ Args:
+ code (`str`):
+ The Python code to be executed.
+ timeout (`float`, defaults to `300`):
+ The maximum time (in seconds) allowed for the code to run.
+
+ Returns:
+ `ToolResponse`:
+ The response containing the return code, standard output, and
+ standard error of the executed code.
+ """
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ temp_file = os.path.join(temp_dir, f"tmp_{shortuuid.uuid()}.py")
+ with open(temp_file, "w", encoding="utf-8") as f:
+ f.write(code)
+
+ proc = await asyncio.create_subprocess_exec(
+ sys.executable,
+ "-u",
+ temp_file,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+
+ try:
+ await asyncio.wait_for(proc.wait(), timeout=timeout)
+ stdout, stderr = await proc.communicate()
+ stdout_str = stdout.decode("utf-8")
+ stderr_str = stderr.decode("utf-8")
+ returncode = proc.returncode
+
+ except asyncio.TimeoutError:
+ stderr_suffix = (
+ f"TimeoutError: The code execution exceeded "
+ f"the timeout of {timeout} seconds."
+ )
+ returncode = -1
+ try:
+ proc.terminate()
+ stdout, stderr = await proc.communicate()
+ stdout_str = stdout.decode("utf-8")
+ stderr_str = stderr.decode("utf-8")
+ if stderr_str:
+ stderr_str += f"\n{stderr_suffix}"
+ else:
+ stderr_str = stderr_suffix
+ except ProcessLookupError:
+ stdout_str = ""
+ stderr_str = stderr_suffix
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"<returncode>{returncode}</returncode>"
+ f"<stdout>{stdout_str}</stdout>"
+ f"<stderr>{stderr_str}</stderr>",
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_coding/_shell.py b/src/agentscope/tool/_coding/_shell.py
new file mode 100644
index 000000000..653eeca14
--- /dev/null
+++ b/src/agentscope/tool/_coding/_shell.py
@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+"""The shell command tool in agentscope."""
+
+import asyncio
+from typing import Any
+
+from .._response import ToolResponse
+from ...message import TextBlock
+
+
+async def execute_shell_command(
+ command: str,
+ timeout: int = 300,
+ **kwargs: Any,
+) -> ToolResponse:
+ """Execute given command and return the return code, standard output and
+ error within <returncode></returncode>, <stdout></stdout> and
+ <stderr></stderr> tags.
+
+ Args:
+ command (`str`):
+ The shell command to execute.
+ timeout (`float`, defaults to `300`):
+ The maximum time (in seconds) allowed for the command to run.
+
+ Returns:
+ `ToolResponse`:
+ The tool response containing the return code, standard output, and
+ standard error of the executed command.
+ """
+
+ proc = await asyncio.create_subprocess_shell(
+ command,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ bufsize=0,
+ )
+
+ try:
+ await asyncio.wait_for(proc.wait(), timeout=timeout)
+ stdout, stderr = await proc.communicate()
+ stdout_str = stdout.decode("utf-8")
+ stderr_str = stderr.decode("utf-8")
+ returncode = proc.returncode
+
+ except asyncio.TimeoutError:
+ stderr_suffix = (
+ f"TimeoutError: The command execution exceeded "
+ f"the timeout of {timeout} seconds."
+ )
+ returncode = -1
+ try:
+ proc.terminate()
+ stdout, stderr = await proc.communicate()
+ stdout_str = stdout.decode("utf-8")
+ stderr_str = stderr.decode("utf-8")
+ if stderr_str:
+ stderr_str += f"\n{stderr_suffix}"
+ else:
+ stderr_str = stderr_suffix
+ except ProcessLookupError:
+ stdout_str = ""
+ stderr_str = stderr_suffix
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=(
+ f"<returncode>{returncode}</returncode>"
+ f"<stdout>{stdout_str}</stdout>"
+ f"<stderr>{stderr_str}</stderr>"
+ ),
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_multi_modality/__init__.py b/src/agentscope/tool/_multi_modality/__init__.py
new file mode 100644
index 000000000..766c169b9
--- /dev/null
+++ b/src/agentscope/tool/_multi_modality/__init__.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""The multi-modal-related tools module in agentscope."""
+from ._dashscope_tools import (
+ dashscope_image_to_text,
+ dashscope_text_to_audio,
+ dashscope_text_to_image,
+)
+from ._openai_tools import (
+ openai_text_to_image,
+ openai_edit_image,
+ openai_text_to_audio,
+ openai_create_image_variation,
+ openai_image_to_text,
+ openai_audio_to_text,
+)
+
+__all__ = [
+ "dashscope_image_to_text",
+ "dashscope_text_to_audio",
+ "dashscope_text_to_image",
+ "openai_text_to_image",
+ "openai_text_to_audio",
+ "openai_edit_image",
+ "openai_create_image_variation",
+ "openai_image_to_text",
+ "openai_audio_to_text",
+]
diff --git a/src/agentscope/tool/_multi_modality/_dashscope_tools.py b/src/agentscope/tool/_multi_modality/_dashscope_tools.py
new file mode 100644
index 000000000..8fba22436
--- /dev/null
+++ b/src/agentscope/tool/_multi_modality/_dashscope_tools.py
@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+"""Use DashScope API to generate images,
+convert text to audio, and convert images to text.
+Please refer to the `official documentation <https://dashscope.aliyun.com/>`_
+ for more details.
+"""
+import base64
+from typing import Literal, Sequence
+
+import os
+
+
+from ..._utils._common import _get_bytes_from_web_url
+from ...message import ImageBlock, TextBlock, AudioBlock
+from ...tool import ToolResponse
+
+
+def dashscope_text_to_image(
+ prompt: str,
+ api_key: str,
+ n: int = 1,
+ size: Literal["1024*1024", "720*1280", "1280*720"] = "1024*1024",
+ model: str = "wanx-v1",
+ use_base64: bool = False,
+) -> ToolResponse:
+ """Generate image(s) based on the given prompt, and return image url(s)
+ or base64 data.
+
+ Args:
+ prompt (`str`):
+ The text prompt to generate image.
+ api_key (`str`):
+ The api key for the dashscope api.
+ n (`int`, defaults to `1`):
+ The number of images to generate.
+ size (`Literal["1024*1024", "720*1280", "1280*720"]`, defaults to \
+ `"1024*1024"`):
+ Size of the image.
+ model (`str`, defaults to '"wanx-v1"'):
+ The model to use, such as "wanx-v1", "qwen-image",
+ "wan2.2-t2i-flash", etc.
+ use_base64 (`bool`, defaults to 'False'):
+ Whether to use base64 data for images.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+ try:
+ import dashscope
+
+ response = dashscope.ImageSynthesis.call(
+ model=model,
+ prompt=prompt,
+ api_key=api_key,
+ n=n,
+ size=size,
+ )
+ images = response.output["results"]
+ urls = [_["url"] for _ in images]
+
+ image_blocks: list = []
+
+ if urls is not None:
+ for url in urls:
+ if use_base64:
+ extension = url.split(".")[-1].lower()
+
+ image_data = _get_bytes_from_web_url(url)
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": f"image/{extension}",
+ "data": image_data,
+ },
+ ),
+ )
+ else:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": url,
+ },
+ ),
+ )
+
+ return ToolResponse(
+ content=image_blocks,
+ )
+
+ else:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate images",
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate images: {str(e)}",
+ ),
+ ],
+ )
+
+
+def dashscope_image_to_text(
+ image_urls: str | Sequence[str],
+ api_key: str,
+ prompt: str = "Describe the image",
+ model: str = "qwen-vl-plus",
+) -> ToolResponse:
+ """Generate text based on the given images.
+
+ Args:
+ image_urls (`str | Sequence[str]`):
+ The url of single or multiple images.
+ api_key (`str`):
+ The api key for the dashscope api.
+ prompt (`str`, defaults to 'Describe the image' ):
+ The text prompt.
+ model (`str`, defaults to 'qwen-vl-plus'):
+ The model to use in DashScope MultiModal API.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+
+ if isinstance(image_urls, str):
+ image_urls = [image_urls]
+
+ # Check if the local url is valid
+ img_abs_urls = []
+ for url in image_urls:
+ if os.path.exists(url):
+ if os.path.isfile(url):
+ img_abs_urls.append(os.path.abspath(url))
+ else:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f'Error: The input image url "{url}" is '
+ f"not a file.",
+ ),
+ ],
+ )
+ else:
+ # Maybe a web url or an invalid url, we leave it to the API
+ # to handle
+ img_abs_urls.append(url)
+
+ # Convert image paths according to the model requirements
+ contents = []
+ for url in img_abs_urls:
+ contents.append(
+ {
+ "image": url,
+ },
+ )
+
+ contents.append({"text": prompt})
+
+ # currently only support one round of conversation
+ # if multiple rounds of conversation are needed,
+ # it would be better to implement an Agent class
+ sys_message = {
+ "role": "system",
+ "content": [{"text": "You are a helpful assistant."}],
+ }
+ user_message = {
+ "role": "user",
+ "content": contents,
+ }
+ messages = [sys_message, user_message]
+ try:
+ import dashscope
+
+ response = dashscope.MultiModalConversation.call(
+ model=model,
+ messages=messages,
+ api_key=api_key,
+ )
+ content = response.output["choices"][0]["message"]["content"]
+ if isinstance(content, list):
+ content = content[0]["text"]
+ if content is not None:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=content,
+ ),
+ ],
+ )
+ else:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate text",
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate text: {str(e)}",
+ ),
+ ],
+ )
+
+
+def dashscope_text_to_audio(
+ text: str,
+ api_key: str,
+ model: str = "sambert-zhichu-v1",
+ sample_rate: int = 48000,
+) -> ToolResponse:
+ """Convert the given text to audio.
+
+ Args:
+ text (`str`):
+ The text to be converted into audio.
+ api_key (`str`):
+ The api key for the dashscope API.
+ model (`str`, defaults to 'sambert-zhichu-v1'):
+ The model to use. Full model list can be found in
+ https://help.aliyun.com/zh/dashscope/model-list
+ sample_rate (`int`, defaults to 48000):
+ Sample rate of the audio.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+
+ """
+ try:
+ import dashscope
+
+ dashscope.api_key = api_key
+
+ res = dashscope.audio.tts.SpeechSynthesizer.call(
+ model=model,
+ text=text,
+ sample_rate=sample_rate,
+ format="wav",
+ )
+
+ audio_data = res.get_audio_data()
+
+ if audio_data is not None:
+ audio_base64 = base64.b64encode(audio_data).decode("utf-8")
+
+ return ToolResponse(
+ [
+ AudioBlock(
+ type="audio",
+ source={
+ "type": "base64",
+ "media_type": "audio/wav",
+ "data": audio_base64,
+ },
+ ),
+ ],
+ )
+ else:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate audio",
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate audio: {str(e)}",
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_multi_modality/_openai_tools.py b/src/agentscope/tool/_multi_modality/_openai_tools.py
new file mode 100644
index 000000000..0e210e297
--- /dev/null
+++ b/src/agentscope/tool/_multi_modality/_openai_tools.py
@@ -0,0 +1,669 @@
+# -*- coding: utf-8 -*-
+"""
+Wrap OpenAI API calls as tools. Refer the official
+`OpenAI API documentation <https://platform.openai.com/docs/overview>`_ for
+more details.
+"""
+import base64
+from io import BytesIO
+import os
+from typing import Literal, IO
+import requests
+
+from .. import ToolResponse
+from ...formatter._openai_formatter import _to_openai_image_url
+from ...message import (
+ ImageBlock,
+ TextBlock,
+ Base64Source,
+ URLSource,
+ AudioBlock,
+)
+
+
+def _parse_url(url: str) -> BytesIO | IO[bytes]:
+ """
+ If url is a local file path, return a BytesIO of the file content.
+ If url is a web URL, fetch the content and return as BytesIO.
+ """
+ if url.startswith(("http://", "https://")):
+ response = requests.get(url)
+ response.raise_for_status() # Raise an exception for HTTP errors
+ return BytesIO(response.content)
+ else:
+ if not os.path.exists(url):
+ raise FileNotFoundError(f"File not found: {url}")
+ return open(os.path.abspath(url), "rb")
+
+
+def openai_text_to_image(
+ prompt: str,
+ api_key: str,
+ n: int = 1,
+ model: Literal["dall-e-2", "dall-e-3", "gpt-image-1"] = "dall-e-2",
+ size: Literal[
+ "256x256",
+ "512x512",
+ "1024x1024",
+ "1792x1024",
+ "1024x1792",
+ ] = "256x256",
+ quality: Literal[
+ "auto",
+ "standard",
+ "hd",
+ "high",
+ "medium",
+ "low",
+ ] = "auto",
+ style: Literal["vivid", "natural"] = "vivid",
+ response_format: Literal["url", "b64_json"] = "url",
+) -> ToolResponse:
+ """
+ Generate image(s) based on the given prompt, and return image URL(s) or
+ base64 data.
+
+ Args:
+ prompt (`str`):
+ The text prompt to generate images.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ n (`int`, defaults to `1`):
+ The number of images to generate.
+ model (`Literal["dall-e-2", "dall-e-3"]`, defaults to `"dall-e-2"`):
+ The model to use for image generation.
+ size (`Literal["256x256", "512x512", "1024x1024", "1792x1024", \
+ "1024x1792"]`, defaults to `"256x256"`):
+ The size of the generated images.
+ Must be one of 1024x1024, 1536x1024 (landscape), 1024x1536 (
+ portrait), or auto (default value) for gpt-image-1,
+ one of 256x256, 512x512, or 1024x1024 for dall-e-2,
+ and one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3.
+ quality (`Literal["auto", "standard", "hd", "high", "medium", \
+ "low"]`, defaults to `"auto"`):
+ The quality of the image that will be generated.
+
+ - `auto` (default value) will automatically select the best
+ quality for the given model.
+ - `high`, `medium` and `low` are supported for gpt-image-1.
+ - `hd` and `standard` are supported for dall-e-3.
+ - `standard` is the only option for dall-e-2.
+ style (`Literal["vivid", "natural"]`, defaults to `"vivid"`):
+ The style of the generated images.
+ This parameter is only supported for dall-e-3.
+ Must be one of `vivid` or `natural`.
+ - `Vivid` causes the model to lean towards generating hyper-real
+ and dramatic images.
+ - `Natural` causes the model to produce more natural,
+ less hyper-real looking images.
+ response_format (`Literal["url", "b64_json"]`, defaults to `"url"`):
+ The format in which generated images with dall-e-2 and dall-e-3
+ are returned.
+ - Must be one of "url" or "b64_json".
+ - URLs are only valid for 60 minutes after the image has been
+ generated.
+ - This parameter isn't supported for gpt-image-1 which will always
+ return base64-encoded images.
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+
+ kwargs = {
+ "model": model,
+ "prompt": prompt,
+ "n": n,
+ "size": size,
+ }
+ if model == "dall-e-3":
+ kwargs["style"] = style
+ if model != "dall-e-2":
+ kwargs["quality"] = quality
+ if model != "gpt-image-1":
+ kwargs["response_format"] = response_format
+ if model == "gpt-image-1":
+ response_format = "b64_json"
+
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+ response = client.images.generate(
+ **kwargs,
+ )
+ image_blocks: list = []
+ if response_format == "url":
+ image_urls = [_.url for _ in response.data]
+ for image_url in image_urls:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=image_url,
+ ),
+ ),
+ )
+ else:
+ image_datas = [_.b64_json for _ in response.data]
+ for image_data in image_datas:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type="image/png",
+ data=image_data,
+ ),
+ ),
+ )
+ return ToolResponse(
+ content=image_blocks,
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate image: {str(e)}",
+ ),
+ ],
+ )
+
+
+def openai_edit_image(
+ image_url: str,
+ prompt: str,
+ api_key: str,
+ model: Literal["dall-e-2", "gpt-image-1"] = "dall-e-2",
+ mask_url: str | None = None,
+ n: int = 1,
+ size: Literal[
+ "256x256",
+ "512x512",
+ "1024x1024",
+ ] = "256x256",
+ response_format: Literal["url", "b64_json"] = "url",
+) -> ToolResponse:
+ """
+ Edit an image based on the provided mask and prompt, and return the edited
+ image URL(s) or base64 data.
+
+ Args:
+ image_url (`str`):
+ The file path or URL to the image that needs editing.
+ prompt (`str`):
+ The text prompt describing the edits to be made to the image.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ model (`Literal["dall-e-2", "gpt-image-1"]`, defaults to `"dall-e-2"`):
+ The model to use for image generation.
+ mask_url (`str | None`, defaults to `None`):
+ The file path or URL to the mask image that specifies the regions
+ to be edited.
+ n (`int`, defaults to `1`):
+ The number of edited images to generate.
+ size (`Literal["256x256", "512x512", "1024x1024"]`, defaults to \
+ `"256x256"`):
+ The size of the edited images.
+ response_format (`Literal["url", "b64_json"]`, defaults to `"url"`):
+ The format in which generated images are returned.
+ Must be one of "url" or "b64_json".
+ URLs are only valid for 60 minutes after generation.
+ This parameter isn't supported for gpt-image-1 which will
+ always return base64-encoded images.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+
+ """
+
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+
+ def prepare_image(url_or_path: str) -> BytesIO:
+ from PIL import Image
+
+ if url_or_path.startswith(("http://", "https://")):
+ response = requests.get(url_or_path)
+ response.raise_for_status()
+ img = Image.open(BytesIO(response.content))
+ else:
+ img = Image.open(url_or_path)
+
+ if img.mode != "RGBA":
+ img = img.convert("RGBA")
+ img_buffer = BytesIO()
+ img.save(img_buffer, format="PNG")
+ img_buffer.seek(0)
+ img_buffer.name = "image.png"
+ return img_buffer
+
+ image_file = prepare_image(image_url)
+
+ kwargs = {
+ "model": model,
+ "image": image_file,
+ "prompt": prompt,
+ "n": n,
+ "size": size,
+ }
+
+ if mask_url:
+ kwargs["mask"] = prepare_image(mask_url)
+
+ if model == "dall-e-2":
+ kwargs["response_format"] = response_format
+ else:
+ response_format = "b64_json"
+
+ response = client.images.edit(**kwargs)
+
+ if response_format == "url":
+ urls = [_.url for _ in response.data]
+ image_blocks: list = []
+ for url in urls:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=url,
+ ),
+ ),
+ )
+ return ToolResponse(
+ content=image_blocks,
+ )
+ elif response_format == "b64_json":
+ image_datas = [_.b64_json for _ in response.data]
+ image_blocks = []
+ for image_data in image_datas:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type="image/png",
+ data=image_data,
+ ),
+ ),
+ )
+ return ToolResponse(
+ content=image_blocks,
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate image: {str(e)}",
+ ),
+ ],
+ )
+
+
+def openai_create_image_variation(
+ image_url: str,
+ api_key: str,
+ n: int = 1,
+ model: Literal["dall-e-2"] = "dall-e-2",
+ size: Literal[
+ "256x256",
+ "512x512",
+ "1024x1024",
+ ] = "256x256",
+ response_format: Literal["url", "b64_json"] = "url",
+) -> ToolResponse:
+ """
+ Create variations of an image and return the image URL(s) or base64 data.
+
+ Args:
+ image_url (`str`):
+ The file path or URL to the image from which variations will be
+ generated.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ n (`int`, defaults to `1`):
+ The number of image variations to generate.
+ model (` Literal["dall-e-2"]`, default to `dall-e-2`):
+ The model to use for image variation.
+ size (`Literal["256x256", "512x512", "1024x1024"]`, defaults to \
+ `"256x256"`):
+ The size of the generated image variations.
+ response_format (`Literal["url", "b64_json"]`, defaults to `"url"`):
+ The format in which generated images are returned.
+ Must be one of url or b64_json.
+ URLs are only valid for 60 minutes after the image has been
+ generated.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+
+ # _parse_url handles both local and web URLs and returns BytesIO
+ image = _parse_url(image_url)
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+ response = client.images.create_variation(
+ model=model,
+ image=image,
+ n=n,
+ size=size,
+ )
+ image_blocks: list = []
+ if response_format == "url":
+ urls = [_.url for _ in response.data]
+ for url in urls:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=url,
+ ),
+ ),
+ )
+ else:
+ image_datas = [_.b64_json for _ in response.data]
+ for image_data in image_datas:
+ image_blocks.append(
+ ImageBlock(
+ type="image",
+ source=Base64Source(
+ type="base64",
+ media_type="image/png",
+ data=image_data,
+ ),
+ ),
+ )
+ return ToolResponse(
+ content=image_blocks,
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate image: {str(e)}",
+ ),
+ ],
+ )
+
+
+def openai_image_to_text(
+ image_urls: str | list[str],
+ api_key: str,
+ prompt: str = "Describe the image",
+ model: str = "gpt-4o",
+) -> ToolResponse:
+ """
+ Generate descriptive text for given image(s) using a specified model, and
+ return the generated text.
+
+ Args:
+ image_urls (`str | list[str]`):
+ The URL or list of URLs pointing to the images that need to be
+ described.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ prompt (`str`, defaults to `"Describe the image"`):
+ The prompt that instructs the model on how to describe
+ the image(s).
+ model (`str`, defaults to `"gpt-4o"`):
+ The model to use for generating the text descriptions.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+
+ """
+ if isinstance(image_urls, str):
+ image_urls = [image_urls]
+
+ content = []
+ for url in image_urls:
+ content.append(
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": _to_openai_image_url(url),
+ },
+ },
+ )
+ content.append(
+ {
+ "type": "text",
+ "text": prompt,
+ },
+ )
+ messages = [
+ {
+ "role": "user",
+ "content": content,
+ },
+ ]
+
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+ response = client.chat.completions.create(
+ messages=messages,
+ model=model,
+ )
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=response.choices[0].message.content,
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Failed to generate text: {str(e)}",
+ ),
+ ],
+ )
+
+
+def openai_text_to_audio(
+ text: str,
+ api_key: str,
+ model: Literal["tts-1", "tts-1-hd", "gpt-4o-mini-tts"] = "tts-1",
+ voice: Literal[
+ "alloy",
+ "ash",
+ "ballad",
+ "coral",
+ "echo",
+ "fable",
+ "nova",
+ "onyx",
+ "sage",
+ "shimmer",
+ ] = "alloy",
+ speed: float = 1.0,
+ res_format: Literal[
+ "mp3",
+ "opus",
+ "aac",
+ "flac",
+ "wav",
+ "pcm",
+ ] = "mp3",
+) -> ToolResponse:
+ """
+ Convert text to an audio file using a specified model and voice.
+
+ Args:
+ text (`str`):
+ The text to convert to audio.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ model (`Literal["tts-1", "tts-1-hd"]`, defaults to `"tts-1"`):
+ The model to use for text-to-speech conversion.
+ voice (`Literal["alloy", "echo", "fable", "onyx", "nova", \
+ "shimmer"]`, defaults to `"alloy"`):
+ The voice to use for the audio output.
+ speed (`float`, defaults to `1.0`):
+ The speed of the audio playback. A value of 1.0 is normal speed.
+ res_format (`Literal["mp3", "wav", "opus", "aac", "flac", \
+ "wav", "pcm"]`,
+ defaults to `"mp3"`):
+ The format of the audio file.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+ response = client.audio.speech.create(
+ model=model,
+ voice=voice,
+ speed=speed,
+ input=text,
+ response_format=res_format,
+ )
+ audio_bytes = response.content
+ audio_base64 = base64.b64encode(audio_bytes).decode("utf-8")
+
+ return ToolResponse(
+ [
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type=f"audio/{res_format}",
+ data=audio_base64,
+ ),
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Error: Failed to generate audio. {str(e)}",
+ ),
+ ],
+ )
+
+
+def openai_audio_to_text(
+ audio_file_url: str,
+ api_key: str,
+ language: str = "en",
+ temperature: float = 0.2,
+) -> ToolResponse:
+ """
+ Convert an audio file to text using OpenAI's transcription service.
+
+ Args:
+ audio_file_url (`str`):
+ The file path or URL to the audio file that needs to be
+ transcribed.
+ api_key (`str`):
+ The API key for the OpenAI API.
+ language (`str`, defaults to `"en"`):
+ The language of the input audio in
+ `ISO-639-1 format \
+ <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`_
+ (e.g., "en", "zh", "fr"). Improves accuracy and latency.
+ temperature (`float`, defaults to `0.2`):
+ The temperature for the transcription, which affects the
+ randomness of the output.
+
+ Returns:
+ `ToolResponse`:
+ A ToolResponse containing the generated content
+ (ImageBlock/TextBlock/AudioBlock) or error information if the
+ operation failed.
+ """
+
+ try:
+ import openai
+
+ client = openai.OpenAI(
+ api_key=api_key,
+ )
+
+ if audio_file_url.startswith(("http://", "https://")):
+ response = requests.get(audio_file_url)
+ response.raise_for_status()
+ audio_buffer = BytesIO(response.content)
+ import urllib.parse
+ from pathlib import Path
+
+ parsed_url = urllib.parse.urlparse(audio_file_url)
+ filename = Path(parsed_url.path).name or "audio.mp3"
+ audio_buffer.name = filename
+ audio_file = audio_buffer
+ transcription = client.audio.transcriptions.create(
+ model="whisper-1",
+ file=audio_file,
+ language=language,
+ temperature=temperature,
+ )
+ else:
+ if not os.path.exists(audio_file_url):
+ raise FileNotFoundError(f"File not found: {audio_file_url}")
+ with open(audio_file_url, "rb") as audio_file:
+ transcription = client.audio.transcriptions.create(
+ model="whisper-1",
+ file=audio_file,
+ language=language,
+ temperature=temperature,
+ )
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=transcription.text,
+ ),
+ ],
+ )
+ except Exception as e:
+ return ToolResponse(
+ [
+ TextBlock(
+ type="text",
+ text=f"Error: Failed to transcribe audio: {str(e)}",
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_registered_tool_function.py b/src/agentscope/tool/_registered_tool_function.py
new file mode 100644
index 000000000..3f9c1dd63
--- /dev/null
+++ b/src/agentscope/tool/_registered_tool_function.py
@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+"""The data model for registered tool functions in AgentScope."""
+from copy import deepcopy
+from dataclasses import field, dataclass
+from typing import Callable, Literal, Type
+
+from pydantic import BaseModel
+
+from ._response import ToolResponse
+from .._utils._common import _remove_title_field
+from ..message import ToolUseBlock
+from ..types import ToolFunction, JSONSerializableObject
+
+
+@dataclass
+class RegisteredToolFunction:
+ """The registered tool function class."""
+
+ name: str
+ """The name of the tool function."""
+ group: str | Literal["basic"]
+ """The belonging group of the tool function"""
+ source: Literal["function", "mcp_server", "function_group"]
+ """"The type of the tool function, can be `function` or `mcp_server`."""
+ original_func: ToolFunction
+ """The original function"""
+ json_schema: dict
+ """The JSON schema of the tool function, which is used to validate the """
+ preset_kwargs: dict[str, JSONSerializableObject] = field(
+ default_factory=dict,
+ )
+ """The preset keyword arguments, which won't be presented in the JSON
+ schema and exposed to the user."""
+ extended_model: Type[BaseModel] | None = None
+ """The base model used to extend the JSON schema of the original tool
+ function, so that we can dynamically adjust the tool function."""
+ mcp_name: str | None = None
+ """The name of the MCP, if the tool function comes from an MCP server."""
+ postprocess_func: Callable[
+ [ToolUseBlock, ToolResponse],
+ ToolResponse | None,
+ ] | None = None
+ """The post-processing function that will be called after the tool
+ function is executed, taking the tool call block and tool
+ response as arguments. If it returns `None`, the tool result will be
+ returned as is. If it returns a `ToolResponse`, the returned block
+ will be used as the final tool response."""
+
+ @property
+ def extended_json_schema(self) -> dict:
+ """Get the JSON schema of the tool function, if an extended model is
+ set, the merged JSON schema will be returned."""
+ if self.extended_model is None:
+ return self.json_schema
+
+ # Merge the extended model with the original JSON schema
+ extended_schema = self.extended_model.model_json_schema()
+
+ merged_schema = deepcopy(self.json_schema)
+
+ _remove_title_field( # pylint: disable=protected-access
+ extended_schema,
+ )
+
+ for key, value in extended_schema["properties"].items():
+ if key in self.json_schema["function"]["parameters"]["properties"]:
+ raise ValueError(
+ f"The field `{key}` already exists in the original "
+ f"function schema of `{self.name}`. Try to use a "
+ "different name.",
+ )
+
+ merged_schema["function"]["parameters"]["properties"][key] = value
+
+ if key in extended_schema.get("required", []):
+ if "required" not in merged_schema["function"]["parameters"]:
+ merged_schema["function"]["parameters"]["required"] = []
+ merged_schema["function"]["parameters"]["required"].append(key)
+ return merged_schema
diff --git a/src/agentscope/tool/_response.py b/src/agentscope/tool/_response.py
new file mode 100644
index 000000000..c27c799bc
--- /dev/null
+++ b/src/agentscope/tool/_response.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""The tool response class."""
+
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+from .._utils._common import _get_timestamp
+from ..message import AudioBlock, ImageBlock, TextBlock
+
+
+@dataclass
+class ToolResponse:
+ """The result chunk of a tool call."""
+
+ content: List[TextBlock | ImageBlock | AudioBlock]
+ """The execution output of the tool function."""
+
+ metadata: Optional[dict] = None
+ """The metadata to be accessed within the agent, so that we don't need to
+ parse the tool result block."""
+
+ stream: bool = False
+ """Whether the tool output is streamed."""
+
+ is_last: bool = True
+ """Whether this is the last response in a stream tool execution."""
+
+ is_interrupted: bool = False
+ """Whether the tool execution is interrupted."""
+
+ id: str = field(default_factory=lambda: _get_timestamp(True))
+ """The identity of the tool response."""
diff --git a/src/agentscope/tool/_text_file/__init__.py b/src/agentscope/tool/_text_file/__init__.py
new file mode 100644
index 000000000..cd404b503
--- /dev/null
+++ b/src/agentscope/tool/_text_file/__init__.py
@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""The text file tool module in agentscope."""
+from ._view_text_file import view_text_file
+from ._write_text_file import (
+ insert_text_file,
+ write_text_file,
+)
+
+__all__ = [
+ "insert_text_file",
+ "write_text_file",
+ "view_text_file",
+]
diff --git a/src/agentscope/tool/_text_file/_utils.py b/src/agentscope/tool/_text_file/_utils.py
new file mode 100644
index 000000000..4f0877f6e
--- /dev/null
+++ b/src/agentscope/tool/_text_file/_utils.py
@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""The utility functions for text file tools in agentscope."""
+from ...exception import ToolInvalidArgumentsError
+
+
+def _calculate_view_ranges(
+ old_n_lines: int,
+ new_n_lines: int,
+ start: int,
+ end: int,
+ extra_view_n_lines: int = 5,
+) -> tuple[int, int]:
+ """Calculate after writing the new content, the view ranges of the file.
+
+ Args:
+ old_n_lines (`int`):
+ The number of lines before writing the new content.
+ new_n_lines (`int`):
+ The number of lines after writing the new content.
+ start (`int`):
+ The start line of the writing range.
+ end (`int`):
+ The end line of the writing range.
+ extra_view_n_lines (`int`, optional):
+ The number of extra lines to view before and after the range.
+ """
+
+ view_start = max(1, start - extra_view_n_lines)
+
+ delta_lines = new_n_lines - old_n_lines
+ view_end = min(end + delta_lines + extra_view_n_lines, new_n_lines)
+
+ return view_start, view_end
+
+
+def _assert_ranges(
+ ranges: list[int],
+) -> None:
+ """Check if the ranges are valid.
+
+ Raises:
+ ToolInvalidArgumentsError: If the ranges are invalid.
+ """
+ if (
+ isinstance(ranges, list)
+ and len(ranges) == 2
+ and all(isinstance(i, int) for i in ranges)
+ ):
+ start, end = ranges
+ if start > end:
+ raise ToolInvalidArgumentsError(
+ f"InvalidArgumentError: The start line is greater than the "
+ f"end line in the given range {ranges}.",
+ )
+ else:
+ raise ToolInvalidArgumentsError(
+ f"InvalidArgumentError: Invalid range format. Expected a list of "
+ f"two integers, but got {ranges}.",
+ )
+
+
+def _view_text_file(
+ file_path: str,
+ ranges: list[int] | None = None,
+) -> str:
+ """Return the file content in the specified range with line numbers."""
+ with open(file_path, "r", encoding="utf-8") as file:
+ lines = file.readlines()
+
+ if ranges:
+ _assert_ranges(ranges)
+ start, end = ranges
+
+ if start > len(lines):
+ raise ToolInvalidArgumentsError(
+ f"InvalidArgumentError: The range '{ranges}' is out of bounds "
+ f"for the file '{file_path}', which has only {len(lines)} "
+ f"lines.",
+ )
+
+ view_content = [
+ f"{index + start}: {line}"
+ for index, line in enumerate(lines[start - 1 : end])
+ ]
+
+ return "".join(view_content)
+
+ return "".join(f"{index + 1}: {line}" for index, line in enumerate(lines))
diff --git a/src/agentscope/tool/_text_file/_view_text_file.py b/src/agentscope/tool/_text_file/_view_text_file.py
new file mode 100644
index 000000000..7e2131f40
--- /dev/null
+++ b/src/agentscope/tool/_text_file/_view_text_file.py
@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+# flake8: noqa: E501
+# pylint: disable=line-too-long
+"""The view text file tool in agentscope."""
+import os
+
+from ._write_text_file import _view_text_file
+from .._response import ToolResponse
+from ...exception import ToolInvalidArgumentsError
+from ...message import TextBlock
+
+
+async def view_text_file(
+ file_path: str,
+ ranges: list[int] | None = None,
+) -> ToolResponse:
+ """View the file content in the specified range with line numbers. If `ranges` is not provided, the entire file will be returned.
+
+ Args:
+ file_path (`str`):
+ The target file path.
+ ranges:
+ The range of lines to be viewed (e.g. lines 1 to 100: [1, 100]), inclusive. If not provided, the entire file will be returned. To view the last 100 lines, use [-100, -1].
+
+ Returns:
+ `ToolResponse`:
+ The tool response containing the file content or an error message.
+ """
+ if not os.path.exists(file_path):
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error: The file {file_path} does not exist.",
+ ),
+ ],
+ )
+ if not os.path.isfile(file_path):
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error: The path {file_path} is not a file.",
+ ),
+ ],
+ )
+
+ try:
+ content = _view_text_file(file_path, ranges)
+ except ToolInvalidArgumentsError as e:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=e.message,
+ ),
+ ],
+ )
+
+ if ranges is None:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"""The content of {file_path}:
+```
+{content}```""",
+ ),
+ ],
+ )
+ else:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"""The content of {file_path} in {ranges} lines:
+```
+{content}```""",
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_text_file/_write_text_file.py b/src/agentscope/tool/_text_file/_write_text_file.py
new file mode 100644
index 000000000..de7a0b40b
--- /dev/null
+++ b/src/agentscope/tool/_text_file/_write_text_file.py
@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+# flake8: noqa: E501
+# pylint: disable=line-too-long
+"""The text file tools in agentscope."""
+import os
+
+from ._utils import _calculate_view_ranges, _view_text_file
+from .._response import ToolResponse
+from ...message import TextBlock
+
+
+async def insert_text_file(
+ file_path: str,
+ content: str,
+ line_number: int,
+) -> ToolResponse:
+ """Insert the content at the specified line number in a text file.
+
+ Args:
+ file_path (`str`):
+ The target file path.
+ content (`str`):
+ The content to be inserted.
+ line_number (`int`):
+ The line number at which the content should be inserted, starting
+ from 1. If exceeds the number of lines in the file, it will be
+ appended to the end of the file.
+
+ Returns:
+ `ToolResponse`:
+ The tool response containing the result of the insertion operation.
+ """
+ if line_number <= 0:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"InvalidArgumentsError: "
+ f"The line number {line_number} is invalid. ",
+ ),
+ ],
+ )
+
+ if not os.path.exists(file_path):
+ with open(file_path, "w", encoding="utf-8") as file:
+ file.write(content + "\n")
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"InvalidArgumentsError: The target file "
+ f"{file_path} does not exist. ",
+ ),
+ ],
+ )
+
+ with open(file_path, "r", encoding="utf-8") as file:
+ original_lines = file.readlines()
+
+ if line_number == len(original_lines) + 1:
+ new_lines = original_lines + ["\n" + content]
+ elif line_number < len(original_lines) + 1:
+ new_lines = (
+ original_lines[: line_number - 1]
+ + [content + "\n"]
+ + original_lines[line_number - 1 :]
+ )
+ else:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="InvalidArgumentsError: The given line_number "
+ f"({line_number}) is not in the valid range "
+ f"[1, {len(original_lines) + 1}].",
+ ),
+ ],
+ )
+
+ with open(file_path, "w", encoding="utf-8") as file:
+ file.writelines(new_lines)
+
+ with open(file_path, "r", encoding="utf-8") as file:
+ new_lines = file.readlines()
+
+ start, end = _calculate_view_ranges(
+ len(original_lines),
+ len(new_lines),
+ line_number,
+ line_number,
+ extra_view_n_lines=5,
+ )
+
+ show_content = _view_text_file(file_path, [start, end])
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Insert content into {file_path} at line "
+ f"{line_number} successfully. The new content "
+ f"between lines {start}-{end} is:\n"
+ f"```\n{show_content}```",
+ ),
+ ],
+ )
+
+
+async def write_text_file(
+ file_path: str,
+ content: str,
+ ranges: None | list[int] = None,
+) -> ToolResponse:
+ """Create/Replace/Overwrite content in a text file. When `ranges` is provided, the content will be replaced in the specified range. Otherwise, the entire file (if exists) will be overwritten.
+
+ Args:
+ file_path (`str`):
+ The target file path.
+ content (`str`):
+ The content to be written.
+ ranges (`list[int] | None`, defaults to `None`):
+ The range of lines to be replaced. If `None`, the entire file will
+ be overwritten.
+
+ Returns:
+ `ToolResponse`:
+ The tool response containing the result of the writing operation.
+ """
+
+ if not os.path.exists(file_path):
+ with open(file_path, "w", encoding="utf-8") as file:
+ file.write(content)
+
+ if ranges:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Create and write {file_path} successfully. "
+ f"The ranges {ranges} is ignored because the "
+ f"file does not exist.",
+ ),
+ ],
+ )
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Create and write {file_path} successfully.",
+ ),
+ ],
+ )
+
+ with open(file_path, "r", encoding="utf-8") as file:
+ original_lines = file.readlines()
+
+ if ranges is not None:
+ if (
+ isinstance(ranges, list)
+ and len(ranges) == 2
+ and all(isinstance(i, int) for i in ranges)
+ ):
+ # Replace content in the specified range
+ start, end = ranges
+ if start > len(original_lines):
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error: The start line {start} is invalid. "
+ f"The file only has {len(original_lines)} "
+ f"lines.",
+ ),
+ ],
+ )
+
+ new_content = (
+ original_lines[: start - 1]
+ + [
+ content,
+ ]
+ + original_lines[end:]
+ )
+
+ with open(file_path, "w", encoding="utf-8") as file:
+ file.write("".join(new_content))
+
+ # The written content may contain multiple "\n", to avoid mis
+ # counting the lines, we read the file again to get the new content
+ with open(file_path, "r", encoding="utf-8") as file:
+ new_lines = file.readlines()
+
+ view_start, view_end = _calculate_view_ranges(
+ len(original_lines),
+ len(new_lines),
+ start,
+ end,
+ )
+
+ content = "".join(
+ [
+ f"{index + view_start}: {line}"
+ for index, line in enumerate(
+ new_lines[view_start - 1 : view_end],
+ )
+ ],
+ )
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"""Write {file_path} successfully. The new content snippet:
+```
+{content}```""",
+ ),
+ ],
+ )
+
+ else:
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error: Invalid range format. Expected a list "
+ f"of two integers, but got {ranges}.",
+ ),
+ ],
+ )
+
+ with open(file_path, "w", encoding="utf-8") as file:
+ file.write(content)
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Overwrite {file_path} successfully.",
+ ),
+ ],
+ )
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
new file mode 100644
index 000000000..d6838f392
--- /dev/null
+++ b/src/agentscope/tool/_toolkit.py
@@ -0,0 +1,953 @@
+# -*- coding: utf-8 -*-
+"""The toolkit class for tool calls in agentscope."""
+
+import asyncio
+import inspect
+from copy import deepcopy
+from dataclasses import dataclass
+from functools import partial
+from typing import (
+ AsyncGenerator,
+ Literal,
+ Dict,
+ Any,
+ Type,
+ Generator,
+ Callable,
+)
+
+from pydantic import (
+ BaseModel,
+ Field,
+ create_model,
+ ConfigDict,
+)
+from docstring_parser import parse
+
+from ._async_wrapper import (
+ _async_generator_wrapper,
+ _object_wrapper,
+ _sync_generator_wrapper,
+)
+from ._registered_tool_function import RegisteredToolFunction
+from ._response import ToolResponse
+from .._utils._common import _remove_title_field
+from ..mcp import (
+ MCPToolFunction,
+ MCPClientBase,
+ StatefulClientBase,
+)
+from ..message import (
+ ToolUseBlock,
+ TextBlock,
+)
+from ..module import StateModule
+from ..types import (
+ JSONSerializableObject,
+ ToolFunction,
+)
+from ..tracing._trace import trace_toolkit
+from .._logging import logger
+
+
+@dataclass
+class ToolGroup:
+ """The tool group class"""
+
+ name: str
+ """The group name, which will be used in the reset function as the group
+ identifier."""
+ active: bool
+ """If the tool group is active, meaning the tool functions in this group
+ is included in the JSON schema"""
+ description: str
+ """The description of the tool group to tell the agent what the tool
+ group is about."""
+ notes: str | None = None
+ """The using notes of the tool group, to remind the agent how to use"""
+
+
+class Toolkit(StateModule):
+ """The class that supports both function- and group-level tool management.
+
+ Use the following methods to manage the tool functions:
+
+ - `register_tool_function`
+ - `remove_tool_function`
+
+ For group-level management:
+
+ - `create_tool_group`
+ - `update_tool_groups`
+ - `remove_tool_groups`
+
+ MCP related methods:
+
+ - `register_mcp_server`
+ - `remove_mcp_servers`
+
+ To run the tool functions or get the data from the activated tools:
+
+ - `call_tool_function`
+ - `get_json_schemas`
+ - `get_tool_group_notes`
+ """
+
+ def __init__(self) -> None:
+ """Initialize the toolkit."""
+ super().__init__()
+
+ self.tools: dict[str, RegisteredToolFunction] = {}
+ self.groups: dict[str, ToolGroup] = {}
+
+ def create_tool_group(
+ self,
+ group_name: str,
+ description: str,
+ active: bool = False,
+ notes: str | None = None,
+ ) -> None:
+ """Create a tool group to organize tool functions
+
+ Args:
+ group_name (`str`):
+ The name of the tool group.
+ description (`str`):
+ The description of the tool group.
+ active (`bool`, defaults to `False`):
+ If the group is active, meaning the tool functions in this
+ group are included in the JSON schema.
+ notes (`str | None`, optional):
+ The notes used to remind the agent how to use the tool
+ functions properly, which can be combined into the system
+ prompt.
+ """
+ if group_name in self.groups or group_name == "basic":
+ raise ValueError(
+ f"Tool group '{group_name}' is already registered in the "
+ "toolkit.",
+ )
+
+ self.groups[group_name] = ToolGroup(
+ name=group_name,
+ description=description,
+ notes=notes,
+ active=active,
+ )
+
+ def update_tool_groups(self, group_names: list[str], active: bool) -> None:
+ """Update the activation status of the given tool groups.
+
+ Args:
+ group_names (`list[str]`):
+ The list of tool group names to be updated.
+ active (`bool`):
+ If the tool groups should be activated or deactivated.
+ """
+
+ for group_name in group_names:
+ if group_name == "basic":
+ logger.warning(
+ "The 'basic' tool group is always active, skipping it.",
+ )
+
+ if group_name in self.groups:
+ self.groups[group_name].active = active
+
+ def remove_tool_groups(self, group_names: list[str]) -> None:
+ """Remove tool functions from the toolkit by their group names.
+
+ Args:
+ group_names (`str`):
+ The group names to be removed from the toolkit.
+ """
+ if isinstance(group_names, str):
+ group_names = [group_names]
+
+ if not isinstance(group_names, list) or not all(
+ isinstance(_, str) for _ in group_names
+ ):
+ raise TypeError(
+ f"The group_names must be a list of strings, "
+ f"but got {type(group_names)}.",
+ )
+
+ if "basic" in group_names:
+ raise ValueError(
+ "Cannot remove the default 'basic' tool group.",
+ )
+
+ for group_name in group_names:
+ self.groups.pop(group_name, None)
+
+ # Remove the tool functions in the given groups
+ tool_names = deepcopy(list(self.tools.keys()))
+ for tool_name in tool_names:
+ if self.tools[tool_name].group in group_names:
+ self.tools.pop(tool_name)
+
+ def register_tool_function( # pylint: disable=too-many-branches
+ self,
+ tool_func: ToolFunction,
+ group_name: str | Literal["basic"] = "basic",
+ preset_kwargs: dict[str, JSONSerializableObject] | None = None,
+ func_description: str | None = None,
+ json_schema: dict | None = None,
+ include_long_description: bool = True,
+ include_var_positional: bool = False,
+ include_var_keyword: bool = False,
+ postprocess_func: Callable[
+ [
+ ToolUseBlock,
+ ToolResponse,
+ ],
+ ToolResponse | None,
+ ]
+ | None = None,
+ ) -> None:
+ """Register a tool function to the toolkit.
+
+ Args:
+ tool_func (`ToolFunction`):
+ The tool function, which can be async or sync, streaming or
+ not-streaming, but the response must be a `ToolResponse`
+ object.
+ group_name (`str | Literal["basic"]`, defaults to `"basic"`):
+ The belonging group of the tool function. Tools in "basic"
+ group is always included in the JSON schema, while the others
+ are only included when their group is active.
+ preset_kwargs (`dict[str, JSONSerializableObject] | None`, \
+ optional):
+ Preset arguments by the user, which will not be included in
+ the JSON schema, nor exposed to the agent.
+ func_description (`str | None`, optional):
+ The function description. If not provided, the description
+ will be extracted from the docstring automatically.
+ json_schema (`dict | None`, optional):
+ Manually provided JSON schema for the tool function, which
+ should be `{"type": "function", "function": {"name":
+ "function_name": "xx", "description": "xx",
+ "parameters": {...}}}`
+ include_long_description (`bool`, defaults to `True`):
+ When extracting function description from the docstring, if
+ the long description will be included.
+ include_var_positional (`bool`, defaults to `False`):
+ Whether to include the variable positional arguments (`*args`)
+ in the function schema.
+ include_var_keyword (`bool`, defaults to `False`):
+ Whether to include the variable keyword arguments (`**kwargs`)
+ in the function schema.
+ postprocess_func (`Callable[[ToolUseBlock, ToolResponse], \
+ ToolResponse | None] | None`, optional):
+ A post-processing function that will be called after the tool
+ function is executed, taking the tool call block and tool
+ response as arguments. If it returns `None`, the tool
+ result will be returned as is. If it returns a
+ `ToolResponse`, the returned block will be used as the
+ final tool result.
+ """
+ # Arguments checking
+ if group_name not in self.groups and group_name != "basic":
+ raise ValueError(
+ f"Tool group '{group_name}' not found.",
+ )
+
+ # Check the manually provided JSON schema if provided
+ if json_schema:
+ assert (
+ isinstance(json_schema, dict)
+ and "type" in json_schema
+ and json_schema["type"] == "function"
+ and "function" in json_schema
+ and isinstance(json_schema["function"], dict)
+ ), "Invalid JSON schema for the tool function."
+
+ # Handle MCP tool function and regular function respectively
+ mcp_name = None
+ if isinstance(tool_func, MCPToolFunction):
+ func_name = tool_func.name
+ original_func = tool_func.__call__
+ self._validate_tool_function(func_name)
+ json_schema = json_schema or tool_func.json_schema
+ mcp_name = tool_func.mcp_name
+
+ elif isinstance(tool_func, partial):
+ # partial function
+ kwargs = tool_func.keywords
+ # Turn args into keyword arguments
+ if tool_func.args:
+ param_names = list(
+ inspect.signature(tool_func.func).parameters.keys(),
+ )
+ for i, arg in enumerate(tool_func.args):
+ if i < len(param_names):
+ kwargs[param_names[i]] = arg
+
+ preset_kwargs = {
+ **kwargs,
+ **(preset_kwargs or {}),
+ }
+
+ func_name = tool_func.func.__name__
+ original_func = tool_func.func
+ self._validate_tool_function(func_name)
+ json_schema = json_schema or self._parse_tool_function(
+ tool_func.func,
+ include_long_description=include_long_description,
+ include_var_positional=include_var_positional,
+ include_var_keyword=include_var_keyword,
+ )
+
+ else:
+ # normal function
+ func_name = tool_func.__name__
+ original_func = tool_func
+ self._validate_tool_function(func_name)
+ json_schema = json_schema or self._parse_tool_function(
+ tool_func,
+ include_long_description=include_long_description,
+ include_var_positional=include_var_positional,
+ include_var_keyword=include_var_keyword,
+ )
+
+ # Override the description if provided
+ if func_description:
+ json_schema["function"]["description"] = func_description
+
+ # Remove the preset kwargs from the JSON schema
+ for arg_name in preset_kwargs or {}:
+ if arg_name in json_schema["function"]["parameters"]["properties"]:
+ json_schema["function"]["parameters"]["properties"].pop(
+ arg_name,
+ )
+
+ if "required" in json_schema["function"]["parameters"]:
+ for arg_name in preset_kwargs or {}:
+ if (
+ arg_name
+ in json_schema["function"]["parameters"]["required"]
+ ):
+ json_schema["function"]["parameters"]["required"].remove(
+ arg_name,
+ )
+
+ # Remove the required field if it is empty
+ if len(json_schema["function"]["parameters"]["required"]) == 0:
+ json_schema["function"]["parameters"].pop("required", None)
+
+ func_obj = RegisteredToolFunction(
+ name=func_name,
+ group=group_name,
+ source="function",
+ original_func=original_func,
+ json_schema=json_schema,
+ preset_kwargs=preset_kwargs or {},
+ extended_model=None,
+ mcp_name=mcp_name,
+ postprocess_func=postprocess_func,
+ )
+
+ self.tools[func_name] = func_obj
+
+ def remove_tool_function(self, tool_name: str) -> None:
+ """Remove tool function from the toolkit by its name.
+
+ Args:
+ tool_name (`str`):
+ The name of the tool function to be removed.
+ """
+
+ if tool_name not in self.tools:
+ logger.warning(
+ "Skipping removing tool function '%s' as it does not exist.",
+ tool_name,
+ )
+
+ self.tools.pop(tool_name, None)
+
+ def get_json_schemas(
+ self,
+ ) -> list[dict]:
+ """Get the JSON schemas from the tool functions that belong to the
+ active groups.
+
+ .. note:: The preset keyword arguments is removed from the JSON
+ schema, and the extended model is applied if it is set.
+
+ Example:
+ .. code-block:: JSON
+ :caption: Example of tool function JSON schemas
+
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "google_search",
+ "description": "Search on Google.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "The search query."
+ }
+ },
+ "required": ["query"]
+ }
+ }
+ },
+ ...
+ ]
+
+ Returns:
+ `list[dict]`:
+ A list of function JSON schemas.
+ """
+ # If meta tool is set here, update its extended model here
+ if "reset_equipped_tools" in self.tools:
+ fields = {}
+ for group_name, group in self.groups.items():
+ if group_name == "basic":
+ continue
+ fields[group_name] = (
+ bool,
+ Field(
+ default=False,
+ description=group.description,
+ ),
+ )
+ extended_model = create_model("_DynamicModel", **fields)
+ self.set_extended_model(
+ "reset_equipped_tools",
+ extended_model,
+ )
+
+ return [
+ tool.extended_json_schema
+ for tool in self.tools.values()
+ if tool.group == "basic" or self.groups[tool.group].active
+ ]
+
+ def set_extended_model(
+ self,
+ func_name: str,
+ model: Type[BaseModel] | None,
+ ) -> None:
+ """Set the extended model for a tool function, so that the original
+ JSON schema will be extended.
+
+ Args:
+ func_name (`str`):
+ The name of the tool function.
+ model (`Union[Type[BaseModel], None]`):
+ The extended model to be set.
+ """
+ if model is not None and not issubclass(model, BaseModel):
+ raise TypeError(
+ "The extended model must be a child class of pydantic "
+ f"BaseModel, but got {type(model)}.",
+ )
+
+ if func_name in self.tools:
+ self.tools[func_name].extended_model = model
+
+ else:
+ raise ValueError(
+ f"Tool function '{func_name}' not found in the toolkit.",
+ )
+
+ async def remove_mcp_clients(
+ self,
+ client_names: list[str],
+ ) -> None:
+ """Remove tool functions from the MCP clients by their names.
+
+ Args:
+ client_names (`list[str]`):
+ The names of the MCP client, which used to initialize the
+ client instance.
+ """
+ if isinstance(client_names, str):
+ client_names = [client_names]
+
+ if isinstance(client_names, list) and not all(
+ isinstance(_, str) for _ in client_names
+ ):
+ raise TypeError(
+ f"The client_names must be a list of strings, "
+ f"but got {type(client_names)}.",
+ )
+
+ to_removed = []
+ func_names = deepcopy(list(self.tools.keys()))
+ for func_name in func_names:
+ if self.tools[func_name].mcp_name in client_names:
+ self.tools.pop(func_name)
+ to_removed.append(func_name)
+
+ logger.info(
+ "Removed %d tool functions from %d MCP: %s",
+ len(to_removed),
+ len(client_names),
+ ", ".join(to_removed),
+ )
+
+ @trace_toolkit
+ async def call_tool_function(
+ self,
+ tool_call: ToolUseBlock,
+ ) -> AsyncGenerator[ToolResponse, None]:
+ """Execute the tool function by the `ToolUseBlock` and return the
+ tool response chunk in unified streaming mode, i.e. an async
+ generator of `ToolResponse` objects.
+
+ .. note:: The tool response chunk is **accumulated**.
+
+ Args:
+ tool_call (`ToolUseBlock`):
+ A tool call block.
+
+ Yields:
+ `ToolResponse`:
+ The tool response chunk, in accumulative manner.
+ """
+
+ # Check
+ if tool_call["name"] not in self.tools:
+ return _object_wrapper(
+ ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="FunctionNotFoundError: Cannot find the "
+ f"function named {tool_call['name']}",
+ ),
+ ],
+ ),
+ None,
+ )
+
+ # Prepare function and keyword arguments
+ tool_func = self.tools[tool_call["name"]]
+ kwargs = {
+ **tool_func.preset_kwargs,
+ **(tool_call.get("input", {}) or {}),
+ }
+
+ # Prepare postprocess function
+ if tool_func.postprocess_func:
+ partial_postprocess_func = partial(
+ tool_func.postprocess_func,
+ tool_call,
+ )
+ else:
+ partial_postprocess_func = None
+
+ # Async function
+ try:
+ if inspect.iscoroutinefunction(tool_func.original_func):
+ try:
+ res = await tool_func.original_func(**kwargs)
+ except asyncio.CancelledError:
+ res = ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text="<system-info>"
+ "The tool call has been interrupted "
+ "by the user."
+ "</system-info>",
+ ),
+ ],
+ stream=True,
+ is_last=True,
+ is_interrupted=True,
+ )
+
+ else:
+ # When `tool_func.original_func` is Async generator function or
+ # Sync function
+ res = tool_func.original_func(**kwargs)
+
+ except Exception as e:
+ res = ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Error: {e}",
+ ),
+ ],
+ )
+
+ # Handle different return type
+
+ # If return an async generator
+ if isinstance(res, AsyncGenerator):
+ return _async_generator_wrapper(res, partial_postprocess_func)
+
+ # If return a sync generator
+ if isinstance(res, Generator):
+ return _sync_generator_wrapper(res, partial_postprocess_func)
+
+ if isinstance(res, ToolResponse):
+ return _object_wrapper(res, partial_postprocess_func)
+
+ raise TypeError(
+ "The tool function must return a ToolResponse object, or an "
+ "AsyncGenerator/Generator of ToolResponse objects, "
+ f"but got {type(res)}.",
+ )
+
+ async def register_mcp_client(
+ self,
+ mcp_client: MCPClientBase,
+ group_name: str = "basic",
+ enable_funcs: list[str] | None = None,
+ disable_funcs: list[str] | None = None,
+ preset_kwargs_mapping: dict[str, dict[str, Any]] | None = None,
+ postprocess_func: Callable[
+ [
+ ToolUseBlock,
+ ToolResponse,
+ ],
+ ToolResponse | None,
+ ]
+ | None = None,
+ ) -> None:
+ """Register tool functions from an MCP client.
+
+ Args:
+ mcp_client (`MCPClientBase`):
+ The MCP client instance to connect to the MCP server.
+ group_name (`str`, defaults to `"basic"`):
+ The group name that the tool functions will be added to.
+ enable_funcs (`list[str] | None`, optional):
+ The functions to be added into the toolkit. If `None`, all
+ tool functions within the MCP servers will be added.
+ disable_funcs (`list[str] | None`, optional):
+ The functions that will be filtered out. If `None`, no
+ tool functions will be filtered out.
+ preset_kwargs_mapping: (`Optional[dict[str, dict[str, Any]]]`, \
+ defaults to `None`):
+ The preset keyword arguments mapping, whose keys are the tool
+ function names and values are the preset keyword arguments.
+ postprocess_func (`Callable[[ToolUseBlock, ToolResponse], \
+ ToolResponse | None] | None`, optional):
+ A post-processing function that will be called after the tool
+ function is executed, taking the tool call block and tool
+ response as arguments. If it returns `None`, the tool
+ result will be returned as is. If it returns a
+ `ToolResponse`, the returned block will be used as the
+ final tool result.
+ """
+ if (
+ isinstance(mcp_client, StatefulClientBase)
+ and not mcp_client.is_connected
+ ):
+ raise RuntimeError(
+ "The MCP client is not connected to the server. Use the "
+ "`connect()` method first.",
+ )
+
+ # Check arguments for enable_funcs and disabled_funcs
+ if enable_funcs is not None and disable_funcs is not None:
+ assert isinstance(enable_funcs, list) and all(
+ isinstance(_, str) for _ in enable_funcs
+ ), (
+ "Enable functions should be a list of strings, but got "
+ f"{enable_funcs}."
+ )
+
+ assert isinstance(disable_funcs, list) and all(
+ isinstance(_, str) for _ in disable_funcs
+ ), (
+ "Disable functions should be a list of strings, but got "
+ f"{disable_funcs}."
+ )
+ intersection = set(enable_funcs).intersection(
+ set(disable_funcs),
+ )
+ assert len(intersection) == 0, (
+ f"The functions in enable_funcs and disable_funcs "
+ f"should not overlap, but got {intersection}."
+ )
+
+ if not (
+ preset_kwargs_mapping is None
+ or isinstance(preset_kwargs_mapping, dict)
+ ):
+ raise TypeError(
+ f"The preset_kwargs_mapping must be a dictionary or None, "
+ f"but got {type(preset_kwargs_mapping)}.",
+ )
+
+ tool_names = []
+ for mcp_tool in await mcp_client.list_tools():
+ # Skip the functions that are not in the enable_funcs if
+ # enable_funcs is not None
+ if enable_funcs is not None and mcp_tool.name not in enable_funcs:
+ continue
+
+ # Skip the disabled functions
+ if disable_funcs is not None and mcp_tool.name in disable_funcs:
+ continue
+
+ tool_names.append(mcp_tool.name)
+
+ # Obtain callable function object
+ func_obj = await mcp_client.get_callable_function(
+ func_name=mcp_tool.name,
+ wrap_tool_result=True,
+ )
+
+ # Prepare preset kwargs
+ preset_kwargs = None
+ if preset_kwargs_mapping is not None:
+ preset_kwargs = preset_kwargs_mapping.get(mcp_tool.name, {})
+
+ # TODO: handle mcp_server_name
+ self.register_tool_function(
+ tool_func=func_obj,
+ group_name=group_name,
+ preset_kwargs=preset_kwargs,
+ postprocess_func=postprocess_func,
+ )
+
+ logger.info(
+ "Registered %d tool functions from MCP: %s.",
+ len(tool_names),
+ ", ".join(tool_names),
+ )
+
+ def state_dict(self) -> dict[str, Any]:
+ """Get the state dictionary of the toolkit.
+
+ Returns:
+ `dict[str, Any]`:
+ A dictionary containing the active tool group names.
+ """
+ return {
+ "active_groups": [
+ name for name, group in self.groups.items() if group.active
+ ],
+ }
+
+ def load_state_dict(
+ self,
+ state_dict: dict[str, Any],
+ strict: bool = True,
+ ) -> None:
+ """Load the state dictionary into the toolkit.
+
+ Args:
+ state_dict (`dict`):
+ The state dictionary to load, which should have "active_groups"
+ key and its value must be a list of group names.
+ strict (`bool`, defaults to `True`):
+ If `True`, raises an error if any key in the module is not
+ found in the state_dict. If `False`, skips missing keys.
+ """
+ if (
+ not isinstance(state_dict, dict)
+ or "active_groups" not in state_dict
+ or not isinstance(state_dict["active_groups"], list)
+ ):
+ raise ValueError(
+ "The state_dict for toolkit must be a dictionary with "
+ "active_groups key and its value must be a list, "
+ f"but got {type(state_dict)}.",
+ )
+
+ if strict and list(state_dict.keys()) != ["active_groups"]:
+ raise ValueError(
+ "Get additional keys in the state_dict: "
+ f'{list(state_dict.keys())}, but only "active_groups" '
+ "is expected.",
+ )
+
+ for group_name, group in self.groups.items():
+ if group_name in state_dict["active_groups"]:
+ group.active = True
+ else:
+ group.active = False
+
+ def get_activated_notes(self) -> str:
+ """Get the notes from the active tool groups, which can be used to
+ construct the system prompt for the agent.
+
+ Returns:
+ `str`:
+ The combined notes from the active tool groups.
+ """
+ collected_notes = []
+ for group_name, group in self.groups.items():
+ if group.active and group.notes:
+ collected_notes.append(
+ "\n".join(
+ [f"## About {group_name} Tools", group.notes],
+ ),
+ )
+ return "\n".join(collected_notes)
+
+ def reset_equipped_tools(self, **kwargs: Any) -> ToolResponse:
+ """Choose appropriate tools to equip yourself with, so that you can
+ finish your task. Each argument in this function represents a group
+ of related tools, and the value indicates whether to activate the
+ group or not. Besides, the tool response of this function will
+ contain the precaution notes for using them, which you
+ **MUST pay attention to and follow**. You can also reuse this function
+ to check the notes of the tool groups.
+
+ Note this function will `reset` the tools, so that the original tools
+ will be removed first.
+ """
+
+ to_activate = []
+ for key, value in kwargs.items():
+ if not isinstance(value, bool):
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Invalid arguments: the argument {key} "
+ f"should be a bool value, but got {type(value)}.",
+ ),
+ ],
+ )
+
+ if value:
+ to_activate.append(key)
+
+ self.update_tool_groups(to_activate, active=True)
+
+ notes = self.get_activated_notes()
+
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Active tool groups successfully: {to_activate}. "
+ "You MUST follow these notes to use the tools:\n"
+ f"<notes>{notes}</notes>",
+ ),
+ ],
+ )
+
+ def clear(self) -> None:
+ """Clear the toolkit, removing all tool functions and groups."""
+ self.tools.clear()
+ self.groups.clear()
+
+ def _validate_tool_function(self, func_name: str) -> None:
+ """Check if the tool function already registered in the toolkit. If
+ so, raise a ValueError."""
+ if func_name in self.tools:
+ raise ValueError(
+ f"A function with name '{func_name} is already registered "
+ "in the toolkit.",
+ )
+
+ @staticmethod
+ def _parse_tool_function(
+ tool_func: ToolFunction,
+ include_long_description: bool,
+ include_var_positional: bool,
+ include_var_keyword: bool,
+ ) -> dict:
+ """Extract JSON schema from the tool function's docstring"""
+ docstring = parse(tool_func.__doc__)
+ params_docstring = {
+ _.arg_name: _.description for _ in docstring.params
+ }
+
+ # Function description
+ descriptions = []
+ if docstring.short_description is not None:
+ descriptions.append(docstring.short_description)
+
+ if include_long_description and docstring.long_description is not None:
+ descriptions.append(docstring.long_description)
+
+ func_description = "\n\n".join(descriptions)
+
+ # Create a dynamic model with the function signature
+ fields = {}
+ for name, param in inspect.signature(tool_func).parameters.items():
+ # Skip the `self` and `cls` parameters
+ if name in ["self", "cls"]:
+ continue
+
+ # Handle `**kwargs`
+ if param.kind == inspect.Parameter.VAR_KEYWORD:
+ if not include_var_keyword:
+ continue
+
+ fields[name] = (
+ Dict[str, Any]
+ if param.annotation == inspect.Parameter.empty
+ else Dict[str, param.annotation], # type: ignore
+ Field(
+ description=params_docstring.get(
+ f"**{name}",
+ params_docstring.get(name, None),
+ ),
+ default={}
+ if param.default is param.empty
+ else param.default,
+ ),
+ )
+
+ elif param.kind == inspect.Parameter.VAR_POSITIONAL:
+ if not include_var_positional:
+ continue
+
+ fields[name] = (
+ list[Any]
+ if param.annotation == inspect.Parameter.empty
+ else list[param.annotation], # type: ignore
+ Field(
+ description=params_docstring.get(
+ f"*{name}",
+ params_docstring.get(name, None),
+ ),
+ default=[]
+ if param.default is param.empty
+ else param.default,
+ ),
+ )
+
+ else:
+ fields[name] = (
+ Any
+ if param.annotation == inspect.Parameter.empty
+ else param.annotation,
+ Field(
+ description=params_docstring.get(name, None),
+ default=...
+ if param.default is param.empty
+ else param.default,
+ ),
+ )
+
+ base_model = create_model(
+ "_StructuredOutputDynamicClass",
+ __config__=ConfigDict(arbitrary_types_allowed=True),
+ **fields,
+ )
+ params_json_schema = base_model.model_json_schema()
+
+ # Remove the title from the json schema
+ _remove_title_field(params_json_schema)
+
+ func_json_schema: dict = {
+ "type": "function",
+ "function": {
+ "name": tool_func.__name__,
+ "parameters": params_json_schema,
+ },
+ }
+
+ if func_description not in [None, ""]:
+ func_json_schema["function"]["description"] = func_description
+
+ return func_json_schema
diff --git a/src/agentscope/tracing/__init__.py b/src/agentscope/tracing/__init__.py
new file mode 100644
index 000000000..1f01bdaf3
--- /dev/null
+++ b/src/agentscope/tracing/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""The tracing interface class in agentscope."""
+
+from ._setup import setup_tracing
+from ._trace import (
+ trace,
+ trace_llm,
+ trace_reply,
+ trace_format,
+ trace_toolkit,
+ trace_embedding,
+)
+
+__all__ = [
+ "setup_tracing",
+ "trace",
+ "trace_llm",
+ "trace_reply",
+ "trace_format",
+ "trace_toolkit",
+ "trace_embedding",
+]
diff --git a/src/agentscope/tracing/_attributes.py b/src/agentscope/tracing/_attributes.py
new file mode 100644
index 000000000..872404ef8
--- /dev/null
+++ b/src/agentscope/tracing/_attributes.py
@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+"""Attributes processor for span attributes."""
+import datetime
+import enum
+import inspect
+import json
+from dataclasses import is_dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..message import Msg
+
+
+def _to_serializable(
+ obj: Any,
+) -> Any:
+ """Convert an object to a JSON serializable type.
+
+ Args:
+ obj (`Any`):
+ The object to be converted to JSON serializable.
+
+ Returns:
+ `Any`:
+ The converted JSON serializable object
+ """
+
+ # Handle primitive types first
+ if isinstance(obj, (str, int, bool, float, type(None))):
+ res = obj
+
+ elif isinstance(obj, (list, tuple, set, frozenset)):
+ res = [_to_serializable(x) for x in obj]
+
+ elif isinstance(obj, dict):
+ res = {str(key): _to_serializable(val) for (key, val) in obj.items()}
+
+ elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):
+ res = repr(obj)
+
+ elif inspect.isclass(obj) and issubclass(obj, BaseModel):
+ res = repr(obj)
+
+ elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):
+ res = obj.isoformat()
+
+ elif isinstance(obj, datetime.timedelta):
+ res = obj.total_seconds()
+
+ elif isinstance(obj, enum.Enum):
+ res = _to_serializable(obj.value)
+
+ else:
+ res = str(obj)
+
+ return res
+
+
+def _serialize_to_str(value: Any) -> str:
+ """Get input attributes
+
+ Args:
+ value (`Any`):
+ The input value
+
+ Returns:
+ `str`:
+ JSON serialized string of the input value
+ """
+ try:
+ return json.dumps(value, ensure_ascii=False)
+
+ except TypeError:
+ return json.dumps(
+ _to_serializable(value),
+ ensure_ascii=False,
+ )
diff --git a/src/agentscope/tracing/_setup.py b/src/agentscope/tracing/_setup.py
new file mode 100644
index 000000000..33835f23e
--- /dev/null
+++ b/src/agentscope/tracing/_setup.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""The tracing interface class in agentscope."""
+from agentscope import _config
+
+
+def setup_tracing(endpoint: str) -> None:
+ """Set up the AgentScope tracing by configuring the endpoint URL.
+
+ Args:
+ endpoint (`str`):
+ The endpoint URL for the tracing exporter.
+ """
+ # Lazy import
+ from opentelemetry.sdk.trace import TracerProvider
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+ OTLPSpanExporter,
+ )
+ from opentelemetry import trace
+
+ tracer_provider = TracerProvider()
+ exporter = OTLPSpanExporter(endpoint=endpoint)
+ span_processor = BatchSpanProcessor(exporter)
+ tracer_provider.add_span_processor(span_processor)
+ trace.set_tracer_provider(tracer_provider)
+
+ _config.trace_enabled = True
diff --git a/src/agentscope/tracing/_trace.py b/src/agentscope/tracing/_trace.py
new file mode 100644
index 000000000..a44a10e29
--- /dev/null
+++ b/src/agentscope/tracing/_trace.py
@@ -0,0 +1,702 @@
+# -*- coding: utf-8 -*-
+"""The tracing decorators for agent, formatter, toolkit, chat and embedding
+models."""
+import inspect
+from functools import wraps
+from typing import (
+ Generator,
+ AsyncGenerator,
+ Callable,
+ Any,
+ Coroutine,
+ TypeVar,
+ TYPE_CHECKING,
+)
+
+import aioitertools
+
+from ._attributes import _serialize_to_str
+from .. import _config
+from ..embedding._embedding_base import EmbeddingModelBase
+from ..model._model_base import ChatModelBase
+from .._logging import logger
+from ._types import SpanKind, SpanAttributes
+
+if TYPE_CHECKING:
+ from ..agent import AgentBase
+ from ..formatter import FormatterBase
+ from ..tool import (
+ Toolkit,
+ ToolResponse,
+ )
+ from ..message import (
+ Msg,
+ ToolUseBlock,
+ )
+ from ..embedding import EmbeddingResponse
+ from ..model import ChatResponse
+ from opentelemetry.trace import Span
+else:
+ Toolkit = "Toolkit"
+ ToolResponse = "ToolResponse"
+ Msg = "Msg"
+ ToolUseBlock = "ToolUseBlock"
+ EmbeddingResponse = "EmbeddingResponse"
+ ChatResponse = "ChatResponse"
+ Span = "Span"
+
+
+T = TypeVar("T")
+
+
+def _check_tracing_enabled() -> bool:
+ """Check if the OpenTelemetry tracer is initialized in AgentScope with an
+ endpoint.
+
+ TODO: We expect an OpenTelemetry official interface to check if the
+ tracer is initialized. Leaving this function here as a temporary
+ solution.
+ """
+ return _config.trace_enabled
+
+
+def _trace_sync_generator_wrapper(
+ res: Generator[T, None, None],
+ span: Span,
+) -> Generator[T, None, None]:
+ """Trace the sync generator output with OpenTelemetry."""
+
+ import opentelemetry
+
+ has_error = False
+
+ try:
+ last_chunk = None
+ for chunk in res:
+ last_chunk = chunk
+ yield chunk
+ except Exception as e:
+ has_error = True
+ span.set_status(opentelemetry.trace.StatusCode.ERROR, str(e))
+ span.record_exception(e)
+ raise e from None
+
+ finally:
+ if not has_error:
+ # Set the last chunk as output
+ span.set_attributes(
+ {
+ SpanAttributes.OUTPUT: _serialize_to_str(last_chunk),
+ },
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+
+
+async def _trace_async_generator_wrapper(
+ res: AsyncGenerator[T, None],
+ span: Span,
+) -> AsyncGenerator[T, None]:
+ """Trace the async generator output with OpenTelemetry.
+
+ Args:
+ res (`AsyncGenerator[T, None]`):
+ The generator or async generator to be traced.
+ span (`Span`):
+ The OpenTelemetry span to be used for tracing.
+
+ Yields:
+ `T`:
+ The output of the async generator.
+ """
+ import opentelemetry
+
+ has_error = False
+
+ try:
+ last_chunk = None
+ async for chunk in aioitertools.iter(res):
+ last_chunk = chunk
+ yield chunk
+
+ except Exception as e:
+ has_error = True
+ span.set_status(opentelemetry.trace.StatusCode.ERROR, str(e))
+ span.record_exception(e)
+ raise e from None
+
+ finally:
+ if not has_error:
+ # Set the last chunk as output
+ span.set_attributes(
+ {
+ SpanAttributes.OUTPUT: _serialize_to_str(last_chunk),
+ },
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+
+
+def trace(
+ name: str,
+) -> Callable:
+ """A generic tracing decorator for synchronous and asynchronous functions.
+
+ Args:
+ name (`str`):
+ The name of the span to be created.
+
+ Returns:
+ `Callable`:
+ Returns a decorator that wraps the given function with
+ OpenTelemetry tracing.
+ """
+
+ def decorator(
+ func: Callable,
+ ) -> Callable:
+ """A decorator that wraps the given function with OpenTelemetry tracing
+
+ Args:
+ func (`Callable`):
+ The function to be traced, which can be sync or async function,
+ and returns an object or a generator.
+
+ Returns:
+ `Callable`:
+ A wrapper function that traces the function call and handles
+ input/output and exceptions.
+ """
+ # Async function
+ if inspect.iscoroutinefunction(func):
+
+ @wraps(func)
+ async def wrapper(
+ *args: Any,
+ **kwargs: Any,
+ ) -> Any:
+ """The wrapper function for tracing the sync function call."""
+ if not _check_tracing_enabled():
+ return await func(*args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ attributes = {
+ SpanAttributes.SPAN_KIND: SpanKind.COMMON,
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(
+ _config.run_id,
+ ),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str({}),
+ }
+
+ with tracer.start_as_current_span(
+ name=name,
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ res = await func(*args, **kwargs)
+
+ # If generator or async generator
+ if isinstance(res, AsyncGenerator):
+ return _trace_async_generator_wrapper(res, span)
+ if isinstance(res, Generator):
+ return _trace_sync_generator_wrapper(res, span)
+
+ # non-generator result
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return wrapper
+
+ # Sync function
+ @wraps(func)
+ def sync_wrapper(
+ *args: Any,
+ **kwargs: Any,
+ ) -> Any:
+ """The wrapper function for tracing the sync function call."""
+ if not _check_tracing_enabled():
+ return func(*args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ attributes = {
+ SpanAttributes.SPAN_KIND: SpanKind.COMMON,
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(
+ _config.run_id,
+ ),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str({}),
+ }
+
+ with tracer.start_as_current_span(
+ name=name,
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ res = func(*args, **kwargs)
+
+ # If generator or async generator
+ if isinstance(res, AsyncGenerator):
+ return _trace_async_generator_wrapper(res, span)
+ if isinstance(res, Generator):
+ return _trace_sync_generator_wrapper(res, span)
+
+ # non-generator result
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return sync_wrapper
+
+ return decorator
+
+
+def trace_toolkit(
+ func: Callable[
+ ...,
+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],
+ ],
+) -> Callable[..., Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]]]:
+ """Trace the toolkit `call_tool_function` method with OpenTelemetry."""
+
+ @wraps(func)
+ async def wrapper(
+ self: Toolkit,
+ tool_call: ToolUseBlock,
+ ) -> AsyncGenerator[ToolResponse, None]:
+ """The wrapper function for tracing the toolkit call_tool_function
+ method."""
+ if not _check_tracing_enabled():
+ return await func(self, tool_call=tool_call)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ # Prepare the attributes for the span
+ attributes = {
+ SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.TOOL),
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "tool_call": tool_call,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str(
+ {
+ **tool_call,
+ },
+ ),
+ }
+
+ with tracer.start_as_current_span(
+ f"{func.__name__}",
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ # Call the toolkit function
+ res = await func(self, tool_call=tool_call)
+
+ # The result must be an AsyncGenerator of ToolResponse objects
+ return _trace_async_generator_wrapper(res, span)
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return wrapper
+
+
+def trace_reply(
+ func: Callable[..., Coroutine[Any, Any, Msg]],
+) -> Callable[..., Coroutine[Any, Any, Msg]]:
+ """Trace the agent reply call with OpenTelemetry.
+
+ Args:
+ func (`Callable[..., Coroutine[Any, Any, Msg]]`):
+ The agent async reply function to be traced.
+
+ Returns:
+ `Callable[..., Coroutine[Any, Any, Msg]]`:
+ A wrapper function that traces the agent reply call and handles
+ input/output and exceptions.
+ """
+
+ @wraps(func)
+ async def wrapper(
+ self: "AgentBase",
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """The wrapper function for tracing the agent reply function call."""
+ if not _check_tracing_enabled():
+ return await func(self, *args, **kwargs)
+
+ from ..agent import AgentBase
+
+ if not isinstance(self, AgentBase):
+ logger.warning(
+ "Skipping tracing for %s as the first argument"
+ "is not an instance of AgentBase, but %s",
+ func.__name__,
+ type(self),
+ )
+ return await func(self, *args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ # Prepare the attributes for the span
+ agent_name = self.name if hasattr(self, "name") else None
+ attributes = {
+ SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.AGENT),
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str(
+ {
+ "id": self.id,
+ "name": agent_name,
+ },
+ ),
+ }
+
+ with tracer.start_as_current_span(
+ f"{self.__class__.__name__}.{func.__name__}",
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ # Call the agent reply function
+ res = await func(self, *args, **kwargs)
+
+ # Set the output attribute
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return wrapper
+
+
+def trace_embedding(
+ func: Callable[..., Coroutine[Any, Any, EmbeddingResponse]],
+) -> Callable[..., Coroutine[Any, Any, EmbeddingResponse]]:
+ """Trace the embedding call with OpenTelemetry."""
+
+ @wraps(func)
+ async def wrapper(
+ self: EmbeddingModelBase,
+ *args: Any,
+ **kwargs: Any,
+ ) -> EmbeddingResponse:
+ """The wrapper function for tracing the embedding call."""
+ if not _check_tracing_enabled():
+ return await func(self, *args, **kwargs)
+
+ if not isinstance(self, EmbeddingModelBase):
+ logger.warning(
+ "Skipping tracing for %s as the first argument"
+ "is not an instance of EmbeddingModelBase, but %s",
+ func.__name__,
+ type(self),
+ )
+ return await func(self, *args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ # Prepare the attributes for the span
+ attributes = {
+ SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.EMBEDDING),
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str(
+ {
+ "model_name": self.model_name,
+ },
+ ),
+ }
+
+ with tracer.start_as_current_span(
+ f"{self.__class__.__name__}.{func.__name__}",
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ # Call the embedding function
+ res = await func(self, *args, **kwargs)
+
+ # Set the output attribute
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return wrapper
+
+
+def trace_format(
+ func: Callable[..., Coroutine[Any, Any, list[dict]]],
+) -> Callable[..., Coroutine[Any, Any, list[dict]]]:
+ """Trace the format function of the formatter with OpenTelemetry.
+
+ Args:
+ func (`Callable[..., Coroutine[Any, Any, list[dict]]]`):
+ The async format function to be traced.
+
+ Returns:
+ `Callable[..., Coroutine[Any, Any, list[dict]]]`:
+ An async wrapper function that traces the format call and handles
+ input/output and exceptions.
+ """
+
+ @wraps(func)
+ async def wrapper(
+ self: "FormatterBase",
+ *args: Any,
+ **kwargs: Any,
+ ) -> list[dict]:
+ """Wrap the formatter __call__ method with OpenTelemetry tracing."""
+ if not _check_tracing_enabled():
+ return await func(self, *args, **kwargs)
+
+ from ..formatter import FormatterBase
+
+ if not isinstance(self, FormatterBase):
+ logger.warning(
+ "Skipping tracing for %s as the first argument"
+ "is not an instance of FormatterBase, but %s",
+ func.__name__,
+ type(self),
+ )
+ return await func(self, *args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ # Prepare the attributes for the span
+ attributes = {
+ SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.FORMATTER),
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str({}),
+ }
+
+ with tracer.start_as_current_span(
+ f"{self.__class__.__name__}.{func.__name__}",
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ # Call the formatter function
+ res = await func(self, *args, **kwargs)
+
+ # Set the output attribute
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return wrapper
+
+
+def trace_llm(
+ func: Callable[
+ ...,
+ Coroutine[
+ Any,
+ Any,
+ ChatResponse | AsyncGenerator[ChatResponse, None],
+ ],
+ ],
+) -> Callable[
+ ...,
+ Coroutine[Any, Any, ChatResponse | AsyncGenerator[ChatResponse, None]],
+]:
+ """Trace the LLM call with OpenTelemetry.
+
+ Args:
+ func (`Callable`):
+ The function to be traced, which should be a coroutine that
+ returns either a `ChatResponse` or an `AsyncGenerator`
+ of `ChatResponse`.
+
+ Returns:
+ `Callable`:
+ A wrapper function that traces the LLM call and handles
+ input/output and exceptions.
+ """
+
+ @wraps(func)
+ async def async_wrapper(
+ self: ChatModelBase,
+ *args: Any,
+ **kwargs: Any,
+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:
+ """The wrapper function for tracing the LLM call."""
+ if not _check_tracing_enabled():
+ return await func(self, *args, **kwargs)
+
+ if not isinstance(self, ChatModelBase):
+ logger.warning(
+ "Skipping tracing for %s as the first argument"
+ "is not an instance of ChatModelBase, but %s",
+ func.__name__,
+ type(self),
+ )
+ return await func(self, *args, **kwargs)
+
+ import opentelemetry
+
+ tracer = opentelemetry.trace.get_tracer(__name__)
+
+ # Prepare the attributes for the span
+ attributes = {
+ SpanAttributes.SPAN_KIND: _serialize_to_str(SpanKind.LLM),
+ SpanAttributes.PROJECT_RUN_ID: _serialize_to_str(_config.run_id),
+ SpanAttributes.INPUT: _serialize_to_str(
+ {
+ "args": args,
+ "kwargs": kwargs,
+ },
+ ),
+ SpanAttributes.META: _serialize_to_str(
+ {
+ "model_name": self.model_name,
+ "stream": self.stream,
+ },
+ ),
+ }
+
+ # Begin the llm call span
+ with tracer.start_as_current_span(
+ f"{self.__class__.__name__}.__call__",
+ attributes=attributes,
+ end_on_exit=False,
+ ) as span:
+ try:
+ # Must be an async calling
+ res = await func(self, *args, **kwargs)
+
+ # If the result is a AsyncGenerator
+ if isinstance(res, AsyncGenerator):
+ return _trace_async_generator_wrapper(res, span)
+
+ # non-generator result
+ span.set_attributes(
+ {SpanAttributes.OUTPUT: _serialize_to_str(res)},
+ )
+ span.set_status(opentelemetry.trace.StatusCode.OK)
+ span.end()
+ return res
+
+ except Exception as e:
+ span.set_status(
+ opentelemetry.trace.StatusCode.ERROR,
+ str(e),
+ )
+ span.record_exception(e)
+ span.end()
+ raise e from None
+
+ return async_wrapper
diff --git a/src/agentscope/tracing/_types.py b/src/agentscope/tracing/_types.py
new file mode 100644
index 000000000..e67e312f1
--- /dev/null
+++ b/src/agentscope/tracing/_types.py
@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""The tracing types class in agentscope."""
+from enum import Enum
+
+from opentelemetry import trace
+
+StatusCode = trace.StatusCode
+
+
+class SpanKind(str, Enum):
+ """The span kind."""
+
+ AGENT = "AGENT"
+ TOOL = "TOOL"
+ LLM = "LLM"
+ EMBEDDING = "EMBEDDING"
+ FORMATTER = "FORMATTER"
+ COMMON = "COMMON"
+
+
+class SpanAttributes:
+ """The span attributes."""
+
+ SPAN_KIND = "span.kind"
+ OUTPUT = "output"
+ INPUT = "input"
+ META = "metadata"
+ PROJECT_RUN_ID = "project.run_id"
diff --git a/src/agentscope/types/__init__.py b/src/agentscope/types/__init__.py
new file mode 100644
index 000000000..a8e92a3f5
--- /dev/null
+++ b/src/agentscope/types/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""The types in agentscope"""
+
+from ._hook import (
+ AgentHookTypes,
+ ReActAgentHookTypes,
+)
+from ._object import Embedding
+from ._json import (
+ JSONPrimitive,
+ JSONSerializableObject,
+)
+from ._tool import ToolFunction
+
+__all__ = [
+ "AgentHookTypes",
+ "ReActAgentHookTypes",
+ "Embedding",
+ "JSONPrimitive",
+ "JSONSerializableObject",
+ "ToolFunction",
+]
diff --git a/src/agentscope/types/_hook.py b/src/agentscope/types/_hook.py
new file mode 100644
index 000000000..638dcb684
--- /dev/null
+++ b/src/agentscope/types/_hook.py
@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""The agent hooks types."""
+from typing import Literal
+
+AgentHookTypes = (
+ str
+ | Literal[
+ "pre_reply",
+ "post_reply",
+ "pre_print",
+ "post_print",
+ "pre_observe",
+ "post_observe",
+ ]
+)
+
+ReActAgentHookTypes = (
+ AgentHookTypes
+ | Literal[
+ "pre_reasoning",
+ "post_reasoning",
+ "pre_acting",
+ "post_acting",
+ ]
+)
diff --git a/src/agentscope/types/_json.py b/src/agentscope/types/_json.py
new file mode 100644
index 000000000..6ab7e230c
--- /dev/null
+++ b/src/agentscope/types/_json.py
@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The JSON related types"""
+
+from typing import Union
+
+JSONPrimitive = Union[
+ str,
+ int,
+ float,
+ bool,
+ None,
+]
+
+JSONSerializableObject = Union[
+ JSONPrimitive,
+ list["JSONSerializableObject"],
+ dict[
+ str,
+ "JSONSerializableObject",
+ ],
+]
diff --git a/src/agentscope/types/_object.py b/src/agentscope/types/_object.py
new file mode 100644
index 000000000..58041c7d6
--- /dev/null
+++ b/src/agentscope/types/_object.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+"""The object types in agentscope."""
+from typing import List
+
+Embedding = List[float]
diff --git a/src/agentscope/types/_tool.py b/src/agentscope/types/_tool.py
new file mode 100644
index 000000000..588eb2ab9
--- /dev/null
+++ b/src/agentscope/types/_tool.py
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""The tool related types"""
+
+from typing import (
+ Callable,
+ Union,
+ Awaitable,
+ AsyncGenerator,
+ Generator,
+ Coroutine,
+ Any,
+ TYPE_CHECKING,
+)
+
+if TYPE_CHECKING:
+ from ..tool import ToolResponse
+else:
+ ToolResponse = "ToolResponse"
+
+ToolFunction = Callable[
+ ...,
+ Union[
+ # sync function
+ ToolResponse,
+ # async function
+ Awaitable[ToolResponse],
+ # sync generator function
+ Generator[ToolResponse, None, None],
+ # async generator function
+ AsyncGenerator[ToolResponse, None],
+ # async function that returns async generator
+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],
+ # async function that returns sync generator
+ Coroutine[Any, Any, Generator[ToolResponse, None, None]],
+ ],
+]
diff --git a/tests/.DS_Store b/tests/.DS_Store
new file mode 100644
index 000000000..28532fb7e
Binary files /dev/null and b/tests/.DS_Store differ
diff --git a/tests/.cache/.DS_Store b/tests/.cache/.DS_Store
new file mode 100644
index 000000000..bab137c26
Binary files /dev/null and b/tests/.cache/.DS_Store differ
diff --git a/tests/embedding_cache_test.py b/tests/embedding_cache_test.py
new file mode 100644
index 000000000..78585498b
--- /dev/null
+++ b/tests/embedding_cache_test.py
@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""The embedding cache tests in agentscope."""
+import os
+import shutil
+import time
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import numpy as np
+
+from agentscope.embedding import FileEmbeddingCache
+
+
+class EmbeddingCacheTest(IsolatedAsyncioTestCase):
+ """The embedding cache tests in agentscope."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test case."""
+ self.embeddings = [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]]
+ self.identifier1 = {
+ "model": "text-embedding-v1",
+ "text": ["This is a test text for embedding cache."],
+ }
+ self.identifier2 = {
+ "model": "text-embedding-v2",
+ "text": ["This is a test text for embedding cache."],
+ }
+ self.identifier3 = {
+ "model": "text-embedding-v3",
+ "text": ["This is a test text for embedding cache."],
+ }
+ self.identifier4 = {
+ "model": "text-embedding-v4",
+ "text": ["This is a test text for embedding cache."],
+ }
+ self.identifier5 = {
+ "model": "text-embedding-v5",
+ "text": ["This is a test text for embedding cache."],
+ }
+ self.ground_truth_filenames = [
+ "56fe1fc64cb2830d0026559607e2ee5b9ae1d4524b256f83fdc2e2c8c23cefb7"
+ ".npy",
+ "fd9deb42e60e87c8358bc262c0ede4f0490385ffad1b85dddec3937ce6a24b03"
+ ".npy",
+ "394cb1f647fa493309abd4b97066649de9d5e5f2bbb03f43b11d56bf7d161497"
+ ".npy",
+ "ce97eac56670400eef1a7c8b7e366107af2129649b02479729bceefe2edd5727"
+ ".npy",
+ "675caa8a352219a9b74ebda4b1930e96d4c292f288f79ccb65e42293dd9de162"
+ ".npy",
+ ]
+
+ self.large_embeddings = np.zeros((600, 600)).tolist()
+
+ self.embedding_cache = FileEmbeddingCache(
+ max_file_number=3,
+ max_cache_size=2,
+ )
+
+ def _get_filenames(self, path_dir: str) -> list[str]:
+ """Get the filenames in the cache directory."""
+ filenames = [
+ (_.name, _.stat().st_mtime)
+ for _ in os.scandir(path_dir)
+ if _.is_file() and _.name.endswith(".npy")
+ ]
+ filenames.sort(key=lambda x: x[1])
+
+ return [_[0] for _ in filenames]
+
+ async def test_embedding_cache(self) -> None:
+ """Test the embedding cache."""
+
+ await self.embedding_cache.store(self.embeddings, self.identifier1)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[:1],
+ )
+
+ time.sleep(1)
+
+ # when overwrite is False
+ await self.embedding_cache.store([[1, 2]], self.identifier1)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[:1],
+ )
+ cached_embedding = await self.embedding_cache.retrieve(
+ self.identifier1,
+ )
+ self.assertListEqual(
+ cached_embedding,
+ self.embeddings,
+ )
+
+ time.sleep(1)
+
+ # when overwrite is True
+ await self.embedding_cache.store(
+ [[1, 2]],
+ self.identifier1,
+ overwrite=True,
+ )
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[:1],
+ )
+ cached_embedding = await self.embedding_cache.retrieve(
+ self.identifier1,
+ )
+ self.assertListEqual(
+ cached_embedding,
+ [[1, 2]],
+ )
+
+ time.sleep(1)
+
+ await self.embedding_cache.store(self.embeddings, self.identifier2)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[:2],
+ )
+
+ time.sleep(1)
+
+ await self.embedding_cache.store(self.embeddings, self.identifier3)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[:3],
+ )
+
+ time.sleep(1)
+
+ await self.embedding_cache.store(self.embeddings, self.identifier4)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[1:4],
+ )
+
+ time.sleep(1)
+
+ await self.embedding_cache.store(self.embeddings, self.identifier5)
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ self.ground_truth_filenames[2:5],
+ )
+
+ time.sleep(1)
+
+ await self.embedding_cache.store(
+ self.large_embeddings,
+ self.identifier1,
+ overwrite=True,
+ )
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ [],
+ )
+
+ await self.embedding_cache.clear()
+ self.assertListEqual(
+ self._get_filenames(self.embedding_cache.cache_dir),
+ [],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Tear down the test case."""
+ if os.path.exists(self.embedding_cache.cache_dir):
+ shutil.rmtree(self.embedding_cache.cache_dir)
diff --git a/tests/formatter_anthropic_test.py b/tests/formatter_anthropic_test.py
new file mode 100644
index 000000000..98643f7e8
--- /dev/null
+++ b/tests/formatter_anthropic_test.py
@@ -0,0 +1,601 @@
+# -*- coding: utf-8 -*-
+"""The Anthropic formatter unittests."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ AnthropicMultiAgentFormatter,
+ AnthropicChatFormatter,
+)
+from agentscope.message import (
+ Msg,
+ ToolUseBlock,
+ ToolResultBlock,
+ TextBlock,
+ ImageBlock,
+ URLSource,
+)
+
+
+class TestAnthropicChatFormatterFormatter(IsolatedAsyncioTestCase):
+ """Unittest for the AnthropicChatFormatter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.image_url = "www.example_image.png"
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_url,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output="The capital of Japan is Tokyo.",
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.msgs_conversation_2 = [
+ Msg(
+ "user",
+ "What is the capital of South Korea?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools_2 = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="2",
+ name="get_capital",
+ input={"country": "South Korea"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output="The capital of South Korea is Seoul.",
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of South Korea is Seoul.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of France?",
+ },
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "www.example_image.png",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "1",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "Japan",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "# Conversation History\nThe content "
+ "between <history></history> tags contains "
+ "your conversation history\n<history>\nuser:"
+ " What is the capital of France?",
+ "type": "text",
+ },
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "www.example_image.png",
+ },
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Japan?"
+ "\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "1",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "Japan",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent_without_first_conversation = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "1",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "Japan",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "# Conversation History\nThe content "
+ "between <history></history> tags contains "
+ "your conversation history\n<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent_2 = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nuser: What"
+ " is the capital of France?",
+ "type": "text",
+ },
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "www.example_image.png",
+ },
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Japan?"
+ "\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "1",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "Japan",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "<history>\nassistant:"
+ " The capital of Japan is Tokyo.\nuser: What"
+ " is the capital of South Korea?\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "2",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "South Korea",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of South Korea is Seoul.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "<history>\nassistant:"
+ " The capital of South Korea is Seoul."
+ "\n</history>",
+ "type": "text",
+ },
+ ],
+ },
+ ]
+
+ async def test_chat_formatter(self) -> None:
+ """Test the chat formatter."""
+ formatter = AnthropicChatFormatter()
+
+ # Full history
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(self.ground_truth_chat, res)
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[
+ 1
+ + len(self.msgs_conversation) : 1
+ + len(self.msgs_conversation)
+ + len(self.msgs_tools)
+ ],
+ )
+
+ # Without tool messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: 1 + len(self.msgs_conversation)],
+ )
+
+ # Empty messages
+ res = await formatter.format([])
+ self.assertListEqual(res, [])
+
+ async def test_multiagent_formater(self) -> None:
+ """Test the multi-agent formatter."""
+ formatter = AnthropicMultiAgentFormatter()
+
+ # system + conversation + tools + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ *self.msgs_tools_2,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent_2)
+
+ # system + conversation + tools + conversation
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ ],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_2[: -len(self.msgs_tools_2)],
+ )
+
+ # system + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[
+ 1 : 1 + len(self.msgs_conversation) + len(self.msgs_tools) - 2
+ ],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation,
+ )
+
+ # Without tool messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[:2],
+ )
+
+ # With only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[:1],
+ )
+
+ # With only conversation messages
+ res = await formatter.format(self.msgs_conversation)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1 : -len(self.msgs_tools)],
+ )
+
+ # With only tool messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation[1:],
+ )
diff --git a/tests/formatter_dashscope_test.py b/tests/formatter_dashscope_test.py
new file mode 100644
index 000000000..779d19eab
--- /dev/null
+++ b/tests/formatter_dashscope_test.py
@@ -0,0 +1,630 @@
+# -*- coding: utf-8 -*-
+"""The dashscope formatter unittests."""
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch, MagicMock
+
+from agentscope.formatter import (
+ DashScopeMultiAgentFormatter,
+ DashScopeChatFormatter,
+)
+from agentscope.message import (
+ Msg,
+ ToolUseBlock,
+ ToolResultBlock,
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ URLSource,
+ Base64Source,
+)
+
+
+class TestDashScopeFormatter(IsolatedAsyncioTestCase):
+ """Unittest for the DashScopeFormatter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.image_path = "./image.png"
+ with open(self.image_path, "wb") as f:
+ f.write(b"fake image content")
+
+ self.mock_audio_path = (
+ "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"
+ )
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of Germany?",
+ ),
+ AudioBlock(
+ type="audio",
+ source=URLSource(
+ type="url",
+ url="https://example.com/audio1.mp3",
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Germany is Berlin.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/wav",
+ data="ZmFrZSBhdWRpbyBjb250ZW50",
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.msgs_conversation_2 = [
+ Msg(
+ "user",
+ "What is the capital of South Korea?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools_2 = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "South Korea"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="2",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of South Korea is Seoul.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/wav",
+ data="ZmFrZSBhdWRpbyBjb250ZW50",
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of South Korea is Seoul.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "What is the capital of France?",
+ },
+ {
+ "image": f"file://{os.path.abspath(self.image_path)}",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "What is the capital of Germany?",
+ },
+ {
+ "audio": "https://example.com/audio1.mp3",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of Germany is Berlin.",
+ },
+ {
+ "role": "user",
+ "content": "What is the capital of Japan?",
+ },
+ {
+ "role": "assistant",
+ "content": [{"text": None}],
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n"
+ "- The returned image can be found at: ./image.png"
+ "\n- The returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of Japan is Tokyo.",
+ },
+ ]
+
+ self.ground_truth_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nuser: What"
+ " is the capital of France?",
+ },
+ {
+ "image": f"file://{os.path.abspath(self.image_path)}",
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Germany?",
+ },
+ {
+ "audio": "https://example.com/audio1.mp3",
+ },
+ {
+ "text": "assistant: The capital of Germany is Berlin."
+ "\nuser: What is the capital of Japan?"
+ "\n</history>",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "text": None,
+ },
+ ],
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned"
+ " image can be found at: ./image.png\n- The"
+ " returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_without_first_conversation = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "text": None,
+ },
+ ],
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned"
+ " image can be found at: ./image.png\n- The"
+ " returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_2 = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "text": "# Conversation History\nThe content between "
+ "<history></history> tags contains your conversation "
+ "history\n<history>\nuser: What is the capital of "
+ "France?",
+ },
+ {
+ "image": f"file://{os.path.abspath(self.image_path)}",
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Germany?",
+ },
+ {
+ "audio": "https://example.com/audio1.mp3",
+ },
+ {
+ "text": "assistant: The capital of Germany is Berlin."
+ "\nuser: What is the capital of Japan?"
+ "\n</history>",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "text": None,
+ },
+ ],
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned"
+ " image can be found at: ./image.png\n- The returned audio can"
+ f" be found at: {self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of Japan "
+ "is Tokyo.\nuser: What is the capital of South Korea?"
+ "\n</history>",
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "text": None,
+ },
+ ],
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "South Korea"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "2",
+ "content": "- The capital of South Korea is Seoul.\n- The "
+ "returned image can be found at: ./image.png\n- The returned"
+ " audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of South"
+ " Korea is Seoul.\n</history>",
+ },
+ ]
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_chat_formatter(
+ self,
+ mock_save_base64_data: MagicMock,
+ ) -> None:
+ """Test the chat formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+
+ formatter = DashScopeChatFormatter()
+
+ # Full history
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(self.ground_truth_chat, res)
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[-len(self.msgs_tools) :],
+ )
+
+ # Without tool messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: -len(self.msgs_tools)],
+ )
+
+ # Empty messages
+ res = await formatter.format([])
+ self.assertListEqual(res, [])
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_multiagent_formater(
+ self,
+ mock_save_base64_data: MagicMock,
+ ) -> None:
+ """Test the multi-agent formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+
+ formatter = DashScopeMultiAgentFormatter()
+
+ # system + conversation + tools + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ *self.msgs_tools_2,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent_2)
+
+ # system + conversation + tools + conversation
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ ],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_2[: -len(self.msgs_tools_2)],
+ )
+
+ # system + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation,
+ )
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[:2],
+ )
+
+ # With only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[:1],
+ )
+
+ # With only conversation messages
+ res = await formatter.format(self.msgs_conversation)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1 : -len(self.msgs_tools)],
+ )
+
+ # Without only tool messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation[1:],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Clean up the test environment."""
+ if os.path.exists(self.image_path):
+ os.remove(self.image_path)
diff --git a/tests/formatter_deepseek_test.py b/tests/formatter_deepseek_test.py
new file mode 100644
index 000000000..a8b769012
--- /dev/null
+++ b/tests/formatter_deepseek_test.py
@@ -0,0 +1,467 @@
+# -*- coding: utf-8 -*-
+"""The DeepSeek formatter unittests."""
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.formatter import (
+ DeepSeekChatFormatter,
+ DeepSeekMultiAgentFormatter,
+)
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+
+
+class TestDeepSeekFormatter(IsolatedAsyncioTestCase):
+ """Unittest for the DeepSeek formatter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.msgs_conversation_2 = [
+ Msg(
+ "user",
+ "What is the capital of South Korea?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools_2 = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="2",
+ name="get_capital",
+ input={"country": "South Korea"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of South Korea is Seoul.",
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": "What is the capital of France?",
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ },
+ {
+ "role": "user",
+ "content": "What is the capital of Japan?",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of Japan is Tokyo.",
+ },
+ ]
+
+ self.ground_truth_multiagent = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nuser: What is"
+ " the capital of France?\nassistant: The capital"
+ " of France is Paris.\nuser: What is the capital"
+ " of Japan?\n</history>",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_without_first_conversation = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nassistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_2 = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between "
+ "<history></history> tags contains your conversation history"
+ "\n<history>\nuser: What is the capital of France?"
+ "\nassistant: The capital of France is Paris."
+ "\nuser: What is the capital of Japan?\n</history>",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of Japan is Tokyo.",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of Japan is "
+ "Tokyo.\nuser: What is the capital of South Korea?"
+ "\n</history>",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "2",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "South Korea"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of South Korea is Seoul.",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of Japan is"
+ " Tokyo.\n</history>",
+ },
+ ]
+
+ async def test_chat_formatter(self) -> None:
+ """Test the DeepSeek chat formatter."""
+ formatter = DeepSeekChatFormatter()
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat,
+ )
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[-len(self.msgs_tools) :],
+ )
+
+ # Without tools messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: -len(self.msgs_tools)],
+ )
+
+ async def test_multi_agent_formatter(
+ self,
+ ) -> None:
+ """Test the DeepSeek multi-agent formatter."""
+
+ formatter = DeepSeekMultiAgentFormatter()
+
+ # system + conversation + tools + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ *self.msgs_tools_2,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent_2)
+
+ # system + conversation + tools + conversation
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ ],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_2[: -len(self.msgs_tools_2)],
+ )
+
+ # system + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent,
+ )
+
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1:],
+ )
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation,
+ )
+
+ # Only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(res, self.ground_truth_multiagent[:1])
+
+ # Only conversation messages
+ res = await formatter.format(self.msgs_conversation)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1 : -len(self.msgs_tools)],
+ )
+
+ # Only tools messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation[1:],
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/formatter_gemini_test.py b/tests/formatter_gemini_test.py
new file mode 100644
index 000000000..bdce9a4c6
--- /dev/null
+++ b/tests/formatter_gemini_test.py
@@ -0,0 +1,715 @@
+# -*- coding: utf-8 -*-
+"""The gemini formatter unittests."""
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch, MagicMock
+
+from agentscope.formatter import GeminiChatFormatter, GeminiMultiAgentFormatter
+from agentscope.message import (
+ Msg,
+ URLSource,
+ TextBlock,
+ AudioBlock,
+ ImageBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+ Base64Source,
+)
+
+
+class TestGeminiFormatter(IsolatedAsyncioTestCase):
+ """Unittest for the Gemini formatter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.image_path = "./image.png"
+ with open(self.image_path, "wb") as f:
+ f.write(b"fake image content")
+
+ self.mock_audio_path = (
+ "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"
+ )
+
+ self.audio_path = "./audio.mp3"
+ with open(self.audio_path, "wb") as f:
+ f.write(b"fake audio content")
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of Germany?",
+ ),
+ AudioBlock(
+ type="audio",
+ source=URLSource(
+ type="url",
+ url=self.audio_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Germany is Berlin.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/wav",
+ data="ZmFrZSBhdWRpbyBjb250ZW50",
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.msgs_conversation_2 = [
+ Msg(
+ "user",
+ "What is the capital of South Korea?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools_2 = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "South Korea"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of South Korea is Seoul.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/wav",
+ data="ZmFrZSBhdWRpbyBjb250ZW50",
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of South Korea is Seoul.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "What is the capital of France?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBpbWFnZSBjb250ZW50",
+ "mime_type": "image/png",
+ },
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "What is the capital of Germany?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBhdWRpbyBjb250ZW50",
+ "mime_type": "image/mp3",
+ },
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "1",
+ "name": "get_capital",
+ "args": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "1",
+ "name": "get_capital",
+ "response": {
+ "output": "- The capital of Japan is Tokyo.\n"
+ "- The returned image can be found"
+ " at: ./image.png\n- The returned "
+ "audio can be found at: "
+ f"{self.mock_audio_path}",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+ self.ground_truth_multiagent = [
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>user: What"
+ " is the capital of France?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBpbWFnZSBjb250ZW50",
+ "mime_type": "image/png",
+ },
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Germany?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBhdWRpbyBjb250ZW50",
+ "mime_type": "image/mp3",
+ },
+ },
+ {
+ "text": "assistant: The capital of Germany is Berlin."
+ "\nuser: What is the capital of Japan?"
+ "\n</history>",
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "1",
+ "name": "get_capital",
+ "args": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "1",
+ "name": "get_capital",
+ "response": {
+ "output": "- The capital of Japan is Tokyo."
+ "\n- The returned image can be found"
+ " at: ./image.png\n- The returned"
+ " audio can be found at: "
+ f"{self.mock_audio_path}",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "<history>assistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent_without_first_conversation = [
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "1",
+ "name": "get_capital",
+ "args": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "1",
+ "name": "get_capital",
+ "response": {
+ "output": "- The capital of Japan is Tokyo."
+ "\n- The returned image can be found"
+ " at: ./image.png\n- The returned"
+ " audio can be found at: "
+ f"{self.mock_audio_path}",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>assistant:"
+ " The capital of Japan is Tokyo.\n</history>",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent_2 = [
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "# Conversation History\nThe content between "
+ "<history></history> tags contains your "
+ "conversation history\n<history>user: What is "
+ "the capital of France?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBpbWFnZSBjb250ZW50",
+ "mime_type": "image/png",
+ },
+ },
+ {
+ "text": "assistant: The capital of France is Paris."
+ "\nuser: What is the capital of Germany?",
+ },
+ {
+ "inline_data": {
+ "data": "ZmFrZSBhdWRpbyBjb250ZW50",
+ "mime_type": "image/mp3",
+ },
+ },
+ {
+ "text": "assistant: The capital of Germany is Berlin."
+ "\nuser: What is the capital of Japan?\n</history>",
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "1",
+ "name": "get_capital",
+ "args": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "1",
+ "name": "get_capital",
+ "response": {
+ "output": "- The capital of Japan is Tokyo."
+ "\n- The returned image can be found "
+ "at: ./image.png\n- The returned audio"
+ " can be found at: "
+ f"{self.mock_audio_path}",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "<history>assistant: "
+ "The capital of Japan is Tokyo.\nuser: What "
+ "is the capital of South Korea?\n</history>",
+ },
+ ],
+ },
+ {
+ "role": "model",
+ "parts": [
+ {
+ "function_call": {
+ "id": "1",
+ "name": "get_capital",
+ "args": {
+ "country": "South Korea",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "function_response": {
+ "id": "1",
+ "name": "get_capital",
+ "response": {
+ "output": "- The capital of South Korea is "
+ "Seoul.\n- The returned image can "
+ "be found at: ./image.png\n- The "
+ "returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "parts": [
+ {
+ "text": "<history>assistant: "
+ "The capital of South Korea is Seoul."
+ "\n</history>",
+ },
+ ],
+ },
+ ]
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_chat_formatter(
+ self,
+ mock_save_base64_data: MagicMock,
+ ) -> None:
+ """Test the gemini chat formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+ formatter = GeminiChatFormatter()
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat,
+ )
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[-len(self.msgs_tools) :],
+ )
+
+ # Without tools messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: -len(self.msgs_tools)],
+ )
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_multi_agent_formatter(
+ self,
+ mock_save_base64_data: MagicMock,
+ ) -> None:
+ """Test the gemini multi-agent formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+
+ formatter = GeminiMultiAgentFormatter()
+
+ # system + conversation + tools + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ *self.msgs_tools_2,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent_2)
+
+ # system + conversation + tools + conversation
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ ],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_2[: -len(self.msgs_tools_2)],
+ )
+
+ # system + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent,
+ )
+
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1:],
+ )
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation,
+ )
+
+ # Only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(res, self.ground_truth_multiagent[:1])
+
+ # Only conversation messages
+ res = await formatter.format(self.msgs_conversation)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1 : -len(self.msgs_tools)],
+ )
+
+ # Only tools messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation[1:],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Clean up the test environment."""
+ if os.path.exists(self.image_path):
+ os.remove(self.image_path)
+ if os.path.exists(self.audio_path):
+ os.remove(self.audio_path)
diff --git a/tests/formatter_ollama_test.py b/tests/formatter_ollama_test.py
new file mode 100644
index 000000000..8d4fc40e5
--- /dev/null
+++ b/tests/formatter_ollama_test.py
@@ -0,0 +1,506 @@
+# -*- coding: utf-8 -*-
+"""The Ollama formatter unittests."""
+import os
+import unittest
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.formatter import OllamaChatFormatter, OllamaMultiAgentFormatter
+from agentscope.message import (
+ Msg,
+ URLSource,
+ TextBlock,
+ ImageBlock,
+ ToolUseBlock,
+ ToolResultBlock,
+)
+
+
+class TestOllamaFormatter(IsolatedAsyncioTestCase):
+ """Unittest for the Ollama formatter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.image_path = "./image.png"
+ with open(self.image_path, "wb") as f:
+ f.write(b"fake image content")
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.msgs_conversation_2 = [
+ Msg(
+ "user",
+ "What is the capital of South Korea?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools_2 = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="2",
+ name="get_capital",
+ input={"country": "South Korea"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of South Korea is Seoul.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of South Korea is Seoul.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": "What is the capital of France?",
+ "images": [
+ "ZmFrZSBpbWFnZSBjb250ZW50",
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ },
+ {
+ "role": "user",
+ "content": "What is the capital of Japan?",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned "
+ "image can be found at: ./image.png",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "content": "The capital of Japan is Tokyo.",
+ },
+ ]
+
+ self.ground_truth_multiagent = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nuser: What is"
+ " the capital of France?\n\nassistant: The capital"
+ " of France is Paris.\nuser: What is the capital"
+ " of Japan?\n</history>",
+ "images": [
+ "ZmFrZSBpbWFnZSBjb250ZW50",
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned"
+ " image can be found at: ./image.png",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The"
+ " capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_without_first_conversation = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned"
+ " image can be found at: ./image.png",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between"
+ " <history></history> tags contains your"
+ " conversation history\n<history>\nassistant: The"
+ " capital of Japan is Tokyo.\n</history>",
+ },
+ ]
+
+ self.ground_truth_multiagent_2 = [
+ {
+ "role": "system",
+ "content": "You're a helpful assistant.",
+ },
+ {
+ "role": "user",
+ "content": "# Conversation History\nThe content between "
+ "<history></history> tags contains your "
+ "conversation history\n<history>\nuser: What is "
+ "the capital of France?\n\nassistant: The capital "
+ "of France is Paris.\nuser: What is the capital of "
+ "Japan?\n</history>",
+ "images": [
+ "ZmFrZSBpbWFnZSBjb250ZW50",
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": {
+ "country": "Japan",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n- The returned "
+ "image can be found at: ./image.png",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of Japan is "
+ "Tokyo.\nuser: What is the capital of South Korea?"
+ "\n</history>",
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "2",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": {
+ "country": "South Korea",
+ },
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of South Korea is Seoul.\n- The "
+ "returned image can be found at: ./image.png",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": "<history>\nassistant: The capital of South Korea"
+ " is Seoul.\n</history>",
+ },
+ ]
+
+ async def test_chat_formatter(self) -> None:
+ """Test the Ollama chat formatter."""
+ formatter = OllamaChatFormatter()
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat,
+ )
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[-len(self.msgs_tools) :],
+ )
+
+ # Without tools messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: -len(self.msgs_tools)],
+ )
+
+ async def test_multi_agent_formatter(
+ self,
+ ) -> None:
+ """Test the Ollama multi-agent formatter."""
+
+ formatter = OllamaMultiAgentFormatter()
+
+ # system + conversation + tools + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ *self.msgs_tools_2,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent_2)
+
+ # system + conversation + tools + conversation
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ *self.msgs_conversation_2,
+ ],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_2[: -len(self.msgs_tools_2)],
+ )
+
+ # system + conversation + tools
+ res = await formatter.format(
+ [
+ *self.msgs_system,
+ *self.msgs_conversation,
+ *self.msgs_tools,
+ ],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent,
+ )
+
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1:],
+ )
+
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation,
+ )
+
+ # Only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(res, self.ground_truth_multiagent[:1])
+
+ # Only conversation messages
+ res = await formatter.format(self.msgs_conversation)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1 : -len(self.msgs_tools)],
+ )
+
+ # Only tools messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_first_conversation[1:],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Clean up the test environment."""
+ if os.path.exists(self.image_path):
+ os.remove(self.image_path)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/formatter_openai_test.py b/tests/formatter_openai_test.py
new file mode 100644
index 000000000..ac779cc1b
--- /dev/null
+++ b/tests/formatter_openai_test.py
@@ -0,0 +1,486 @@
+# -*- coding: utf-8 -*-
+"""The OpenAI formatter unittests."""
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch, MagicMock
+
+from agentscope.formatter import OpenAIChatFormatter
+from agentscope.formatter._openai_formatter import OpenAIMultiAgentFormatter
+from agentscope.message import (
+ Msg,
+ TextBlock,
+ ImageBlock,
+ AudioBlock,
+ URLSource,
+ ToolResultBlock,
+ ToolUseBlock,
+ Base64Source,
+)
+
+
+class TestOpenAIFormatter(IsolatedAsyncioTestCase):
+ """OpenAI formatter unittests."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.image_path = os.path.abspath("./image.png")
+ with open(self.image_path, "wb") as f:
+ f.write(b"fake image content")
+
+ self.mock_audio_path = (
+ "/var/folders/gf/krg8x_ws409cpw_46b2s6rjc0000gn/T/tmpfymnv2w9.wav"
+ )
+
+ self.audio_path = os.path.abspath("./audio.wav")
+ with open(self.audio_path, "wb") as f:
+ f.write(b"fake audio content")
+
+ self.msgs_system = [
+ Msg(
+ "system",
+ "You're a helpful assistant.",
+ "system",
+ ),
+ ]
+ self.msgs_conversation = [
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of France?",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of France is Paris.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ [
+ TextBlock(
+ type="text",
+ text="What is the capital of Germany?",
+ ),
+ AudioBlock(
+ type="audio",
+ source=URLSource(
+ type="url",
+ url=self.audio_path,
+ ),
+ ),
+ ],
+ "user",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Germany is Berlin.",
+ "assistant",
+ ),
+ Msg(
+ "user",
+ "What is the capital of Japan?",
+ "user",
+ ),
+ ]
+
+ self.msgs_tools = [
+ Msg(
+ "assistant",
+ [
+ ToolUseBlock(
+ type="tool_use",
+ id="1",
+ name="get_capital",
+ input={"country": "Japan"},
+ ),
+ ],
+ "assistant",
+ ),
+ Msg(
+ "system",
+ [
+ ToolResultBlock(
+ type="tool_result",
+ id="1",
+ name="get_capital",
+ output=[
+ TextBlock(
+ type="text",
+ text="The capital of Japan is Tokyo.",
+ ),
+ ImageBlock(
+ type="image",
+ source=URLSource(
+ type="url",
+ url=self.image_path,
+ ),
+ ),
+ AudioBlock(
+ type="audio",
+ source=Base64Source(
+ type="base64",
+ media_type="audio/wav",
+ data="ZmFrZSBhdWRpbyBjb250ZW50",
+ ),
+ ),
+ ],
+ ),
+ ],
+ "system",
+ ),
+ Msg(
+ "assistant",
+ "The capital of Japan is Tokyo.",
+ "assistant",
+ ),
+ ]
+
+ self.ground_truth_chat = [
+ {
+ "role": "system",
+ "name": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of France?",
+ },
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": "data:image/png;"
+ "base64,ZmFrZSBpbWFnZSBjb250ZW50",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Germany?",
+ },
+ {
+ "type": "input_audio",
+ "input_audio": {
+ "data": "ZmFrZSBhdWRpbyBjb250ZW50",
+ "format": "wav",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n"
+ "- The returned image can be found at: "
+ f"{self.image_path}\n"
+ "- The returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "# Conversation History\n"
+ "The content between <history></history> tags contains"
+ " your conversation history\n"
+ "<history>\n"
+ "user: What is the capital of France?\n"
+ "assistant: The capital of France is Paris.\n"
+ "user: What is the capital of Germany?\n"
+ "assistant: The capital of Germany is Berlin.\n"
+ "user: What is the capital of Japan?\n"
+ "</history>",
+ },
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": "data:image/png;base64,"
+ "ZmFrZSBpbWFnZSBjb250ZW50",
+ },
+ },
+ {
+ "type": "input_audio",
+ "input_audio": {
+ "data": "ZmFrZSBhdWRpbyBjb250ZW50",
+ "format": "wav",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n"
+ "- The returned image can be found at: "
+ f"{self.image_path}\n"
+ "- The returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>",
+ },
+ ],
+ },
+ ]
+
+ self.ground_truth_multiagent_without_conversation = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "- The capital of Japan is Tokyo.\n"
+ "- The returned image can be found at: "
+ f"{self.image_path}\n"
+ "- The returned audio can be found at: "
+ f"{self.mock_audio_path}",
+ "name": "get_capital",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "# Conversation History\n"
+ "The content between <history></history> tags contains"
+ " your conversation history\n<history>\n"
+ "assistant: The capital of Japan is Tokyo.\n"
+ "</history>",
+ },
+ ],
+ },
+ ]
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_formatter(self, mock_save_base64_data: MagicMock) -> None:
+ """Test the chat formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+
+ formatter = OpenAIChatFormatter()
+
+ # Full history
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat,
+ )
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[:1]
+ + self.ground_truth_chat[-len(self.msgs_tools) :],
+ )
+
+ # Without tools messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_chat[: -len(self.msgs_tools)],
+ )
+
+ @patch("agentscope.formatter._formatter_base._save_base64_data")
+ async def test_multiagent_formatter(
+ self,
+ mock_save_base64_data: MagicMock,
+ ) -> None:
+ """Test the OpenAI multi-agent formatter."""
+ mock_save_base64_data.return_value = self.mock_audio_path
+
+ formatter = OpenAIMultiAgentFormatter()
+
+ # Full test: system + conversation + tools
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],
+ )
+
+ self.assertListEqual(res, self.ground_truth_multiagent)
+
+ # Without system message
+ res = await formatter.format(
+ [*self.msgs_conversation, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent[1:],
+ )
+
+ # Without conversation messages
+ res = await formatter.format(
+ [*self.msgs_system, *self.msgs_tools],
+ )
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_conversation,
+ )
+
+ # Only system message
+ res = await formatter.format(self.msgs_system)
+ self.assertListEqual(res, self.ground_truth_multiagent[:1])
+
+ # Only tools messages
+ res = await formatter.format(self.msgs_tools)
+ self.assertListEqual(
+ res,
+ self.ground_truth_multiagent_without_conversation[1:],
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Clean up the test environment."""
+ if os.path.exists(self.image_path):
+ os.remove(self.image_path)
+ if os.path.exists(self.audio_path):
+ os.remove(self.audio_path)
diff --git a/tests/hook_test.py b/tests/hook_test.py
new file mode 100644
index 000000000..90d148f2f
--- /dev/null
+++ b/tests/hook_test.py
@@ -0,0 +1,788 @@
+# -*- coding: utf-8 -*-
+"""Hook related tests in agentscope."""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.agent import AgentBase
+from agentscope.message import Msg, TextBlock
+
+
+class MyAgent(AgentBase):
+ """Test agent class for testing hooks."""
+
+ def __init__(self) -> None:
+ """Initialize the test agent."""
+ super().__init__()
+ self.records: list[str] = []
+ self.memory: list[Msg] = []
+
+ async def reply(self, msg: Msg) -> Msg:
+ """Reply to the message."""
+ await self.print(msg)
+ if isinstance(msg.content, list):
+ msg.content.append(
+ TextBlock(
+ type="text",
+ text="mark",
+ ),
+ )
+ return msg
+
+ async def observe(self, msg: Msg) -> None:
+ """Observe the message without generating a reply."""
+ self.memory.append(msg)
+
+ async def handle_interrupt(self, *args: Any, **kwargs: Any) -> Msg:
+ """Handle the interrupt signal."""
+ # This is a placeholder for handling interrupts.
+ return Msg("test", "Interrupt handled", "assistant")
+
+
+class ChildAgent(MyAgent):
+ """Child agent for testing hook isolation."""
+
+
+class GrandChildAgent(ChildAgent):
+ """Grandchild agent for testing deeper inheritance."""
+
+
+class AgentA(MyAgent):
+ """First parent class."""
+
+
+class AgentB(MyAgent):
+ """Second parent class."""
+
+
+class AgentC(AgentA, AgentB):
+ """Multiple inheritance class."""
+
+
+async def async_pre_func_w_modifying(
+ self: MyAgent,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """A pre-hook function that modifies the keyword arguments."""
+
+ if isinstance(kwargs.get("msg"), Msg):
+ kwargs["msg"].content.append(
+ TextBlock(
+ type="text",
+ text="pre_1",
+ ),
+ )
+ self.records.append("pre_1")
+ return kwargs
+
+
+async def async_pre_func_wo_modifying(
+ self: MyAgent,
+ kwargs: dict[str, Any],
+) -> None:
+ """A pre-hook function that does not modify the keyword arguments."""
+ if isinstance(kwargs.get("msg"), Msg):
+ kwargs["msg"].content.append(
+ TextBlock(
+ type="text",
+ text="pre_2",
+ ),
+ )
+ self.records.append("pre_2")
+
+
+def sync_pre_func_w_modifying(
+ self: MyAgent,
+ kwargs: dict[str, Any],
+) -> dict[str, Any]:
+ """A synchronous pre-hook function that does not modify the keyword
+ arguments."""
+ if isinstance(kwargs.get("msg"), Msg):
+ kwargs["msg"].content.append(
+ TextBlock(
+ type="text",
+ text="pre_3",
+ ),
+ )
+ self.records.append("pre_3")
+ return kwargs
+
+
+def sync_pre_func_wo_modifying(
+ self: MyAgent,
+ kwargs: dict[str, Any],
+) -> None:
+ """A synchronous pre-hook function that does not modify the keyword
+ arguments."""
+ if isinstance(kwargs.get("msg"), Msg):
+ kwargs["msg"].content.append(
+ TextBlock(
+ type="text",
+ text="pre_4",
+ ),
+ )
+ self.records.append("pre_4")
+
+
+async def async_post_func_w_modifying(
+ self: MyAgent,
+ _kwargs: dict[str, Any],
+ output: Any,
+) -> Any:
+ """A post-hook function that modifies the output."""
+ if isinstance(output, Msg):
+ output.content.append(
+ TextBlock(
+ type="text",
+ text="post_1",
+ ),
+ )
+ self.records.append("post_1")
+ return output
+
+
+async def async_post_func_wo_modifying(
+ self: MyAgent,
+ _kwargs: dict[str, Any],
+ output: Any,
+) -> None:
+ """A post-hook function that does not modify the output."""
+ if isinstance(output, Msg):
+ output.content.append(
+ TextBlock(
+ type="text",
+ text="post_2",
+ ),
+ )
+ self.records.append("post_2")
+
+
+def sync_post_func_w_modifying(
+ self: MyAgent,
+ _kwargs: dict[str, Any],
+ output: Any,
+) -> Any:
+ """A synchronous post-hook function that modifies the output."""
+ if isinstance(output, Msg):
+ output.content.append(
+ TextBlock(
+ type="text",
+ text="post_3",
+ ),
+ )
+ self.records.append("post_3")
+ return output
+
+
+def sync_post_func_wo_modifying(
+ self: MyAgent,
+ _kwargs: dict[str, Any],
+ output: Any,
+) -> None:
+ """A synchronous post-hook function that does not modify the output."""
+ if isinstance(output, Msg):
+ output.content.append(
+ TextBlock(
+ type="text",
+ text="post_4",
+ ),
+ )
+ self.records.append("post_4")
+
+
+class HookTest(IsolatedAsyncioTestCase):
+ """The hook test class."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.agent = MyAgent()
+
+ @property
+ def msg(self) -> Msg:
+ """Get the test message."""
+ return Msg(
+ "user",
+ [TextBlock(type="text", text="0")],
+ "user",
+ )
+
+ async def test_reply_hooks(self) -> None:
+ """Test the reply hooks."""
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+
+ # Add pre 1
+ self.agent.register_instance_hook(
+ "pre_reply",
+ "pre_1",
+ async_pre_func_w_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ ["pre_1"],
+ )
+
+ # Add pre 2
+ self.agent.register_instance_hook(
+ "pre_reply",
+ "pre_2",
+ async_pre_func_wo_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ ["pre_1", "pre_1", "pre_2"],
+ )
+
+ # Add sync pre 3
+ self.agent.register_instance_hook(
+ "pre_reply",
+ "pre_3",
+ sync_pre_func_w_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ ],
+ )
+
+ # Add sync pre 4
+ self.agent.register_instance_hook(
+ "pre_reply",
+ "pre_4",
+ sync_pre_func_wo_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ ],
+ )
+
+ # Add post 1
+ self.agent.register_instance_hook(
+ "post_reply",
+ "post_1",
+ async_post_func_w_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ TextBlock(type="text", text="post_1"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ ],
+ )
+
+ # Add post 2
+ self.agent.register_instance_hook(
+ "post_reply",
+ "post_2",
+ async_post_func_wo_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ TextBlock(type="text", text="post_1"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ ],
+ )
+
+ # Add sync post 3
+ self.agent.register_instance_hook(
+ "post_reply",
+ "post_3",
+ sync_post_func_w_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ TextBlock(type="text", text="post_1"),
+ TextBlock(type="text", text="post_3"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ "post_3",
+ ],
+ )
+
+ # Add sync post 4
+ self.agent.register_instance_hook(
+ "post_reply",
+ "post_4",
+ sync_post_func_wo_modifying,
+ )
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ TextBlock(type="text", text="pre_3"),
+ TextBlock(type="text", text="mark"),
+ TextBlock(type="text", text="post_1"),
+ TextBlock(type="text", text="post_3"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_1",
+ "pre_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ "post_3",
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ "post_1",
+ "post_2",
+ "post_3",
+ "post_4",
+ ],
+ )
+
+ self.agent.clear_instance_hooks()
+ self.agent.records.clear()
+ res = await self.agent(self.msg)
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="mark"),
+ ],
+ )
+ self.assertListEqual(
+ self.agent.records,
+ [],
+ )
+
+ async def test_print_hooks(self) -> None:
+ """Test the print hooks."""
+ self.agent.register_instance_hook(
+ "pre_print",
+ "pre_1",
+ async_pre_func_w_modifying,
+ )
+ self.agent.register_instance_hook(
+ "pre_print",
+ "pre_2",
+ async_pre_func_wo_modifying,
+ )
+ self.agent.register_instance_hook(
+ "pre_print",
+ "pre_3",
+ sync_pre_func_w_modifying,
+ )
+ self.agent.register_instance_hook(
+ "pre_print",
+ "pre_4",
+ sync_pre_func_wo_modifying,
+ )
+ await self.agent(self.msg)
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_2",
+ "pre_3",
+ "pre_4",
+ ],
+ )
+
+ async def test_observe_hooks(self) -> None:
+ """Test the observe hooks."""
+ self.agent.register_instance_hook(
+ "pre_observe",
+ "pre_1",
+ async_pre_func_w_modifying,
+ )
+ self.agent.register_instance_hook(
+ "pre_observe",
+ "pre_2",
+ async_pre_func_wo_modifying,
+ )
+ await self.agent.observe(self.msg)
+ self.assertEqual(len(self.agent.memory), 1)
+ self.assertListEqual(
+ self.agent.records,
+ [
+ "pre_1",
+ "pre_2",
+ ],
+ )
+ self.assertListEqual(
+ self.agent.memory[0].content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ ],
+ )
+
+ self.agent.register_instance_hook(
+ "post_observe",
+ "post_1",
+ async_post_func_w_modifying,
+ )
+ self.agent.register_instance_hook(
+ "post_observe",
+ "post_2",
+ async_post_func_wo_modifying,
+ )
+ await self.agent.observe(self.msg)
+ self.assertEqual(
+ len(self.agent.memory),
+ 2,
+ )
+ self.assertListEqual(
+ self.agent.records,
+ ["pre_1", "pre_2", "pre_1", "pre_2", "post_1", "post_2"],
+ )
+ self.assertListEqual(
+ self.agent.memory[1].content,
+ [
+ TextBlock(type="text", text="0"),
+ TextBlock(type="text", text="pre_1"),
+ ],
+ )
+
+ # TODO: The studio requires the hook inherited from AgentBase, we will
+ # solving this problem later.
+ # async def test_instance_and_class_hooks(self) -> None:
+ # """Test instance and class hooks."""
+ # AgentBase.register_class_hook(
+ # "pre_reply",
+ # "pre_3",
+ # sync_pre_func_w_modifying,
+ # )
+ # self.agent.register_instance_hook(
+ # "pre_reply",
+ # "pre_1",
+ # async_pre_func_w_modifying,
+ # )
+ # res = await self.agent(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_1"),
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ #
+ # # remove hook
+ # AgentBase.remove_class_hook("pre_reply", "pre_3")
+ # res = await self.agent(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_1"),
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ #
+ # async def test_class_hook_inheritance_isolation(self) -> None:
+ # """Test that class hooks are isolated between parent and child
+ # classes."""
+ #
+ # # Register different hooks on different classes
+ # MyAgent.register_class_hook(
+ # "pre_reply",
+ # "parent_hook",
+ # sync_pre_func_w_modifying, # adds "pre_3" to content
+ # )
+ #
+ # ChildAgent.register_class_hook(
+ # "pre_reply",
+ # "child_hook",
+ # async_pre_func_w_modifying, # adds "pre_1" to content
+ # )
+ #
+ # GrandChildAgent.register_class_hook(
+ # "pre_reply",
+ # "grandchild_hook",
+ # sync_pre_func_wo_modifying, # adds "pre_4" to content
+ # )
+ #
+ # # Create instances of each class
+ # parent_agent = MyAgent()
+ # child_agent = ChildAgent()
+ # grandchild_agent = GrandChildAgent()
+ #
+ # # Test parent agent - should only execute parent hook
+ # res = await parent_agent(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_3"), # only parent hook
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ # self.assertListEqual(parent_agent.records, ["pre_3"])
+ #
+ # # Test child agent - should only execute child hook
+ # res = await child_agent(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_1"), # only child hook
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ # self.assertListEqual(child_agent.records, ["pre_1"])
+ #
+ # # Test grandchild agent - should only execute grandchild hook
+ # res = await grandchild_agent(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="mark"),
+ # # pre_4 doesn't modify content
+ # ],
+ # )
+ # self.assertListEqual(grandchild_agent.records, ["pre_4"])
+ #
+ # async def test_multiple_inheritance_hook_isolation(self) -> None:
+ # """Test hook isolation in multiple inheritance scenarios."""
+ #
+ # # Register hooks on different classes
+ # AgentA.register_class_hook(
+ # "pre_reply",
+ # "hook_a",
+ # sync_pre_func_w_modifying, # adds "pre_3"
+ # )
+ #
+ # AgentB.register_class_hook(
+ # "pre_reply",
+ # "hook_b",
+ # async_pre_func_w_modifying, # adds "pre_1"
+ # )
+ #
+ # AgentC.register_class_hook(
+ # "pre_reply",
+ # "hook_c",
+ # sync_pre_func_wo_modifying, # adds "pre_4" (no content change)
+ # ) # Create instances
+ # agent_a = AgentA()
+ # agent_b = AgentB()
+ # agent_c = AgentC()
+ #
+ # # Test AgentA - should only execute hook_a
+ # res = await agent_a(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_3"),
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ # self.assertListEqual(agent_a.records, ["pre_3"])
+ #
+ # # Test AgentB - should only execute hook_b
+ # res = await agent_b(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="pre_1"),
+ # TextBlock(type="text", text="mark"),
+ # ],
+ # )
+ # self.assertListEqual(agent_b.records, ["pre_1"])
+ #
+ # # Test AgentC - should only execute hook_c
+ # res = await agent_c(self.msg)
+ # self.assertListEqual(
+ # res.content,
+ # [
+ # TextBlock(type="text", text="0"),
+ # TextBlock(type="text", text="mark"),
+ # # pre_4 doesn't modify content
+ # ],
+ # )
+ # self.assertListEqual(agent_c.records, ["pre_4"])
+
+ async def asyncTearDown(self) -> None:
+ """Tear down the test environment."""
+ self.agent.clear_instance_hooks()
+ MyAgent.clear_class_hooks()
+
+ ChildAgent.clear_class_hooks()
+ GrandChildAgent.clear_class_hooks()
+
+ AgentA.clear_class_hooks()
+ AgentB.clear_class_hooks()
+ AgentC.clear_class_hooks()
diff --git a/tests/mcp_sse_client_test.py b/tests/mcp_sse_client_test.py
new file mode 100644
index 000000000..11e2bcbd3
--- /dev/null
+++ b/tests/mcp_sse_client_test.py
@@ -0,0 +1,408 @@
+# -*- coding: utf-8 -*-
+"""The MCP client test module in agentscope."""
+import asyncio
+from multiprocessing import Process
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import mcp.types
+from mcp.server import FastMCP
+
+from agentscope.mcp import HttpStatelessClient, HttpStatefulClient
+from agentscope.message import TextBlock, ToolUseBlock
+from agentscope.tool import ToolResponse, Toolkit
+
+
+async def tool_1(arg1: str, arg2: list[int]) -> str:
+ """A test tool function.
+
+ Args:
+ arg1 (`str`):
+ The first argument named arg1.
+ arg2 (`list[int]`):
+ The second argument named arg2.
+ """
+ return f"arg1: {arg1}, arg2: {arg2}"
+
+
+def setup_server() -> None:
+ """Set up the streamable HTTP MCP server."""
+ sse_server = FastMCP("SSE", port=8001)
+ sse_server.tool(description="A test tool function.")(tool_1)
+ sse_server.run(transport="sse")
+
+
+class SseMCPClientTest(IsolatedAsyncioTestCase):
+ """Test class for MCP server functionality."""
+
+ async def asyncTearDown(self) -> None:
+ """Tear down the test environment."""
+ del self.toolkit
+
+ while self.process.is_alive():
+ self.process.terminate()
+ await asyncio.sleep(1)
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.port = 8001
+ self.process = Process(target=setup_server)
+ self.process.start()
+ await asyncio.sleep(2)
+
+ self.toolkit = Toolkit()
+ self.schemas_wo_arg1 = [
+ {
+ "type": "function",
+ "function": {
+ "name": "tool_1",
+ "description": "A test tool function.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "arg2": {
+ "items": {
+ "type": "integer",
+ },
+ "title": "Arg2",
+ "type": "array",
+ },
+ },
+ "required": [
+ "arg2",
+ ],
+ },
+ },
+ },
+ ]
+ self.schemas = [
+ {
+ "type": "function",
+ "function": {
+ "name": "tool_1",
+ "description": "A test tool function.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "arg1": {
+ "title": "Arg1",
+ "type": "string",
+ },
+ "arg2": {
+ "items": {
+ "type": "integer",
+ },
+ "title": "Arg2",
+ "type": "array",
+ },
+ },
+ "required": [
+ "arg1",
+ "arg2",
+ ],
+ },
+ },
+ },
+ ]
+
+ async def test_stateless_client(self) -> None:
+ """Test the stateless sse MCP client."""
+ stateless_client = HttpStatelessClient(
+ name="test_sse_client",
+ transport="sse",
+ url=f"http://127.0.0.1:{self.port}/sse",
+ )
+
+ func_1 = await stateless_client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=False,
+ )
+ res_1: mcp.types.CallToolResult = await func_1(
+ arg1="123",
+ arg2=[1, 2, 3],
+ )
+ self.assertEqual(
+ res_1.content[0].text,
+ "arg1: 123, arg2: [1, 2, 3]",
+ )
+
+ func_2 = await stateless_client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=True,
+ )
+ # Repeat to ensure idempotency
+ res_2: ToolResponse = await func_2(arg1="345", arg2=[4, 5, 6])
+ res_3: ToolResponse = await func_2(arg1="345", arg2=[4, 5, 6])
+ res_4: ToolResponse = await func_2(arg1="345", arg2=[4, 5, 6])
+ self.assertEqual(
+ res_2,
+ ToolResponse(
+ id=res_2.id,
+ content=[
+ TextBlock(
+ text="arg1: 345, arg2: [4, 5, 6]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+ self.assertEqual(
+ res_3,
+ ToolResponse(
+ id=res_3.id,
+ content=[
+ TextBlock(
+ text="arg1: 345, arg2: [4, 5, 6]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+ self.assertEqual(
+ res_4,
+ ToolResponse(
+ id=res_4.id,
+ content=[
+ TextBlock(
+ text="arg1: 345, arg2: [4, 5, 6]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ self.toolkit.register_tool_function(
+ func_2,
+ )
+
+ schemas = self.toolkit.get_json_schemas()
+ self.assertListEqual(
+ schemas,
+ self.schemas,
+ )
+
+ res_gen = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ id="xx",
+ type="tool_use",
+ name="tool_1",
+ input={
+ "arg1": "789",
+ "arg2": [7, 8, 9],
+ },
+ ),
+ )
+
+ async for chunk in res_gen:
+ self.assertEqual(
+ chunk,
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ text="arg1: 789, arg2: [7, 8, 9]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ self.toolkit.clear()
+ self.assertDictEqual(self.toolkit.tools, {})
+
+ # Try to add the mcp client
+ await self.toolkit.register_mcp_client(stateless_client)
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ self.schemas,
+ )
+
+ self.toolkit.clear()
+ await self.toolkit.register_mcp_client(
+ stateless_client,
+ preset_kwargs_mapping={
+ "tool_1": {
+ "arg1": "default_value",
+ },
+ },
+ )
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ self.schemas_wo_arg1,
+ )
+ res_gen = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ id="xx",
+ type="tool_use",
+ name="tool_1",
+ input={
+ "arg2": [11, 12],
+ },
+ ),
+ )
+ async for chunk in res_gen:
+ self.assertEqual(
+ chunk,
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ text="arg1: default_value, arg2: [11, 12]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ async def test_stateful_client(self) -> None:
+ """Test the stateful sse MCP client."""
+
+ # Test stateful client
+ stateful_client = HttpStatefulClient(
+ name="test_sse_client_stateful",
+ transport="sse",
+ url=f"http://127.0.0.1:{self.port}/sse",
+ )
+
+ self.assertFalse(stateful_client.is_connected)
+ await stateful_client.connect()
+
+ self.assertTrue(stateful_client.is_connected)
+
+ func_1 = await stateful_client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=False,
+ )
+ res_1: mcp.types.CallToolResult = await func_1(
+ arg1="12",
+ arg2=[1, 2],
+ )
+ self.assertEqual(
+ res_1.content[0].text,
+ "arg1: 12, arg2: [1, 2]",
+ )
+
+ func_2 = await stateful_client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=True,
+ )
+ res_2: ToolResponse = await func_2(arg1="34", arg2=[4, 5])
+ res_3: ToolResponse = await func_2(arg1="34", arg2=[4, 5])
+ res_4: ToolResponse = await func_2(arg1="34", arg2=[4, 5])
+ self.assertEqual(
+ res_2,
+ ToolResponse(
+ id=res_2.id,
+ content=[
+ TextBlock(
+ text="arg1: 34, arg2: [4, 5]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+ self.assertEqual(
+ res_3,
+ ToolResponse(
+ id=res_3.id,
+ content=[
+ TextBlock(
+ text="arg1: 34, arg2: [4, 5]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+ self.assertEqual(
+ res_4,
+ ToolResponse(
+ id=res_4.id,
+ content=[
+ TextBlock(
+ text="arg1: 34, arg2: [4, 5]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ # with toolkit
+ self.toolkit.register_tool_function(func_2)
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ self.schemas,
+ )
+
+ res_gen = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ id="xx",
+ type="tool_use",
+ name="tool_1",
+ input={
+ "arg1": "56",
+ "arg2": [5, 6],
+ },
+ ),
+ )
+ async for chunk in res_gen:
+ self.assertEqual(
+ chunk,
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ text="arg1: 56, arg2: [5, 6]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ # mcp client level test
+ self.toolkit.clear()
+ self.assertDictEqual(self.toolkit.tools, {})
+
+ await self.toolkit.register_mcp_client(stateful_client)
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ self.schemas,
+ )
+
+ self.toolkit.clear()
+ await self.toolkit.register_mcp_client(
+ stateful_client,
+ preset_kwargs_mapping={
+ "tool_1": {
+ "arg1": "default_value",
+ },
+ },
+ )
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ self.schemas_wo_arg1,
+ )
+ res_gen = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ id="xx",
+ type="tool_use",
+ name="tool_1",
+ input={
+ "arg2": [11, 12],
+ },
+ ),
+ )
+ async for chunk in res_gen:
+ self.assertEqual(
+ chunk,
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ text="arg1: default_value, arg2: [11, 12]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ await stateful_client.close()
+ self.assertFalse(stateful_client.is_connected)
diff --git a/tests/mcp_streamable_http_client_test.py b/tests/mcp_streamable_http_client_test.py
new file mode 100644
index 000000000..cc5bf97dd
--- /dev/null
+++ b/tests/mcp_streamable_http_client_test.py
@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""The MCP client test module in agentscope."""
+import asyncio
+from multiprocessing import Process
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import mcp.types
+from mcp.server import FastMCP
+
+from agentscope.mcp import HttpStatelessClient, HttpStatefulClient
+from agentscope.message import TextBlock
+from agentscope.tool import ToolResponse
+
+
+async def tool_1(arg1: str, arg2: list[int]) -> str:
+ """A test tool function.
+
+ Args:
+ arg1 (`str`):
+ The first argument named arg1.
+ arg2 (`list[int]`):
+ The second argument named arg2.
+ """
+ return f"arg1: {arg1}, arg2: {arg2}"
+
+
+def setup_server() -> None:
+ """Set up the streamable HTTP MCP server."""
+ sse_server = FastMCP("StreamableHTTP", port=8002)
+ sse_server.tool(description="A test tool function.")(tool_1)
+ sse_server.run(transport="streamable-http")
+
+
+class StreamableHttpMCPClientTest(IsolatedAsyncioTestCase):
+ """Test class for streamable HTTP MCP client."""
+
+ async def asyncTearDown(self) -> None:
+ """Tear down the test environment."""
+ while self.process.is_alive():
+ self.process.terminate()
+ await asyncio.sleep(1)
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment."""
+ self.port = 8002
+ self.process = Process(target=setup_server)
+ self.process.start()
+ await asyncio.sleep(2)
+
+ async def test_streamable_http_stateless_client(self) -> None:
+ """Test the MCP server connection functionality."""
+
+ client = HttpStatelessClient(
+ name="test_streamable_http_stateless_client",
+ transport="streamable_http",
+ url=f"http://127.0.0.1:{self.port}/mcp",
+ )
+
+ func_1 = await client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=False,
+ )
+ res_1: mcp.types.CallToolResult = await func_1(
+ arg1="123",
+ arg2=[1, 2, 3],
+ )
+ self.assertEqual(
+ res_1.content[0].text,
+ "arg1: 123, arg2: [1, 2, 3]",
+ )
+
+ func_2 = await client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=True,
+ )
+ res_2: ToolResponse = await func_2(arg1="345", arg2=[4, 5, 6])
+ self.assertEqual(
+ res_2,
+ ToolResponse(
+ id=res_2.id,
+ content=[
+ TextBlock(
+ text="arg1: 345, arg2: [4, 5, 6]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ # Test stateful client connection
+ client = HttpStatefulClient(
+ name="test_streamable_http_stateless_client",
+ transport="streamable_http",
+ url=f"http://127.0.0.1:{self.port}/mcp",
+ )
+
+ self.assertFalse(client.is_connected)
+ await client.connect()
+
+ self.assertTrue(client.is_connected)
+
+ func_1 = await client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=False,
+ )
+ res_3: mcp.types.CallToolResult = await func_1(
+ arg1="12",
+ arg2=[1, 2],
+ )
+ self.assertEqual(
+ res_3.content[0].text,
+ "arg1: 12, arg2: [1, 2]",
+ )
+
+ func_2 = await client.get_callable_function(
+ "tool_1",
+ wrap_tool_result=True,
+ )
+ res_4: ToolResponse = await func_2(arg1="34", arg2=[4, 5])
+ self.assertEqual(
+ res_4,
+ ToolResponse(
+ id=res_4.id,
+ content=[
+ TextBlock(
+ text="arg1: 34, arg2: [4, 5]",
+ type="text",
+ ),
+ ],
+ ),
+ )
+
+ await client.close()
+ self.assertFalse(client.is_connected)
diff --git a/tests/pipeline_test.py b/tests/pipeline_test.py
new file mode 100644
index 000000000..32586744e
--- /dev/null
+++ b/tests/pipeline_test.py
@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=signature-differs
+"""Unit tests for pipeline classes and functions"""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.message import Msg
+from agentscope.pipeline import (
+ SequentialPipeline,
+ sequential_pipeline,
+)
+
+from agentscope.agent import AgentBase
+
+
+class AddAgent(AgentBase):
+ """Add agent class."""
+
+ def __init__(self, value: int) -> None:
+ """Initialize the agent"""
+ super().__init__()
+ self.name = "Add"
+ self.value = value
+
+ async def reply(self, x: Msg) -> Msg:
+ """Reply function"""
+ x.metadata["result"] += self.value
+ return x
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Observe function"""
+
+ async def handle_interrupt(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """Handle interrupt"""
+
+
+class MultAgent(AgentBase):
+ """Mult agent class."""
+
+ def __init__(self, value: int) -> None:
+ """Initialize the agent"""
+ super().__init__()
+ self.name = "Mult"
+ self.value = value
+
+ async def reply(self, x: Msg) -> Msg:
+ """Reply function"""
+ x.metadata["result"] *= self.value
+ return x
+
+ async def observe(self, msg: Msg | list[Msg] | None) -> None:
+ """Observe function"""
+
+ async def handle_interrupt(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """Handle interrupt"""
+
+
+class PipelineTest(IsolatedAsyncioTestCase):
+ """Test cases for Pipelines"""
+
+ async def test_functional_sequential_pipeline(self) -> None:
+ """Test SequentialPipeline executes agents sequentially"""
+
+ add1 = AddAgent(1)
+ add2 = AddAgent(2)
+ mult3 = MultAgent(3)
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ res = await sequential_pipeline([add1, add2, mult3], x)
+ self.assertEqual(9, res.metadata["result"])
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ res = await sequential_pipeline([add1, mult3, add2], x)
+ self.assertEqual(5, res.metadata["result"])
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ res = await sequential_pipeline([mult3, add1, add2], x)
+ self.assertEqual(3, res.metadata["result"])
+
+ async def test_class_sequential_pipeline(self) -> None:
+ """Test SequentialPipeline executes agents sequentially"""
+
+ add1 = AddAgent(1)
+ add2 = AddAgent(2)
+ mult3 = MultAgent(3)
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ pipeline = SequentialPipeline([add1, add2, mult3])
+ res = await pipeline(x)
+ self.assertEqual(res.metadata["result"], 9)
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ pipeline = SequentialPipeline([add1, mult3, add2])
+ res = await pipeline(x)
+ self.assertEqual(res.metadata["result"], 5)
+
+ x = Msg("user", "", "user", metadata={"result": 0})
+ pipeline = SequentialPipeline([mult3, add1, add2])
+ res = await pipeline(x)
+ self.assertEqual(res.metadata["result"], 3)
diff --git a/tests/react_agent_test.py b/tests/react_agent_test.py
new file mode 100644
index 000000000..2730db00b
--- /dev/null
+++ b/tests/react_agent_test.py
@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""The ReAct agent unittests."""
+from typing import Any
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import TextBlock, ToolUseBlock, Msg
+from agentscope.model import ChatModelBase, ChatResponse
+from agentscope.tool import Toolkit
+
+
+class MyModel(ChatModelBase):
+ """Test model class."""
+
+ def __init__(self) -> None:
+ """Initialize the test model."""
+ super().__init__("test_model", stream=False)
+ self.fake_content = [TextBlock(type="text", text="123")]
+
+ async def __call__(
+ self,
+ _messages: list[dict],
+ **kwargs: Any,
+ ) -> ChatResponse:
+ """Mock model call."""
+ return ChatResponse(
+ content=self.fake_content,
+ )
+
+
+async def pre_reasoning_hook(self: ReActAgent, _kwargs: Any) -> None:
+ """Mock pre-reasoning hook."""
+ if hasattr(self, "cnt_pre_reasoning"):
+ self.cnt_pre_reasoning += 1
+ else:
+ self.cnt_pre_reasoning = 1
+
+
+async def post_reasoning_hook(
+ self: ReActAgent,
+ _kwargs: Any,
+ _output: Msg | None,
+) -> None:
+ """Mock post-reasoning hook."""
+ if hasattr(self, "cnt_post_reasoning"):
+ self.cnt_post_reasoning += 1
+ else:
+ self.cnt_post_reasoning = 1
+
+
+async def pre_acting_hook(self: ReActAgent, _kwargs: Any) -> None:
+ """Mock pre-acting hook."""
+ if hasattr(self, "cnt_pre_acting"):
+ self.cnt_pre_acting += 1
+ else:
+ self.cnt_pre_acting = 1
+
+
+async def post_acting_hook(
+ self: ReActAgent,
+ _kwargs: Any,
+ _output: Msg | None,
+) -> None:
+ """Mock post-acting hook."""
+ if hasattr(self, "cnt_post_acting"):
+ self.cnt_post_acting += 1
+ else:
+ self.cnt_post_acting = 1
+
+
+class ReActAgentTest(IsolatedAsyncioTestCase):
+ """Test class for ReActAgent."""
+
+ async def test_react_agent(self) -> None:
+ """Test the ReActAgent class"""
+ model = MyModel()
+ agent = ReActAgent(
+ name="Friday",
+ sys_prompt="You are a helpful assistant named Friday.",
+ model=model,
+ formatter=DashScopeChatFormatter(),
+ memory=InMemoryMemory(),
+ toolkit=Toolkit(),
+ )
+
+ agent.register_instance_hook(
+ "pre_reasoning",
+ "test_hook",
+ pre_reasoning_hook,
+ )
+
+ agent.register_instance_hook(
+ "post_reasoning",
+ "test_hook",
+ post_reasoning_hook,
+ )
+
+ agent.register_instance_hook(
+ "pre_acting",
+ "test_hook",
+ pre_acting_hook,
+ )
+
+ agent.register_instance_hook(
+ "post_acting",
+ "test_hook",
+ post_acting_hook,
+ )
+
+ await agent()
+ self.assertEqual(
+ getattr(agent, "cnt_pre_reasoning"),
+ 1,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_post_reasoning"),
+ 1,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_pre_acting"),
+ 1,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_post_acting"),
+ 1,
+ )
+
+ model.fake_content = [
+ ToolUseBlock(
+ type="tool_use",
+ name=agent.finish_function_name,
+ id="xx",
+ input={"response": "123"},
+ ),
+ ]
+
+ await agent()
+ self.assertEqual(
+ getattr(agent, "cnt_pre_reasoning"),
+ 2,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_post_reasoning"),
+ 2,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_pre_acting"),
+ 2,
+ )
+ self.assertEqual(
+ getattr(agent, "cnt_post_acting"),
+ 2,
+ )
diff --git a/tests/session_test.py b/tests/session_test.py
new file mode 100644
index 000000000..8cae45d00
--- /dev/null
+++ b/tests/session_test.py
@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""Session module tests."""
+import os
+from typing import Union
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.agent import ReActAgent, AgentBase
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.session import JSONSession
+from agentscope.tool import Toolkit
+
+
+class MyAgent(AgentBase):
+ """Test agent class."""
+
+ def __init__(self) -> None:
+ """Initialize the test agent."""
+ super().__init__()
+ self.name = "Friday"
+ self.sys_prompt = "A helpful assistant."
+ self.memory = InMemoryMemory()
+
+ self.register_state("name")
+ self.register_state("sys_prompt")
+
+ async def reply(self, msg: Msg) -> None:
+ """Reply to the message."""
+
+ async def observe(self, msg: Msg) -> None:
+ """Observe the message."""
+ await self.memory.add(msg)
+
+ async def handle_interrupt(
+ self,
+ msg: Union[Msg, list[Msg], None] = None,
+ ) -> Msg:
+ """Handle interrupt."""
+
+
+class SessionTest(IsolatedAsyncioTestCase):
+ """Test cases for the session module."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test case."""
+ session_file = "./user_1.json"
+ if os.path.exists(session_file):
+ os.remove(session_file)
+
+ async def test_session_base(self) -> None:
+ """Test the SessionBase class."""
+ session = JSONSession(
+ "user_1",
+ save_dir="./",
+ )
+
+ agent1 = ReActAgent(
+ name="Friday",
+ sys_prompt="A helpful assistant.",
+ model=DashScopeChatModel(api_key="xxx", model_name="qwen_max"),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+ )
+ agent2 = MyAgent()
+
+ await agent2.memory.add(
+ Msg(
+ "Alice",
+ "Hi!",
+ "user",
+ ),
+ )
+
+ await session.save_session_state(agent1=agent1, agent2=agent2)
+
+ async def asyncTearDown(self) -> None:
+ """Clean up after the test."""
+ # Remove the session file if it exists
+ session_file = "./user_1.json"
+ if os.path.exists(session_file):
+ os.remove(session_file)
diff --git a/tests/token_anthropic_test.py b/tests/token_anthropic_test.py
new file mode 100644
index 000000000..8908bd4ba
--- /dev/null
+++ b/tests/token_anthropic_test.py
@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+"""The unittests for huggingface token counter."""
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.token import AnthropicTokenCounter
+
+
+class AnthropicTokenCounterTest(IsolatedAsyncioTestCase):
+ """The unittests for the Anthropic token counter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test case."""
+ self.messages = [
+ {
+ "role": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of France?",
+ },
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "BhdWRpbyBjb250ZW50",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "id": "1",
+ "type": "tool_use",
+ "name": "get_capital",
+ "input": {
+ "country": "Japan",
+ },
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "1",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+
+ async def test_anthropic_token_counter(self) -> None:
+ """Test the HuggingFace token counter."""
+
+ if os.environ.get("ANTHROPIC_API_KEY"):
+ counter = AnthropicTokenCounter(
+ api_key=os.environ.get("ANTHROPIC_API_KEY"),
+ model_name="claude-sonnet-4-20250514",
+ )
+
+ res = await counter.count(self.messages)
+ self.assertEqual(res, 49)
diff --git a/tests/token_huggingface_test.py b/tests/token_huggingface_test.py
new file mode 100644
index 000000000..754061385
--- /dev/null
+++ b/tests/token_huggingface_test.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""The unittests for huggingface token counter."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.token import HuggingFaceTokenCounter
+
+
+class TokenCounterTest(IsolatedAsyncioTestCase):
+ """The unittests for the HuggingFace token counter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test case."""
+ self.common_messages = [
+ {"role": "user", "content": "Hi!"},
+ {"role": "assistant", "content": "Hi! How can I help you today?"},
+ {"role": "user", "content": "What is the capital of France?"},
+ {
+ "role": "assistant",
+ "content": "The capital of France is Paris.",
+ },
+ ]
+
+ async def test_huggingface_token_counter(self) -> None:
+ """Test the HuggingFace token counter."""
+ counter = HuggingFaceTokenCounter(
+ pretrained_model_name_or_path="Qwen/Qwen3-8B",
+ use_mirror=True,
+ )
+
+ res = await counter.count(
+ self.common_messages,
+ )
+ self.assertEqual(res, 49)
diff --git a/tests/token_openai_test.py b/tests/token_openai_test.py
new file mode 100644
index 000000000..004c2a311
--- /dev/null
+++ b/tests/token_openai_test.py
@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=line-too-long
+# flake8: noqa: E501
+"""The unittests for OpenAI token counter."""
+import os
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from agentscope.token import OpenAITokenCounter
+
+
+class OpenAITokenCounterTest(IsolatedAsyncioTestCase):
+ """The unittests for the OpenAI token counter."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test case."""
+ self.image_path = os.path.abspath("./image.png")
+ self.messages = [
+ {
+ "role": "system",
+ "name": "system",
+ "content": [
+ {
+ "type": "text",
+ "text": "You're a helpful assistant.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of France?",
+ },
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiYAAAImCAYAAABnzkFGAAAAAXNSR0IArs4c6QAAAARzQklUCAgICHwIZIgAACAASURBVHic7b1tsyTJdd93smcGAGkGlpfmo4ILygTC4sNGGKTliAUwwFQDixUAkRQoCgzTIVqSCX+Oe++X8BsvLJJ2mAyJFB2mYIjcgW6Nd4mZFw7ILwhYdoAOCkQIoEDjkgAI7GL2dvpFd9XNOnWyKqs6q7u6+/eLmLmVeatP/yv74Z7816ksEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgLng9i0AAABG8HtPi2pzsZJCZCEiK6l+rlZSth7zsXvtPoCZQWICsCMWj/2Fd/KgansvlyIi8i5X7ksTHAC/97RYyKIQEfHOPRDxhfjIvrq/d7/Ne8+Hv7pZvy9JYmBPkJgATMwmITmP/d55uVy9y13sUBLMld97WiwWi0JExIuci/fS+Jqu25uful1lGF6MtkFfIuPWrotb+Ue1A/MrJCwwLSQmABPSl5RUkJycKL//tFisFkV+J2Tsfj2JT9V2vhRZiLu5ebQSEhbIC4kJwESkJiUVJCcnQp2MGO+NvsSilWh0JBAullh0xUt9XrO/dN6vExWSFNgCEhOAiXBP9F+Bfvzzjs/kEbL4/ZsLkc3pmeRTMQF7c1JSTh3pfhHxUq67/SVJCgyFL0GACRjqllTgmhwRv78uWl0nIworUXBW/+jEwCbFkTF1jN2vOvUjpReSFEjj7r4FABwjY5ISOA4Wn7y58N49ECeFj51KqaaE1R9yJ5H+TYd3zbZE+uu2ilPRil/pqn5X15BII+Fxlv6q3zgOrV+kcOIK+Z/fuE1SRKhLARMcE4DMjHVLKjidc4D8/vpqGu/lPMlJiPUPftwQJyVSY5LVIenTq9rOl/5GLuVXSVDgFr4AATIzprak8XhO5xwMi09WtSMukpDM9FRMcrwhCY/xxKl6RUp/40lQQERITADy8tgXzsnVtmFwTebN4pM3a1ds8hoN/cwpicGAq3B27pj06i29x0E5dfjyA8iIe+KvRKTYOg6uySxZfOrmwovrSEiGOAsTXIWzdaIxH4fHeX+5+tV7F5HIcMSQmADkIpNbsqH0z7tlpliwJbcJycgajVj/1o+7PReybg5JhDIlFmMeF93P0O9c6T2neU4JEhOATORySyq8lyX30dkvi0/dXHhnOCQVyTUa4Q6pNRoHeSrGaHfFS31eEREhQTkRSEwAcpDXLRERTufsk8WnwgXRAiZ3DPr22zIx2Lle3R54qstIbJwIp3iOHBITgAzkdksqKILdPbVLEpL1VErmGo0xj4vuZ55KSXR4dqq39IJ7cqzwpQewLRO4JRW4Jrtj8Qc3F973LBk/5NTEFOt+tPYb6EB0FdvuRG9Mf9BOSYS8rPcTX/pfvUct1pFBYgKwJVO5JRW4JtOy+INNYWtItj/IQxKGxJqSVB1Za0qswH2JW/Yak+h+buUvV/+I0zvHAl94ANswoVtSgWsyHbdJyaHVaFTN4TUau9Xbt19Gh8dJ6d+QS/knnN45dBb7FgBwyDjuiXOQLP7g5sL94crfOiWbP/bObTbDttu03W071l/FqvcR1W+1g39y+yu7reaSpl5Df1Rv33FF9Df6E/RH94vob/RH9Op+7wp3x10tfuPphfHMcEDgmACMZQduSQWnc/Kx+IOguHXUDD5W82DF62nn3i+pRsOp/fap13pAn94ER8vJ+h48uCcHCY4JwEh26ZYsHvuLXT3X0fKyL9wfrq4aV9x0zeC1OxB1JiIzeLOtYop6LrMd6tN6g3b4mBQnpe4f4qQk6LUcoahe9S9Jr97P1I97csAwCwMYww7dkgpck/HcuiQpM/COGXlFTscg1WlxkqhXOzz71Kv7e2pkuhypkXqdEwpjDwy+6ABGMPWVOOZzUgQ7Cvfy6va14lRKu91IICp9uj3wVMrO9Pbtt9lwnlM7BwSncgCG8tgXsuOkBEbwsi/cyysvIkX8D6Fv/lGr21WnN/p9u13/k+CP9WYf3W7t13x4J3q/1uMsvR3HVR1LfVzSbvce1zZ6dX+KXr2ffg2C16h6zErWDuc/fVr0i4Z9Q2ICMJB9XYnjuQIomcXLNxeNU226rqHud3Y7paakaqfUaLQeI901G43+UF+knVKjET53X42GvkKnr8Yk1t+rVx9Xil5Df2KtjHNytfinTy8EZg2JCcAQ9uyWUATbz+Jl407A4cS7yyGp2qZD4u12rN/ar4ppOSlhu9Ef6o3o73RI9HMn6PXqd/V2h/7ocRn6+xwSPVYxh6RXb1u/d3JOcjJvqDEBGMA+aks0FMHGWbys7nPjIzvq/rH7eempedjskFSjYdRs7Fyv7rf0drTrBGLHeqP7deot/T++u4wogz3CFxxAKnu4EseCIlgb9zAocq1I+YPW6kj9A2wkElsnAkP16v5KlyWgLzHa5nkzP67uH5IIdSRGHc/rRZYUxc4LTuUAJMIqrzPlZV+4T6+8OFesOyas0UhdR6O3RkO1G3pz1GgE7Yw1Gi0Bpl5D/+DXoepPeR1cpG3p1ccl4pyj7mRmuP5dAGAubkmF97KUd7ly3zr2zsu+cAt/NXwGrttdM/OueAPb2fdLcXgm0muEH+/wpDhSuj1Qb89+TuRy9U/uXUT2hB2CYwKQwNzckgWXK4tcbZISke4ZuTkDV+2kq3DSZuDDV3pthzWPw9yvywkxHpBzpdeWo6PbKccV0a8dHasdc6cax6X0d7wOXhxFsTPB9e8CcOLMzC2pOOki2JeDpERkxzP42Ix+oI4seiP6U2tlhtSYTKJX9/c4WmYRcV69Dudk7+CYAPQwV3fiZC8dvvKFu+Ov4jN4PSMOHptlBq/baqbe6Uyk6DX0R/Ua+ruOw1pLJbXGpKFPt3XMsD9Bf93v1H6RsepztHpfB6U/iO3FnbMQ236x3hoAEOCepCxxuRdK/7xb7lvETrnyhfNDakr69kt0FoZchZOqw0X6B8XL4PCk6p1kvxEOT+q4bTm+3nG1zr7AMQHoYOauRDFzfXmpkpLWTF3UzFdUv9EOHQYJHpvkmPQ4C4NrNPR+XXr1caXojejPXKPR0J/6OiTpVe0kJ6T6Kao/ot94PzlxLGG/J0hMADpgGfiZUCclIrJZfMKc/nrVrdux/th+dWdVy6CeO3avFmulVB2r1qvb2+jVjzP0tjR5tV94TCl69X7b6NWPMzT0HVfjdRBpvD6mXt0vddt57q+zD1z/LgCnyeKxvziExOQUimDdVbWeeOXRV6ScAlC797V3dKqgU7956kW3U+Ln1qvbXeMeae90fPv2S9HrxIvntM4OwTEBiHAISYnI7E83bY27Wl21HYhglt93Dxf9T8JtYwYexmg4Iqodu0+LdLRb/RH94c9ar57RK/36OGLHtZXeiH4feS7rdQmThCS9er9t9Op/KXq9uBXOyS4hMQEwOKQ/9oeSQI1hcXVzIeKKztqG2kDpqNGIbnfVMlT9Tu1n1Dak1miEsftqTGLbMf2x42i1E2s0kvXq5+rSq0jSq/t79A+pKXFi7Gfr57TO7iAxATDwTh7sW8MQDimRSmVxtblLcFdtQNgMHRJRu1rbYdvcSbpn9GGg6Ezd0huZmbeeO0WvIb/LkTCPw9AfBupzpFr7baNXPy4y7lp/eHyDa0p0O47zxzsJmBMkJgCax76Qma5dcjJc+cK7xXl8Bj9kRizmDLh7Bq/buWbwkRl9lxPRqbfnuEy9HfqHXnVkOg6G/kZ/gv6639Kr2rkdLensLxafeHohMCnWWx3gpHFP/JUcYGJyNEWwV75wEqzqKhKffet+q+269tvssClyTCqGHKMjm17dXz1AtyP6Gy6Tbu9Cb1/b0tv3ugyIn2k/J3K5+rV7F5FHwZbgmACEHLBbciync5yT861rNBqzbrXdaKuYk9VoVP0d+lsOTyBY6w8Ga7zDo9vBdkuvauuYXcfV0KuOo9W29Pa0hzg8pj6j3ehv6/Ui5zgn02G91QFOlkN1SyoO3TVZXN1ceOfOp5rpDt7vQGbw8cel6NX9+9Sr+1P0duifWK//tXsH/XmbKzgmABUH7JZUHLRrEtaVTFKjsYMZ/NAaDVPv8Bl8q133p+jV/V169XGl6E3QHz2uFL2G/iGOViig73Vo6HXi/oenzVOOkAUSE4AN7ogvuz0EnPNXt1dTBFdXDF1Ho7W+idhtCfbtu/pjynU0Wno72v5WWrreDv2D9erHdeiNHoehv+5PeR286h+iVx+n3La7xl3rvx1jimEnwJhCAJwgj33hnFztW0YODvF0zuKRv/Ai7VM4x3wqJVpsu0+9ur/SpdpJp1KC12Nneg2Zjf4e/bH3U8/zOophs4JjAiDH5ZYc3OmcK19478+j62iEP/tmtBJsNmbmkee29vN6B4nP4E2t4czc0BvGMI9jG726P6I/9tNypKxj7DquUMRgvRH9nXpVO3RFwu2o3r73V79eL3Iu/z2Lr+WCxATgCGpLQg5tJVh3J7wKJ7U2oNqW5s91RNWW2zqEaC2DasdqHMy2U/1deiM1Dpb+KWo0wtjR4+rRHtM/uEbD0mvoT30d6ufqed+E77EkvZH3U6hXZP0+hiyQmMDJc0xuScWhuCaLRzcX4n2RXlOi9qtmuJ1Oiqj9RPWHbRVzkGOSordjBj+qRkP9S9Hb6u/Rm1Sj0aXX0B99HVL0RvTHtmPtZL2x95M0od4kG65/F4Aj5ohqSxSlf94t9y2ik1d84VZq7PWXvXgRq8YhqUZDtzueJ7Jb736DH2fp7WjXf4D3oNdZ/Sl6df8+9cb0qwdmrFly1JtsDY4JnDTH6JZsKDanqGbL+r4jwey0/hnObEXNdIN9e2s0jL8a0Zl6bL/ITD32MzYzbzxRZGZuxRysN6K/8YuO44rVl2iHJPbTOq5Bensw9QbPZR5X+DqETxbTq49rmF4vR/udsjNITOB0ObLaEs1izsf2SjX2wfl8ke7agKOu0RhS8yCqv0d/o79Dfx3Tqf0M/dHajYj+zuNS+s3jMPSHMfpqgJJrT1L06ueWFpzS2Q5jSAFOg0Nf5TWFuV467P731ZX4YOyTrfhIwNH7VU8ctKOniLRAJ61TRZPrNdoNWZZe13NcO9Tbu1/XuCfoz6039X1p4DilMxocEzhNjtwtqZhlEewrvhBxhX2VRGwGPmRGK8120gxcP6ZnBm45JJ0zcNehNzYDd9LWa/xrHFeH/uhxGfpTrsJxKnb0uAKN+jhabbVz5+sgCXoN/UOuwmmNb6RtwCmd8ZCYwElyxLUlDeZ46XC8tkSkXaMhzXa1b2dtgNz2h09Rbet2bDusWejU26G/1uc79OqYovaTNsk1Dyl69X6+fRxdNSYpNRq6GdWr5Xv1OEuv7tda1euR8jro91OqXgWndMZBYgKnx4m4JRWzck10bUnuGXyXExHO4KOOg27PbAbf0hdp1/0penV/h94pHK2GXn1czm4n1ZSIobfvuCy9RrvR3z6MCs9diEdBYgInx6m4JXPEeb8Z+5hDEmmnrKPRu55J4EAYpka/k2D0D9Zr6M+xjobWX/f3OCRD9fY5Wlpv9VymfsOCaB1XRL/lkGzzOvQ5Wrrd6G8fhjqk8+49QNOR6wEcIce7bkknsyiCfcUXzkfGXn+5x77sU4ohW0WeXfHG6hi7X6UraCcX2+5Dr7WDC/ojr0Ojf496I8PY0t/1fqoxjqdP3+0jKYQdAI4JnBSn6pbM4XSOE6O2pNOBqPoTZrQ6ZmM/Q0xrZh7Zr/W4yAy+87gM/eETZl5Ho6lXPy5Fr9YQ/Kv16baK2ejfRq9+XNf7xjiuauxjjomp19DfiNmlL3pY3EtnACQmcDqcWG1JyN6LYKvakkE1GlV/V22ARGoepNnuq3GI1QpEax6U/pSah6TaE0tvX7tLb0R/yutQ93fp1ceVolf3R/Q641/n+ybW36VXH5fY7c7jkiQWi9P87hkDiQmcDKfqllTs0zVx3p/Xs9CoQxLMaJNrA6R7Bh8+Z/1TpDUjrme+yjGYvEZDty29CTP6+lcpenX/Nnr1P0tfpF333x7GbYzgNYq+bwz9g/Xqx4l6nKVXH5ck4SmETYbEBE6JYt8CTpJXfCHOFXlntDJuRtuagat+0zHQeg39Q67C6dWrXYAuvTpkil7dn6C/5UjpdqDfcnSienW/s9upjpQ4SXsdXDt2lyMV1avaPXgKYZMgMYGTYA41Fvtmv6dzEh2Ivpmu6H3VT3NmHpHjVdvcT8UYVFMSPpFvP6bLSZCwf4heYz+vdxBxq9Wll9VSxJedx6X113qDdu9xbaNX93e9b4Lnbuyn3keNbUuv/jlCbwe4Jv0MyPUADhf3JFZOf1o4L5erd7mLnT7nq765/LxI9x+qvrYL+zcdrbaX+NUutTLVHqBjtN6+/Sy9He36D3CqXld6ubmUX7xX1n2/97Rw/s65iC+G69X9KXp1f5fesTrG7pei19AfixfBcZVOJzgmcPTgltyyc9fkFV+sk5LITHdobUBr1iuRdvBcrRoNsdtyG+a239Kr+4fo7dmvitnQF2nX/aHeiH7vxXm59L+4WDaSEhGRX7xX+r+/WPqb1VKcL4fp1dspevV+hv66v+t9o2LX/UP0duhPfR0aeiEHOCZw9OCWNNmpa/LKZt0Y/QrEXpG+/eqZarhDZEbrDEckl45kvX2Ps/Tmd3icl8vVL965iKhpsfjdmwsf1kNY8ZMdnkB/nUD06O963rGP24fD04H/tXv8/Y2AYwJHDW7JfnEi550ORMqMuDUlDWe6Ys90JexXD+8iNoNvdPTp1T8jM/ioXn1comIP0Svi/Wo5JCkREVn90p0L/0t3nFutLsX7sqG/sW3p1T9F7detN/W4zOeyXpeY9rE1Syl6E6DWJA4ZGxw1uCU2O1kJ9pVgld1tZsSzqtHIrVf3V7/Q7a7jsPU6kcvV3xuWkET5508Ld+fOuax80dSr9mvpSHkdBsRLHd8h8Tof1/W+GeBoGVBnEgfHBI6Xx+pLFGp24SQtRIreGo3ec/4d2+bvdOzNc8farZm5t9t9js7omhL1r9an213HFepd/3OrjEmJiMjHNnUofrUUv6lDSTnOpNdBosdhjner37fbsX+9enV/RH+jX9pt2AoSEzhaTn1BtS52UQTrnTzoXUejsaZEz/oTsXUzkld6Fbvd6HeRduQ4YnqjxyF2u/O4uvS2284NqycZxMfulf5jd5de/FLcorT1qnatz5l6G/90vzneut9F2sH4p66Lk/T+6tKbzmol5bBHnA4kJnCcnPDy86lM6ppUS9DrmbDpOBjtxs+EGax+jDmjjWg1Z+qx/VL06v0s/V7ienXsRL3Olf7v3XFZnZIYH7tX+n+wWCco4svo69DQazg8wa/SXgfVmfQ+ijgk1muW9P4aohfGQGICRwluST/eyYOpYi+qpLA1w4zMgJNmxB0z39R7tcRmwHLbtf0MPkF/ygw+2SGSdVLyC4ul7JrKQXEbB6XWVx1XRH+j/3b3aLvud2q/yPsoZWXbrvfTNo5WCk5K+W/VZdtQQ2ICxwduSSrFVHU4ddIzqEYjaKfUaJi1AZsYsZmv2R8K1/8iM/GYYzK6liGiv28G72W9Psk+kpKQj90r/ccCB2VUjYYYbWt8+9pj3jex/Sy9Cfp78Ddymb736UFiAkcHbkk6i6kTuEE1GkG7zyEZNaPtcEh020kzxr4cHrH6G3LzFrluS+Wg/PJd57y7jDs8kvY6JDlSup3yvgnec6MdnnGOiRO5xC3pZoj5BDB/HgeXqEISU1w67F5Vlyj4cMO123W/1bbiSHd/GKZvv9R45n4D9WfU4fzMkpIYv/W0cHfcuYS3Jcj1Oujx7nodXML7aev3Q6S/wknp/5t7y569Th4cEzgqcEuGk70I9hVf9M6AB82IuxwHPSOW23afEzFqBq/omsHXs+0hM3jdb+t37kCSEhGRX7lX+l++u/QLvxQnZf/rEtD1Omg3I/Y6VO26f8jrYOkz2o1+exicyCVJSRp39y0AIBvUlsyChUhxezo+ZUarfh0yaqbq2+1Gv26rXRs6hszAVbur7mDQcTX1Ou8PJykJ+di90ouU8ltPC+fcuUhV36RfFwleh473jTdel/D9FDLakRERF3vfqHa9XxMn63oSFlNLJ5LbARwe7om/EhKTUeQ8neM+469kJcX8TqVM8Idr6/26Eh6t14kTf7n6+QNMSix+62mRXOO0SozZt99K1ucJcu4X+9WKK2/GQmICxwG1JVvhvSzlXa7MEatOTBpPEG7E/gD3JRZWvEg7db8hTk1jBl/19+jPmAg5keNJSgA64FQOHAXUlswIv3FL1ttr6rZxzt/q1+3b2CqeblcJT9WvEoaw7YLEIRpPtWt9uq316v6O+GFiVOtrtp0/IqcEoAeKX+HwobZka7JdNvzKpm6grq+oHAPfbsf6R6034Zsx6/7guXS7fu5Qr26n6DX0J+vV/W39JCVwauCYwMGDWzJDYg5JsmOi4lRYDonlhFj9dVtunYqW3h79Uzg8oRCl96hqSgASITGBwwa3ZFa4O3JuXo2iE4G6f0iNRqxmwzd/aoekdfWEelgrXget47L09tXOdARt6JWSpAROERITOGhwS2ZKtEZD9w+t0TBqNho1Gjq+clKqBzSciepxRrFtb+1JTG9Hu1Pv7VP7v7tYCsAJQmIChwtuSTZWkvkW7D7ciDkhCVfhxIyGmNth7hepB4k7FW39SU5I4lU4vXpFvF+RlMDJQmICBwtuyQzxwV2FRTocg8QajYreGo2umhKjxkRi8XQ7Ve+Aq3Aax9XW50Qu/c+x/gWcLpFvAYCZw7olWcm1wJr7o43lkeJ0iCQ6KcbjovF62tn3G1JTEnGEwj1WrFUCgGMCBwluSVbK7BGjNSW6nVqjoR6nn6evxkQnDLEaE50IddSAdOtV7Vpv1d+OzxU4AGtITODwoLZk/rRqNKrmkBqNXI6JrinRtSZ6v/DxPfqHXoUT0+tcufoISQmACIkJHCC4JXnxfn2Tsa2pFlcTMWo0qv6hNRp9jkmVCOi2ckZ0cW3lkDTaAS29qj3kKpyGXh1/07xxeV4DgCOAxAQOC9yS3JS57pETpesqlEFXu8QciJjz0eOQ6EJYS1+vU5Oi10iMGg93pfz8xK8BwAFBYgIHBW5JXrK5JTGy1Wjo/tT4Vk1J0O5aGdaMp583Va+hv/4VbglACIkJHBrFvgUcETtwS4bUYnTUlEQMkzSHQzsmRrvRb+kP2r13Ra66e67C8SLOy6X/yKK0VAOcKiQmcDAsHvuLmLMOw5ncLRHpdkLqK2GCn33rgMSuuumsKYldhSPtRKQVXzsciQ6PMx7fjl+u/u7iQgCgAXcXhoPBcxonJ9ndksXCcLO8xGtMQtciuiqr+tm6S68EroRyPmJ3Fe6iV6/eL9AV1Wvr9+6GUzgABjgmcBDgluRlJ26JSNMhcFb/FjUaYZyKljNhOCYpdx/uOo4u/el3Hy7lw6zuCmBBYgIHAW5JZqauLalouQwpNRo6gYjEs9pmv+FaWP1mjUkgK+zo1NtzFY6I+I/cWUaUA5w8nMqB2bN47C/2reGYcBO5JauVsYKsk2Z9SOgs6JoNq4bDuc325l+sXfdvYoTPpdut/i69ejtFr96vqde5HblVAAcKjgnMHtySvKze5S529mThKRyzXkOf40lwUmoCK6PLIbHqPhr7dWi3trtIuOpoJVyFA9AFiQnMm8fBaqKwNc7L5U5rdaJX01RtVSSSXqOh+mPxq1MsVX/H1TrhqaPK9Rh9FY/hzqz7S/kwi6kBdEFiArOGBdXyslO3RCRwDOoOiTshjWIOkZZDIu3EwHqY3i+MYdaU6CtojCB9NSZJDo+IlxWncQB6oMYE5gvLz2dlqtqSmvcaTkBVc5FSo1HVgdQ1Gbpt1JQ41S+bmLrGJNYfqzGJ1p4Y+nuPq/7HlTgACeCYwGzBLcnLzt2SkJjTkeQ4aGciEq/VMH72XYXTq9fYMTwd1eGkOJFHOz2NBnCgkJjAPMEtycrOa0taAjY/dQ1Ick2J7o/Ea9WAVImBbm9qSszEqIpn1JhEa0pUu6XXycpTWwKQAokJzBLckrysxLiUd5e0ajRUO7FGox0v0m70R2pMoqvNxh4X6q2aqQ4PRa8AqVBjAvMDtyQ309+sr8JFEqBWjUb1b1CNxu0Do+1G8EhNiVFjEq0p0SGd6o/ob/Q78cIdhAFSwTGB2YFbkpedLT/fKULsGo2W8zHkahdnBFBBrZoSF3NIxui1djD0/u4bRjAAsMAxgXmBW5Kb3bklIuK8PLJ/EfzsdCYsx6GvneKkuOZjUpyUrqt2dLvlCAUxvioi4q7k429cycefFub4AEANjgnMCtySvMzCLREZWFOi2pYxMmo9E2k7KNXPrvVNq17UEgAAIABJREFUGvESakz0PXO+WscpRFwhH39DRKQU8ZfyEpcPA2hwTGA+4JbkZqduiUjkfjkiTUch1QmpXYzEGpPkmhLdH+oz2mZNiW6rmEG//6o5IgUuCoCNdRYVYC+4J/5KSEyy4b0sd52YiIi4P4pdSiMdNSVBO+Xuw7GrdgZdrZNhv5ZT09brH/nN6ZxeSlwUABwTmAu4JbnZuVtSE7syZ/27uAMRcRzMdqM/ocYk992HG3Ul4XasxiSJAhcFgMQEZgK1JXnZZ21JtABWJKjzqNpBPYeXWwekscaIb7cb/Qntut94Luu5G/2G/vqfpTdofzV8cDLFJkHxJClwipCYwP7BLcnN/tySPqKOSbxG49b5CAOk1p4EsaKOiajn7tIbtFMcnnS3JEaBiwKnBokJ7B3ckrzs+0qcaAGsiO1ANLa92s+4gib82eeYVPt2OSRajHklT+RYevbz4xwTiwIXBU4Fil9hvzz2hXNytW8ZR0Tpn3fLfYvoLIANSSkuHfO46H5jim3H6/XlKodrEqOkWBaOERwT2Cu4JXnZt1tSEyuArWovwhqN8Keu0YjWiqTWlOj9pN3urT3p+GfqDWJMl5SI4KLAkUJiAvuD2pLczKa2JL4CbGQdkL6VXYfeM2fIVTgNfSJJNSZdV+FU7d1SUIsCxwIrv8LewC3Jy2zcki7UmZRGf7hDdYrFXLdEt7vibRqd9Sqxx9m7RPdzjY2p3ZIYhaxXly1F/CMRKTnVA4cGNSawH6gtyc0saktCkupMJq8p0W2V2HQlPM5IfIbo+OqmxmT/lNSiwCHBqRzYC7gleZmjW+LE0DS0RsOsPRlSUxKpMal+mjUl6rkbetVxaP1a7zwogtM8F/sWA9AHiQnsi2LfAo6I2dSW9DK0RsOsPemqKdG1J5vH6hqTWH9rnRKtV/1O62+tUDsrChF3TrEszB0SE9g5i8f+Yt8ajok5uiUiIqv3uIvoLy0HwtzPckzCB4SOiG7Hakp6HBNLU7Le4Hf/YVauiaagWBbmyizTejhu3JPENS4ghdnVloQs/shfeOk4bTd5TUnf46yaklhxbWqx7ab9OS/+8wf1Vi+pRYE5gGMCOwW3JC9zdUsqoq5Jao1Go1YkaOu6kpQaE7NfjJoS7aRIpB3TG7QPiwIXBeYAjgnsFNySrMzaLalwn/FX4iM1RZbTYCy4On4/5YB0XnZsBNxCx8Srvu6KEhcFdg2OCewM3JK8zN0tqTAXW9M1G+EvGrUcVk1JuF/ECWk8QU9NSasWxdAX1Ttgv8OkwEWBXYNjAjsDtyQrB+GWVETXNEl1PmL9Wz8uxUmpCIQmPK8vVyL/IaLnsClxUWBKcExgJ+CW5OVQ3JKK1pomYY1Jl0Ni1n14tV+HY9Jbe6JjS7O/odffhm7pVW3df1wUuCgwJSQmsBO8kwf71nBEHM66JTHCdUAa64NY65YE+1VrlcTupaMXHgkf03XPnEa/RNrBdkuvauv+46QQbiIIE0BiAtPDzfqyEr1B3oxZvcddmCvBivTUaFg1JdJde9JwTMR2SKzYXVfhJOvt6T9eClwUyAWJCUwOy8/nZfWujoXLDo3YiqqxlVVj7b6VYaMrxW4eG3NSxOrv0hs5rtOhwEWBbSExgWnBLcmKO7DakhDTNUmpKfF6v47akdR75uiVYbtqTFr9hv7630nUmKRS4KLAGE4zp4ed4Z74KyExyYZ/3h38Z9a8Qkf3xP6oD97Pi3m1TdJVONvpOOKrcsZSivhHIlJyRQ90gWMC04FbkpVDdktCGq5Jy4HQe0dqSmL3wela2TVaU2LUmMTo1RvZD0SqmwjiokAPBz/7gvmCW5KXY3BLKlquSWhc6P6u9tb7GY5J9J45ah2TPr2f8+I/R3bSQ4mLAhocE5gG3JKsHItbUlG7JqGzEK0pibTr/iE1JXq/TczOmpJIjYk3/rX0Qg8FLgpojmYGBvMCtyQvx+SWVDRck+xOSGy/lBoTXYsSiY9jMhWlsLLsSYNjAvnBLclNuW8BU+BELvtrNHRiYNWU6LZha/RdhRP72VVTordTak8ghYJLjk8bEhPIDuuW5OXQlp9PZfUed+Hc5tii64C427ZI/3omjXVKgkDR9U1E9Yt0rmcSLpsSWxlW1DZsQ8FpntODjw/k5bEvnJOrfcs4Ig7qZn2DeUW/X1JOsVQkXN47pKg2S/FtoPdzIv7zWCcTUHKq57jBMYGs4Jbk5Vjdkpr3utI5uRy00qtzqr9jZVen+qWKIe121DEJ9Dr1T/e39MIEFLgoxw2JCeSD2pLcHP7N+hJYvcdduJWqN9E1JrruI1Zj0nd1jo5lxe5a6bWlL9IWEflBMpOJKUTc1TP/6HV//6PXF/sWA/ngkwPZ4EqcvHgvy1NITCrcZ/yVrNT7J/UUS6y/93FDrs5JOHWk+v0/W0V2gJy87duvy7Pf/o44kctX/8XZxb71wHaQmEAeqC3JzXHXlli84gvn/FV/YtCRKFRMlsj07Vfp27RITHbG2779uvzot76zXh9P5PIzJCgHC6dyIAvUluTl6GtLLN7rSufd5iodVffRdxVOo/ak5yqcsEik6yqcsMYkWlOiQ6rakh8cOxgwlC9+15vl62+6IyIiTuT8Pb907e//A07xHCI4JrA9uCW5OT23JGDxir/wVaLbciaGOCnGOaCcDknKKaY/9lyZs2Pe87Vv1Nte1rmid3L5md/BQTkUSExga6gtycup1ZZYuFfVe2rnp2KG1J50xGP1151T1Zs01pxZUzqRy1d/56zcizBIhsQEtgO3JDcn7ZaEuFe9T1tC3mCydUr69mvWmMgfr8R/PrIvTMaz335d3vbt76xfJpWgOBKU2UONCWwFtSV5OcnakgjOy2X3eiZVu6umRNWfJNWU6P7bMNF23a9qTH6Ir9h98Gff9Wb5s+9+U+OlrF8WJ8XKydX9X6b+ZK7gmMB4cEtyg1uiWLxyc+FlcZv8er8pGuipKamLCwbWmOTez4v4f86VOfvi3V/7RnWVTjuxlI17ckcuX/1t3JM5QToPo8EtyQtuSZvVe+9cOAnvp9N1dU69k9ov4WqdlJVhG/fWCfsDwWE75qrAzvjSd7/p9mWWtiHmnRR+JVfvxj2ZFXxsYDTuSewEP4wAt6SD2jkxHRMJpsShYyI7qCnpa3vxpRf5auTxMDnvvt5cpWM4JuG2c1I6h3syB3BMYBSLx/5i3xqOCdySbmrnxHRMnN3uXM9E1Zx01p5Is91Va9JyTJw4lqbfK1/6rje1HBOR4C2y2c+LFCsvV+/+L3FP9g2fGBgFbklWcEsSuXVOqp6gxiRaexKwg5qSllPzVRF/RZ3JPnn2tdflba995/ZlsdwT9ddw4WSJe7IfcExgMLglecEtSefWOZF2jUn1s1V70lVTop0UabdTVoYViW//QKaDh9F8/e5dETEMsuDtUuclm/6V4J7sCxwTGAxuSVZwS0aweHRz4d3iPLrAWcUYh2PbeNYTsJ7J3nn2tdfl2de+c9sRcUrC/s2rd/mZ32bV2F2CYwKDwC3JC27JOFYP7lw4J5dm7ciQq3DC6XJXjYnc/iqpxiTm6MDe+LO3vFlEjLdJReu1q1/C8/f8yjXLIuwQPi0wCNySrOCWbEnTOUmoMamYzCGJ78d6Jvundk0Sakxqx2TzcyFS3ni5fELdyeTgmEA6j32xbwnHBG7J9qwe3LnwTpbNmhKRVo1J6nomEjy210kJakxSnBTuNLx3vn73rl1jIu0ak7DPyXrNk8VCru7/w+tiZ4JPFBITSIYF1bJSnvqN+rLxXleukxMpxfuNS7L559U/3d9qi9zaHX7z67528E+CED6I5b2478eg3jd/dfeOfPHNb7p9GX3waocvf1i65IOfXuRmJVfv/q8oip0SEhNIY+2WFHtWcTTglmTmva7073NLca4cdxWODHBMguftdUwC5+aHSEzmgF7H5PYXwc9mjcntz9vt83f/Q5KTqSAxgSRwS7KCWzIR/n1u6bxcNlyP2hHRbcMh0T9jDknriVW/tQ+XDc+CL755XQTrU19LaTom1WO9JzmZChIT6Ae3JCu4JdOyeuAu/MItbx2L5lTXrDGJ1p6I7aw0+sVuB09Xd/80rskc+NJb3tS7jonpnISlSyIiJCeTQGICveCWZAa3ZHre60p/I0vxvkyuMTH7xa4xafRLpB3sW03Bf2q6Q4Z0vvjmNzdrTLSBpt8WwT6Nt4DgnEwBiQl0g1uSFYdbsjuWrvTFYimLTd1JX41J7qtwwhqToNYE12QefP3endE1JuHLvbmcmOQkIyQm0AluSV5W73IX+9Zwavj3uaVbrS4bTkijkGDAVTgSbJpX4fSJEZGfIjGZA391505vjUnjlffKKal+d+uqnD/PpcRZIDGBOLglWcEt2R+r5Z0L791SxJXdNSWRGpNOJ0XUFFrs/qCNa7J/Wm5I+IvQMQn31W+Javv2H+ucZIDEBKLgluQFt2TPLF3pC7d0PnBPemtPxKgpidWYBNt1v7fbLKC8d7745jc360eqX6Q4Js0ak8bb5sbJ1e6O4jghMQEb3JKs4JbMh9XyzoWXjXtSOx8ZrsIxHRNnt396gWsyA75+7067c4BjInL79glLit71q9xbZxtITMAEtyQvuCUzo3ZP/KXpkIhIvPZEul2P1NoTTJO981d3jMTEeM30lTuhEVb3SeNxxbv/a4phx0JiAm1wS7KCWzJfGu5JWGPStzJs2E5ZGVaM/udwTPbN1+/eHb6Oib46J3w7NA2yc5KTcfDJgBbuib8SEpNs+Oe55/1BcOUL533Tgvey/pbU7kaqC1Lf7Vi3Nz8/txL/+fGSYXve/fVv3DZU8li/Wi54G1iJZke/c3L5md88u8il9xTAMYEmuCW5KfctABJZutK/f+HW99uRoJCg5yqckJZjEqkxCWtNuHx4HoSJhXZKqp+JNSZhHC+cFh8KiQk0oLYkLyw/f3j4pVt6cetVY9c96VfSpK5vUvd7EYpg58WAq3JEojUmjTic0hkGnwi45bEvHJe65aT0z7vlvkXAFlz5wnm5qk19fSrG7Fe/Dom1P+fFf55q2H3w3Le+JW+9uRl9qibsb7wrXPPldsIpnVRwTKAGtyQvuCVHwNKV/v3O3V69IxK/Wsc3ZsmtRWbDKbVxDx1O6ewRax2T8CocuW3X/+T25Q/XMWk4Kc0Lufh+TYTEBNZQW5Kbkpv1HQ+rD9y58B9YOCf+sjFF7roKJ2zX/cGVPLrNKZ15oGtM5Pal6qwx6XsvCKd0UiExARHBLckNbslxsk5Q3CZBUQ6JqG1R/eZ+zQc47j68c1prmYxdx6RrzZrbOOfP/2OWrO+DxARwS/KDW3LkrD5w58Kv3FIWUjbWM2lc2dFxFU843Q77uUpn5zSuvKk6Gi7XuHVMYq+i80wC+yAxAdySzOCWnAgfdKV//2LpV7IUkbJ161nzXjpqyq1rTbzn7sM7pnZDwo4JakyCJ2RV2B5ITE4d3JLc4JacGh90pX9hsfTeLcVJqWfbImHbqDEx+t0DkpNd8czNTbNjbI1J+AAVR0MhbDckJifOgqQkK7glJ0yYoHgp0+6Z45v91VT8B0hO9kbwWjWuwwqdEqvGJHxAArgmcXjnnzjuCfdfzwjrlkCTl33hxJ9LNQEIF7oIiX0KWd9kcna1jonF498842+wAY7JCbN47C/2reGYwC2BFh90pf/gYrOSrJRRhyRWe/KTXKkzNW9942a3NSYBuCY2ZGsnDG5JVnBLoJ/KQfHqFKrloITOyudxTqaivonfEKdksx06Iy2HJPGvK65JGxyTEwW3JC+4JZBE5aC8uHDeuc3VPOEOQVVD6KT8pIj7Sf5+7YQJ1zGxwDVpwzv9RMEtyQpuCYznZV84v6lD6as9+ZwX/3/x0c3FMzc38txff0u8k73UmFTgmjTBMTlBcEvyglsCW/FBV/oXF0t/U1/NUzZrT4Iihp8ScT+5Z71HxFvfeGP365gY4Jo0ubtvAbB7PAuq5YR1SyAPH3alFylFRORTvnB3/LmsXCEit7NyLyI/5cT9wMY5+eo+hB4PrTVMRBqOSGsdE/WLHDUm0AbH5NRYL6gGmcAtgUn48MZF+dDC1euiiEj9p+8HRNz7FiI/sDeFR8FbnxqJydh1TEbWmGxCn+Oa3EJicmKw/HxWcEtgej7sSv/hTZIii/XqspvpuHvfgqLYkTxzc9NYsdW6V059GyS5bdf/qt0G3isH+mHsTonHvnBOrvYt41jwXpYkJrA3PvW0cP7OuYgv5Ksi/hWKYofw3F9/a72GSUdRa+NUjWxZHJsARbBrcExOCNySrOCWwH758L3Sf2Sx9G6x9D+4WLq/vyg5tTOA8F42kXvcDLpXjr43Tse9cmJwOmcNxa+nAjfrywq1JTAbPrxOkL1IKZ96WsjvSiHiHgif907q+pL6+t7NL4LtxuW/Xm4vKw732WzXCzDgeWwNQ3giuCf+SviiygXrlsD8+fjTQsSt10eBBm97/XV59vXv3CYee17HJITTOSQmpwG1JVmhtgQODpKUBnV9iUhyjUnYH9u/sz8Rv5Dlk18/K4c96rigxuQEoLYkK9SWwOHx0r1SXrq7FPFLEX8p1XopJ8gzb9zIW9+4adeEVERqTBpX40xUYyIisliRPOKYHDu4JVnBLYGj4URdlIZbIhIvgJUBV+VY21v8dT310zknffCnALUlefHPOz4zcHycSJLyzBvre+OISLMmZEY1JiIkJpzKOWa4Eicrjitx4Fg5kVM9z772euMeN+FNnLe6V46OF7THcOqXDZ90Vnbs4JbkBbcEToojdFHe85ffsItaU07F9J3qiRXJjsFJ+fg3zk72yj/WMTlWcEuy4rxcbrOu5ofecl1Y/W+IyGLRfJ1Wi+7Z6sNvnnbFPuyIl+6VUjknR5CkVG5JRWPdEWsdE68Sj12uY+IPd5xzwAzwSMEtyYvllnzobp1sFNVJUe/lgSxk/cWSUjSX2G+eu17/vqz2cSKPRERWm76Hf0kCA5n5+NNC5PAWcGvUllQopyPr5zSsWRnJKV82TGJyjHAlTja+77NvyNm/eUN+/BOvXS5ExDt5IF4KP8T6DfqTrN+UL8QhVnLlwHh5VG0//IvT/MKDjByQi/LcN74lb71R65ZUzGwdk+Bhl5/5zbOLcY8+bEhMjhDcknFUSUi9/dn19tgvsq0vL8w4o2vFWc/oys0X7qUIyQpswYyTlGfeuJHnvrl2S6KJfN9nM7I9WY2JkJjAMYFbkszbP/GaiKgkpIttEw/djlm/05zy6Y5zu13KQkTcJln5CskKDGCGp3qe+0b/XYRb/VbiIevPaetxse1t/7qecAEsicmRgVtiE7ohb3/ptWEPHjGbmszpiO0/rQNTbrYuSVQgmRm4KG977XV59rXvrBuxz4NMMDEI423Bqa5ncpIHfbTgljSoHJHBiYiBZdnmPrXSelxXnCFWcv5EqHSCowID2EOS8swbN/LT3wgKXvc9MRjBqRbAkpgcEafullSuSPKpmVTmnygkx88+Q3RSuvX25cMvnd4XKAxkh6d6nvvGt+SZ8BSODKwxSfg8TFljsglxknUmJCbHwom6JTldkV6mOrUis6ox2TZe6ar6FBIV6GJCF+XZb78ub3vtO+MT+ikmGiM41cSEBdaOhFO6g/BOkxGRxhdN4zvH3f6M7d/4YtS/N+I4Y5/eBCbYjsYL46Q6MDqe3sXWVfjNH5oPPHtdiog4j5sCBhMt4PbMGzfytk1dSd/ntO/zoN/3ZhwdT/LVmJwqOCZHgnvij/ozsPNkRJFr5rSXdUwGOC9bX3XUnVCVJCnQyZanep55eiPPfeNbk3weOvdP2R7DiV6ZQ2JyBCwe+wt/hI5JVTOyr2SkJneiENveJlEYGifx+VPiDY6zucrHObl8+KckKRBhhIvy3De+Jc88VQuppUwMRn4epq4xETnNK3NO7oCPkWNzS97+idf2n4xYTO8ozLrGZApdTkhSIIGEJOVt335dnv3Wd7ZPnIPtrBONkZzilTkkJgfOsbgl+z5V08mUp0Ri/dYXY1ecHTswjXgyMLGK6y2d3xTOkqSAReRUz9u+/bo8++3v3O43p8/DlpCYwMFx6G7JbN0RhTVz2uaLbKdW8hQJ1cRf/K6qRyFBgRgbF+WZpzfFc1/vWXJeZP+fh5G4E7wyh6tyDpjFY39xiFnJrN0RC9f+rnGqf5D1q+N1fJGZX4yWLmfEM46jz+Ewjy9lhmj9Xh+aMV6NOM14hV9I8f4fvxbn1pcgP/wCSQoEvHSvvP/Ra/Fu45wkfB7MU4pqnyGfh87PO4yGxOSAObRTOIfijrSovm3UH2Lngz/s1S9ExG+2ffC4wfHC3Tf7+444VaA6jmUlB/uID+Lp7EJ/8frIF2+KLtVfx/FBPDVeOp73UngvxQfefk2CAjX3P3pdeAnWbgo/V8H7S3+uqt288fmpd9j0mRMD9f4248FWkJgcKo99sW8JqRxsQlIxF0dBIk5HsK11NaTZzkSnY6PjmPFiuoxxMeNFxkvH87JOUN7/jmtxm2XxSVJOk/sfvS5E5Mp0OqTtmMQ+p32fB/1WNuPoeJK3xuQUITE5UA5hQbUtE5Lyaz9yp7j+kTvmL7/2w+237tci+1p835dvbre/8oa8499859J7aRTUiSjHQJpfZK1vnXDGFcYI+qNxtGNhbPtgFtea0WkHokNXPcMz9Da+qL0KFXFYal3bxAuo4rSqp4I4KyeFEymW77guvchlSYJyMtz/6HXh/SYpUZ+TKT8PnXG6Pg8wGIbuEJnx8vND60e+9iN3JEw+vvbDdwclGNl46W79WfiQXBciIrKQwnt5IE5domg5AoGtO8d75bTiWDPNkfFGxbHGK6Yrtq2exy2kvHFyWf5bkpRjpXX6RmTQ+y76+Rz5eUj6vG+Jo/gVDoE5uiUpCcmf/OybRGSPyUcUfxm2/pVs/rCtNstl+02yclfE+/XYe5EiW43JZna1VY1J0BWrMWnEiZxTj8br0NV1fFacakbbGq9QiybYJzZe3kvhvBTLv3VdehKUo6N2SiqM952ZyKv3Y+2QaFfS+DyMjpcR7+RB3ojzB8fk0JiZW7I5XVOKsfDRn/zsm+Sb33un/Mp/crf1u1kRuCWpfOjudeFlkyAajsocHYWcDkwjnsiwdUxS4gU6x8TZ/Ci9k0cLkfIhScpBc/+j14V4uUp+/+7482B9TvXEYDQnuCw9icmB4Z74K5n4duEpvP0Tr8k7PvHaZeUgiMzZEemklJfubvWhr5IUn3LKZ9PeqZW8TSLUs3/f8+w0EereXteikKAcHPd/4frCi5xH3xfB9qw/D2MhMYFZMwO3RJ+y+ZOffdOhJSIKv9zc5TQLH7p7Xfg7cu69FLNb4Glih2PrL/4pZq7t/UvvSVAOhfu/cH0hIueDE47Idvi+P5QaExITmDX7dEvChKRyRr7wM2/eh5ScbO2WdPHim9ZfqgfiKHTHC3Rum8DkKD7Momsh61qUPyZJmSP3f+H6wvvuz0+sf6tToMF2NgdmS07tRn4ndbAHzR7dkuq0zRd+5k3nR5CMBOR1S2J86C3XF6uhX7Bqe4eOwqDt2dSYbJdYkaDMjPs/f30l4anRKRKFXU0MMkBiArNkH27J2z/xmshnV/KFn3lzuevn3gGTuiUWL75lPQPc+eWKu0pc9vXFP3I2rBMXcVIKCcpeuf9zm8uB5+BwDImT8nnYAhITmB87dkvOPvlUvu9/e3oMp2o62I1bYvHid19fOC8PvNze46PxU27buRyOJGt7ii/sHr2zSqya7XWxLEnKzrj/c+1Tn1kdNDnQGhMhMYEZsiu3JHBIpn6qfbNzt8TiQ2+5Lm6cXB2Qo7C9Lon8gUn8wzCZAxPTJVIKCcrkVEnJtgnqoBqmrvhTJM5jofgVZscO3JITSkg27M8tsfg7/9H1lfdSjP5ijG1P6yj0J0LTJAp7mSFvHr+uRfk/SVJyUbskIdsmCrHtCRNdy5Gs423LCSYmi30LgG4mX+X1syv5gr93QkmJlHNKSkRE/uCvz5arhSz9+lJW8SJS/ZTNtvjbnzVVnwQ/q8eG/4L+MI4P4iTFk6a2Rhwdz6t4QXwznqHL+2asRpwwnkTiSSSeGPG8imfp8lLISq6K/+z6qnjn5rYFMJr7H7m+8Cs51++Txms6l8+D3O5jxhEVxzelwTBwTObMlG7JZ1fiP3uKH515uSWaF7/n+kJ8vaLsdg7HLmeIQ+N0zIB3oitxu45jO0LlZgsXZQD3P9J/GX31M3wdt17HJObIdewf01WRpGtbcExgTkzilnx2Jf6lmxNNSubnlmj+8JtnFyu3cU82fa0ZXUWXA1D9DGd2Q+KFYfWMNiWO1aVnvWp7rK5Rx2eNl0TiqX2CXxTipRCRq+KduCgp1ElJiHYm5HbMG69N9dN4P0iwf71P1RU4HVa8dqNbV8ORS9EFg8ExmSu53ZIve5Ev+1NNSDbM2y3RfOh7rosbCYpjD89RSNbVihfoHF1jsk28SH90hhw+drG57Pj/wEWpuP+R6wu3KW6tyeSwjYq3ae/k87AljrsLw1zI6pac7GmbBrN3SzT/6ptnpYi4D37P9ZWIFPXMrPoy9JE/vPqlDvYPfx3GqYLUcfztF2z9gMh2tY9Xz1OHrr6wtYth7B/q8sZx1HGcSOzuzqa74pRLM0KXhLrc7ay5MV4i4lZSeJHiwc9eizgp3QknKfc/tHFIVsH7I+X9a73X1PuilRRO/HloaOnYbn0eYDAkJnPksS8k1+XBJCUb/OW+FYzl5W+eLV9867r2RP8Brb/rXd01/ly4Uw91Kl6wvxlHx9NSgvhjZ8Bal5aWOgPW46V1NY5T4o5QbLzqMOtTPUXxn1+X4uRSROQUkpT7Hwockg7HQo+Xfv82Eg2JOF46nkQ+DyKDr9KK6arjBXGinwcYDDndDMm2bglJyS0v3T3o95FNAAAdlElEQVT49/oL33NdOCfn0nEX41GnVmLbCX/g9f6630oUZrmOiTVeQ7dTjnPdLp0cZ5Jy/8XrC3G3xds1Pa9vrlM0SafaBnwesp46GolfyPLJrx/X+6QPHJO5kcMt+bIX/8lVDjVHwuG6JSEP16d2yhffqm4DHzoBm/9aM/cNQ8+pt+KofbZ2FNT+fTNkM15Ee0qiMEpXLOEwdJnxRArvpHAi8uC/uC5lIeKcXJZPDvOPz/tevL4QEfFGQpLkKBjj5cJGsN2XKJjj35Eo9H0eenXF4mRKSk4Vhm9mbO2W4JK0OQK3RFMlJ9lmdFPMEF3/F39qnEY8GegIpcQLdA4ZryRdsW3reTY1KSIic05U7r9wXSwWUjRuTlmRMF4VWRyO1ERoqs9Dqt6R4JjAftnWLSEpMTgOt0Tzh18/u3jhe69Lt17zpOirManaO5khxuIF7bGJUCOOa0szj0/HC7Y74w1IrPriNOJJRwIjUvh1XYo8eP663Px6FonK+15oOiPV2NSMSPj0eOn3r+WgJTkvkc/D0ES07/OQlFjBYBi+GbGNW+I/uVpfEgyKw7pEeAwvfu/6rsUn4SgYurIc377HK9Kv//DJ+t494p08WizW2+Wr+ROW+y9cF4vV+rvIOkVjJpYSSVBj2z1/4Ld5PWbnwGzBqd3AT4TEZFa4J60LJPuhnqSLWdysbxe8+L2buhOR5C/szi/+xC/ynZ6q6YoT0Tt1ojDqD1+wva0uf9ssqw23kEcrEVmsNivTdvjiK5FCFiLOywNZiKz8uvZlL+OVsL23U43bfB624QRXfRUhMZkNi8f+wg9du4RTNz0cv1sS8sL3XhciwaJ8Q76o9/3Fn9ify+HYWpc1XjLeMcimS/UfmiM0F4dj0GXFqXrHcKKJCUvSzwSSkuwc3IJq2/LwL89KEVk6t/4yrf9tfu+ciLjbnzXBF2nj3PzmZxgnfGgjjo5nxJEwTqouZ8RzRjxDV+vvQhhHx1Pj5XScMF5svMJjU3Fa8UTFSxyvRnx9nCPGK1VXK14wji1d1njpFymMo8ZxyHg1ULoa8Yzxcl26dDylq/X+DeOJ2PpG4DeF0KcGickMWDz2F4MeQFKSwHEWvfbx8C/Pypevz5wXKcXLsHt6BP2NxwRxwodad+vV2604wWMbcSbQ1Qpl6G3oisVT2s14hq5wF2/o8uGDIscdvVtu6nHG4oW7puiKvb6Wruq59P6J4zVIV+z4EsZrUDylq/dzZcWDZDLldbANg2pLSEpSOJnaki4++B9fX4kPiqmdpJ8qsLb1t0UYx/XES+wPdW1TbLt1vKFxBm4f1Hh17N/3PI33W1+8BL3ReAN1Ve1cn4dWnEx/WU+x8FUEx2TvDHJLSEoSOU23RPPy/3e29CKXrRm7nmkHs7zojDP8p+OJEc+reEF8K445ozVm2o3n8s3HNuIZx1nPaK14XsXri6N1WccZ09UxXpauQeMVi7PNeIkRr2e8eh0xK55xfFpvGKflsCldjXiRccz1eWjoCmNsg9sUL58gJCZ7Jrm2hKQklZOrLeni4dfOLhYil41z9upcezgDHFNj4sIHiDR27KvlqOME8RpxwnhhnDBel66Qxk5tXa14CePViKOPU9Q/NV6NeB266tdA1LbSZdVM9I2Xfn0bxzJivKK1HPo4jfGSME7qeKlguWpMWvHCpx4wXjAOEpN9sl5QrRf/SZKSdHBLNH/4tbMLv3FORIwZYoWegYrYM1orjtcPau7cmCjrmaaK16JHlzIJ2nefteL0OQqx4xygK9ylMUMPn1MLteKpY9p7zYTlKKh4uXT1jpeKU2/OabxGcqqFryIkJnvFJbglLJw2CNySCA+/dnYhTpYiOApH6SjEdKlgs3QU+nSJihfum6DLupqmIUUdd7Iu4/U1Pw8wGMZuXzz2hXPBmhMGJCVDOa11S8bwwvdfF+I37zvjS92LzKe40Ihfx3E98XLp6tGbNF6x7Sl0qf5c49WKF+gcMl56e9B6IQnPk+v9a+oaMV7bcKqFryI4Jnuj1y35LEnJQHBLEnj4F2elOFlOPQOu/m1dYxL+C+OE8Zq7JDlCfbpcGEfHGzBedVvr0vG6dIkRL6Zr4Hi1dImtqxXPGfESxku/vo14XeMV0xUSxtHxDF1djpCpS8fTh2eM12hOuPBVhMRkP/TdrI9C1xFQW5LKw79YL8TW+kVwjrxxqjxXDUJwrr/3qo2BuhpSVC2BFecgakzCOAk1E126WvHCXVWchq7I6xs7zlqrdXyJ4zVIV+z4EsZrUDyla+oaE+fl0XYRDhvuLrwHOt0SkpIx4JYMZJOcuBe+//pKqiQ5mOW1Zu7q99Uv/WZfv/m1D/fTs8qOOI14ItF75Zi6dEwrXqCzEU/pMie6Oo6hK+pQ9B2n6tfPq+M4tX+vLiuetMfRjGeMV6cufZwqjnWqphXH0hVsR+N16epwMcz3r44X05VynCNZLXBMYJd0uSUkJSPxJz272IaHf3G2FL/5EuyacYb/gv76MXqG7FW8IH7SuhxWPInEEyOeoatznY+YrlicFF2J8WSMLj1eMV3hWGYer0Y8FafXEbPixXSJEc+reIYu0XEMvdH3b4ou6zgtXUNxUj759fx3jD4kSEx2TNQt+bInKRnLS/cu9i3hkHn4F2dL2dydNqlmovrdpmHObqvf6Zmxk/Y5eteM1yLobzkwLtCYqivoj+lyYZwwXmtwenSJEU+MeM6I16GrFS8YRzNOZLz069s4lp7xah1noLVPV2Mo1ftkzHiJjhPG69IVidOKp3RNWWNyypcJV5CY7JKYW/Jlv74CB0ZAbUkOHn5145yo3Lg1oxVjhigieuaqd25MlPVMU8VrYfTHHIA6jnToCrajjkLsOAfoCndpzNDD5wx1bRNPVLzIOHY6YlpOYxC0qLauMN5oXbE4KeMVbB96jcmps0VeB0NxT/yV6MSEpGQ7XrrLezgjL/zQ5v46kRlkA7f+/t375a2xbaUry+WtQZxtLm8drSsWZ9/jFenPNV698QbGqbZb79+E98Dgz8MQnJSPf+NsOfRhxwaOya6IuCWcvtmKct8Cjo2Hf362FCfl3GpMzOfyzcc24hm6wpqJXl26T8cJ9mn09YzX1rq6xqsOqOJlGK+qs/FcHcc3qsZkSDyv4hlxOl8PvW8wRtaY9ulqvB5qHIfAaZw1JCY7wqwtYa2SLeE0zhQ8/POzpdusozDqnHpwQj5XjUnsKqHeGhMVR8Ln6tDlwjg6XnDMqTU5jXhixOvSJW1drXgtET3jFdMltq5WPGfESxgv/aI04o0YL/2+O/R1TE696LWCxGQXWG4Jxa7bwiXCE/Lwz9cFsXqmvWmufxoz4OYOygEQNePsiheiZ+zVT8MBqONYoQyNdRwdz9BlxvPtrtaMPTjumCNkatQauuL16Kr6R9eEaGcicpy11n2MV+Q9cDA1Jie+qFoIickOaLkl1JVkALdkah7++dnSBVfr4Cg0w4xxFKyZ+6SOggo2N0chabxExXNGvC5dzogX0zVwvEynLhavB07j3DJi+GAQxj1xuAfO1pTy0t3lvkWcCh/4oc0ibK2/zKpt9HuRtOJYa3ubeIn9dZw+LT3buXRNMl4i+e+VY8XrihPRGx7nbIptg+1cunqh6LUBjsnEtNwS6koygFuySz69qTkxZ66xP0Lh7LH6dddMU8cLCfobTxfESZq5OvUvjCNNXVW7ES+Mk6pLVDzXfM6h4xUea4qT03guY7y6dHU6HNZxBlpbcZSuxlCq4x4yXvr1bbz2I8ar8YsOXVPVmMAaEpMp0bUl1JXkgNqSPfDwK2dLL+urdXrPqTdOyLe7wlqOxu86zvV31SaEdQR1nMR4jfqFMJ6ha/KaiW3iiYrXVzOhajBaYxH0N4M39Y6uWYnpisVJHC8rXpbxUrqst/42NSacxmnCvXImpOGWUFeSCdySfeFELsUFibZrWt1OlOXtGo+9/ekiE8owjkuIF8ymdZxWPEufEcfpGGo71GWdKojG69Ll2rpMfXqXAeNVtc14Q3WFjkK7qzleVjwdM0FXI54z4lnHqaUbr2nr/WvpkqZz0jW+5uehD5agb4FjMhXKLcEpyQJuyR55+JWzUrwsWzNQ7SgE09St1uUI4lnrU3TGM3TF1gvpWueitY5G+Fi13RlvhK7B4xXO1q3XZgtdVWfjuTri9DpY28bzzXhWnMbrIc04Xu8bjJE1pn26vKGr0tsHbkkbEpOJ0G4JdSU5wC3ZNw+/clY6L0uRjnPqwQn5XDUm1tU9EsQZVGMi0q5BULqcEaflpkR0WVd/NOKJES9xvMJjTa59cSqetON16hIjnlPxEsdLv76NeCPGq0uXBHGs8XJGnOpBfbqy1ZjglpikDh8MQV2J41+62aeaY4ErcWbECz98XfjqPW59GW+2vUjceo99iXf0N+Jt4nc9f992Hcf1xEvsD3UNuprD2t4mXqQ/+nrEtMTiuDy6so5XTFds/23Ga2CcGI9/84y/wQY4JhPQcEs+S11JHnBL5sTDr5yVzsll3wwZR8GIk6Cr8St13EPGS/9BbrhTPeO1C0ehb7wGOWwxXa6ty3LYGmL7xiumyxm6IjjhFE6MhOGDQYRuCQWvucAtmSkv/I3rCy+bRFx9qYsYDoexT3Rbfzu5AY5JYn+nrgHxcunayhHa8Xi14g3ddls4JpH+QY7QwHjb6LLALYmDY5KZBQWvE4BbMlce/vuzC7e+WueW4Iu55XDIgBlwGC+ME8brmAFHa0x0PENX+NCWw2Hp0vGULqfjhPGCJ9zGEWrFSxivRhwdz+kASnuirkaMWDzX3CV1vPTrO6jGxBivBmEcfZyGriE1Jn6xrtMCm57hg6G4J5s67s+uSExy8dJd3qcz54W/cX3hw1OY6g8GjkKixli8QOcYXRVzdRQG13L06N1bTU5su/k8rPLaA45JRhaP/YWIsJBaVnBLDoGH//7swlWXPRoz5KijEP5LmCEfo6Pgwhjqj1kYRw3F8TgKXbrU6xuOV5fD1lf7kuqw9Y1X631ijKOGy4P7iY0djKByS7gXTkZwSw6KF370+sJ7Oa++WXI5HFNe3ZPy/LF9ZnXV0TbxEvvn6ghZcbZ5fXNdpdUCtyQJHJNM1G4J98LJCG7JofHwS03npM/hEBk+A65+jpkBi2vHi86AdbwwTqqu8F8YR8czdFnjpfWaM/NAfONvZN94xXSJiueMeFWcnvHSYsM4aigGOUKNOB2vbxjHPM7Y8enxN+Kk1JjglqQRGT4YSu2WsGZJPnBLDpYXfnR9tQ6OQmKciN5DcBRy65rDeFXkrDFxIpef+c2zC4FecEwy0HBLIBflvgXAeB5+6ezCLeTy0B2FJF2i4jkjXhhH63JGPEOXGorZOAqWrlRHwdLViqPjOSNe4nh1OUbNg1ZxIuOV7Pw5KUlK0iExyYB3ck7Ba244jXPoPPzi2YX4dYLpN/95kVH3yqn+bXOvnDCO6Dhal4rXqavaJ0FXfQw6TvC4pOPbwXh13isnjKeHNuhvjE0QpxXPG/EMvWGcRjwjjoRxlC4rXuO10K/HNrpEOIUzEBKTbVnfrI+kJC/crO9I+PSXzpYiUoaz+qSZppq5ijFztRyOME5XjYnlcCTXmKTqMhyAPsdkG0eoEc+1Qpvj1aurY7xaDoeOZxxfp2MS0yVGPP0ihXHUOA52hHQ8Q5dzRryILr+QJffDGQaJyZa4jVtCwWtOcEuOiU//2To5EWnPtOs+6Z65SriPEad3hh6iHQArnqGrFarLAbDiKV1emo8VQ2/DUZCmtpbDYelSwRoa+nQNidehy4yjnYlqU+sKx1LUY/c4XqnxnMglSclwrDwRUtksP8/lwVlh+fkj5QM/dn0lXgrTFdm0/aZ7bjfVCx8/Kl6HrpTn79Ql8xuvreNF+huvg5NmPjHkuF3eeFachZPyj7g0eBQ4JluAWzIFuCXHyqf/3dlSnJStc/TWDFTNkKO1AzqG6m/NxmNxpK2lNdM24uXQFU7rW+6FMUazrDGxtiPHZMbzKl5kHPXYJMeJvL4p8brGqyvODXUlo8ExGQtuyRTglpwAH/ix6yvZ3FPKS2TGGpuNh+0JZ8BVuxFvE3+uDkcux2AbXVuPV+z4DskREhF/h7qSbcAxGYlzcs5iarnBLTkFPv3v1jUn9Zd49dOHjeABeiZb/eyaAet4ISnxDF2tUIbeOk7w2HCmbe3TiKGepOEESFPbkJqQVpzg92NqTLKPV9/xTTBejXiR98mgGpPNhnPUlWwLjskYKreExdRygltyYnzgx6793B2FRhwchXicgY5CbP++52mM3zaOmOEYjRkvQ1f5+H+krmRbcExG4Jyc+0+ymFpecEtODedkadZySPBTJNjBcB3Cf0Ec01EwZtrhcw2tMWn0JeqKxWnEE2nP0PuOb9vxMnQNrjFJjSdGPK/iqThJjpjS1Rg/PY49x9l4PQbo8p66khzgmAzlsS/cV/wViUlWcEtOlBf+5nXhRa68JMyoE7bDOHuvMdkmXmJ/HcdyTLriTOQItXQlPn8sXufxzcwRuiOyfPV/4hRODnBMBuKcnLOYWm5wS06Vh396VjqRpYg9o9bbDQdA2i5CYx89Axb1IP10emYcxvNGqC4HYNt4hq7G8eo4YbzY15M1RuH2AF11vD5dsTjamYjEq3fNPV7hQ1OOT42XjudJSrKCYzIE3JIpwC2BtXPims7JnGbIs3AUYrrkMByFSdcxiWnp0RuNN0DXgqQkOzgmA8AtmQLcEtg4J16W9SxVOQBWLYd1rl/3t1yCWBxRcVS8KXWFU3jLvWjpMmbsrXiGLvEyerxExwnjGeM1OJ5X8SLjWMcJ41mvkY4TeX2txw4ZrxVJySTgmKSCWzINL93lPQg1L/zN62Ll5Ioak4njdIzXTnQdgSO0cCQlU4FjkghuyRTglkCTh396VoqTy0ZGEWybDoD0z6gb6JmxFU9UPG+E8jpAh6PQFS+MoZ6k4SgM0WV1hXE6xqvzOI142cZLpOVMWPuMGa86nm9JMONU/bEakxVJyaQwW00Bt2QacEsgwvt//PrCiZznnCHjKPT353QUdlpjMjCO9fqm6losSEqmBsckAdySKcAtgTj/+v89u3CL9dU64bQ3uWZCup0JazaeWoMQxrNqTLp0xeK0dKkZemftixjxho6XoeuQakzq8dPjGGrreX1bzomha0VSshNITPp47Av5si9Yej475b4FwLx5+IWzcrGQpTiR6p/bzF6d3Lbrf5vH1ftUj6sIZsCtONKM04rn2hPqRpweXS6Mo+PFdImhS4x4YsTrGi8ZoCv8p8arES+mS42XdiHCOK14CeOlX99GvHD8UsZLjHjB63tnIcsnJCU7gcSkB9ySSSjlpXvlvkXA/Hn4hbNy4W6dk4YDIO2ZcON3egYs4YPacSwHIIzTCuV1gA5HwdDVGc/QFe7S65hY8SzXIdweoKuO16crFifF6Qi17mK8LF2b9mqFU7JLSEy6wC2ZCE7jQDp1coKjMGtHIdTlDF21g5WqS8fThzdivIY6bAsn5eKOLJ/8NknJLml9NuAW98Rf+U+uSEzywoJqMIoX3nFd3Hg5d06Kxicy8keza9uLzP6mcju93Dmxv47jMscLdA4ZryRdse1+XZef+e2zC4GdQ2ISgytxJsIvOY0D2/CBd1xfeZFiVn/YE//w5UoUWnEGJGXh9qmMVyOedCQwt22Skj3CqZwI1JZMArUlsDWf/sLZ0m+Kp8P6AV2+cDDrmFjxDF2tp1Q1E80HdegSadfQBPFa9Og6hPGq3iPRGpNmHJKSPYNjEsH9dzeexCQ3uCWQj/f/p9cX4uV8K0chbCc6Clmdjp7nT4onEQdgj6dWto4X6Y86PHkco/KPfvtsKbB3cEwMFo/9BUlJdnBLICv/+v85uxAvl+Z6IdXPiKPQd3XPNuuYmOtm9MRp6dLxfEc8MeIZuqQjTiueGPFEPZcxXlqvdmm0HRLGaTkmht7G2ARxzHgxXWLE83JJUjIfcEwMcEumALcEpuGFn7guViu5EumYUYsMcxKsGbXIsFqOHddMDHncznTF9p/BeNXxFpy6mRs4JgrckknALYHJePhvz8rVSpbe3dadiKgZdYiesVc/u2bUwT6NOGo76igYulrSDL0tByD8pxyTlq4B8YbqqvqjuqyHdDkcmXQNGa/NLiQlMwTHRIFbMgW4JbAbPvC3NlfsiGStwThpR2Fk/cbea0w64jmRy1f/GQnJXMExCcAtmQTcEtgZn/6/z5bi5dKcIeuZedUXuiS6T5r7NmbuKo5Ifxyr9iJ0EUbVmFjxDF3SpSsyXtruiY1pjhqTrvHqqzHpPE79+pKUzB4ckwDckinALYHdU/zEdXFH5HxVuSciR1VjkqRrGwcil67Y/ntwhNyChORQIDGpeOwL+cTN1b5lHBms8gp75f0/cX3hRc5FJP8fUt3OeOqoFS/QOSSxasSJHWdse5tTUUPjTD9el5/5HZKSQ4HEpOLjb1xJOLuCDOCWwP554Seuixsn5xLUnjR+imqfqKPQmygM3d4msYr0R1+PyPM7kctXSUgODhITEZGPPy1EHG5JVvylvHTvYt8qACre/1PXF96v3ZNcCcegP5QJ2yebCAVxxzhCOp44KZ2TRyQlhwmJiQhuyRS8dJf3FsyO4ieuC3dHzsX31J4MSRRi27kTBSP+tjUmg3X16N3beAVtt8AlOXT444FbMgGcwoF5UyUo3ktxio7CtqdWeuMkblunjsbqck4uX/0XJCTHAIkJbklmOIUDh0Px3HXh/Kb+ZAeOQiOezOcqH0vX7BIrFSd0ZEhKjovTTkxwSzJDUgKHSfHcdSEJCYrup8ZknK5GvDFx1onTpYjIq/8LCcmxceKJCW5JPjh9A8dB8dx14TZX8bT+EI90OKyEY5s/7Em6tkmshuqyEiuZJhFyTi5JRo6b001McEtyUW6cknLfQgByUzx3XYiTc3FpC7VNeSpk61NHu3Q6ErdTx8uJXMoCd+RUOOHEBLdkS0oR/4hTN3AKFO9c16L43CvJ9uzf9zw7rTEZut12OoYVtS6kFC+PXv1fSUZOjdNMTHBLtsBfioiQkMCpUrzzth5lUI1J7A9ysH2yNSZBIuQWcikrKV/9l2elwElyookJbkkipYh/VLdIRgAaFO/cnOrZNEVkukTB2D7IdUza8UoReSQLEdwREDnVxAQAIDPFO68LERGp1keRIzu1MiROf6K0rhn5lyQi0IbEBABgAoq/fV2ISCFeHogqnt35qZrE/gmLd8uFk0erBadooB8SEwCAHVD87evCS3Da57hrTEpx8khEylf/FYkIDIPEBABgD2wcFZGFFN7Jg6pbRHqThq2KbYP+LInQ5oZ5IiIrEhHIAIkJAMCMKJ7fJCzrq34eiIj4gSvSmkWy253yKZ2TRysRWSxEVispX31IAgLTQGICAHAAFPfrhKXuWonIQkRWIuI2SUz9rb4Q8eouym59iqWBX6zdjpDVQsq7IvKGiJCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADA4fL/Axgs/rJgxZZZAAAAAElFTkSuQmCC",
+ },
+ },
+ {
+ "type": "image_url",
+ "image_url": {
+ "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg",
+ },
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of France is Paris.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Germany?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Germany is Berlin.",
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "name": "user",
+ "content": [
+ {
+ "type": "text",
+ "text": "What is the capital of Japan?",
+ },
+ ],
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "1",
+ "type": "function",
+ "function": {
+ "name": "get_capital",
+ "arguments": '{"country": "Japan"}',
+ },
+ },
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "1",
+ "content": "The capital of Japan is Tokyo.",
+ },
+ {
+ "role": "assistant",
+ "name": "assistant",
+ "content": [
+ {
+ "type": "text",
+ "text": "The capital of Japan is Tokyo.",
+ },
+ ],
+ },
+ ]
+ self.tools = [
+ {
+ "type": "function",
+ "function": {
+ "name": "get_location",
+ "description": "Get the location of the user",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "city": {
+ "type": "string",
+ "description": "The city to get the location "
+ "for",
+ },
+ },
+ "required": ["city"],
+ },
+ },
+ },
+ ]
+
+ async def test_openai_token_counter(self) -> None:
+ """Test the OpenAI token counter."""
+ counter = OpenAITokenCounter(
+ model_name="gpt-4o-mini",
+ )
+ n_tokens = await counter.count(self.messages)
+ self.assertEqual(n_tokens, 2016)
+
+ n_tokens = await counter.count(self.messages, self.tools)
+ self.assertEqual(n_tokens, 2058)
+
+ counter = OpenAITokenCounter(
+ model_name="o3-mini",
+ )
+ n_tokens = await counter.count(self.messages)
+ self.assertEqual(n_tokens, 1796)
+
+ n_tokens = await counter.count(self.messages, self.tools)
+ self.assertEqual(n_tokens, 1841)
diff --git a/tests/tool_dashscope_test.py b/tests/tool_dashscope_test.py
new file mode 100644
index 000000000..af2aed30c
--- /dev/null
+++ b/tests/tool_dashscope_test.py
@@ -0,0 +1,399 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for DashScope tools"""
+
+import base64
+from unittest.mock import Mock, patch, MagicMock
+
+from agentscope.message import ImageBlock, TextBlock, AudioBlock
+from agentscope.tool import ToolResponse
+from agentscope.tool import (
+ dashscope_text_to_image,
+ dashscope_image_to_text,
+ dashscope_text_to_audio,
+)
+
+
+class TestDashScopeTextToImage:
+ """Test cases for dashscope_text_to_image function"""
+
+ def test_text_to_image_success_url_mode(self) -> None:
+ """Test successful image generation in URL mode"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.ImageSynthesis.call.return_value.output = {
+ "results": [
+ {"url": "https://example.com/image1.jpg"},
+ {"url": "https://example.com/image2.png"},
+ ],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ n=2,
+ use_base64=False,
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/image1.jpg",
+ },
+ ),
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/image2.png",
+ },
+ ),
+ ]
+
+ def test_text_to_image_success_base64_mode(self) -> None:
+ """Test successful image generation in base64 mode"""
+ fake_image_data = b"fake_image_data"
+ expected_base64 = base64.b64encode(fake_image_data).decode("utf-8")
+
+ mock_dashscope = MagicMock()
+ mock_dashscope.ImageSynthesis.call.return_value.output = {
+ "results": [{"url": "https://example.com/image1.jpg"}],
+ }
+
+ with (
+ patch.dict(
+ "sys.modules",
+ {"dashscope": mock_dashscope},
+ ),
+ patch(
+ "agentscope.tool._multi_modality._dashscope_tools."
+ "_get_bytes_from_web_url",
+ ) as mock_get_bytes,
+ ):
+ mock_get_bytes.return_value = expected_base64
+ result = dashscope_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ n=1,
+ use_base64=True,
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/jpg",
+ "data": expected_base64,
+ },
+ ),
+ ]
+
+ def test_text_to_image_empty_results(self) -> None:
+ """Test when empty results are returned"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.ImageSynthesis.call.return_value.output = {
+ "results": [],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert len(result.content) == 0
+
+ def test_text_to_image_none_results(self) -> None:
+ """Test when None results are returned"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.ImageSynthesis.call.return_value.output = {}
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate images: 'results'",
+ ),
+ ]
+
+ def test_text_to_image_exception(self) -> None:
+ """Test exception handling"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.ImageSynthesis.call.side_effect = Exception("API Error")
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate images: API Error",
+ ),
+ ]
+
+
+class TestDashScopeImageToText:
+ """Test cases for dashscope_image_to_text function"""
+
+ def test_image_to_text_single_url_success(self) -> None:
+ """Test successful processing of single image URL"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.return_value.output = {
+ "choices": [
+ {"message": {"content": "This is a beautiful landscape"}},
+ ],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="This is a beautiful landscape",
+ ),
+ ]
+
+ def test_image_to_text_multiple_urls_success(self) -> None:
+ """Test successful processing of multiple image URLs"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.return_value.output = {
+ "choices": [
+ {"message": {"content": "Multiple images description"}},
+ ],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_image_to_text(
+ image_urls=[
+ "https://example.com/1.jpg",
+ "https://example.com/2.jpg",
+ ],
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Multiple images description",
+ ),
+ ]
+
+ def test_image_to_text_local_file_success(self) -> None:
+ """Test successful processing of local file"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.return_value.output = {
+ "choices": [{"message": {"content": "Local image description"}}],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}), patch(
+ "agentscope.tool._multi_modality._dashscope_tools.os.path.exists",
+ ) as mock_exists, patch(
+ "agentscope.tool._multi_modality._dashscope_tools.os.path.isfile",
+ ) as mock_isfile, patch(
+ "agentscope.tool._multi_modality._dashscope_tools.os.path.abspath",
+ ) as mock_abspath:
+ mock_exists.return_value = True
+ mock_isfile.return_value = True
+ mock_abspath.return_value = "/absolute/path/to/image.jpg"
+
+ result = dashscope_image_to_text(
+ image_urls="./local_image.jpg",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Local image description",
+ ),
+ ]
+
+ def test_image_to_text_invalid_local_path(self) -> None:
+ """Test error handling for invalid local path"""
+ with patch(
+ "agentscope.tool._multi_modality._dashscope_tools.os.path.exists",
+ ) as mock_exists, patch(
+ "agentscope.tool._multi_modality._dashscope_tools.os.path.isfile",
+ ) as mock_isfile:
+ mock_exists.return_value = True
+ mock_isfile.return_value = False
+
+ result = dashscope_image_to_text(
+ image_urls="./invalid_path",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text='Error: The input image url "./invalid_path" is not a '
+ "file.",
+ ),
+ ]
+
+ def test_image_to_text_list_content_response(self) -> None:
+ """Test handling of list content in response"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.return_value.output = {
+ "choices": [
+ {"message": {"content": [{"text": "Image description"}]}},
+ ],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Image description",
+ ),
+ ]
+
+ def test_image_to_text_none_content(self) -> None:
+ """Test handling of None content in response"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.return_value.output = {
+ "choices": [{"message": {"content": None}}],
+ }
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate text",
+ ),
+ ]
+
+ def test_image_to_text_exception(self) -> None:
+ """Test exception handling"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.MultiModalConversation.call.side_effect = Exception(
+ "API Error",
+ )
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate text: API Error",
+ ),
+ ]
+
+
+class TestDashScopeTextToAudio:
+ """Test cases for dashscope_text_to_audio function"""
+
+ def test_text_to_audio_success(self) -> None:
+ """Test successful audio generation"""
+ fake_audio_data = b"fake_audio_data"
+ expected_base64 = base64.b64encode(fake_audio_data).decode("utf-8")
+
+ mock_dashscope = MagicMock()
+ mock_response = Mock()
+ mock_response.get_audio_data.return_value = fake_audio_data
+ mock_dashscope.audio.tts.SpeechSynthesizer.call.return_value = (
+ mock_response
+ )
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ AudioBlock(
+ type="audio",
+ source={
+ "type": "base64",
+ "media_type": "audio/wav",
+ "data": expected_base64,
+ },
+ ),
+ ]
+
+ def test_text_to_audio_no_data(self) -> None:
+ """Test when no audio data is returned"""
+ mock_dashscope = MagicMock()
+ mock_response = Mock()
+ mock_response.get_audio_data.return_value = None
+ mock_dashscope.audio.tts.SpeechSynthesizer.call.return_value = (
+ mock_response
+ )
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate audio",
+ ),
+ ]
+
+ def test_text_to_audio_api_exception(self) -> None:
+ """Test exception handling during API call"""
+ mock_dashscope = MagicMock()
+ mock_dashscope.audio.tts.SpeechSynthesizer.call.side_effect = (
+ Exception(
+ "TTS API Error",
+ )
+ )
+
+ with patch.dict("sys.modules", {"dashscope": mock_dashscope}):
+ result = dashscope_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate audio: TTS API Error",
+ ),
+ ]
diff --git a/tests/tool_openai_test.py b/tests/tool_openai_test.py
new file mode 100644
index 000000000..4a4240db5
--- /dev/null
+++ b/tests/tool_openai_test.py
@@ -0,0 +1,689 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for OpenAI tools"""
+
+import base64
+from io import BytesIO
+from unittest.mock import Mock, patch, mock_open, MagicMock
+
+from agentscope.message import ImageBlock, TextBlock, AudioBlock
+from agentscope.tool import ToolResponse
+from agentscope.tool import (
+ openai_text_to_image,
+ openai_edit_image,
+ openai_create_image_variation,
+ openai_image_to_text,
+ openai_text_to_audio,
+ openai_audio_to_text,
+)
+
+
+class TestOpenAITextToImage:
+ """Test cases for openai_text_to_image function"""
+
+ def test_text_to_image_success_url_mode(self) -> None:
+ """Test successful image generation in URL mode"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_response = Mock()
+ mock_response.data = [
+ Mock(url="https://example.com/image1.jpg"),
+ Mock(url="https://example.com/image2.png"),
+ ]
+ mock_client.images.generate.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ n=2,
+ response_format="url",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/image1.jpg",
+ },
+ ),
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/image2.png",
+ },
+ ),
+ ]
+
+ def test_text_to_image_success_base64_mode(self) -> None:
+ """Test successful image generation in base64 mode"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ fake_base64_data = base64.b64encode(b"fake_image_data").decode("utf-8")
+ mock_response = Mock()
+ mock_response.data = [Mock(b64_json=fake_base64_data)]
+ mock_client.images.generate.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ n=1,
+ response_format="b64_json",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/png",
+ "data": fake_base64_data,
+ },
+ ),
+ ]
+
+ def test_text_to_image_gpt_image_1_force_base64(self) -> None:
+ """Test gpt-image-1 forces base64 format"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ fake_base64_data = base64.b64encode(b"fake_image_data").decode("utf-8")
+ mock_response = Mock()
+ mock_response.data = [Mock(b64_json=fake_base64_data)]
+ mock_client.images.generate.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ model="gpt-image-1",
+ response_format="url", # Should be ignored
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/png",
+ "data": fake_base64_data,
+ },
+ ),
+ ]
+
+ def test_text_to_image_exception(self) -> None:
+ """Test exception handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.images.generate.side_effect = Exception("API Error")
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_image(
+ prompt="A beautiful landscape",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate image: API Error",
+ ),
+ ]
+
+
+class TestOpenAIEditImage:
+ """Test cases for openai_edit_image function"""
+
+ def test_edit_image_success_url_input(self) -> None:
+ """Test successful image editing with URL input"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_api_response = Mock()
+ mock_api_response.data = [Mock(url="https://example.com/edited.jpg")]
+ mock_client.images.edit.return_value = mock_api_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools.requests.get",
+ ) as mock_requests, patch("PIL.Image.open") as mock_image_open:
+ mock_response = Mock()
+ mock_response.content = b"fake_image_data"
+ mock_response.raise_for_status.return_value = None
+ mock_requests.return_value = mock_response
+
+ mock_img = Mock()
+ mock_img.mode = "RGB"
+ mock_img.convert.return_value = mock_img
+ mock_image_open.return_value = mock_img
+
+ result = openai_edit_image(
+ image_url="https://example.com/image.jpg",
+ prompt="Add a sunset",
+ api_key="test_key",
+ response_format="url",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/edited.jpg",
+ },
+ ),
+ ]
+
+ def test_edit_image_success_local_file(self) -> None:
+ """Test successful image editing with local file"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ fake_base64_data = base64.b64encode(b"fake_edited_data").decode(
+ "utf-8",
+ )
+ mock_api_response = Mock()
+ mock_api_response.data = [Mock(b64_json=fake_base64_data)]
+ mock_client.images.edit.return_value = mock_api_response
+
+ with (
+ patch.dict("sys.modules", {"openai": mock_openai}),
+ patch("PIL.Image.open") as mock_image_open,
+ ):
+ mock_img = Mock()
+ mock_img.mode = "RGBA" # Already RGBA
+ mock_image_open.return_value = mock_img
+
+ result = openai_edit_image(
+ image_url="./local_image.jpg",
+ prompt="Add a sunset",
+ api_key="test_key",
+ model="gpt-image-1", # Forces base64
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/png",
+ "data": fake_base64_data,
+ },
+ ),
+ ]
+
+ def test_edit_image_exception(self) -> None:
+ """Test exception handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.images.edit.side_effect = Exception("Edit Error")
+
+ with (
+ patch.dict("sys.modules", {"openai": mock_openai}),
+ patch("PIL.Image.open") as mock_image_open,
+ ):
+ mock_img = Mock()
+ mock_img.mode = "RGB"
+ mock_img.convert.return_value = mock_img
+ mock_image_open.return_value = mock_img
+
+ result = openai_edit_image(
+ image_url="./image.jpg",
+ prompt="Edit image",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate image: Edit Error",
+ ),
+ ]
+
+ def test_edit_image_file_not_found(self) -> None:
+ """Test file not found error handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_edit_image(
+ image_url="./nonexistent_image.jpg",
+ prompt="Edit image",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate image: [Errno 2] No such file or "
+ "directory: './nonexistent_image.jpg'",
+ ),
+ ]
+
+
+class TestOpenAICreateImageVariation:
+ """Test cases for openai_create_image_variation function"""
+
+ def test_create_variation_success_url_mode(self) -> None:
+ """Test successful image variation creation in URL mode"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_response = Mock()
+ mock_response.data = [
+ Mock(url="https://example.com/variation1.jpg"),
+ Mock(url="https://example.com/variation2.jpg"),
+ ]
+ mock_client.images.create_variation.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools._parse_url",
+ ) as mock_parse_url:
+ mock_parse_url.return_value = BytesIO(b"fake_image_data")
+
+ result = openai_create_image_variation(
+ image_url="https://example.com/image.jpg",
+ api_key="test_key",
+ n=2,
+ response_format="url",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/variation1.jpg",
+ },
+ ),
+ ImageBlock(
+ type="image",
+ source={
+ "type": "url",
+ "url": "https://example.com/variation2.jpg",
+ },
+ ),
+ ]
+
+ def test_create_variation_success_base64_mode(self) -> None:
+ """Test successful image variation creation in base64 mode"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ fake_base64_data = base64.b64encode(b"fake_variation").decode("utf-8")
+ mock_response = Mock()
+ mock_response.data = [Mock(b64_json=fake_base64_data)]
+ mock_client.images.create_variation.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools._parse_url",
+ ) as mock_parse_url:
+ mock_parse_url.return_value = BytesIO(b"fake_image_data")
+
+ result = openai_create_image_variation(
+ image_url="./image.jpg",
+ api_key="test_key",
+ response_format="b64_json",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ ImageBlock(
+ type="image",
+ source={
+ "type": "base64",
+ "media_type": "image/png",
+ "data": fake_base64_data,
+ },
+ ),
+ ]
+
+ def test_create_variation_exception(self) -> None:
+ """Test exception handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.images.create_variation.side_effect = Exception(
+ "Variation Error",
+ )
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools._parse_url",
+ ) as mock_parse_url:
+ mock_parse_url.return_value = BytesIO(b"fake_image_data")
+
+ result = openai_create_image_variation(
+ image_url="./image.jpg",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate image: Variation Error",
+ ),
+ ]
+
+
+class TestOpenAIImageToText:
+ """Test cases for openai_image_to_text function"""
+
+ def test_image_to_text_single_url_success(self) -> None:
+ """Test successful processing of single image URL"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_message = Mock()
+ mock_message.content = "This is a beautiful landscape"
+ mock_response = Mock()
+ mock_response.choices = [Mock(message=mock_message)]
+ mock_client.chat.completions.create.return_value = mock_response
+
+ with (
+ patch.dict("sys.modules", {"openai": mock_openai}),
+ patch(
+ "agentscope.tool._multi_modality._openai_tools."
+ "_to_openai_image_url",
+ ) as mock_to_url,
+ ):
+ mock_to_url.return_value = "https://example.com/image.jpg"
+
+ result = openai_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="This is a beautiful landscape",
+ ),
+ ]
+
+ def test_image_to_text_multiple_urls_success(self) -> None:
+ """Test successful processing of multiple image URLs"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_message = Mock()
+ mock_message.content = "Multiple images description"
+ mock_response = Mock()
+ mock_response.choices = [Mock(message=mock_message)]
+ mock_client.chat.completions.create.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools."
+ "_to_openai_image_url",
+ ) as mock_to_url:
+ mock_to_url.side_effect = [
+ "https://example.com/1.jpg",
+ "https://example.com/2.jpg",
+ ]
+
+ result = openai_image_to_text(
+ image_urls=[
+ "https://example.com/1.jpg",
+ "https://example.com/2.jpg",
+ ],
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Multiple images description",
+ ),
+ ]
+
+ def test_image_to_text_exception(self) -> None:
+ """Test exception handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.chat.completions.create.side_effect = Exception(
+ "Vision API Error",
+ )
+
+ with (
+ patch.dict(
+ "sys.modules",
+ {"openai": mock_openai},
+ ),
+ patch(
+ "agentscope.tool._multi_modality._openai_tools."
+ "_to_openai_image_url",
+ ) as mock_to_url,
+ ):
+ mock_to_url.return_value = "https://example.com/image.jpg"
+
+ result = openai_image_to_text(
+ image_urls="https://example.com/image.jpg",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Failed to generate text: Vision API Error",
+ ),
+ ]
+
+
+class TestOpenAITextToAudio:
+ """Test cases for openai_text_to_audio function"""
+
+ def test_text_to_audio_success(self) -> None:
+ """Test successful audio generation"""
+ fake_audio_data = b"fake_audio_data"
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_response = Mock()
+ mock_response.content = fake_audio_data
+ mock_client.audio.speech.create.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ )
+ expected_base64 = base64.b64encode(fake_audio_data).decode("utf-8")
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ AudioBlock(
+ type="audio",
+ source={
+ "type": "base64",
+ "media_type": "audio/mp3",
+ "data": expected_base64,
+ },
+ ),
+ ]
+
+ def test_text_to_audio_different_format(self) -> None:
+ """Test audio generation with different format"""
+ fake_audio_data = b"fake_wav_data"
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_response = Mock()
+ mock_response.content = fake_audio_data
+ mock_client.audio.speech.create.return_value = mock_response
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ res_format="wav",
+ voice="echo",
+ speed=1.2,
+ )
+ expected_base64 = base64.b64encode(fake_audio_data).decode("utf-8")
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ AudioBlock(
+ type="audio",
+ source={
+ "type": "base64",
+ "media_type": "audio/wav",
+ "data": expected_base64,
+ },
+ ),
+ ]
+
+ def test_text_to_audio_exception(self) -> None:
+ """Test exception handling"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.audio.speech.create.side_effect = Exception(
+ "TTS API Error",
+ )
+
+ with patch.dict("sys.modules", {"openai": mock_openai}):
+ result = openai_text_to_audio(
+ text="Hello world",
+ api_key="test_key",
+ )
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Error: Failed to generate audio. TTS API Error",
+ ),
+ ]
+
+
+class TestOpenAIAudioToText:
+ """Test cases for openai_audio_to_text function"""
+
+ def test_audio_to_text_local_file_success(self) -> None:
+ """Test successful processing of local audio file"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_transcription = Mock()
+ mock_transcription.text = "Hello, this is a test transcription"
+ mock_client.audio.transcriptions.create.return_value = (
+ mock_transcription
+ )
+
+ with (
+ patch.dict("sys.modules", {"openai": mock_openai}),
+ patch(
+ "agentscope.tool._multi_modality._openai_tools.os.path.exists",
+ ) as mock_exists,
+ patch(
+ "builtins.open",
+ mock_open(read_data=b"fake_audio_data"),
+ ),
+ ):
+ mock_exists.return_value = True
+
+ result = openai_audio_to_text(
+ audio_file_url="./audio.mp3",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Hello, this is a test transcription",
+ ),
+ ]
+
+ def test_audio_to_text_url_success(self) -> None:
+ """Test successful processing of audio URL"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_transcription = Mock()
+ mock_transcription.text = "URL audio transcription"
+ mock_client.audio.transcriptions.create.return_value = (
+ mock_transcription
+ )
+
+ with patch.dict("sys.modules", {"openai": mock_openai}), patch(
+ "agentscope.tool._multi_modality._openai_tools.requests.get",
+ ) as mock_requests:
+ # Mock requests
+ mock_response = Mock()
+ mock_response.content = b"fake_audio_data"
+ mock_response.raise_for_status.return_value = None
+ mock_requests.return_value = mock_response
+
+ result = openai_audio_to_text(
+ audio_file_url="https://example.com/audio.mp3",
+ api_key="test_key",
+ language="zh",
+ temperature=0.5,
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="URL audio transcription",
+ ),
+ ]
+
+ def test_audio_to_text_file_not_found(self) -> None:
+ """Test error handling when local file not found"""
+ with patch(
+ "agentscope.tool._multi_modality._openai_tools.os.path.exists",
+ ) as mock_exists:
+ mock_exists.return_value = False
+
+ result = openai_audio_to_text(
+ audio_file_url="./nonexistent.mp3",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Error: Failed to transcribe audio: File not found: "
+ "./nonexistent.mp3",
+ ),
+ ]
+
+ def test_audio_to_text_api_exception(self) -> None:
+ """Test exception handling during API call"""
+ mock_openai = MagicMock()
+ mock_client = Mock()
+ mock_openai.OpenAI.return_value = mock_client
+ mock_client.audio.transcriptions.create.side_effect = Exception(
+ "Transcription Error",
+ )
+
+ with (
+ patch.dict("sys.modules", {"openai": mock_openai}),
+ patch(
+ "agentscope.tool._multi_modality._openai_tools.requests.get",
+ ) as mock_requests,
+ ):
+ # Mock requests
+ mock_response = Mock()
+ mock_response.content = b"fake_audio_data"
+ mock_response.raise_for_status.return_value = None
+ mock_requests.return_value = mock_response
+
+ result = openai_audio_to_text(
+ audio_file_url="https://example.com/audio.mp3",
+ api_key="test_key",
+ )
+
+ assert isinstance(result, ToolResponse)
+ assert result.content == [
+ TextBlock(
+ type="text",
+ text="Error: Failed to transcribe audio: Transcription Error",
+ ),
+ ]
diff --git a/tests/tool_test.py b/tests/tool_test.py
new file mode 100644
index 000000000..4d44ead83
--- /dev/null
+++ b/tests/tool_test.py
@@ -0,0 +1,329 @@
+# -*- coding: utf-8 -*-
+"""The tool module unit tests"""
+
+import os
+import tempfile
+from unittest import IsolatedAsyncioTestCase
+
+import shortuuid
+
+from agentscope.tool import (
+ execute_python_code,
+ execute_shell_command,
+ view_text_file,
+ write_text_file,
+ insert_text_file,
+)
+
+
+class ToolTest(IsolatedAsyncioTestCase):
+ """Test cases for the tool module."""
+
+ def setUp(self) -> None:
+ """Set up the test environment."""
+ self.path_file = "./tmp.txt"
+ if os.path.exists(self.path_file):
+ os.remove(self.path_file)
+
+ async def test_execute_python_code(self) -> None:
+ """Test executing Python code."""
+
+ # empty output
+ res = await execute_python_code(code="a = 1 + 1")
+ self.assertEqual(
+ "<returncode>0</returncode>"
+ "<stdout></stdout>"
+ "<stderr></stderr>",
+ res.content[0]["text"],
+ )
+
+ # with output
+ res = await execute_python_code(code="print('Hello, World!')")
+ self.assertEqual(
+ "<returncode>0</returncode>"
+ "<stdout>Hello, World!\n</stdout>"
+ "<stderr></stderr>",
+ res.content[0]["text"],
+ )
+
+ # with exception
+ res = await execute_python_code(code="raise Exception('Test error')")
+ self.assertTrue(
+ res.content[0]["text"].startswith(
+ "<returncode>1</returncode>"
+ "<stdout></stdout>"
+ "<stderr>Traceback (most recent call last):\n File ",
+ ),
+ )
+ self.assertTrue(
+ res.content[0]["text"].endswith(
+ '.py", line 1, in <module>\n'
+ " raise Exception('Test error')\n"
+ "Exception: Test error\n"
+ "</stderr>",
+ ),
+ )
+
+ # with timeout
+ code = """print("123")
+import time
+time.sleep(5)
+print("456")"""
+
+ res = await execute_python_code(code)
+ self.assertEqual(
+ "<returncode>0</returncode>"
+ "<stdout>123\n456\n</stdout>"
+ "<stderr></stderr>",
+ res.content[0]["text"],
+ )
+
+ res = await execute_python_code(code, timeout=2)
+ self.assertEqual(
+ "<returncode>-1</returncode>"
+ "<stdout>123\n</stdout>"
+ "<stderr>TimeoutError: The code execution exceeded the "
+ "timeout of 2 seconds.</stderr>",
+ res.content[0]["text"],
+ )
+
+ async def test_execute_shell_command(self) -> None:
+ """Test executing shell command."""
+ # empty output
+ res = await execute_shell_command(command="echo 'Hello, World!'")
+ self.assertEqual(
+ "<returncode>0</returncode>"
+ "<stdout>Hello, World!\n</stdout>"
+ "<stderr></stderr>",
+ res.content[0]["text"],
+ )
+
+ # with exception
+ res = await execute_shell_command(command="non_existent_command")
+ self.assertEqual(
+ "<returncode>127</returncode>"
+ "<stdout></stdout>"
+ "<stderr>/bin/sh: non_existent_command: command not found\n"
+ "</stderr>",
+ res.content[0]["text"],
+ )
+
+ # with timeout
+ res = await execute_shell_command(
+ command='echo "123"; sleep 5; echo "456"',
+ )
+ self.assertEqual(
+ "<returncode>0</returncode>"
+ "<stdout>123\n456\n</stdout>"
+ "<stderr></stderr>",
+ res.content[0]["text"],
+ )
+
+ res = await execute_shell_command(
+ command='echo "123"; sleep 5; echo "456"',
+ timeout=2,
+ )
+ self.assertEqual(
+ "<returncode>-1</returncode>"
+ "<stdout>123\n</stdout>"
+ "<stderr>TimeoutError: The command execution exceeded "
+ "the timeout of 2 seconds.</stderr>",
+ res.content[0]["text"],
+ )
+
+ async def test_view_text_file(self) -> None:
+ """Test viewing text file."""
+ with tempfile.TemporaryDirectory() as temp_dir:
+ temp_file = os.path.join(temp_dir, f"tmp_{shortuuid.uuid()}.txt")
+ with open(temp_file, "w", encoding="utf-8") as f:
+ f.write("""1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n""")
+
+ # View the whole file
+ res = await view_text_file(file_path=temp_file)
+ self.assertEqual(
+ f"The content of {temp_file}:\n```\n1: 1\n2: 2\n3: 3\n"
+ f"4: 4\n5: 5\n6: 6\n7: 7\n8: 8\n9: 9\n10: 10\n```",
+ res.content[0]["text"],
+ )
+
+ # View a specific range
+ res = await view_text_file(temp_file, ranges=[3, 5])
+ self.assertEqual(
+ f"The content of {temp_file} in [3, 5] lines:\n"
+ f"```\n3: 3\n4: 4\n5: 5\n```",
+ res.content[0]["text"],
+ )
+
+ # View a range that exceeds the file length
+ res = await view_text_file(temp_file, ranges=[8, 13])
+ self.assertEqual(
+ f"The content of {temp_file} in [8, 13] lines:\n"
+ f"```\n8: 8\n9: 9\n10: 10\n```",
+ res.content[0]["text"],
+ )
+
+ # View a range that is invalid
+ res = await view_text_file(temp_file, ranges=[11, 13])
+ self.assertEqual(
+ f"InvalidArgumentError: The range '[11, 13]' is out of "
+ f"bounds for the file '{temp_file}', which has only 10 lines.",
+ res.content[0]["text"],
+ )
+
+ # View invalid file path
+ res = await view_text_file(file_path="non_existent_file.txt")
+ self.assertEqual(
+ "Error: The file non_existent_file.txt does not exist.",
+ res.content[0]["text"],
+ )
+
+ # View a non-file path
+ res = await view_text_file("/")
+ self.assertEqual(
+ "Error: The path / is not a file.",
+ res.content[0]["text"],
+ )
+
+ async def test_write_text_file(self) -> None:
+ """Test writing to text file."""
+ # create and write a new file
+ res = await write_text_file(
+ self.path_file,
+ "a\nb\nc\n",
+ None,
+ )
+ self.assertEqual(
+ "Create and write ./tmp.txt successfully.",
+ res.content[0]["text"],
+ )
+
+ # replace content
+ res = await write_text_file(
+ self.path_file,
+ "d\n",
+ [2, 2],
+ )
+ self.assertEqual(
+ "Write ./tmp.txt successfully. The new content snippet:\n"
+ "```\n1: a\n2: d\n3: c\n```",
+ res.content[0]["text"],
+ )
+
+ async def test_insert_text_file(self) -> None:
+ """Test inserting text into a file."""
+ with open(self.path_file, "w", encoding="utf-8") as f:
+ f.write("\n".join([str(_) for _ in range(50)]))
+ res = await insert_text_file(
+ self.path_file,
+ "d",
+ line_number=1,
+ )
+ self.assertEqual(
+ res.content[0]["text"],
+ "Insert content into ./tmp.txt at line 1 successfully. "
+ "The new content between lines 1-7 is:\n"
+ "```\n"
+ "1: d\n"
+ "2: 0\n"
+ "3: 1\n"
+ "4: 2\n"
+ "5: 3\n"
+ "6: 4\n"
+ "7: 5\n"
+ "```",
+ )
+
+ res = await insert_text_file(
+ self.path_file,
+ "e",
+ line_number=25,
+ )
+ self.assertEqual(
+ res.content[0]["text"],
+ "Insert content into ./tmp.txt at line 25 successfully. "
+ "The new content between lines 20-31 is:\n"
+ "```\n"
+ "20: 18\n"
+ "21: 19\n"
+ "22: 20\n"
+ "23: 21\n"
+ "24: 22\n"
+ "25: e\n"
+ "26: 23\n"
+ "27: 24\n"
+ "28: 25\n"
+ "29: 26\n"
+ "30: 27\n"
+ "31: 28\n"
+ "```",
+ )
+
+ res = await insert_text_file(
+ self.path_file,
+ "\n".join(["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"]),
+ line_number=25,
+ )
+ self.assertEqual(
+ res.content[0]["text"],
+ "Insert content into ./tmp.txt at line 25 successfully. "
+ "The new content between lines 20-40 is:\n"
+ "```\n"
+ "20: 18\n"
+ "21: 19\n"
+ "22: 20\n"
+ "23: 21\n"
+ "24: 22\n"
+ "25: a\n"
+ "26: b\n"
+ "27: c\n"
+ "28: d\n"
+ "29: e\n"
+ "30: f\n"
+ "31: g\n"
+ "32: h\n"
+ "33: i\n"
+ "34: j\n"
+ "35: e\n"
+ "36: 23\n"
+ "37: 24\n"
+ "38: 25\n"
+ "39: 26\n"
+ "40: 27\n"
+ "```",
+ )
+
+ res = await insert_text_file(
+ self.path_file,
+ "The\nlast\nline",
+ 63,
+ )
+ self.assertEqual(
+ res.content[0]["text"],
+ "Insert content into ./tmp.txt at line 63 successfully. "
+ "The new content between lines 58-65 is:\n"
+ "```\n"
+ "58: 45\n"
+ "59: 46\n"
+ "60: 47\n"
+ "61: 48\n"
+ "62: 49\n"
+ "63: The\n"
+ "64: last\n"
+ "65: line```",
+ )
+
+ res = await insert_text_file(
+ self.path_file,
+ "end\nof\ntest",
+ 100,
+ )
+ self.assertEqual(
+ res.content[0]["text"],
+ "InvalidArgumentsError: The given line_number (100) is "
+ "not in the valid range [1, 66].",
+ )
+
+ def tearDown(self) -> None:
+ """Clean up after tests."""
+ if os.path.exists(self.path_file):
+ os.remove(self.path_file)
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
new file mode 100644
index 000000000..01556dc06
--- /dev/null
+++ b/tests/toolkit_test.py
@@ -0,0 +1,851 @@
+# -*- coding: utf-8 -*-
+"""Test toolkit module in agentscope."""
+import asyncio
+import time
+from copy import deepcopy
+from functools import partial
+from typing import Union, Optional, Any, AsyncGenerator, Generator, Tuple
+from unittest import IsolatedAsyncioTestCase
+
+from pydantic import BaseModel, Field
+
+from agentscope.message import ToolUseBlock, TextBlock
+from agentscope.tool import ToolResponse, Toolkit
+
+
+async def aenumerate(
+ agen: AsyncGenerator[ToolResponse, None],
+) -> AsyncGenerator[Tuple[int, ToolResponse], None]:
+ """Asynchronous enumerate function."""
+ n = 0
+ async for item in agen:
+ yield n, item
+ n += 1
+
+
+response1 = ToolResponse(
+ content=[TextBlock(type="text", text="1")],
+ stream=True,
+)
+response2 = ToolResponse(
+ content=[TextBlock(type="text", text="12")],
+ stream=True,
+)
+response3 = ToolResponse(
+ content=[TextBlock(type="text", text="123")],
+ is_last=True,
+)
+
+
+async def async_func(raise_cancel: bool) -> ToolResponse:
+ """An async function for testing."""
+ if raise_cancel:
+ await asyncio.sleep(1)
+ raise asyncio.CancelledError("test")
+ return response1
+
+
+def sync_func(
+ arg1: int,
+ arg2: Optional[list[Union[str, int]]] = None,
+) -> ToolResponse:
+ """A sync function for testing.
+
+ Long description.
+
+ Args:
+ arg1 (`int`):
+ Test argument 1.
+ arg2 (`Optional[list[Union[str, int]]]`, defaults to `None`):
+ Test argument 2.
+ """
+ time.sleep(1)
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"arg1: {arg1}, arg2: {arg2}",
+ ),
+ ],
+ )
+
+
+async def async_generator_func(
+ raise_cancel: bool,
+) -> AsyncGenerator[ToolResponse, None]:
+ """An async generator function for testing."""
+ yield response1
+ yield deepcopy(response2)
+ if raise_cancel:
+ await asyncio.sleep(1)
+ raise asyncio.CancelledError("test")
+ yield response3
+
+
+async def async_func_return_async_generator(
+ raise_cancel: bool,
+) -> AsyncGenerator[ToolResponse, None]:
+ """Async function that returns async generator"""
+ return async_generator_func(raise_cancel=raise_cancel)
+
+
+async def async_func_return_sync_generator() -> Generator[
+ ToolResponse,
+ None,
+ None,
+]:
+ """Async function that returns sync generator"""
+ return sync_generator_func()
+
+
+def sync_generator_func() -> Generator[ToolResponse, None, None]:
+ """A sync generator function for testing."""
+ yield response1
+ yield response2
+ yield response3
+
+
+class StructuredModel(BaseModel):
+ """Test structured model"""
+
+ arg3: int = Field(description="Test argument 3.")
+
+
+class ToolkitTest(IsolatedAsyncioTestCase):
+ """Unittest for the toolkit module."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the test environment before each test."""
+ self.toolkit = Toolkit()
+
+ async def test_basic_functionalities(self) -> None:
+ """Test sync function:
+ 1. register tool function
+ 2. set/cancel extended model
+ 3. get JSON schemas
+ 4. call tool function
+ """
+ self.toolkit.register_tool_function(
+ tool_func=sync_func,
+ preset_kwargs={"arg1": 55},
+ )
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "sync_func",
+ "parameters": {
+ "properties": {
+ "arg2": {
+ "anyOf": [
+ {
+ "items": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "integer",
+ },
+ ],
+ },
+ "type": "array",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "default": None,
+ "description": "Test argument 2.",
+ },
+ },
+ "type": "object",
+ },
+ "description": "A sync function for testing.\n\n"
+ "Long description.",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+
+ # Test extended model
+ self.toolkit.set_extended_model(
+ "sync_func",
+ StructuredModel,
+ )
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "sync_func",
+ "parameters": {
+ "properties": {
+ "arg2": {
+ "anyOf": [
+ {
+ "items": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "integer",
+ },
+ ],
+ },
+ "type": "array",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "default": None,
+ "description": "Test argument 2.",
+ },
+ "arg3": {
+ "description": "Test argument 3.",
+ "type": "integer",
+ },
+ },
+ "type": "object",
+ "required": [
+ "arg3",
+ ],
+ },
+ "description": "A sync function for testing.\n\n"
+ "Long description.",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+
+ self.toolkit.set_extended_model("sync_func", None)
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "sync_func",
+ "parameters": {
+ "properties": {
+ "arg2": {
+ "anyOf": [
+ {
+ "items": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "integer",
+ },
+ ],
+ },
+ "type": "array",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "default": None,
+ "description": "Test argument 2.",
+ },
+ },
+ "type": "object",
+ },
+ "description": "A sync function for testing.\n\n"
+ "Long description.",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="sync_func",
+ input={"arg2": [1, 2, 3]},
+ ),
+ )
+ async for chunk in res:
+ self.assertEqual(
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ type="text",
+ text="arg1: 55, arg2: [1, 2, 3]",
+ ),
+ ],
+ ),
+ chunk,
+ )
+
+ async def test_detailed_arguments(self) -> None:
+ """Verify the arguments in `register_tool_function`."""
+
+ def func(
+ *args: Any, # pylint: disable=unused-argument
+ **kwargs: Any,
+ ) -> ToolResponse:
+ """A test function.
+
+ Note this function is test.
+ """
+ return ToolResponse(content=[])
+
+ # Test positional and keyword arguments
+ self.toolkit.register_tool_function(
+ func,
+ include_var_positional=False,
+ include_var_keyword=False,
+ )
+
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "func",
+ "parameters": {
+ "properties": {},
+ "type": "object",
+ },
+ "description": "A test function.\n\n"
+ "Note this function is test.",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+
+ self.toolkit.remove_tool_function("func")
+
+ # Test func_description
+ self.toolkit.register_tool_function(func, func_description="你好")
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "func",
+ "parameters": {
+ "properties": {},
+ "type": "object",
+ },
+ "description": "你好",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+ self.toolkit.remove_tool_function("func")
+
+ # Test long description
+ self.toolkit.register_tool_function(
+ func,
+ include_long_description=False,
+ )
+ self.assertListEqual(
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "func",
+ "parameters": {
+ "properties": {},
+ "type": "object",
+ },
+ "description": "A test function.",
+ },
+ },
+ ],
+ self.toolkit.get_json_schemas(),
+ )
+
+ async def _verify_async_generator_wo_interruption(
+ self,
+ async_generator: AsyncGenerator[ToolResponse, None],
+ ) -> None:
+ """Verify async generator without interruption."""
+ async for index, chunk in aenumerate(async_generator):
+ if index == 0:
+ assert chunk == response1
+ elif index == 1:
+ assert chunk == response2
+ elif index == 2:
+ assert chunk == response3
+
+ async def test_async_func(self) -> None:
+ """Test asynchronous tool function"""
+ self.toolkit.register_tool_function(async_func)
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_func",
+ input={"raise_cancel": False},
+ ),
+ )
+ async for chunk in res:
+ self.assertEqual(
+ response1,
+ chunk,
+ )
+
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_func",
+ input={"raise_cancel": True},
+ ),
+ )
+ async for chunk in res:
+ self.assertEqual(
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ type="text",
+ text="<system-info>"
+ "The tool call has been interrupted by the "
+ "user.</system-info>",
+ ),
+ ],
+ is_last=True,
+ stream=True,
+ is_interrupted=True,
+ ),
+ chunk,
+ )
+
+ async def test_register_async_generator_func(self) -> None:
+ """Test asynchronous generator function"""
+ # Without interruption
+ self.toolkit.register_tool_function(async_generator_func)
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_generator_func",
+ input={"raise_cancel": False},
+ ),
+ )
+ await self._verify_async_generator_wo_interruption(res)
+
+ # With interruption
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_generator_func",
+ input={"raise_cancel": True},
+ ),
+ )
+ async for index, chunk in aenumerate(res):
+ if index == 0:
+ self.assertEqual(response1, chunk)
+ elif index == 1:
+ self.assertEqual(response2, chunk)
+ elif index == 2:
+ self.assertEqual(
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ type="text",
+ text="12",
+ ),
+ TextBlock(
+ type="text",
+ text="<system-info>The tool call has been "
+ "interrupted by the user.</system-info>",
+ ),
+ ],
+ stream=True,
+ is_last=True,
+ is_interrupted=True,
+ ),
+ chunk,
+ )
+
+ async def test_register_async_func_return_async_generator(self) -> None:
+ """Test async function that returns async generator"""
+ # Without interruption
+ self.toolkit.register_tool_function(async_func_return_async_generator)
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_func_return_async_generator",
+ input={"raise_cancel": False},
+ ),
+ )
+ await self._verify_async_generator_wo_interruption(res)
+
+ # With interruption
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_func_return_async_generator",
+ input={"raise_cancel": True},
+ ),
+ )
+ async for index, chunk in aenumerate(res):
+ if index == 0:
+ self.assertEqual(response1, chunk)
+ elif index == 1:
+ self.assertEqual(response2, chunk)
+ elif index == 2:
+ self.assertEqual(
+ ToolResponse(
+ id=chunk.id,
+ content=[
+ TextBlock(
+ type="text",
+ text="12",
+ ),
+ TextBlock(
+ type="text",
+ text="<system-info>The tool call has been "
+ "interrupted by the user.</system-info>",
+ ),
+ ],
+ stream=True,
+ is_last=True,
+ is_interrupted=True,
+ ),
+ chunk,
+ )
+
+ async def test_register_async_func_return_sync_generator(self) -> None:
+ """Test async function that returns sync generator"""
+ self.toolkit.register_tool_function(async_func_return_sync_generator)
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="async_func_return_sync_generator",
+ input={},
+ ),
+ )
+ await self._verify_async_generator_wo_interruption(res)
+
+ async def test_register_sync_generator_func(self) -> None:
+ """Text sync generator function"""
+ self.toolkit.register_tool_function(sync_generator_func)
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="sync_generator_func",
+ input={},
+ ),
+ )
+ await self._verify_async_generator_wo_interruption(res)
+
+ async def test_create_tool_group(self) -> None:
+ """Test tool group functionalities."""
+
+ with self.assertRaises(ValueError):
+ self.toolkit.register_tool_function(
+ sync_func,
+ group_name="my_group",
+ )
+
+ self.toolkit.create_tool_group(
+ "my_group",
+ "Browser use related tools.",
+ active=False,
+ )
+
+ self.toolkit.register_tool_function(
+ sync_func,
+ group_name="my_group",
+ )
+
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [],
+ )
+
+ # Active the tool group
+ self.toolkit.update_tool_groups(["my_group"], True)
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "sync_func",
+ "parameters": {
+ "properties": {
+ "arg1": {
+ "description": "Test argument 1.",
+ "type": "integer",
+ },
+ "arg2": {
+ "anyOf": [
+ {
+ "items": {
+ "anyOf": [
+ {"type": "string"},
+ {"type": "integer"},
+ ],
+ },
+ "type": "array",
+ },
+ {"type": "null"},
+ ],
+ "default": None,
+ "description": "Test argument 2.",
+ },
+ },
+ "required": ["arg1"],
+ "type": "object",
+ },
+ "description": "A sync function for testing.\n\n"
+ "Long description.",
+ },
+ },
+ ],
+ )
+
+ # Deactivate the tool group
+ self.toolkit.update_tool_groups(["my_group"], False)
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [],
+ )
+
+ # Unregister the tool group
+ self.toolkit.remove_tool_groups(["my_group"])
+ self.assertDictEqual(
+ self.toolkit.tools,
+ {},
+ )
+
+ async def test_postprocess_func(self) -> None:
+ """Test postprocess function."""
+ tool_use_block = ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="sync_func",
+ input={"arg1": 10, "arg2": ["test"]},
+ )
+
+ def postprocess_func(
+ tool_use: ToolUseBlock,
+ tool_response: ToolResponse,
+ ) -> ToolResponse | None:
+ """Postprocess function to modify tool response."""
+
+ self.assertEqual(tool_use, tool_use_block)
+
+ if tool_response.content:
+ tool_response.content.append(
+ TextBlock(type="text", text="Processed"),
+ )
+ return tool_response
+
+ self.toolkit.register_tool_function(
+ sync_func,
+ postprocess_func=postprocess_func,
+ )
+
+ res = await self.toolkit.call_tool_function(tool_use_block)
+
+ async for chunk in res:
+ print(chunk)
+ self.assertEqual(
+ chunk.content,
+ [
+ TextBlock(type="text", text="arg1: 10, arg2: ['test']"),
+ TextBlock(type="text", text="Processed"),
+ ],
+ )
+
+ async def test_partial_function(self) -> None:
+ """Test the partial function registration."""
+
+ def example_func(
+ a: int,
+ b: str,
+ c: list[str],
+ d: str = "abc",
+ ) -> ToolResponse:
+ """Example function for partial testing"""
+ return ToolResponse(
+ content=[
+ TextBlock(
+ type="text",
+ text=f"Received: a={a}, b={b}, c={c}, d={d}",
+ ),
+ ],
+ )
+
+ partial_func = partial(example_func, 1, c=[1, 2, 3])
+
+ self.toolkit.register_tool_function(partial_func)
+
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "example_func",
+ "parameters": {
+ "properties": {
+ "b": {
+ "type": "string",
+ },
+ "d": {
+ "default": "abc",
+ "type": "string",
+ },
+ },
+ "required": [
+ "b",
+ ],
+ "type": "object",
+ },
+ "description": "Example function for partial testing",
+ },
+ },
+ ],
+ )
+
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="example_func",
+ input={"b": "test", "d": "xyz"},
+ ),
+ )
+
+ async for chunk in res:
+ self.assertEqual(
+ chunk.content[0]["text"],
+ "Received: a=1, b=test, c=[1, 2, 3], d=xyz",
+ )
+
+ async def test_meta_tool(self) -> None:
+ """Test the meta tool."""
+ self.toolkit.register_tool_function(
+ self.toolkit.reset_equipped_tools,
+ )
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "reset_equipped_tools",
+ "parameters": {
+ "properties": {},
+ "type": "object",
+ },
+ "description": (
+ "Choose appropriate tools to equip yourself "
+ "with, so that you can\n\n"
+ "finish your task. Each argument in this function "
+ "represents a group\n"
+ "of related tools, and the value indicates "
+ "whether to activate the\n"
+ "group or not. Besides, the tool response of "
+ "this function will\n"
+ "contain the precaution notes for using them, "
+ "which you\n"
+ "**MUST pay attention to and follow**. You can "
+ "also reuse this function\n"
+ "to check the notes of the tool groups.\n\n"
+ "Note this function will `reset` the tools, so "
+ "that the original tools\n"
+ "will be removed first."
+ ),
+ },
+ },
+ ],
+ )
+ self.toolkit.create_tool_group(
+ "browser_use",
+ "The browser-use related tools.",
+ notes="""## About Browser-Use Tools
+1. You must xxx
+2. First click xxx
+""",
+ )
+ self.assertListEqual(
+ self.toolkit.get_json_schemas(),
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "reset_equipped_tools",
+ "parameters": {
+ "properties": {
+ "browser_use": {
+ "default": False,
+ "description": "The browser-use related "
+ "tools.",
+ "type": "boolean",
+ },
+ },
+ "type": "object",
+ },
+ "description": (
+ "Choose appropriate tools to equip yourself "
+ "with, so that you can\n\n"
+ "finish your task. Each argument in this function "
+ "represents a group\n"
+ "of related tools, and the value indicates "
+ "whether to activate the\n"
+ "group or not. Besides, the tool response of "
+ "this function will\n"
+ "contain the precaution notes for using them, "
+ "which you\n"
+ "**MUST pay attention to and follow**. You can "
+ "also reuse this function\n"
+ "to check the notes of the tool groups.\n\n"
+ "Note this function will `reset` the tools, so "
+ "that the original tools\n"
+ "will be removed first."
+ ),
+ },
+ },
+ ],
+ )
+ res = await self.toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="123",
+ name="reset_equipped_tools",
+ input={"browser_use": True},
+ ),
+ )
+
+ async for chunk in res:
+ self.assertEqual(
+ chunk.content[0]["text"],
+ "Active tool groups successfully: ['browser_use']. "
+ "You MUST follow these notes to use the tools:\n"
+ "<notes>## About browser_use Tools\n"
+ "## About Browser-Use Tools\n"
+ "1. You must xxx\n"
+ "2. First click xxx\n"
+ "</notes>",
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Clean up after each test."""
+ self.toolkit = None
diff --git a/tests/tracer_test.py b/tests/tracer_test.py
new file mode 100644
index 000000000..a56ccdef7
--- /dev/null
+++ b/tests/tracer_test.py
@@ -0,0 +1,381 @@
+# -*- coding: utf-8 -*-
+"""Unittests for the tracing functionality in AgentScope."""
+from typing import (
+ AsyncGenerator,
+ Generator,
+ Any,
+)
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope import _config
+from agentscope.agent import AgentBase
+from agentscope.embedding import EmbeddingModelBase
+from agentscope.formatter import FormatterBase
+from agentscope.message import (
+ TextBlock,
+ Msg,
+ ToolUseBlock,
+)
+from agentscope.model import ChatModelBase, ChatResponse
+from agentscope.tool import Toolkit, ToolResponse
+from agentscope.tracing import (
+ trace,
+ trace_llm,
+ trace_reply,
+ trace_format,
+ trace_embedding,
+)
+
+
+class TracingTest(IsolatedAsyncioTestCase):
+ """Test cases for tracing functionality"""
+
+ async def asyncSetUp(self) -> None:
+ """Set up the environment"""
+ _config.trace_enabled = True
+
+ async def test_trace(self) -> None:
+ """Test the basic tracing functionality"""
+
+ @trace(name="test_func")
+ async def test_func(x: int) -> int:
+ """Test async function""" ""
+ return x * 2
+
+ result = await test_func(5)
+ self.assertEqual(result, 10)
+
+ @trace(name="test_gen")
+ async def test_gen() -> AsyncGenerator[str, None]:
+ """Test async generator"""
+ for i in range(3):
+ yield f"chunk_{i}"
+
+ results = [_ async for _ in test_gen()]
+ self.assertListEqual(results, ["chunk_0", "chunk_1", "chunk_2"])
+
+ @trace(name="test_func_return_with_sync_gen")
+ async def test_func_return_with_sync_gen() -> Generator[
+ str,
+ None,
+ None,
+ ]:
+ """Test async func returning sync generator"""
+
+ def sync_gen() -> Generator[str, None, None]:
+ """sync generator"""
+ for i in range(3):
+ yield f"sync_chunk_{i}"
+
+ return sync_gen()
+
+ results = list(await test_func_return_with_sync_gen())
+ self.assertListEqual(
+ results,
+ ["sync_chunk_0", "sync_chunk_1", "sync_chunk_2"],
+ )
+
+ @trace(name="sync_func")
+ def sync_func(x: int) -> int:
+ """Test synchronous function"""
+ return x + 3
+
+ result = sync_func(4)
+ self.assertEqual(result, 7)
+
+ @trace(name="sync_gen")
+ def sync_gen() -> Generator[str, None, None]:
+ """Test synchronous generator"""
+ for i in range(3):
+ yield f"sync_chunk_{i}"
+
+ results = list(sync_gen())
+ self.assertListEqual(
+ results,
+ ["sync_chunk_0", "sync_chunk_1", "sync_chunk_2"],
+ )
+
+ @trace(name="sync_func_return_with_async_gen")
+ def sync_func_return_with_async_gen() -> AsyncGenerator[str, None]:
+ """Test sync func returning async generator"""
+
+ async def async_gen() -> AsyncGenerator[str, None]:
+ """async generator"""
+ for i in range(3):
+ yield f"chunk_{i}"
+
+ return async_gen()
+
+ results = [_ async for _ in sync_func_return_with_async_gen()]
+ self.assertListEqual(results, ["chunk_0", "chunk_1", "chunk_2"])
+
+ # Error handling
+ @trace(name="error_sync_func")
+ def error_sync_func() -> int:
+ """Test error handling in sync function"""
+ raise ValueError("Negative value not allowed")
+
+ with self.assertRaises(ValueError):
+ error_sync_func()
+
+ @trace(name="error_async_func")
+ async def error_async_func() -> int:
+ """Test error handling in async function"""
+ raise ValueError("Negative value not allowed")
+
+ with self.assertRaises(ValueError):
+ await error_async_func()
+
+ async def test_trace_llm(self) -> None:
+ """Test tracing LLM"""
+
+ class LLM(ChatModelBase):
+ """Test LLM class"""
+
+ def __init__(self, stream: bool, raise_error: bool) -> None:
+ """Initialize LLM"""
+ super().__init__("test", stream)
+ self.raise_error = raise_error
+
+ @trace_llm
+ async def __call__(
+ self,
+ messages: list[dict],
+ **kwargs: Any,
+ ) -> AsyncGenerator[ChatResponse, None] | ChatResponse:
+ """Simulate LLM call"""
+
+ if self.raise_error:
+ raise ValueError("Simulated error in LLM call")
+
+ if self.stream:
+
+ async def generator() -> AsyncGenerator[
+ ChatResponse,
+ None,
+ ]:
+ for i in range(3):
+ yield ChatResponse(
+ id=f"msg_{i}",
+ content=[
+ TextBlock(
+ type="text",
+ text="x" * (i + 1),
+ ),
+ ],
+ )
+
+ return generator()
+ return ChatResponse(
+ id="msg_0",
+ content=[
+ TextBlock(
+ type="text",
+ text="Hello, world!",
+ ),
+ ],
+ )
+
+ stream_llm = LLM(True, False)
+ res = [_.content async for _ in await stream_llm([])]
+ self.assertListEqual(
+ res,
+ [
+ [TextBlock(type="text", text="x")],
+ [TextBlock(type="text", text="xx")],
+ [TextBlock(type="text", text="xxx")],
+ ],
+ )
+
+ non_stream_llm = LLM(False, False)
+ res = await non_stream_llm([])
+ self.assertListEqual(
+ res.content,
+ [
+ TextBlock(type="text", text="Hello, world!"),
+ ],
+ )
+
+ error_llm = LLM(False, True)
+ with self.assertRaises(ValueError):
+ await error_llm([])
+
+ async def test_trace_reply(self) -> None:
+ """Test tracing reply"""
+
+ class Agent(AgentBase):
+ """Test Agent class"""
+
+ @trace_reply
+ async def reply(self, raise_error: bool = False) -> Msg:
+ """Simulate agent reply"""
+ if raise_error:
+ raise ValueError("Simulated error in reply")
+ return Msg(
+ "assistant",
+ [TextBlock(type="text", text="Hello, world!")],
+ "assistant",
+ )
+
+ async def observe(self, msg: Msg) -> None:
+ raise NotImplementedError()
+
+ async def handle_interrupt(
+ self,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Msg:
+ """Handle interrupt"""
+ raise NotImplementedError()
+
+ agent = Agent()
+ res = await agent()
+ self.assertListEqual(
+ res.content,
+ [TextBlock(type="text", text="Hello, world!")],
+ )
+
+ with self.assertRaises(ValueError):
+ await agent.reply(raise_error=True)
+
+ async def test_trace_format(self) -> None:
+ """Test tracing formatter"""
+
+ class Formatter(FormatterBase):
+ """Test Formatter class"""
+
+ @trace_format
+ async def format(self, raise_error: bool = False) -> list[dict]:
+ """Simulate formatting"""
+ if raise_error:
+ raise ValueError("Simulated error in formatting")
+ return [{"role": "user", "content": "Hello, world!"}]
+
+ formatter = Formatter()
+ res = await formatter.format()
+ self.assertListEqual(
+ res,
+ [{"role": "user", "content": "Hello, world!"}],
+ )
+
+ with self.assertRaises(ValueError):
+ await formatter.format(raise_error=True)
+
+ async def test_trace_toolkit(self) -> None:
+ """Test tracing toolkit"""
+ toolkit = Toolkit()
+
+ def func(raise_error: bool) -> ToolResponse:
+ """Test tool function"""
+ if raise_error:
+ raise ValueError("Simulated error in tool function")
+ return ToolResponse(
+ content=[
+ TextBlock(type="text", text="Tool executed successfully"),
+ ],
+ )
+
+ toolkit.register_tool_function(func)
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="func",
+ input={"raise_error": False},
+ ),
+ )
+ async for chunk in res:
+ self.assertListEqual(
+ chunk.content,
+ [TextBlock(type="text", text="Tool executed successfully")],
+ )
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="func",
+ input={"raise_error": True},
+ ),
+ )
+ async for chunk in res:
+ self.assertListEqual(
+ chunk.content,
+ [
+ TextBlock(
+ type="text",
+ text="Error: Simulated error in tool function",
+ ),
+ ],
+ )
+
+ async def gen_func(
+ raise_error: bool,
+ ) -> AsyncGenerator[ToolResponse, None]:
+ """Test async generator tool function"""
+ yield ToolResponse(
+ content=[TextBlock(type="text", text="Chunk 0")],
+ )
+ if raise_error:
+ raise ValueError(
+ "Simulated error in async generator tool function",
+ )
+ yield ToolResponse(
+ content=[TextBlock(type="text", text="Chunk 1")],
+ )
+
+ toolkit.register_tool_function(gen_func)
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="gen_func",
+ input={"raise_error": False},
+ ),
+ )
+ index = 0
+ async for chunk in res:
+ self.assertListEqual(
+ chunk.content,
+ [TextBlock(type="text", text=f"Chunk {index}")],
+ )
+ index += 1
+
+ res = await toolkit.call_tool_function(
+ ToolUseBlock(
+ type="tool_use",
+ id="xxx",
+ name="gen_func",
+ input={"raise_error": True},
+ ),
+ )
+ with self.assertRaises(ValueError):
+ async for _ in res:
+ pass
+
+ async def test_trace_embedding(self) -> None:
+ """Test tracing embedding"""
+
+ class EmbeddingModel(EmbeddingModelBase):
+ """Test embedding model class"""
+
+ def __init__(self) -> None:
+ """Initialize embedding model"""
+ super().__init__("test_embedding")
+
+ @trace_embedding
+ async def __call__(self, raise_error: bool) -> list[list[float]]:
+ """Simulate embedding call"""
+ if raise_error:
+ raise ValueError("Simulated error in embedding call")
+ return [[0, 1, 2]]
+
+ model = EmbeddingModel()
+ res = await model(False)
+ self.assertListEqual(res, [[0, 1, 2]])
+
+ with self.assertRaises(ValueError):
+ await model(True)
+
+ async def asyncTearDown(self) -> None:
+ """Tear down the environment"""
+ _config.trace_enabled = True
diff --git a/tests/user_input_test.py b/tests/user_input_test.py
new file mode 100644
index 000000000..4006b2afc
--- /dev/null
+++ b/tests/user_input_test.py
@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""The unittests for user input handling."""
+from typing import Literal
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch, MagicMock
+
+from pydantic import BaseModel, Field
+
+from agentscope.agent import UserAgent
+
+
+class UserInputTest(IsolatedAsyncioTestCase):
+ """The user input test class."""
+
+ @patch("builtins.input", side_effect=["Hi!", "sth", "apple"])
+ async def test_user_terminal_input(self, mock_input: MagicMock) -> None:
+ """Test the user input from terminal."""
+
+ user_agent = UserAgent("Alice")
+
+ class Choice(BaseModel):
+ """The choice model."""
+
+ thinking: str = Field(min_length=1, max_length=10)
+ """The thinking"""
+ decision: Literal["apple", "banana", "cherry"]
+
+ msg_res = await user_agent(structured_model=Choice)
+
+ self.assertEqual(
+ msg_res.content,
+ "Hi!",
+ )
+
+ self.assertEqual(
+ msg_res.metadata,
+ {
+ "thinking": "sth",
+ "decision": "apple",
+ },
+ )
+
+ self.assertEqual(mock_input.call_count, 3)