Skip to content

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

Enriched the current README.md and README_zh.md; Fix the bug in the ``handle_interrupt`` method of ``ReActAgent`` (#698)

DavdGaoa7c5c3fc346a
diff --git a/.github/workflows/toc.yml b/.github/workflows/toc.yml
new file mode 100644
index 000000000..66764c476
--- /dev/null
+++ b/.github/workflows/toc.yml
@@ -0,0 +1,25 @@
+name: Generate TOC
+on:
+ push:
+ paths:
+ - 'README.md'
+ - 'README_ZH.md'
+ branches-ignore:
+ - 'main'
+
+jobs:
+ generateTOC:
+ name: TOC Generator
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+
+ - uses: technote-space/toc-generator@v4
+ with:
+ TOC_TITLE: "## 📑 Table of Contents"
+ CREATE_PR: false
+ TARGET_PATHS: "README.md,README_ZH.md"
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ TOC_TITLE_MAP: |
+ README.md: ## 📑 Table of Contents
+ README_ZH.md: ## 📑 目录
\ No newline at end of file
diff --git a/README.md b/README.md
index 7fd35f871..041737d6c 100644
--- a/README.md
+++ b/README.md
@@ -57,30 +57,33 @@
Easy for beginners, powerful for experts.
+<p align="center">
+<img src="./assets/images/agentscope_v1_0822.png" alt="AgentScope Framework" width="80%"/>
+</p>
+
- **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.
+- **[Realtime Steering](https://doc.agentscope.io/tutorial/task_agent.html#realtime-steering)**: Native support for realtime interruption and customized handling.
+- **More Agentic**: Support [agentic tools management](https://doc.agentscope.io/tutorial/task_tool.html), [agentic long-term memory control](https://doc.agentscope.io/tutorial/task_long_term_memory.html) and agentic RAG, etc.
- **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:
+Quick overview of important features in **AgentScope 1.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 | |
+| | Support group-wise tools management | |
+| | Support agentic tools management by meta tool | |
| MCP | Support streamable HTTP/SSE/StdIO transport | [MCP](https://doc.agentscope.io/tutorial/task_mcp.html) |
+| | Support both **stateful** and **stateless** mode MCP Client | |
| | Support client- & function-level fine-grained control | |
| agent | Support async execution | |
| | Support parallel tool calls | |
@@ -88,15 +91,17 @@ Quick overview of AgentScope's new features in v1.0:
| | 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) |
+| tracing | Support OpenTelemetry-based tracing in LLM, tools, agent and formatter | [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) |
+| session | Provide session/application-level automatic 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) |
+| | Support truncation-based formatter strategy | |
| ... | | |
## 📢 News
+- **[2025-09]** **AgentScope Studio** is open-sourced now! Check out the [GitHub repo](https://github.com/agentscope-ai/agentscope-studio).
- **[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.
@@ -110,6 +115,23 @@ Welcome to join our community on
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## 📑 Table of Contents
+
+- [🚀 Quickstart](#-quickstart)
+ - [💻 Installation](#-installation)
+ - [🛠️ From source](#-from-source)
+ - [📦 From PyPi](#-from-pypi)
+- [Example](#example)
+ - [👋 Hello AgentScope!](#-hello-agentscope)
+ - [🎯 Realtime Steering](#-realtime-steering)
+- [🛠️ Fine-Grained MCP Control](#-fine-grained-mcp-control)
+ - [🧑‍🤝‍🧑 Multi-Agent Conversation](#-multi-agent-conversation)
+ - [💻 AgentScope Studio](#-agentscope-studio)
+- [📖 Documentation](#-documentation)
+- [⚖️ License](#-license)
+- [📚 Publications](#-publications)
+- [✨ Contributors](#-contributors)
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## 🚀 Quickstart
@@ -135,7 +157,9 @@ pip install -e .
pip install agentscope
```
-## 👋 Hello AgentScope!
+## Example
+
+### 👋 Hello AgentScope!
Start with a conversation between user and a ReAct agent 🤖 named "Friday"!
@@ -178,6 +202,112 @@ async def main():
asyncio.run(main())
```
+### 🎯 Realtime Steering
+
+Natively support **realtime interruption** in ``ReActAgent`` with robust memory preservation, and convert interruption into an **observable event** for agent to seamlessly resume conversations.
+
+<p align="center">
+ <img src="./assets/images/realtime_steering_zh.gif" alt="Realtime Steering" width="49%"/>
+ <img src="./assets/images/realtime_steering_en.gif" alt="Realtime Steering" width="49%"/>
+</p>
+
+## 🛠️ Fine-Grained MCP Control
+
+Developers can obtain the MCP tool as a **local callable function**, and use it anywhere (e.g. call directly, pass to agent, wrap into a more complex tool, etc.)
+
+```python
+from agentscope.mcp import HttpStatelessClient
+from agentscope.tool import Toolkit
+import os
+
+async def fine_grained_mcp_control():
+ # Initialize the MCP client
+ client = HttpStatelessClient(
+ name="gaode_mcp",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+ )
+
+ # Obtain the MCP tool as a **local callable function**, and use it anywhere
+ func = await client.get_callable_function(func_name="maps_geo")
+
+ # Option 1: Call directly
+ await func(address="Tiananmen Square", city="Beijing")
+
+ # Option 2: Pass to agent as a tool
+ toolkit = Toolkit()
+ toolkit.register_tool_function(func)
+ # ...
+
+ # Option 3: Wrap into a more complex tool
+ # ...
+```
+
+### 🧑‍🤝‍🧑 Multi-Agent Conversation
+
+AgentScope provides ``MsgHub`` and pipelines to streamline multi-agent conversations, offering efficient message routing and seamless information sharing
+
+```python
+from agentscope.pipeline import MsgHub, sequential_pipeline
+from agentscope.message import Msg
+import asyncio
+
+async def multi_agent_conversation():
+ # Create agents
+ agent1 = ...
+ agent2 = ...
+ agent3 = ...
+ agent4 = ...
+
+ # Create a message hub to manage multi-agent conversation
+ async with MsgHub(
+ participants=[agent1, agent2, agent3],
+ announcement=Msg("Host", "Introduce yourselves.", "assistant")
+ ) as hub:
+ # Speak in a sequential manner
+ await sequential_pipeline([agent1, agent2, agent3])
+ # Dynamic manage the participants
+ hub.add(agent4)
+ hub.delete(agent3)
+ await hub.broadcast(Msg("Host", "Goodbye!", "assistant"))
+
+asyncio.run(multi_agent_conversation())
+```
+
+### 💻 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
+```
+
+<p align="center">
+ <img
+ src="./assets/images/home.gif"
+ width="49%"
+ alt="home"
+ />
+ <img
+ src="./assets/images/projects.gif"
+ width="49%"
+ alt="projects"
+ />
+ <img
+ src="./assets/images/runtime.gif"
+ width="49%"
+ alt="runtime"
+ />
+ <img
+ src="./assets/images/friday.gif"
+ width="49%"
+ alt="friday"
+ />
+</p>
+
+
## 📖 Documentation
- Tutorial
@@ -200,6 +330,7 @@ asyncio.run(main())
- [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)
+ - [Pipeline](https://doc.agentscope.io/tutorial/task_pipeline.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)
@@ -210,17 +341,19 @@ asyncio.run(main())
- [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
-```
+- [Examples](https://github.com/agentscope-ai/agentscope/tree/main/examples)
+ - Game
+ - [Nine-player Werewolves](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
+ - Workflow
+ - [Multi-agent Debate](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_debate)
+ - [Multi-agent Conversation](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_conversation)
+ - Evaluation
+ - [ACEBench](https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench)
+ - Functional
+ - [ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/react_agent)
+ - [MCP](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_with_mcp)
+ - [Structured Output](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/structured_output)
+ - [Long-Term Memory](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory)
## ⚖️ License
@@ -230,29 +363,63 @@ AgentScope is released under Apache License 2.0.
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)
+- [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279)
+
+- [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
```
+@article{agentscope_v1,
+ author = {
+ Dawei Gao,
+ Zitao Li,
+ Yuexiang Xie,
+ Weirui Kuang,
+ Liuyi Yao,
+ Bingchen Qian,
+ Zhijian Ma,
+ Yue Cui,
+ Haohao Luo,
+ Shen Li,
+ Lu Yi,
+ Yi Yu,
+ Shiqi He,
+ Zhiling Luo,
+ Wenmeng Zhou,
+ Zhicheng Zhang,
+ Xuguang He,
+ Ziqian Chen,
+ Weikai Liao,
+ Farruh Isakulovich Kushnazarov,
+ Yaliang Li,
+ Bolin Ding,
+ Jingren Zhou}
+ title = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications},
+ journal = {CoRR},
+ volume = {abs/2508.16279},
+ year = {2025},
+}
+
@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}
+ author = {
+ Dawei Gao,
+ Zitao Li,
+ Xuchen Pan,
+ Weirui Kuang,
+ Zhijian Ma,
+ Bingchen Qian,
+ Fei Wei,
+ Wenhao Zhang,
+ Yuexiang Xie,
+ Daoyuan Chen,
+ Liuyi Yao,
+ Hongyi Peng,
+ Zeyu Zhang,
+ Lin Zhu,
+ Chen Cheng,
+ Hongzhu Shi,
+ Yaliang Li,
+ Bolin Ding,
+ Jingren Zhou}
title = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
journal = {CoRR},
volume = {abs/2402.14034},
@@ -266,4 +433,4 @@ 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
+</a>
diff --git a/README_zh.md b/README_zh.md
index d4f32ec6c..0c842d1b9 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -57,45 +57,52 @@
浅显入门,精深致用。
+<p align="center">
+<img src="./assets/images/agentscope_v1_0822.png" alt="AgentScope Framework" width="80%"/>
+</p>
+
- **对开发者透明**: 透明是 AgentScope 的**首要原则**。无论提示工程、API调用、智能体构建还是工作流程编排,坚持对开发者可见&可控。拒绝深度封装或隐式魔法。
-- **实时引导**: 支持在**任意**时刻打断智能体回复,并支持**自定义**处理方式。
+- **[实时介入](https://doc.agentscope.io/zh_CN/tutorial/task_agent.html#realtime-steering)**: 原生支持**实时**中断和**自定义**中断处理。
+- **更智能化**: 支持[智能体工具管理](https://doc.agentscope.io/zh_CN/tutorial/task_tool.html)、[智能体长期记忆控制](https://doc.agentscope.io/zh_CN/tutorial/task_long_term_memory.html)和智能化RAG等。
- **模型无关**: 一次编程,适配所有模型。
- **“乐高式”智能体构建**: 所有组件保持**模块化**且**相互独立**。
- **面向多智能体**:专为**多智能体**设计,**显式**的消息传递和工作流编排,拒绝深度封装。
-- **高度可定制**: 工具、提示、Agent、工作流、第三方库和可视化,AgentScope 支持&鼓励开发者进行定制。
-- **开发者友好**: 低代码开发,可视化追踪和监控。从开发到部署,一站式解决。
+- **高度可定制**: 工具、提示、智能体、工作流、第三方库和可视化,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) |
-| ... | | |
+| 模块 | 功能 | 文档 |
+|------------|----------------------------------------|-------------------------------------------------------------------------------|
+| 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) |
+| | 支持工具函数流式/非流式返回 | |
+| | 支持用户打断 | |
+| | 支持工具函数的后处理 | |
+| | 支持分组工具管理 | |
+| | 支持智能体通过 Meta Tool 自主管理工具 | |
+| MCP | 支持 Streamable HTTP/SSE/StdIO 传输 | [MCP](https://doc.agentscope.io/zh_CN/tutorial/task_mcp.html) |
+| | 支持**有状态**和**无状态**两种模式的MCP客户端 | |
+| | 支持客户端和函数级别的精细控制 | |
+| agent | 支持异步执行 | |
+| | 支持并行工具调用 | |
+| | 支持用户实时介入和自定义的中断处理 | |
+| | 支持自动状态管理 | |
+| | 允许智能体自主控制长期记忆 | |
+| | 支持智能体钩子函数 | |
+| tracing | 支持基于 OpenTelemetry 的 LLM、工具、智能体和格式化器追踪 | [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-09]** **AgentScope Studio** 现已开源!查看 [GitHub 仓库](https://github.com/agentscope-ai/agentscope-studio)。
- **[2025-08]** v1 版本 Tutorial 已上线!查看[tutorial](https://doc.agentscope.io/zh_CN/)了解更多详情。
- **[2025-08]** 🎉🎉 AgentScope v1现已发布!在完全拥抱异步执行的基础上提供许多新功能和改进。查看[changelog](https://github.com/agentscope-ai/agentscope/blob/main/docs/changelog.md)了解详细变更。
@@ -109,6 +116,23 @@ AgentScope v1.0 新功能概览:
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## 📑 Table of Contents
+
+- [🚀 快速开始](#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
+ - [💻 安装](#-%E5%AE%89%E8%A3%85)
+ - [🛠️ 从源码安装](#-%E4%BB%8E%E6%BA%90%E7%A0%81%E5%AE%89%E8%A3%85)
+ - [📦 从PyPi安装](#-%E4%BB%8Epypi%E5%AE%89%E8%A3%85)
+- [样例](#%E6%A0%B7%E4%BE%8B)
+ - [👋 Hello AgentScope!](#-hello-agentscope)
+ - [🎯 实时介入](#-%E5%AE%9E%E6%97%B6%E4%BB%8B%E5%85%A5)
+ - [🛠️ 细粒度 MCP 控制](#-%E7%BB%86%E7%B2%92%E5%BA%A6-mcp-%E6%8E%A7%E5%88%B6)
+ - [🧑‍🤝‍🧑 多智能体对话](#-%E5%A4%9A%E6%99%BA%E8%83%BD%E4%BD%93%E5%AF%B9%E8%AF%9D)
+ - [💻 AgentScope Studio](#-agentscope-studio)
+- [📖 文档](#-%E6%96%87%E6%A1%A3)
+- [⚖️ 许可](#-%E8%AE%B8%E5%8F%AF)
+- [📚 论文](#-%E8%AE%BA%E6%96%87)
+- [✨ 贡献者](#-%E8%B4%A1%E7%8C%AE%E8%80%85)
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## 🚀 快速开始
@@ -134,7 +158,9 @@ pip install -e .
pip install agentscope
```
-## 👋 Hello AgentScope!
+## 样例
+
+### 👋 Hello AgentScope!
使用 AgentScope 显式地创建一个名为“Friday”的助手🤖,并与之对话。
@@ -177,6 +203,113 @@ async def main():
asyncio.run(main())
```
+### 🎯 实时介入
+
+在 ``ReActAgent`` 中原生支持**实时介入**功能,提供面向打断的记忆处理机制,将中断转换为智能体的**可观察事件**,让智能体能够无缝恢复对话。
+
+<p align="center">
+ <img src="./assets/images/realtime_steering_zh.gif" alt="Realtime Steering" width="49%"/>
+ <img src="./assets/images/realtime_steering_en.gif" alt="Realtime Steering" width="49%"/>
+</p>
+
+### 🛠️ 细粒度 MCP 控制
+
+开发者能够以**本地可调用函数**的方式获得 MCP 工具,并以任意方式使用(例如直接调用、装备给智能体,或将其包装为更复杂的工具等)
+
+```python
+from agentscope.mcp import HttpStatelessClient
+from agentscope.tool import Toolkit
+import os
+
+async def fine_grained_mcp_control():
+ # 以高德MCP为例,初始化MCP客户端
+ client = HttpStatelessClient(
+ name="gaode_mcp",
+ transport="streamable_http",
+ url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
+ )
+
+ # 将MCP工具获取为**本地可调用函数**,并在任何地方使用
+ func = await client.get_callable_function(func_name="maps_geo")
+
+ # 选项1:直接调用
+ await func(address="天安门广场", city="北京")
+
+ # 选项2:作为工具传递给智能体
+ toolkit = Toolkit()
+ toolkit.register_tool_function(func)
+ # ...
+
+ # 选项3:包装为更复杂的工具
+ # ...
+```
+
+### 🧑‍🤝‍🧑 多智能体对话
+
+AgentScope 提供 ``MsgHub`` 和多种 pipeline 来简化多智能体对话的构建,提供高效的消息路由和无缝信息共享
+
+```python
+from agentscope.pipeline import MsgHub, sequential_pipeline
+from agentscope.message import Msg
+import asyncio
+
+async def multi_agent_conversation():
+ # 创建智能体
+ agent1 = ...
+ agent2 = ...
+ agent3 = ...
+ agent4 = ...
+
+ # 创建消息中心来管理多智能体对话
+ async with MsgHub(
+ participants=[agent1, agent2, agent3],
+ announcement=Msg("Host", "请介绍一下自己。", "assistant")
+ ) as hub:
+ # 按顺序发言
+ await sequential_pipeline([agent1, agent2, agent3])
+ # 动态管理参与者
+ hub.add(agent4)
+ hub.delete(agent3)
+ await hub.broadcast(Msg("Host", "再见!", "assistant"))
+
+asyncio.run(multi_agent_conversation())
+```
+
+
+### 💻 AgentScope Studio
+
+使用以下命令安装并启动 AgentScope Studio,以追踪和可视化基于 AgentScope 构建的智能体应用。
+
+```bash
+npm install -g @agentscope/studio
+
+as_studio
+```
+
+<p align="center">
+ <img
+ src="./assets/images/home.gif"
+ width="49%"
+ alt="home"
+ />
+ <img
+ src="./assets/images/projects.gif"
+ width="49%"
+ alt="projects"
+ />
+ <img
+ src="./assets/images/runtime.gif"
+ width="49%"
+ alt="runtime"
+ />
+ <img
+ src="./assets/images/friday.gif"
+ width="49%"
+ alt="friday"
+ />
+</p>
+
+
## 📖 文档
- 教程
@@ -210,16 +343,19 @@ asyncio.run(main())
- [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
-```
+- [示例](https://github.com/agentscope-ai/agentscope/tree/main/examples)
+ - 游戏
+ - [九人制狼人杀](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
+ - 工作流
+ - [多智能体辩论](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_debate)
+ - [多智能体对话](https://github.com/agentscope-ai/agentscope/tree/main/examples/workflows/multiagent_conversation)
+ - 评测
+ - [ACEBench](https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench)
+ - 功能演示
+ - [ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/react_agent)
+ - [MCP](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/agent_with_mcp)
+ - [结构化输出](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/structured_output)
+ - [长期记忆](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/long_term_memory)
## ⚖️ 许可
@@ -229,29 +365,63 @@ AgentScope 基于 Apache License 2.0发布。
如果我们的工作对您的研究或应用有帮助,请引用我们的论文。
-[AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
+- [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279)
+
+- [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034)
```
+@article{agentscope_v1,
+ author = {
+ Dawei Gao,
+ Zitao Li,
+ Yuexiang Xie,
+ Weirui Kuang,
+ Liuyi Yao,
+ Bingchen Qian,
+ Zhijian Ma,
+ Yue Cui,
+ Haohao Luo,
+ Shen Li,
+ Lu Yi,
+ Yi Yu,
+ Shiqi He,
+ Zhiling Luo,
+ Wenmeng Zhou,
+ Zhicheng Zhang,
+ Xuguang He,
+ Ziqian Chen,
+ Weikai Liao,
+ Farruh Isakulovich Kushnazarov,
+ Yaliang Li,
+ Bolin Ding,
+ Jingren Zhou}
+ title = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications},
+ journal = {CoRR},
+ volume = {abs/2508.16279},
+ year = {2025},
+}
+
@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}
+ author = {
+ Dawei Gao,
+ Zitao Li,
+ Xuchen Pan,
+ Weirui Kuang,
+ Zhijian Ma,
+ Bingchen Qian,
+ Fei Wei,
+ Wenhao Zhang,
+ Yuexiang Xie,
+ Daoyuan Chen,
+ Liuyi Yao,
+ Hongyi Peng,
+ Zeyu Zhang,
+ Lin Zhu,
+ Chen Cheng,
+ Hongzhu Shi,
+ Yaliang Li,
+ Bolin Ding,
+ Jingren Zhou}
title = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
journal = {CoRR},
volume = {abs/2402.14034},
@@ -264,6 +434,5 @@ AgentScope 基于 Apache License 2.0发布。
感谢所有贡献者:
<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" />
+ <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" />
</a>
-
diff --git a/assets/images/agentscope_v1_0822.png b/assets/images/agentscope_v1_0822.png
new file mode 100644
index 000000000..14950eb4c
Binary files /dev/null and b/assets/images/agentscope_v1_0822.png differ
diff --git a/assets/images/friday.gif b/assets/images/friday.gif
new file mode 100644
index 000000000..14670eee8
Binary files /dev/null and b/assets/images/friday.gif differ
diff --git a/assets/images/home.gif b/assets/images/home.gif
new file mode 100644
index 000000000..9a24757b9
Binary files /dev/null and b/assets/images/home.gif differ
diff --git a/assets/images/projects.gif b/assets/images/projects.gif
new file mode 100644
index 000000000..4800993c9
Binary files /dev/null and b/assets/images/projects.gif differ
diff --git a/assets/images/realtime_steering_en.gif b/assets/images/realtime_steering_en.gif
new file mode 100644
index 000000000..1e5b3846b
Binary files /dev/null and b/assets/images/realtime_steering_en.gif differ
diff --git a/assets/images/realtime_steering_zh.gif b/assets/images/realtime_steering_zh.gif
new file mode 100644
index 000000000..034e2591c
Binary files /dev/null and b/assets/images/realtime_steering_zh.gif differ
diff --git a/assets/images/runtime.gif b/assets/images/runtime.gif
new file mode 100644
index 000000000..28c54b802
Binary files /dev/null and b/assets/images/runtime.gif differ
diff --git a/examples/agent_deep_research/deep_research_agent.py b/examples/agent_deep_research/deep_research_agent.py
index f4b290be5..df3b6c503 100644
--- a/examples/agent_deep_research/deep_research_agent.py
+++ b/examples/agent_deep_research/deep_research_agent.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
"""Deep Research Agent"""
-# pylint: disable=too-many-lines
+# pylint: disable=too-many-lines, no-name-in-module
import os
import json
import asyncio
diff --git a/examples/agent_with_mcp/README.md b/examples/functionality/agent_with_mcp/README.md
similarity index 100%
rename from examples/agent_with_mcp/README.md
rename to examples/functionality/agent_with_mcp/README.md
diff --git a/examples/agent_with_mcp/main.py b/examples/functionality/agent_with_mcp/main.py
similarity index 100%
rename from examples/agent_with_mcp/main.py
rename to examples/functionality/agent_with_mcp/main.py
diff --git a/examples/agent_with_mcp/mcp_servers.py b/examples/functionality/agent_with_mcp/mcp_servers.py
similarity index 100%
rename from examples/agent_with_mcp/mcp_servers.py
rename to examples/functionality/agent_with_mcp/mcp_servers.py
diff --git a/examples/long_term_memory/mem0/README.md b/examples/functionality/long_term_memory/mem0/README.md
similarity index 100%
rename from examples/long_term_memory/mem0/README.md
rename to examples/functionality/long_term_memory/mem0/README.md
diff --git a/examples/long_term_memory/mem0/memory_example.py b/examples/functionality/long_term_memory/mem0/memory_example.py
similarity index 100%
rename from examples/long_term_memory/mem0/memory_example.py
rename to examples/functionality/long_term_memory/mem0/memory_example.py
diff --git a/examples/structured_output/README.md b/examples/functionality/structured_output/README.md
similarity index 100%
rename from examples/structured_output/README.md
rename to examples/functionality/structured_output/README.md
diff --git a/examples/structured_output/main.py b/examples/functionality/structured_output/main.py
similarity index 100%
rename from examples/structured_output/main.py
rename to examples/functionality/structured_output/main.py
diff --git a/examples/game/werewolf/README.md b/examples/game/werewolves/README.md
similarity index 80%
rename from examples/game/werewolf/README.md
rename to examples/game/werewolves/README.md
index deb00c15f..a639c9df6 100644
--- a/examples/game/werewolf/README.md
+++ b/examples/game/werewolves/README.md
@@ -1,8 +1,14 @@
-# 🐺⚔️👨‍🌾 Werewolf Game Powered by AgentScope
+# 🐺⚔️👨‍🌾 Nine-Player Werewolves Game
-This is a 9-players werewolf game example built using AgentScope, showcasing **multi-agent interactions**,
+This is a nine-players werewolves game example built using AgentScope, showcasing **multi-agent interactions**,
**role-based gameplay**, and **structured output handling**.
-Specifically, this game is consisted of three villagers, three werewolves, one seer, one witch and one hunter.
+Specifically, this game is consisted of
+
+- three villagers 👨‍🌾,
+- three werewolves 🐺,
+- one seer 🔮,
+- one witch 🧙‍♀️ and
+- one hunter 🏹.
## QuickStart
@@ -18,11 +24,11 @@ python main.py
Running the example with AgentScope Studio provides a more interactive experience.
-- Demo Video in Chinese:
+- Demo Video in Chinese (click to play):
[![Werewolf Game in Chinese](https://img.alicdn.com/imgextra/i3/6000000007235/O1CN011pK6Be23JgcdLWmLX_!!6000000007235-0-tbvideo.jpg)](https://cloud.video.taobao.com/vod/KxyR66_CWaWwu76OPTvOV2Ye1Gas3i5p4molJtzhn_s.mp4)
-- Demo Video in English:
+- Demo Video in English (click to play):
[![Werewolf Game in English](https://img.alicdn.com/imgextra/i3/6000000007389/O1CN011alyGK24SDcFBzHea_!!6000000007389-0-tbvideo.jpg)](https://cloud.video.taobao.com/vod/bMiRTfxPg2vm76wEoaIP2eJfkCi8CUExHRas-1LyK1I.mp4)
diff --git a/examples/game/werewolf/main.py b/examples/game/werewolves/main.py
similarity index 98%
rename from examples/game/werewolf/main.py
rename to examples/game/werewolves/main.py
index af0c544b7..c50026abf 100644
--- a/examples/game/werewolf/main.py
+++ b/examples/game/werewolves/main.py
@@ -89,12 +89,11 @@ async def create_player(role: str) -> ReActAgent:
async def main() -> None:
"""The main entry of the werewolf game"""
# Enable studio if you want
- import agentscope
-
- agentscope.init(
- studio_url="http://localhost:3000",
- project="Werewolf Game",
- )
+ # import agentscope
+ # agentscope.init(
+ # studio_url="http://localhost:3000",
+ # project="Werewolf Game",
+ # )
global healing, poison, villagers, werewolves, seer, witch, hunter
global current_alive
# Create players
diff --git a/examples/game/werewolf/prompt.py b/examples/game/werewolves/prompt.py
similarity index 100%
rename from examples/game/werewolf/prompt.py
rename to examples/game/werewolves/prompt.py
diff --git a/examples/game/werewolf/structured_output.py b/examples/game/werewolves/structured_output.py
similarity index 100%
rename from examples/game/werewolf/structured_output.py
rename to examples/game/werewolves/structured_output.py
diff --git a/examples/game/werewolf/utils.py b/examples/game/werewolves/utils.py
similarity index 100%
rename from examples/game/werewolf/utils.py
rename to examples/game/werewolves/utils.py
diff --git a/examples/react_agent/main.py b/examples/react_agent/main.py
index d5cbe89b4..ea3506a1d 100644
--- a/examples/react_agent/main.py
+++ b/examples/react_agent/main.py
@@ -35,7 +35,7 @@ async def main() -> None:
toolkit=toolkit,
memory=InMemoryMemory(),
)
- user = UserAgent("Bob")
+ user = UserAgent("User")
msg = None
while True:
diff --git a/src/agentscope/_version.py b/src/agentscope/_version.py
index 1f397c8a4..02673ce4f 100644
--- a/src/agentscope/_version.py
+++ b/src/agentscope/_version.py
@@ -1,4 +1,4 @@
# -*- coding: utf-8 -*-
"""The version of agentscope."""
-__version__ = "1.0.0"
+__version__ = "1.0.1"
diff --git a/src/agentscope/agent/_react_agent.py b/src/agentscope/agent/_react_agent.py
index a693a24d5..00f90335c 100644
--- a/src/agentscope/agent/_react_agent.py
+++ b/src/agentscope/agent/_react_agent.py
@@ -482,7 +482,6 @@ class ReActAgent(ReActAgentBase):
await self.print(response_msg, True)
await self.memory.add(response_msg)
- await self.memory.clear()
return response_msg
def generate_response(
diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.py
index 2e57b1064..b6b9813f3 100644
--- a/src/agentscope/formatter/_formatter_base.py
+++ b/src/agentscope/formatter/_formatter_base.py
@@ -35,13 +35,13 @@ class FormatterBase:
@staticmethod
def convert_tool_result_to_string(
- output: List[TextBlock | ImageBlock | AudioBlock],
+ output: str | 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]`):
+ output (`str | List[TextBlock | ImageBlock | AudioBlock]`):
The output of the tool response, including text and multimodal
data like images and audio.
@@ -52,6 +52,9 @@ class FormatterBase:
or URLs.
"""
+ if isinstance(output, str):
+ return output
+
textual_output = []
for block in output:
assert isinstance(block, dict) and "type" in block, (