Repository navigation
en use subagent
Subagents let the built-in AI delegate tasks to background agents with independent contexts while continuing the main conversation. No plugin installation is required.
Open Config → AI → Capabilities → Subagents in the target profile and enable the capability. You can use generic subagents immediately. The default concurrency limit is 3, and the default timeout is 600 seconds, including queue time.

- Click Configure Specialized Agents, then Create Agent.
- Select the AstrBot runtime and enter a name and description. The description helps the main agent decide when to delegate.
- Select a persona and chat model, or leave them empty to follow the main agent.
- Save, close the dialog, and select the agent under Specialized Agent Configurations.


The selected persona supplies the agent's instructions, tools, and skills, within the parent agent's authorized capabilities. Other execution settings, such as step limits and tool timeouts, follow the main agent when the session is created. Configuration changes apply to new sessions.
To edit an agent, click its card. To delete one, remove any references from profiles or other agent configurations first. Configurations for unavailable runtimes remain saved but cannot start new sessions.
Ask the main agent to delegate a task, for example: “Have a subagent review this report while we discuss the next steps.” The main agent uses these tools:
| Tool | Purpose |
|---|---|
spawn_agent |
Start a background task. |
list_agents |
Check task status. |
wait_agent |
Wait for results. |
get_agent_result |
Read a result. |
send_message |
Add instructions to an existing agent. |
cancel_agent |
Stop a task. |
The configuration dialog manages saved agents; ask the main agent to check or stop running tasks. Subagents cannot create further subagents.
Delegated input supports text, images, and file references. Images from the original user message are not forwarded automatically. Follow-up instructions retain the subagent's history; in the built-in runtime, follow-up images and files are passed as text references.
Users in the same conversation share its subagents. Results return to the original parent conversation, even if you switch conversations. Deleted or stopped parents are not woken.
After a restart, queued and unfinished tasks are marked interrupted and are not replayed automatically. Check their status, then ask the main agent to send new instructions to continue in the same subagent conversation.
The previous SubAgent Orchestration / Subagent Management sidebar entry has moved to Config → AI → Capabilities → Subagents → Configure Specialized Agents. The /subagent URL remains accessible.
Existing global settings and expert configurations migrate automatically. Existing conversations and history are preserved.
API clients should replace /api/v1/subagents/config and /api/subagent/config with /api/v1/agent-configs and /api/v1/agent-configs/{config_id}. Use /api/v1/agent-runtimes to list runtimes and their defaults. These endpoints require the config scope; see OpenAPI scopes.
For plugin integration, see running an Agent and runtime events.
- 首页
- 文档入口
- Top Level
- community events
- config
- deploy
- dev
- others
- platform
- 接入 OneBot v11 协议实现
- 接入钉钉 DingTalk
- 接入 Discord
- 接入 Kook
- 接入飞书
- 接入 LINE
- 接入 Matrix
- 接入 Mattermost
- 接入 Misskey 平台
- 接入 QQ 官方机器人平台
- 通过 QQ官方机器人 接入 QQ (Webhook)
- 通过 QQ官方机器人 接入 QQ (Websockets)
- 接入 Satori 协议
- 接入 server-satori (基于 Koishi)
- 接入 Slack
- 接入消息平台
- 接入 Telegram
- 接入 VoceChat
- AstrBot 接入企业微信
- 接入企业微信智能机器人平台
- AstrBot 接入微信公众平台
- 接入个人微信
- providers
- use
- Home
- Docs Entry
- Top Level
- config
- deploy
- Deploy AstrBot on 1Panel
- Deploy AstrBot on BT Panel
- Deploy AstrBot on CasaOS
- Deploy AstrBot from Source Code
- Community-Provided Deployment Methods
- Deploy via Compshare
- Deploy with AstrBot Desktop Client
- Deploy AstrBot with Docker
- Deploy AstrBot with Kubernetes
- Deploy AstrBot with AstrBot Launcher
- Other Deployments
- Script Deployment
- Installation via System Package Manager
- Preface
- dev
- AstrBot Configuration File
- API Scope–Endpoint Reference
- AstrBot HTTP API
- AstrBot Plugin Market JSON Specification
- Developing a Platform Adapter
- plugin
- AI
- Agents
- Sessions and Conversations
- Models
- Other APIs
- Tools
- Documentation moved
- Text to Image
- Handling Message Events
- Plugin Configuration
- Plugin Internationalization
- Documentation moved
- Shared Bridge API
- Interactive message component
- Standalone plugin page
- Backend Web APIs
- Workbench page
- Sending Messages
- Session Control
- Minimal Example
- Plugin Storage
- AstrBot Plugin Development Guide 🌠
- Publishing Plugins to the Plugin Marketplace
- ospp
- others
- platform
- Connect OneBot v11 Protocol Implementations
- Connect to DingTalk
- Connecting to Discord
- Connect to KOOK
- Connecting to Lark
- Connecting to LINE
- Connecting to Matrix
- Connecting to Mattermost
- Connecting to Misskey Platform
- Connect QQ Official Bot
- Connect QQ via QQ Official Bot (Webhook)
- Connect QQ via QQ Official Bot (Websockets)
- Connect to Satori Protocol
- Connect server-satori (Koishi)
- Connecting to Slack
- Messaging Platforms
- Connecting to Telegram
- Connect to VoceChat
- Connect AstrBot to WeCom
- Connect to WeCom AI Bot Platform
- Connect AstrBot to WeChat Official Account Platform
- Connect Personal WeChat
- providers
- Connect 302.AI
- Agent Runners
- Built-in Agent Runner
- Connect to Coze
- Connect to Alibaba Cloud Bailian Application
- Connect to DeerFlow
- Connect to Dify
- Connect AIHubMix
- coze
- dashscope
- DeepSeek STT Integration
- DeepSeek TTS Integration
- dify
- Model input images
- Large Language Model Providers
- Connect MiraRouter
- NewAPI
- Connect PPIO Cloud
- Connect LM Studio to Use DeepSeek-R1 and Other Models
- Integrating Ollama
- Connect ShengSuanYun
- Connecting to SiliconFlow
- Connecting Model Services
- Connecting to TokenPony
- use
- Agent Execution Mode {#agent-runner}
- Agent Sandbox Environment
- astrbot sandbox
- AstrBot CLI {#cli-commands}
- Docker-based Code Interpreter
- Built-in Commands
- computer
- Context Compression
- Session Configuration Mappings (formerly Custom Rules)
- AstrBot Knowledge Base
- MCP
- AstrBot Plugins {#astrbot-star}
- Proactive Capabilities
- Skills {#anthropic-skills}
- Subagents {#agent-handsoff-and-subagent}
- Unified Webhook Mode
- Web Search
- DeepSeek Search API
- SerpApi
- WebUI