Skip to content

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

docs(contributing): add CONTRIBUTING.md; adjust the example directories (#890)

DavdGao073d16d33514
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..ba8f4b686
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,245 @@
+# Contributing to AgentScope
+
+## Welcome! 🎉
+
+Thank you for your interest in contributing to AgentScope! As an open-source project, we warmly welcome and encourage
+contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing
+ideas, your contributions help make AgentScope better for everyone.
+
+## How to Contribute
+
+To ensure smooth collaboration and maintain the quality of the project, please follow these guidelines when contributing:
+
+### 1. Check Existing Plans and Issues
+
+Before starting your contribution, please review our development roadmap:
+
+- **Check the [Projects](https://github.com/orgs/agentscope-ai/projects/2) page** and **[Issues with `roadmap` label](https://github.com/agentscope-ai/agentscope/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** to see our planned development tasks.
+
+ - **If a related issue exists** and is marked as unassigned or open:
+ - Please comment on the issue to express your interest in working on it
+ - This helps avoid duplicate efforts and allows us to coordinate development
+
+ - **If no related issue exists**:
+ - Please create a new issue describing your proposed changes or feature
+ - Our team will respond promptly to provide feedback and guidance
+ - This helps us maintain the project roadmap and coordinate community efforts
+
+### 2. Commit Message Format
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This leads to more readable
+commit history and enables automatic changelog generation.
+
+**Format:**
+```
+<type>(<scope>): <subject>
+```
+
+**Types:**
+- `feat:` A new feature
+- `fix:` A bug fix
+- `docs:` Documentation only changes
+- `style:` Changes that do not affect the meaning of the code (white-space, formatting, etc)
+- `refactor:` A code change that neither fixes a bug nor adds a feature
+- `perf:` A code change that improves performance
+- `ci:` Adding missing tests or correcting existing tests
+- `chore:` Changes to the build process or auxiliary tools and libraries
+
+**Examples:**
+```bash
+feat(models): add support for Claude-3 model
+fix(agent): resolve memory leak in ReActAgent
+docs(readme): update installation instructions
+refactor(formatter): simplify message formatting logic
+ci(models): add unit tests for OpenAI integration
+```
+
+### 3. Code Development Guidelines
+
+#### a. Pre-commit Checks
+
+Before submitting code, you must run pre-commit hooks to ensure code quality and consistency:
+
+**Installation:**
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+**Running pre-commit:**
+```bash
+# Run on all files
+pre-commit run --all-files
+
+# Pre-commit will automatically run on git commit after installation
+```
+
+#### b. Import Statement Guidelines
+
+AgentScope follows a **lazy import principle** to minimize resource loading:
+
+- **DO**: Import modules only when they are actually used
+ ```python
+ def some_function():
+ import openai
+ # Use openai library here
+ ```
+
+This approach ensures that `import agentscope` remains lightweight and doesn't load unnecessary dependencies.
+
+#### c. Unit Tests
+
+- All new features must include appropriate unit tests
+- Ensure existing tests pass before submitting your PR
+- Run tests using:
+ ```bash
+ pytest tests
+ ```
+
+#### d. Documentation
+
+- Update relevant documentation for new features
+- Include code examples where appropriate
+- Update the README.md if your changes affect user-facing functionality
+
+
+## Types of Contributions
+
+### Adding New Chat Models
+
+AgentScope currently supports the following API providers at the chat model level: **OpenAI**, **DashScope**,
+**Gemini**, **Anthropic**, and **Ollama**. These APIs are compatible with various service providers including vLLM,
+DeepSeek, SGLang, and others.
+
+**⚠️ Important Notice:**
+
+Adding a new chat model is not merely a model-level task. It involves multiple components including:
+- Message formatters
+- Token counters
+- Tools API integration
+
+This is a substantial amount of work. To better focus our efforts on agent capability development and maintenance,
+**the official development team currently does not plan to add support for new chat model APIs**. However, when there
+is a strong need from the developer community, we will do our best to accommodate these requirements.
+
+**If you wish to contribute a new chat model**, here are the components needed to be compatible with the
+existing `ReActAgent` in the repository:
+
+#### Required Components:
+
+1. **Chat Model Class** (under `agentscope.model`):
+ ```python
+ from agentscope.model import ChatModelBase
+
+
+ class YourChatModel(ChatModelBase):
+ """
+ The functionalities that you need to consider include:
+ - Tools API integration
+ - Both streaming and non-streaming modes (compatible with tools API)
+ - tool_choice argument
+ - reasoning models
+ """
+ ```
+
+2. **Formatter Class** (under `agentscope.formatter`):
+ ```python
+ from agentscope.formatter import FormatterBase
+
+ class YourModelFormatter(FormatterBase):
+ """
+ Convert `Msg` objects into the format required by your API provider.
+ If your API doesn't support multi-agent scenarios (e.g. doesn't support the name field in messages), you need to
+ implement two separate formatter classes for chatbot and multi-agent scenarios.
+ """
+ ```
+
+3. **Token Counter** (under `agentscope.token`, recommended):
+ ```python
+ from agentscope.token import TokenCounterBase
+
+ class YourTokenCounter(TokenCounterBase):
+ """
+ Implement token counting logic for your model.
+ This is recommended but not strictly required.
+ """
+ ```
+
+### Adding New Agents
+
+To achieve true modularity, the `agentscope.agent` module currently aims to maintain only the **`ReActAgent`** class
+as the core implementation. We ensure all functionalities in this class are **modular, detachable, and composable**.
+
+In AgentScope, we follow an examples-first development workflow: prototype new implementations in the `examples/`
+directory, then abstract and modularize the functionality, and finally integrate it into the core library.
+
+For specialized or domain-specific agents, we recommend contributing them to the **`examples/agents`** directory:
+
+```
+examples/
+└── agents/
+ ├── main.py
+ ├── README.md # Explain the agent's purpose and usage
+ └── ... # The other scripts
+```
+
+### Adding New Examples
+
+We highly encourage contributions of new examples that showcase the capabilities of AgentScope.
+Please add them to the `examples/` directory with a clear README explaining the purpose and usage of the example.
+
+Now our examples are organized into subdirectories based on their type:
+
+- `examples/agent/` for specialized agents
+- `examples/functionality/` for showcasing specific functionalities of AgentScope
+- `examples/game/` for game-related examples
+- `examples/evaluation/` for evaluation scripts
+- `examples/workflows/` for workflow demonstrations
+- `examples/training/` for training-related examples
+
+An example structure could be:
+
+```
+examples/
+└── {example_type}/
+ └── {example_name}/
+ ├── main.py
+ ├── README.md # Explain the example's purpose and usage
+ └── ... # The other scripts
+```
+
+
+## Do's and Don'ts
+
+### ✅ DO:
+
+- **Start small**: Begin with small, manageable contributions
+- **Communicate early**: Discuss major changes before implementing them
+- **Write tests**: Ensure your code is well-tested
+- **Document your code**: Help others understand your contributions
+- **Follow commit conventions**: Use conventional commit messages
+- **Be respectful**: Follow our Code of Conduct
+- **Ask questions**: If you're unsure about something, just ask!
+
+### ❌ DON'T:
+
+- **Don't surprise us with big pull requests**: Large, unexpected PRs are difficult to review and may not align with project goals. Always open an issue first to discuss major changes
+- **Don't ignore CI failures**: Fix any issues flagged by continuous integration
+- **Don't mix concerns**: Keep PRs focused on a single feature or fix
+- **Don't forget to update tests**: Changes in functionality should be reflected in tests
+- **Don't break existing APIs**: Maintain backward compatibility when possible, or clearly document breaking changes
+- **Don't add unnecessary dependencies**: Keep the core library lightweight
+- **Don't bypass the lazy import principle**: This keeps AgentScope fast to import
+
+## Getting Help
+
+If you need assistance or have questions:
+
+- 💬 Open a [Discussion](https://github.com/agentscope-ai/agentscope/discussions)
+- 🐛 Report bugs via [Issues](https://github.com/agentscope-ai/agentscope/issues)
+- 📧 Contact the maintainers at DingTalk or Discord (links in the README.md)
+
+
+---
+
+Thank you for contributing to AgentScope! Your efforts help build a better tool for the entire community. 🚀
diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md
new file mode 100644
index 000000000..5e52727fd
--- /dev/null
+++ b/CONTRIBUTING_zh.md
@@ -0,0 +1,240 @@
+# 贡献到 AgentScope
+
+## 欢迎!🎉
+
+感谢开源社区对 AgentScope 项目的关注和支持,作为一个开源项目,我们热烈欢迎并鼓励来自社区的贡献。无论是修复错误、添加新功能、改进文档还是
+分享想法,这些贡献都能帮助 AgentScope 变得更好。
+
+## 如何贡献
+
+为了确保顺利协作并保持项目质量,请在贡献时遵循以下指南:
+
+### 1. 检查现有计划和问题
+
+在开始贡献之前,请查看我们的开发路线图:
+
+- **查看 [Projects](https://github.com/orgs/agentscope-ai/projects/2) 页面** 和 **[带有 `roadmap` 标签的 Issues](https://github.com/agentscope-ai/agentscope/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** 以了解我们计划的开发任务。
+
+ - **如果存在相关问题** 并且标记为未分配或开放状态:
+ - 请在该问题下评论,表达您有兴趣参与该任务
+ - 这有助于协调开发工作,避免重复工作
+
+ - **如果不存在相关问题**:
+ - 请创建一个新 issue 用以描述对应的更改或功能
+ - 我们的团队将及时进行回复并提供反馈
+ - 这有助于我们维护项目路线图并协调社区工作
+
+### 2. 提交信息格式
+
+AgentScope 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。这使得提交历史更易读,并能够自动生成更新日志。
+
+**格式:**
+```
+<type>(<scope>): <subject>
+```
+
+**类型:**
+- `feat:` 新功能
+- `fix:` 错误修复
+- `docs:` 仅文档更改
+- `style:` 不影响代码含义的更改(空格、格式等)
+- `refactor:` 既不修复错误也不添加功能的代码更改
+- `perf:` 提高性能的代码更改
+- `ci:` 添加缺失的测试或更正现有测试
+- `chore:` 对构建过程或辅助工具和库的更改
+
+**示例:**
+```bash
+feat(models): add support for Claude-3 model
+fix(agent): resolve memory leak in ReActAgent
+docs(readme): update installation instructions
+refactor(formatter): simplify message formatting logic
+ci(models): add unit tests for OpenAI integration
+```
+
+### 3. 代码开发指南
+
+#### a. 提交前检查
+
+在提交代码之前,请运行 pre-commit 钩子以确保代码质量和一致性:
+
+**安装:**
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+**运行 pre-commit:**
+```bash
+# 在所有文件上运行
+pre-commit run --all-files
+
+# 安装后,pre-commit 将在 git commit 时自动运行
+```
+
+#### b. 关于代码中的 Import
+
+AgentScope 遵循**懒加载导入原则**以最小化资源加载:
+
+- **推荐做法**:仅在实际使用时导入模块
+ ```python
+ def some_function():
+ import openai
+ # 在此处使用 openai 库
+ ```
+
+这种方法确保 `import agentscope` 是一个轻量操作,不会加载不必要的依赖项。
+
+#### c. 单元测试
+
+- 所有新功能都必须包含适当的单元测试
+- 在提交 PR 之前确保现有测试通过
+- 使用以下命令运行测试:
+ ```bash
+ pytest tests
+ ```
+
+#### d. 文档
+
+- 为新功能更新相关文档
+- 在适当的地方包含代码示例
+- 如果更改影响面向用户的功能,请更新 README.md
+
+
+## 贡献类型
+
+### 添加新的 ChatModel
+
+AgentScope 目前内置支持以下 API 提供商:**OpenAI**、**DashScope**、**Gemini**、**Anthropic** 和 **Ollama**。
+其中 `OpenAIChatModel` 的实现还兼容不同的服务提供商,如 vLLM,DeepSeek、SGLang 等。
+
+**⚠️ 重要:**
+
+添加新的 ChatModel 不仅涉及模型层面的实现,还涉及到其它组件的配合,具体包括:
+- 消息格式化器(formatter)
+- Token 计数器(token counter)
+- Tools API 集成
+
+这意味着添加一个 ChatModel 需要大量的工作来确保其与 AgentScope 生态系统的其他部分无缝集成。
+为了更好地专注于智能体能力开发和维护,**官方开发团队目前不计划添加对新 API 的支持**。
+但是当开发者社区有强烈需求时,我们将尽力满足这些需求。
+
+**对于一个 ChatModel 类的实现**,为了与仓库中 `ReActAgent` 兼容,所需要实现的组件如下:
+
+#### 必需组件:
+
+1. **ChatModel**(位于 `agentscope.model` 下):
+ ```python
+ from agentscope.model import ChatModelBase
+
+
+ class YourChatModel(ChatModelBase):
+ """
+ 需要考虑的功能包括:
+ - 集成 tools API
+ - 支持流式和非流式模式,并与 tools API 兼容
+ - 支持 tool_choice 参数
+ - 考虑支持推理模型
+ """
+ ```
+
+2. **格式化器类**(位于 `agentscope.formatter` 下):
+ ```python
+ from agentscope.formatter import FormatterBase
+
+ class YourModelFormatter(FormatterBase):
+ """
+ 将 `Msg` 对象转换为对应 API 提供商所需的格式。
+ 如果模型 API 不支持多智能体场景(例如不支持消息中的 name 字段),需要
+ 为 chatbot 和多智能体场景分别实现两个格式化器类。
+ """
+ ```
+
+3. **Token 计数器**(位于 `agentscope.token` 下,推荐):
+ ```python
+ from agentscope.token import TokenCounterBase
+
+ class YourTokenCounter(TokenCounterBase):
+ """
+ 为对应模型实现 token 计数逻辑(推荐实现,非严格要求)。
+ """
+ ```
+
+### 添加新的智能体
+
+为了确保 AgentScope 中所有的功能实现都是**模块化的、可拆卸的和可组合的**,`agentscope.agent` 模块目前仅维护 **`ReActAgent`** 类作为核心实现。
+
+在 AgentScope 中,我们遵循示例优先的开发工作流程:
+
+- 在 `examples/` 目录中初步实现新的功能
+- 然后将重要功能抽象和模块化,集成到核心库中
+- 修改 `examples/` 目录中的示例以使用新的核心功能
+
+对于专门的或特定领域的智能体,我们建议按照以下组织形式将它们贡献到 **`examples/agent`** 目录:
+
+```
+examples/
+└── agent/
+ ├── main.py
+ ├── README.md # 解释智能体的目的和用法
+ └── ... # 其他脚本
+```
+
+### 添加新的示例
+
+
+请将它们添加到 `examples/` 目录,并附上清晰的 README 说明示例的目的和用法。
+
+目前我们的示例根据类型组织到子目录中:
+- `examples/functionality/` 用于展示 AgentScope 的特定基础功能
+- `examples/evaluation/` 用于评估
+- `examples/workflows/` 用于工作流演示
+- `examples/training/` 用于训练相关示例
+
+示例结构如下:
+
+```
+examples/
+└── {example_type}/
+ └── {example_name}/
+ ├── main.py
+ ├── README.md # 解释示例的目的和用法
+ └── ... # 其他脚本
+```
+
+
+## Do's and Don'ts
+
+### ✅ DO
+
+- **从小处着手**:从小的、可管理的贡献开始
+- **及早沟通**:在实现主要功能之前进行讨论
+- **编写测试**:确保代码经过充分测试
+- **添加代码注释**:帮助他人理解贡献内容
+- **遵循提交约定**:使用约定式提交消息
+- **保持尊重**:遵守我们的行为准则
+- **提出问题**:如果不确定某事,请提问!
+
+### ❌ DON'T
+
+- **不要用大型 PR 让我们措手不及**:大型的、意外的 PR 难以审查,并且可能与项目目标不一致。在进行重大更改之前,请务必先开启一个问题进行讨论
+- **不要忽略 CI 失败**:修复持续集成标记的任何问题
+- **不要混合关注点**:保持 PR 专注于单一功能的实现或修复
+- **不要忘记更新测试**:功能的更改应反映在测试中
+- **不要破坏现有 API**:在可能的情况下保持向后兼容性,或清楚地记录破坏性更改
+- **不要添加不必要的依赖项**:保持核心库轻量级
+- **不要绕过懒加载导入原则**:确保 AgentScope 在导入阶段不至于臃肿
+
+## 获取帮助
+
+如果需要帮助或有疑问:
+
+- 💬 开启一个 [Discussion](https://github.com/agentscope-ai/agentscope/discussions)
+- 🐛 通过 [Issues](https://github.com/agentscope-ai/agentscope/issues) 报告错误
+- 📧 通过钉钉交流群或 Discord 联系开发团队(链接在 README.md 中)
+
+
+---
+
+感谢为 AgentScope 做出贡献!🚀
+
diff --git a/README.md b/README.md
index 602f29d1b..e6a809da8 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,7 @@ Quick overview of important features in **AgentScope 1.0**:
| ... | | |
## 📢 News
+- **[2025-11]** [Contributing Guide](./CONTRIBUTING.md) is online now! Welcome to contribute to AgentScope.
- **[2025-09]** **RAG** module in AgentScope 1.0 is online now! Check our [tutorial](https://doc.agentscope.io/tutorial/task_rag.html) and [example](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag) for more details.
- **[2025-09]** **Voice agent** is online! `ReActAgent` supports Qwen-Omni and GPT-Audio natively now, check our [new example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent) and [roadmap](https://github.com/agentscope-ai/agentscope/issues/773).
- **[2025-09]** A new powerful 📋**Plan** module is online now! Check out the [tutorial](https://doc.agentscope.io/tutorial/task_plan.html) for more details.
@@ -137,6 +138,7 @@ Welcome to join our community on
- [🧑‍🤝‍🧑 Multi-Agent Conversation](#-multi-agent-conversation)
- [💻 AgentScope Studio](#-agentscope-studio)
- [📖 Documentation](#-documentation)
+- [🤝 Contributing](#-contributing)
- [⚖️ License](#-license)
- [📚 Publications](#-publications)
- [✨ Contributors](#-contributors)
@@ -371,7 +373,7 @@ as_studio
- API
- [API Docs](https://doc.agentscope.io/api/agentscope.html)
- [Examples](https://github.com/agentscope-ai/agentscope/tree/main/examples)
- - Functional
+ - Functionality
- [MCP](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/mcp)
- [Plan](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/plan)
- [Structured Output](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/structured_output)
@@ -380,11 +382,11 @@ as_studio
- [Session with SQLite](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/session_with_sqlite)
- [Stream Printing Messages](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/stream_printing_messages)
- Agent
- - [ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/react_agent)
+ - [ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/react_agent)
- [Voice Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent)
- - [Deep Research Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_deep_research)
- - [Browser-use Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_browser)
- - [Meta Planner Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/meta_planner_agent)
+ - [Deep Research Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/deep_research_agent)
+ - [Browser-use Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/browser_agent)
+ - [Meta Planner Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/meta_planner_agent)
- Game
- [Nine-player Werewolves](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
- Workflow
@@ -396,6 +398,12 @@ as_studio
- Training
- [Reinforcement learning (RL) with Trinity-RFT](https://github.com/agentscope-ai/agentscope/tree/main/examples/training/react_agent)
+
+## 🤝 Contributing
+
+We welcome contributions from the community! Please refer to our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines
+on how to contribute.
+
## ⚖️ License
AgentScope is released under Apache License 2.0.
diff --git a/README_zh.md b/README_zh.md
index 84653a794..26528c909 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -106,6 +106,7 @@ AgentScope v1.0 新功能概览:
| ... | | |
## 📢 新闻
+- **[2025-11]** [Contributing Guide](./CONTRIBUTING.md) 已更新,欢迎贡献到 AgentScope!
- **[2025-09]** AgentScope 1.0 **RAG** 模块已上线!欢迎查看 [文档](https://doc.agentscope.io/zh_CN/tutorial/task_rag.html) 和 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/rag)。
- **[2025-09]** **Voice agent** 已上线!`ReActAgent` 已原生支持 Qwen-Omni 和 GPT-Audio 系列模型,欢迎查看 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent) 和 [roadmap](https://github.com/agentscope-ai/agentscope/issues/773)。
- **[2025-09]** 一个全新功能强大的 📋**Plan** 模块已经上线 AgentScope!查看[文档](https://doc.agentscope.io/zh_CN/tutorial/task_plan.html)了解更多详情。
@@ -138,6 +139,7 @@ AgentScope v1.0 新功能概览:
- [🧑‍🤝‍🧑 多智能体对话](#-%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%B4%A1%E7%8C%AE)
- [⚖️ 许可](#-%E8%AE%B8%E5%8F%AF)
- [📚 论文](#-%E8%AE%BA%E6%96%87)
- [✨ 贡献者](#-%E8%B4%A1%E7%8C%AE%E8%80%85)
@@ -382,11 +384,11 @@ as_studio
- [基于DB的会话管理](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/session_with_sqlite)
- [流式获取打印消息](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/stream_printing_messages)
- 智能体
- - [ReAct 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/react_agent)
+ - [ReAct 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/react_agent)
- [语音智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/voice_agent)
- - [Deep Research 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_deep_research)
- - [Browser-use 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_browser)
- - [Meta Planner 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/meta_planner_agent)
+ - [Deep Research 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/deep_research_agent)
+ - [Browser-use 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/browser_agent)
+ - [Meta Planner 智能体](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent/meta_planner_agent)
- 游戏
- [九人制狼人杀](https://github.com/agentscope-ai/agentscope/tree/main/examples/game/werewolves)
- 工作流
@@ -399,6 +401,10 @@ as_studio
- [使用 Trinity-RFT 进行强化学习训练](https://github.com/agentscope-ai/agentscope/tree/main/examples/training/react_agent)
+## 🤝 贡献
+
+我们欢迎并鼓励社区成员为 AgentScope 做出贡献!请参阅我们的 [贡献指南](./CONTRIBUTING.md) 了解更多详情。
+
## ⚖️ 许可
AgentScope 基于 Apache License 2.0 发布。
diff --git a/examples/agent_browser/README.md b/examples/agent/browser_agent/README.md
similarity index 97%
rename from examples/agent_browser/README.md
rename to examples/agent/browser_agent/README.md
index ced1c26ee..4767276e0 100644
--- a/examples/agent_browser/README.md
+++ b/examples/agent/browser_agent/README.md
@@ -44,6 +44,6 @@ npx @playwright/mcp@latest
### Basic Example
You can start running the browser agent in your terminal with the following command
```bash
-cd examples/agent_browser
+cd examples/agent/browser_agent
python main.py
```
diff --git a/examples/agent_browser/browser_agent.py b/examples/agent/browser_agent/browser_agent.py
similarity index 100%
rename from examples/agent_browser/browser_agent.py
rename to examples/agent/browser_agent/browser_agent.py
diff --git a/examples/agent_browser/main.py b/examples/agent/browser_agent/main.py
similarity index 100%
rename from examples/agent_browser/main.py
rename to examples/agent/browser_agent/main.py
diff --git a/examples/agent_deep_research/README.md b/examples/agent/deep_research_agent/README.md
similarity index 100%
rename from examples/agent_deep_research/README.md
rename to examples/agent/deep_research_agent/README.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_decompose_subtask.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_decompose_subtask.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_decompose_subtask.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_decompose_subtask.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_deeper_expansion.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_deeper_expansion.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_deeper_expansion.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_deeper_expansion.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_deepresearch_summary_report.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_deepresearch_summary_report.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_deepresearch_summary_report.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_deepresearch_summary_report.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_inprocess_report.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_inprocess_report.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_inprocess_report.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_inprocess_report.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_reflect_failure.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_reflect_failure.md
similarity index 97%
rename from examples/agent_deep_research/built_in_prompt/prompt_reflect_failure.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_reflect_failure.md
index b3159ac72..2d5d1435f 100644
--- a/examples/agent_deep_research/built_in_prompt/prompt_reflect_failure.md
+++ b/examples/agent/deep_research_agent/built_in_prompt/prompt_reflect_failure.md
@@ -1,47 +1,47 @@
-Your job is reflecting your failure based on your work history and generate the follow-up subtask. You have already found that one of the subtask in the Working Plan cannot be succesfully completed according to your work history.
-
-## Instructions
-1. Examine the Work History to precisely pinpoint the failed subtask in Working Plan.
-2. Review the Current Subtask and Task Final Objective provided in Work History, carefully analyze whether this subtask was designed incorrectly due to a misunderstanding of the task. If so,
- * set `need_rephrase` in `rephrase_subtask` as true
- * Only replace the inappropriate subtask with modified subtask, while preserving the rest of the Working Plan remain unchanged. You should output the updated Working Plan in `rephrased_plan`.
- * If the subtask was not poorly designed, proceed to Step 3.
-3. Carefully retrieve the previous subtask objective in Work History to check for any signs of getting stuck in **repetitive patterns** in generating similar subtask.
- * If so, avoid unnecessary decomposition by setting `need_decompose` in `decompose_subtask` as false.
- * Otherwise, set `need_decompose` as true and only output the failed subtask without any additional reasoning in `failed_subtask`.
-
-## Important Notes
-1. `need_decompose` and `need_rephrase` can NOT be both true at the same time.
-2. Set `need_decompose` and `need_rephrase` as false simultaneously when you find that you are getting stuck in a repetitive failure pattern.
-
-## Example
-Work History:
-1. Reflect the failure of this subtask and identify the failed subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs"
-2. Decompose subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs" and generate a plan.
-Working Plan:
-1. Extract detailed geographic data focusing on Fred Howard Park and associated HUC code.
-2. Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes.
-3. Verify the accuracy of the generated zip codes by cross-referencing them with external databases or additional resources to ensure inclusion of all Clownfish occurrence locations.
-4. Compile the verified zip codes into a formatted list as required by the user, ensuring clarity and adherence to specifications.
-Failed Subtask: "Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes."
-Output:
-```json
-{
- "rephrase_subtask":{
- "need_rephrase": false,
- "rephrased_plan": ""
- },
- "decompose_subtask":{
- "need_decompose": false,
- "failed_subtask": ""
- }
-}
-```
-Explanation: The current failed subtask "Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes" is similar to the previous failed subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs", which has already been identified and decomposed in work history. Therefore, we don't need to make decomposition repeatedly.
-
-### Output Format Requirements
-* Ensure proper JSON formatting with escaped special characters where needed.
-* Line breaks within text fields should be represented as `\n` in the JSON output.
-* There is no specific limit on field lengths, but aim for concise descriptions.
-* All field values must be strings.
+Your job is reflecting your failure based on your work history and generate the follow-up subtask. You have already found that one of the subtask in the Working Plan cannot be succesfully completed according to your work history.
+
+## Instructions
+1. Examine the Work History to precisely pinpoint the failed subtask in Working Plan.
+2. Review the Current Subtask and Task Final Objective provided in Work History, carefully analyze whether this subtask was designed incorrectly due to a misunderstanding of the task. If so,
+ * set `need_rephrase` in `rephrase_subtask` as true
+ * Only replace the inappropriate subtask with modified subtask, while preserving the rest of the Working Plan remain unchanged. You should output the updated Working Plan in `rephrased_plan`.
+ * If the subtask was not poorly designed, proceed to Step 3.
+3. Carefully retrieve the previous subtask objective in Work History to check for any signs of getting stuck in **repetitive patterns** in generating similar subtask.
+ * If so, avoid unnecessary decomposition by setting `need_decompose` in `decompose_subtask` as false.
+ * Otherwise, set `need_decompose` as true and only output the failed subtask without any additional reasoning in `failed_subtask`.
+
+## Important Notes
+1. `need_decompose` and `need_rephrase` can NOT be both true at the same time.
+2. Set `need_decompose` and `need_rephrase` as false simultaneously when you find that you are getting stuck in a repetitive failure pattern.
+
+## Example
+Work History:
+1. Reflect the failure of this subtask and identify the failed subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs"
+2. Decompose subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs" and generate a plan.
+Working Plan:
+1. Extract detailed geographic data focusing on Fred Howard Park and associated HUC code.
+2. Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes.
+3. Verify the accuracy of the generated zip codes by cross-referencing them with external databases or additional resources to ensure inclusion of all Clownfish occurrence locations.
+4. Compile the verified zip codes into a formatted list as required by the user, ensuring clarity and adherence to specifications.
+Failed Subtask: "Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes."
+Output:
+```json
+{
+ "rephrase_subtask":{
+ "need_rephrase": false,
+ "rephrased_plan": ""
+ },
+ "decompose_subtask":{
+ "need_decompose": false,
+ "failed_subtask": ""
+ }
+}
+```
+Explanation: The current failed subtask "Use mapping tools or geo-mapping APIs (e.g., 'maps_regeocode') to convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes" is similar to the previous failed subtask "Convert the extracted geographic coordinates or landmarks into corresponding five-digit zip codes by mapping tools or geo-mapping APIs", which has already been identified and decomposed in work history. Therefore, we don't need to make decomposition repeatedly.
+
+### Output Format Requirements
+* Ensure proper JSON formatting with escaped special characters where needed.
+* Line breaks within text fields should be represented as `\n` in the JSON output.
+* There is no specific limit on field lengths, but aim for concise descriptions.
+* All field values must be strings.
* For each JSON document, only include the following fields:
\ No newline at end of file
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_tool_usage_rules.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_tool_usage_rules.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_tool_usage_rules.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_tool_usage_rules.md
diff --git a/examples/agent_deep_research/built_in_prompt/prompt_worker_additional_sys_prompt.md b/examples/agent/deep_research_agent/built_in_prompt/prompt_worker_additional_sys_prompt.md
similarity index 100%
rename from examples/agent_deep_research/built_in_prompt/prompt_worker_additional_sys_prompt.md
rename to examples/agent/deep_research_agent/built_in_prompt/prompt_worker_additional_sys_prompt.md
diff --git a/examples/agent_deep_research/built_in_prompt/promptmodule.py b/examples/agent/deep_research_agent/built_in_prompt/promptmodule.py
similarity index 97%
rename from examples/agent_deep_research/built_in_prompt/promptmodule.py
rename to examples/agent/deep_research_agent/built_in_prompt/promptmodule.py
index a3c75b40b..54794cfa8 100644
--- a/examples/agent_deep_research/built_in_prompt/promptmodule.py
+++ b/examples/agent/deep_research_agent/built_in_prompt/promptmodule.py
@@ -1,140 +1,140 @@
-# -*- coding: utf-8 -*-
-"""The output format of deep research agent"""
-from pydantic import BaseModel, Field
-
-
-class SubtasksDecomposition(BaseModel):
- """
- Model for structured subtask decomposition output in deep research.
- """
-
- knowledge_gaps: str = Field(
- description=(
- "A markdown checklist of essential knowledge gaps "
- "and optional perspective-expansion gaps (flagged "
- "with (EXPANSION)), each on its own line. "
- "E.g. '- [ ] Detailed analysis of JD.com's "
- "...\\n- [ ] (EXPANSION) X...'."
- ),
- )
- working_plan: str = Field(
- description=(
- "A logically ordered step-by-step working "
- "plan (3-5 steps), each step starting with "
- "its number (1., 2., etc), including both "
- "core and expansion steps. Expanded steps "
- "should be clearly marked with (EXPANSION) "
- "and provide contextual or analytical depth.."
- ),
- )
-
-
-class WebExtraction(BaseModel):
- """
- Model for structured follow-up web extraction output in deep research.
- """
-
- reasoning: str = Field(
- description="The reasoning for your decision, including a "
- "summary of evidence and logic for whether more "
- "information is needed.",
- )
- need_more_information: bool = Field(
- description="Whether more information is needed.",
- )
- title: str = Field(
- description="Title of the identified search result snippet "
- "that requires further extraction, or an empty "
- "string if not applicable.",
- )
- url: str = Field(
- description="Direct URL to the original search result "
- "requiring further extraction, or an empty "
- "string if not applicable.",
- )
- subtask: str = Field(
- description="Actionable description of the follow-up task "
- "to obtain needed information, or an empty string "
- "if not applicable.",
- )
-
-
-class FollowupJudge(BaseModel):
- """
- Model for structured follow-up decompose judging output in deep research.
- """
-
- reasoning: str = Field(
- description="The reasoning for your decision, including a "
- "summary of evidence and logic for whether "
- "more information is needed.",
- )
- is_sufficient: bool = Field(
- description="whether the information content is adequate.",
- )
-
-
-class ReflectFailure(BaseModel):
- """
- Model for structured failure reflection output in deep research.
- """
-
- rephrase_subtask: dict = Field(
- description=(
- "Information about whether the problematic "
- "subtask needs to be rephrased due "
- "to a design flaw or misunderstanding. "
- "If rephrasing is needed, provide the "
- "modified working plan with only the "
- "inappropriate subtask replaced by its "
- "improved version."
- ),
- json_schema_extra={
- "additionalProperties": {
- "type": "object",
- "properties": {
- "need_rephrase": {
- "type": "boolean",
- "description": "Set to 'true' if the failed subtask "
- "needs to be rephrased due to a design "
- "flaw or misunderstanding; otherwise, 'false'.",
- },
- "rephrased_plan": {
- "type": "string",
- "description": "The modified working plan "
- "with only the inappropriate "
- "subtask replaced by its improved version. If no "
- "rephrasing is needed, provide an empty string.",
- },
- },
- },
- },
- )
- decompose_subtask: dict = Field(
- description=(
- "Information about whether the problematic subtask "
- "should be further decomposed. If decomposition "
- "is required, provide the failed subtask "
- "and the reason for its decomposition."
- ),
- json_schema_extra={
- "additionalProperties": {
- "type": "object",
- "properties": {
- "need_decompose": {
- "type": "boolean",
- "description": "Set to 'true' if "
- "the failed subtask should "
- "be further decomposed; otherwise, 'false'.",
- },
- "rephrased_plan": {
- "type": "string",
- "description": "Information about whether "
- "the failed subtask requires "
- "decomposition, and the "
- "failed subtask itself if needed.",
- },
- },
- },
- },
- )
+# -*- coding: utf-8 -*-
+"""The output format of deep research agent"""
+from pydantic import BaseModel, Field
+
+
+class SubtasksDecomposition(BaseModel):
+ """
+ Model for structured subtask decomposition output in deep research.
+ """
+
+ knowledge_gaps: str = Field(
+ description=(
+ "A markdown checklist of essential knowledge gaps "
+ "and optional perspective-expansion gaps (flagged "
+ "with (EXPANSION)), each on its own line. "
+ "E.g. '- [ ] Detailed analysis of JD.com's "
+ "...\\n- [ ] (EXPANSION) X...'."
+ ),
+ )
+ working_plan: str = Field(
+ description=(
+ "A logically ordered step-by-step working "
+ "plan (3-5 steps), each step starting with "
+ "its number (1., 2., etc), including both "
+ "core and expansion steps. Expanded steps "
+ "should be clearly marked with (EXPANSION) "
+ "and provide contextual or analytical depth.."
+ ),
+ )
+
+
+class WebExtraction(BaseModel):
+ """
+ Model for structured follow-up web extraction output in deep research.
+ """
+
+ reasoning: str = Field(
+ description="The reasoning for your decision, including a "
+ "summary of evidence and logic for whether more "
+ "information is needed.",
+ )
+ need_more_information: bool = Field(
+ description="Whether more information is needed.",
+ )
+ title: str = Field(
+ description="Title of the identified search result snippet "
+ "that requires further extraction, or an empty "
+ "string if not applicable.",
+ )
+ url: str = Field(
+ description="Direct URL to the original search result "
+ "requiring further extraction, or an empty "
+ "string if not applicable.",
+ )
+ subtask: str = Field(
+ description="Actionable description of the follow-up task "
+ "to obtain needed information, or an empty string "
+ "if not applicable.",
+ )
+
+
+class FollowupJudge(BaseModel):
+ """
+ Model for structured follow-up decompose judging output in deep research.
+ """
+
+ reasoning: str = Field(
+ description="The reasoning for your decision, including a "
+ "summary of evidence and logic for whether "
+ "more information is needed.",
+ )
+ is_sufficient: bool = Field(
+ description="whether the information content is adequate.",
+ )
+
+
+class ReflectFailure(BaseModel):
+ """
+ Model for structured failure reflection output in deep research.
+ """
+
+ rephrase_subtask: dict = Field(
+ description=(
+ "Information about whether the problematic "
+ "subtask needs to be rephrased due "
+ "to a design flaw or misunderstanding. "
+ "If rephrasing is needed, provide the "
+ "modified working plan with only the "
+ "inappropriate subtask replaced by its "
+ "improved version."
+ ),
+ json_schema_extra={
+ "additionalProperties": {
+ "type": "object",
+ "properties": {
+ "need_rephrase": {
+ "type": "boolean",
+ "description": "Set to 'true' if the failed subtask "
+ "needs to be rephrased due to a design "
+ "flaw or misunderstanding; otherwise, 'false'.",
+ },
+ "rephrased_plan": {
+ "type": "string",
+ "description": "The modified working plan "
+ "with only the inappropriate "
+ "subtask replaced by its improved version. If no "
+ "rephrasing is needed, provide an empty string.",
+ },
+ },
+ },
+ },
+ )
+ decompose_subtask: dict = Field(
+ description=(
+ "Information about whether the problematic subtask "
+ "should be further decomposed. If decomposition "
+ "is required, provide the failed subtask "
+ "and the reason for its decomposition."
+ ),
+ json_schema_extra={
+ "additionalProperties": {
+ "type": "object",
+ "properties": {
+ "need_decompose": {
+ "type": "boolean",
+ "description": "Set to 'true' if "
+ "the failed subtask should "
+ "be further decomposed; otherwise, 'false'.",
+ },
+ "rephrased_plan": {
+ "type": "string",
+ "description": "Information about whether "
+ "the failed subtask requires "
+ "decomposition, and the "
+ "failed subtask itself if needed.",
+ },
+ },
+ },
+ },
+ )
diff --git a/examples/agent_deep_research/deep_research_agent.py b/examples/agent/deep_research_agent/deep_research_agent.py
similarity index 100%
rename from examples/agent_deep_research/deep_research_agent.py
rename to examples/agent/deep_research_agent/deep_research_agent.py
diff --git a/examples/agent_deep_research/main.py b/examples/agent/deep_research_agent/main.py
similarity index 96%
rename from examples/agent_deep_research/main.py
rename to examples/agent/deep_research_agent/main.py
index ab6b0ac18..7dca3b2b2 100644
--- a/examples/agent_deep_research/main.py
+++ b/examples/agent/deep_research_agent/main.py
@@ -1,82 +1,82 @@
-# -*- coding: utf-8 -*-
-"""The main entry point of the Deep Research agent example."""
-import asyncio
-import os
-
-from deep_research_agent import DeepResearchAgent
-
-from agentscope import logger
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.model import DashScopeChatModel
-from agentscope.message import Msg
-from agentscope.mcp import StdIOStatefulClient
-
-
-async def main(user_query: str) -> None:
- """The main entry point for the Deep Research agent example."""
- logger.setLevel("DEBUG")
-
- tavily_search_client = StdIOStatefulClient(
- name="tavily_mcp",
- command="npx",
- args=["-y", "tavily-mcp@latest"],
- env={"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY", "")},
- )
-
- default_working_dir = os.path.join(
- os.path.dirname(__file__),
- "deepresearch_agent_demo_env",
- )
- agent_working_dir = os.getenv(
- "AGENT_OPERATION_DIR",
- default_working_dir,
- )
- os.makedirs(agent_working_dir, exist_ok=True)
-
- try:
- await tavily_search_client.connect()
- agent = DeepResearchAgent(
- 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(),
- memory=InMemoryMemory(),
- search_mcp_client=tavily_search_client,
- tmp_file_storage_dir=agent_working_dir,
- )
- user_name = "Bob"
- msg = Msg(
- user_name,
- content=user_query,
- role="user",
- )
- result = await agent(msg)
- logger.info(result)
-
- except Exception as err:
- logger.exception(err)
- finally:
- await tavily_search_client.close()
-
-
-if __name__ == "__main__":
- query = (
- "If Eliud Kipchoge could maintain his record-making "
- "marathon pace indefinitely, how many thousand hours "
- "would it take him to run the distance between the "
- "Earth and the Moon its closest approach? Please use "
- "the minimum perigee value on the Wikipedia page for "
- "the Moon when carrying out your calculation. Round "
- "your result to the nearest 1000 hours and do not use "
- "any comma separators if necessary."
- )
- try:
- asyncio.run(main(query))
- except Exception as e:
- logger.exception(e)
+# -*- coding: utf-8 -*-
+"""The main entry point of the Deep Research agent example."""
+import asyncio
+import os
+
+from deep_research_agent import DeepResearchAgent
+
+from agentscope import logger
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.model import DashScopeChatModel
+from agentscope.message import Msg
+from agentscope.mcp import StdIOStatefulClient
+
+
+async def main(user_query: str) -> None:
+ """The main entry point for the Deep Research agent example."""
+ logger.setLevel("DEBUG")
+
+ tavily_search_client = StdIOStatefulClient(
+ name="tavily_mcp",
+ command="npx",
+ args=["-y", "tavily-mcp@latest"],
+ env={"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY", "")},
+ )
+
+ default_working_dir = os.path.join(
+ os.path.dirname(__file__),
+ "deepresearch_agent_demo_env",
+ )
+ agent_working_dir = os.getenv(
+ "AGENT_OPERATION_DIR",
+ default_working_dir,
+ )
+ os.makedirs(agent_working_dir, exist_ok=True)
+
+ try:
+ await tavily_search_client.connect()
+ agent = DeepResearchAgent(
+ 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(),
+ memory=InMemoryMemory(),
+ search_mcp_client=tavily_search_client,
+ tmp_file_storage_dir=agent_working_dir,
+ )
+ user_name = "Bob"
+ msg = Msg(
+ user_name,
+ content=user_query,
+ role="user",
+ )
+ result = await agent(msg)
+ logger.info(result)
+
+ except Exception as err:
+ logger.exception(err)
+ finally:
+ await tavily_search_client.close()
+
+
+if __name__ == "__main__":
+ query = (
+ "If Eliud Kipchoge could maintain his record-making "
+ "marathon pace indefinitely, how many thousand hours "
+ "would it take him to run the distance between the "
+ "Earth and the Moon its closest approach? Please use "
+ "the minimum perigee value on the Wikipedia page for "
+ "the Moon when carrying out your calculation. Round "
+ "your result to the nearest 1000 hours and do not use "
+ "any comma separators if necessary."
+ )
+ try:
+ asyncio.run(main(query))
+ except Exception as e:
+ logger.exception(e)
diff --git a/examples/agent_deep_research/utils.py b/examples/agent/deep_research_agent/utils.py
similarity index 100%
rename from examples/agent_deep_research/utils.py
rename to examples/agent/deep_research_agent/utils.py
diff --git a/examples/meta_planner_agent/README.md b/examples/agent/meta_planner_agent/README.md
similarity index 99%
rename from examples/meta_planner_agent/README.md
rename to examples/agent/meta_planner_agent/README.md
index ebef5d11f..4ce54cbb3 100644
--- a/examples/meta_planner_agent/README.md
+++ b/examples/agent/meta_planner_agent/README.md
@@ -60,7 +60,7 @@ export AGENT_OPERATION_DIR="/path/to/custom/working/directory"
Run the agent interactively:
```bash
-cd examples/agent_meta_planner
+cd examples/agent/meta_planner_agent
python main.py
```
diff --git a/examples/meta_planner_agent/_built_in_long_sys_prompt/_tool_usage_rules.md b/examples/agent/meta_planner_agent/_built_in_long_sys_prompt/_tool_usage_rules.md
similarity index 100%
rename from examples/meta_planner_agent/_built_in_long_sys_prompt/_tool_usage_rules.md
rename to examples/agent/meta_planner_agent/_built_in_long_sys_prompt/_tool_usage_rules.md
diff --git a/examples/meta_planner_agent/_built_in_long_sys_prompt/_worker_additional_sys_prompt.md b/examples/agent/meta_planner_agent/_built_in_long_sys_prompt/_worker_additional_sys_prompt.md
similarity index 100%
rename from examples/meta_planner_agent/_built_in_long_sys_prompt/_worker_additional_sys_prompt.md
rename to examples/agent/meta_planner_agent/_built_in_long_sys_prompt/_worker_additional_sys_prompt.md
diff --git a/examples/meta_planner_agent/_built_in_long_sys_prompt/meta_planner_sys_prompt.md b/examples/agent/meta_planner_agent/_built_in_long_sys_prompt/meta_planner_sys_prompt.md
similarity index 100%
rename from examples/meta_planner_agent/_built_in_long_sys_prompt/meta_planner_sys_prompt.md
rename to examples/agent/meta_planner_agent/_built_in_long_sys_prompt/meta_planner_sys_prompt.md
diff --git a/examples/meta_planner_agent/_meta_planner.py b/examples/agent/meta_planner_agent/_meta_planner.py
similarity index 100%
rename from examples/meta_planner_agent/_meta_planner.py
rename to examples/agent/meta_planner_agent/_meta_planner.py
diff --git a/examples/meta_planner_agent/_planning_tools/__init__.py b/examples/agent/meta_planner_agent/_planning_tools/__init__.py
similarity index 100%
rename from examples/meta_planner_agent/_planning_tools/__init__.py
rename to examples/agent/meta_planner_agent/_planning_tools/__init__.py
diff --git a/examples/meta_planner_agent/_planning_tools/_planning_notebook.py b/examples/agent/meta_planner_agent/_planning_tools/_planning_notebook.py
similarity index 100%
rename from examples/meta_planner_agent/_planning_tools/_planning_notebook.py
rename to examples/agent/meta_planner_agent/_planning_tools/_planning_notebook.py
diff --git a/examples/meta_planner_agent/_planning_tools/_roadmap_manager.py b/examples/agent/meta_planner_agent/_planning_tools/_roadmap_manager.py
similarity index 100%
rename from examples/meta_planner_agent/_planning_tools/_roadmap_manager.py
rename to examples/agent/meta_planner_agent/_planning_tools/_roadmap_manager.py
diff --git a/examples/meta_planner_agent/_planning_tools/_worker_manager.py b/examples/agent/meta_planner_agent/_planning_tools/_worker_manager.py
similarity index 100%
rename from examples/meta_planner_agent/_planning_tools/_worker_manager.py
rename to examples/agent/meta_planner_agent/_planning_tools/_worker_manager.py
diff --git a/examples/meta_planner_agent/main.py b/examples/agent/meta_planner_agent/main.py
similarity index 100%
rename from examples/meta_planner_agent/main.py
rename to examples/agent/meta_planner_agent/main.py
diff --git a/examples/react_agent/README.md b/examples/agent/react_agent/README.md
similarity index 100%
rename from examples/react_agent/README.md
rename to examples/agent/react_agent/README.md
diff --git a/examples/react_agent/main.py b/examples/agent/react_agent/main.py
similarity index 100%
rename from examples/react_agent/main.py
rename to examples/agent/react_agent/main.py
diff --git a/examples/alibabacloud_api_mcp/README.md b/examples/integration/alibabacloud_api_mcp/README.md
similarity index 100%
rename from examples/alibabacloud_api_mcp/README.md
rename to examples/integration/alibabacloud_api_mcp/README.md
diff --git a/examples/alibabacloud_api_mcp/main.py b/examples/integration/alibabacloud_api_mcp/main.py
similarity index 100%
rename from examples/alibabacloud_api_mcp/main.py
rename to examples/integration/alibabacloud_api_mcp/main.py
diff --git a/examples/alibabacloud_api_mcp/oauth_handler.py b/examples/integration/alibabacloud_api_mcp/oauth_handler.py
similarity index 100%
rename from examples/alibabacloud_api_mcp/oauth_handler.py
rename to examples/integration/alibabacloud_api_mcp/oauth_handler.py