diff --git a/.vitepress/config.mjs b/.vitepress/config.mjs index c826893..267ebfc 100644 --- a/.vitepress/config.mjs +++ b/.vitepress/config.mjs @@ -161,6 +161,8 @@ export default defineConfig({ { text: "内置指令", link: "/command" }, { text: "工具使用 Tools", link: "/function-calling" }, { text: "技能 Skills", link: "/skills" }, + { text: "SubAgent 编排", link: "/subagent" }, + { text: "主动型 Agent 能力", link: "/proactive-agent" }, { text: "MCP", link: "/mcp" }, { text: "网页搜索", link: "/websearch" }, { text: "知识库", link: "/knowledge-base" }, @@ -380,6 +382,8 @@ export default defineConfig({ { text: "Built-in Commands", link: "/command" }, { text: "Tool Use", link: "/function-calling" }, { text: "Anthropic Skills", link: "/skills" }, + { text: "SubAgent Orchestration", link: "/subagent" }, + { text: "Proactive Tasks", link: "/proactive-agent" }, { text: "MCP", link: "/mcp" }, { text: "Web Search", link: "/websearch" }, { text: "Knowledge Base", link: "/knowledge-base" }, diff --git a/en/use/proactive-agent.md b/en/use/proactive-agent.md new file mode 100644 index 0000000..f4a121a --- /dev/null +++ b/en/use/proactive-agent.md @@ -0,0 +1,52 @@ +# Proactive Capabilities + +AstrBot introduces a Proactive Agent system, enabling AstrBot to not only respond passively to users but also schedule future tasks and proactively execute them at specified times, delivering results (text, images, files, etc.) to users. + +![](/source/images/proactive-agent/image.png) + +Introduced in v4.14.0, this is currently an **experimental feature** and not yet stable. + +## Future Tasks (FutureTask) + +The Main Agent can now manage a global **Cron Job List**, setting tasks for its future self. + +### Features + +- **Self-Wakeup**: AstrBot automatically wakes up at the scheduled time to execute tasks. +- **Task Feedback**: After execution, AstrBot reports the results back to the task creator. +- **WebUI Management**: You can view, edit, or delete scheduled tasks in the "Future Tasks" page of the WebUI. + +### How to Use + +> [!TIP] +> First, ensure that "Proactive Capabilities" is enabled in the configuration. + +The Main Agent has the ability to manage scheduled tasks. You can tell it: +- "Remind me to have a meeting at 8 AM tomorrow." +- "Summarize this week's work log every Friday at 5 PM." +- "Set a timer for 10 minutes." + +The Main Agent will call built-in scheduling tools to arrange these plans. + +You can view and manage all future tasks by clicking **Future Tasks** in the left navigation bar of the AstrBot WebUI. + +![](/source/images/proactive-agent/image-1.png) + +### Supported Platforms + +Scheduling tasks is supported on all platforms. However, due to some platforms not providing APIs for proactive message pushing, only the following platforms support AstrBot proactively pushing results to users: +- Telegram +- OneBot (QQ) +- Slack +- Feishu (Lark) +- Discord +- Misskey +- Satori + +## Sending Multimedia Messages + +To make it easier for Agents to send images, audio, video, and other files directly to users, AstrBot provides a `send_message_to_user` tool by default. + +### Features +- **Direct Sending**: Agents can send generated or retrieved multimedia files directly to users without complex text conversions. +- **Multiple Formats**: Supports images, files, audio, video, etc. diff --git a/en/use/subagent.md b/en/use/subagent.md new file mode 100644 index 0000000..bd5cdf2 --- /dev/null +++ b/en/use/subagent.md @@ -0,0 +1,54 @@ +# Agent Handoff and SubAgent + +SubAgent Orchestration is an advanced agent organization method provided by AstrBot. It allows you to decompose complex tasks into multiple specialized SubAgents, reducing the Main Agent's prompt length and improving task execution success rates. + +v4.14.0 introduced this feature, which is currently an **experimental feature** and not yet stable. + +![](/source/images/subagent/image.png) + +## Motivation + +In traditional architectures, all tools are directly mounted on the Main Agent. When there are many tools, several issues arise: +1. **Prompt Bloat**: The Main Agent must include descriptions for all tools in its System Prompt, consuming excessive context. +2. **Execution Errors**: With a large number of tools, the LLM may confuse tool purposes or generate incorrect parameters. +3. **Complexity**: The Main Agent is overburdened with both conversation and the organization/invocation of numerous tools. + +With SubAgent Orchestration, the Main Agent is only responsible for user interaction and **task delegation**. Actual tool execution is handled by specialized SubAgents. + +## How It Works + +1. **Main Agent Delegation**: When SubAgent mode is enabled, the Main Agent only sees a series of delegation tools named `transfer_to_`. +2. **Task Handoff**: When the Main Agent determines a task needs execution, it calls the corresponding delegation tool, passing the task description to the SubAgent. +3. **SubAgent Execution**: The SubAgent receives the task, performs operations using its assigned tools, and returns the organized results to the Main Agent. +4. **Feedback**: The Main Agent receives the results and continues the conversation with the user. + +## Configuration + +In the AstrBot WebUI, click **SubAgents** in the left navigation bar. + +### 1. Enable SubAgent Mode + +Toggle "Enable SubAgent Orchestration" at the top of the page. + +### 2. Create a SubAgent + +Click the "Add SubAgent" button: + +- **Agent Name**: Used to generate the delegation tool name (e.g., `transfer_to_weather`). Use lowercase and underscores. +- **Select Persona**: Choose a preset Persona, which defines the SubAgent's basic character, behavioral guidance, and the Tools collection it can use. You can create and manage Personas on the "Persona Settings" page. +- **Description for Main LLM**: This description tells the Main Agent what this SubAgent is good at, ensuring accurate delegation. +- **Assign Tools**: Select the tools this SubAgent can invoke. +- **Provider Override (Optional)**: You can specify different model providers for specific SubAgents. For example, the Main Agent could use GPT-4o, while a simple query SubAgent uses GPT-4o-mini to save costs. + +## Best Practices + +- **Single Responsibility**: Each SubAgent should handle one category of related tasks (e.g., search, file processing, smart home control). +- **Clear Descriptions**: Descriptions for the Main Agent should be concise and highlight the SubAgent's core capabilities. +- **Layered Management**: For extremely complex tasks, consider multi-level delegation if necessary. + +## Known Issues + +SubAgent orchestration is currently an **experimental feature** and not yet stable. + +1. Skills of personas cannot be isolated at this time. +2. SubAgent conversation histories are not currently saved. diff --git a/source/images/proactive-agent/image-1.png b/source/images/proactive-agent/image-1.png new file mode 100644 index 0000000..c57224b Binary files /dev/null and b/source/images/proactive-agent/image-1.png differ diff --git a/source/images/proactive-agent/image.png b/source/images/proactive-agent/image.png new file mode 100644 index 0000000..1404c48 Binary files /dev/null and b/source/images/proactive-agent/image.png differ diff --git a/source/images/subagent/image.png b/source/images/subagent/image.png new file mode 100644 index 0000000..441184f Binary files /dev/null and b/source/images/subagent/image.png differ diff --git a/zh/use/proactive-agent.md b/zh/use/proactive-agent.md new file mode 100644 index 0000000..0126418 --- /dev/null +++ b/zh/use/proactive-agent.md @@ -0,0 +1,53 @@ +# 主动型能力 + +AstrBot 引入了主动 Agent(Proactive Agent)系统,使 AstrBot 不仅能被动响应用户,还能通过给自己下达未来的任务来在未来的指定时刻主动执行任务并向用户主动反馈结果(文本、图片、文件都可)。 + +![](/source/images/proactive-agent/image.png) + +在 v4.14.0 引入,目前是**实验性功能**,未稳定。 + +## 未来任务 (FutureTask) + +主 Agent 现在可以管理一个全局的 **Cron Job 列表**,为未来的自己设置任务。 + +### 功能特点 + +- **自我唤醒**:AstrBot 会在预定时间自动唤醒并执行任务。 +- **任务反馈**:执行完成后,AstrBot 会将结果告知任务布置方。 +- **WebUI 管理**:你可以在 WebUI 的“定时任务”页面查看、编辑或删除已设置的任务。 + +### 如何使用 + +> [!TIP] +> 首先,确保配置中 “主动型能力” 已启用。 + +主 Agent 拥有管理定时任务的能力。你可以直接对它说: +- “明天早上 8 点提醒我开会” +- “每周五下午 5 点总结本周的工作日志” +- “帮我定一个 10 分钟后的闹钟” + +主 Agent 会调用内置的定时任务工具来安排这些计划。 + +你可以在 AstrBot WebUI 左侧导航栏中点击 **未来任务** 来查看和管理所有未来任务。 + +![](/source/images/proactive-agent/image-1.png) + +### 支持的平台 + +“定时任务”的设置支持所有平台,然而,由于部分平台没有开放主动消息推送的 API,因此只有以下平台支持 AstrBot 主动向用户推送结果: + +- Telegram +- OneBot v11 +- Slack +- 飞书 (Lark) +- Discord +- Misskey +- Satori + +## 多媒体消息的发送 + +为了方便 Agent 直接向用户发送图片、音频、视频等文件,AstrBot 默认提供了一个 `send_message_to_user` 工具。 + +### 功能特点 +- **直接发送**:Agent 可以直接将生成或获取的多媒体文件发送给用户,而无需通过复杂的文本转换。 +- **支持多种格式**:支持图片、文件、音频、视频等。 diff --git a/zh/use/subagent.md b/zh/use/subagent.md new file mode 100644 index 0000000..76f24ce --- /dev/null +++ b/zh/use/subagent.md @@ -0,0 +1,54 @@ +# Agent Handsoff 与 Subagent + +SubAgent 编排是 AstrBot 提供的一种高级 Agent 组织方式。它允许你将复杂的任务分解给多个专门的子 Agent(SubAgent)来完成,从而降低主 Agent 的 Prompt 长度,提高任务执行的成功率。 + +在 v4.14.0 引入,目前是**实验性功能**,未稳定。 + +![](/source/images/subagent/image.png) + +## 动机 + +在传统的架构中,所有的工具(Tools)都直接挂载在主 Agent 上。当工具数量较多时,会带来以下问题: +1. **Prompt 爆炸**:主 Agent 需要在 System Prompt 中包含所有工具的描述,导致上下文占用过多。 +2. **调用失误**:面对大量工具,LLM 容易混淆工具用途或产生错误的调用参数。 +3. **逻辑复杂**:主 Agent 既要负责对话,又要负责组织和调用大量工具,负担过重。 + +通过 SubAgent 编排,主 Agent 仅负责与用户对话以及**任务委派**。具体的工具调用由专门的 SubAgent 负责。 + +## 工作原理 + +1. **主 Agent 委派**:开启 SubAgent 模式后,主 Agent 只能看到一系列名为 `transfer_to_` 的委派工具。 +2. **任务移交**:当主 Agent 认为需要执行某项任务时,它会调用对应的委派工具,将任务描述传递给 SubAgent。 +3. **子 Agent 执行**:SubAgent 接收到任务后,使用其挂载的工具进行操作,并将结果整理后回传给主 Agent。 +4. **结果反馈**:主 Agent 收到 SubAgent 的执行结果,继续与用户对话。 + +## 配置方法 + +在 AstrBot WebUI 中,点击左侧导航栏的 **SubAgent 编排**。 + +### 1. 启用 SubAgent 模式 + +在页面顶部开启“启用 SubAgent 编排”。 + +### 2. 创建 SubAgent + +点击“新增 SubAgent”按钮: + +- **Agent 名称**:用于生成委派工具名(如 `transfer_to_weather`)。建议使用英文小写和下划线。 +- **选择 Persona**:选择一个预设的 Persona,即人格,作为该子 Agent 的基础性格、行为指导和可以使用的 Tools 集合。你可以在“人格设定”页面创建和管理 Persona。 +- **对主 LLM 的描述**:这段描述会告诉主 Agent 这个子 Agent 擅长做什么,以便主 Agent 准确委派。 +- **分配工具**:选择该子 Agent 可以调用的工具。 +- **Provider 覆盖(可选)**:你可以为特定的子 Agent 指定不同的模型提供商。例如,主 Agent 使用 GPT-4o,而负责简单查询的子 Agent 使用 GPT-4o-mini 以节省成本。 + +## 最佳实践 + +- **职责单一**:每个 SubAgent 应该只负责一类相关的任务(如:搜索、文件处理、智能家居控制)。 +- **清晰的描述**:给主 Agent 的描述应当简洁明了,突出该子 Agent 的核心能力。 +- **分层管理**:对于极其复杂的任务,可以考虑多级委派(如果需要)。 + +## 已知问题 + +SubAgent 系统目前是**实验性功能**,未稳定。 + +1. 目前无法隔离人格的 Skills。 +2. 子 Agent 的对话历史暂时不会被保存。