156 lines
10 KiB
Markdown
156 lines
10 KiB
Markdown
# Agent Capabilities
|
|
|
|
Astrion's agent capabilities fall into five areas: **sub agents** (delegates dispatched by the main agent), **multi-agent conversation** (a team of roles), **workflows** (predefined process templates), **Skills** (specialized capability packs), and **MCP** (external tool integration). This chapter covers how to use and configure each one.
|
|
|
|
---
|
|
|
|
## 1. Sub Agents
|
|
|
|
### What It Is
|
|
|
|
A sub agent is an independent executor dispatched by the main agent **within the same process**: it has its own context, its own model configuration, and an independent lifecycle. The main agent uses it to **process mutually independent tasks in parallel** — typical scenarios: researching three technical approaches at once, or organizing documentation while tests run.
|
|
|
|
What it is **not** for: sub agents cannot communicate with each other and cannot see the main conversation history, so collaborative tasks (where A's output is B's input) should be executed sequentially or handed to a single sub agent. Code writing/editing tasks are by default handled directly by the main agent.
|
|
|
|
### How to Use
|
|
|
|
Usually you don't need to operate directly — tell the main agent "do X and Y for me at the same time" and it will decide on its own whether to split the work into sub agents. Two ways of running:
|
|
|
|
- **Foreground (blocking)**: the main agent pauses and waits for it to finish; suited for fast tasks or scenarios where subsequent steps depend on the result;
|
|
- **Background**: the main agent keeps working or chats with you; when the sub agent finishes, the system notifies you automatically.
|
|
|
|
You can watch each sub agent's status and output in real time via the **"Sub Agents" pane in the Quick Dock** on the right side of the conversation area (see "Quick Dock").
|
|
|
|
### Lifecycle & Limits
|
|
|
|
- States: `running` → `idle` (context is preserved, can continue the conversation) / terminal states (completed / failed / timed out / terminated);
|
|
- Default concurrency limit: **5** (`SUB_AGENT_MAX_ACTIVE`);
|
|
- Default timeout: **180 seconds**; you can specify a longer timeout for an individual task when creating it (1800+ seconds recommended for large-scale analyses);
|
|
- Outputs are conventionally placed under `sub_agent_results/` in the workspace.
|
|
|
|
### Configuration (Model Library)
|
|
|
|
Sub agents use a separate model library, `sub_agent_models.json`; see Section 6 of "Quick Start" for configuration. When creating an individual task, the main agent can specify: the model entry, thinking mode, timeout, max rounds, and more. If not specified, the `default_model` entry is used.
|
|
|
|
## 2. Multi-Agent Conversation
|
|
|
|
### What It Is
|
|
|
|
A **conversation type** (chosen at creation time and immutable): the main agent is fixed as Team Leader, responsible for understanding your requirements, breaking down tasks, creating and directing a group of **role-assigned sub agents**, and consolidating their outputs.
|
|
|
|
### Role System
|
|
|
|
5 preset roles:
|
|
|
|
| Role | Responsibility |
|
|
|------|------|
|
|
| Full-Stack Engineer | Frontend/backend implementation, API design, debugging and integration |
|
|
| UI Operator | UI operations and visual verification |
|
|
| Code Reviewer | Code review |
|
|
| Researcher | Research and information gathering |
|
|
| Brainstormer | Brainstorming and idea exploration |
|
|
|
|
A role = `role ID + instance number`, with display names like `Full-Stack Engineer_1`; numbers increment within each role.
|
|
|
|
**Custom roles**: Personal Space has a role editor (role list → create/edit). A role definition is a Markdown file with metadata:
|
|
|
|
```markdown
|
|
---
|
|
id: full-stack-engineer # Role ID
|
|
name: Full-Stack Engineer # Display name
|
|
description: One-line role summary # Team Leader assigns tasks based on this
|
|
model: "" # Pin a model (empty = sub-agent model library default)
|
|
thinking_mode: thinking # fast / thinking
|
|
---
|
|
|
|
(The body is the role's system prompt: responsibilities, working principles, constraints...)
|
|
```
|
|
|
|
### Communication Mechanics (What You Need to Know)
|
|
|
|
- Team Leader sends messages to sub agents in two ways: **assigning work** (non-blocking, keeps doing other things) and **asking** (blocking, waits for one round of reply);
|
|
- Sub agents can ask/answer each other, but **all inter-sub-agent communication is reported to the Team Leader in sync**;
|
|
- Every round of a sub agent's output is reported to the Team Leader in real time and shown in the conversation flow; you can jump in at any time to correct course.
|
|
|
|
### When to Use Multi-Agent
|
|
|
|
Good fit: a small project that needs "a coder + a code reviewer + a UI runner" working in division of labor; not a fit: tasks a single thread can finish on its own (it only adds coordination overhead).
|
|
|
|
## 3. Workflows
|
|
|
|
### What It Is
|
|
|
|
Write a **predefined process** (stages, review gates, branches, ending conditions) into a `WORKFLOW.md` file and save it as a template; once activated, the agent advances strictly stage by stage, reporting to you or a review agent after each stage, and only moves to the next stage after the review passes.
|
|
|
|
### How to Use
|
|
|
|
- Activate: `+` menu → "Workflow", or type `/workflow` to choose;
|
|
- Progression: after each stage, the AI reports automatically and moves to the next stage (when the stage includes a review gate, the review agent checks it; a rejection is sent back to the previous stage with remediation feedback);
|
|
- Branches: at a branch point, the AI presents a menu of paths for you to decide;
|
|
- Exit / check progress: ask the AI to exit the workflow or report current progress at any time;
|
|
- Only one workflow can be active in a conversation at a time.
|
|
|
|
### Built-in Workflows
|
|
|
|
| Workflow | Purpose |
|
|
|--------|------|
|
|
| bug-fix-triage | Defect triage and fix process |
|
|
| code-review-pipeline | Code review pipeline |
|
|
| feature-development | Full feature development process |
|
|
| research-report | Research report generation process |
|
|
|
|
### Custom Workflows
|
|
|
|
Write one following the `WORKFLOW.md` format of the built-in workflows and drop it into the workflow library directory. It's recommended to just ask the AI in natural language, e.g. "use the workflow-authoring skill to write me an xx workflow" — the system has built-in authoring guidelines and format validation, and the finished workflow is archived automatically and ready to activate.
|
|
|
|
Workflow reviews are performed by the **workflow review agent** (`workflow_review`); see "Review Agents" below for configuration.
|
|
|
|
## 4. Skills (Skill Packs)
|
|
|
|
### What It Is
|
|
|
|
A Skill = a folder + a `SKILL.md` file (a skill specification with metadata). It captures the experience of "how to do a certain type of task"; when the AI encounters a matching scenario, it reads the skill before acting — like giving the AI an on-the-job training manual.
|
|
|
|
### Built-in Skills (12)
|
|
|
|
`agent-build-standard` (Agent architecture guide), `agents-md-writer` (writing AGENTS.md), `docx` (Word documents), `pptx` (PPT), `frontend-design` (frontend design), `ui-aesthetic-design` (UI aesthetics), `skill-creator` (creating new Skills), `workflow-authoring` (writing workflows), `run-command-guide` (command execution guidelines), `terminal-guide` (terminal usage guidelines), `sub-agent-guide` (sub agent guidelines), `mcp-tool-config` (MCP self-service configuration).
|
|
|
|
### How to Use
|
|
|
|
- Insert a reference: type `//` or use the `+` menu → "Select AgentSkill" to insert a skill reference into your message;
|
|
- Enable/disable: manage the enabled list on the "Tools & Skills" page in Personal Space;
|
|
- **Strict-guard toggles** (all off by default): you can require "read terminal-guide before using the terminal", "read the guidelines before using run_command in foreground/background mode", and "read sub-agent-guide before dispatching a sub agent" — useful during the learning phase to prevent misuse, and can be turned off once you're experienced;
|
|
- **Skill suggestions** (off by default): dynamically suggests potentially relevant skills based on the current task.
|
|
|
|
### Custom Skills
|
|
|
|
Just tell the AI "capture today's process as a skill" and it will create, validate, and archive it following the `skill-creator` guidelines, ready to reuse afterwards. User skills are stored in `.astrion/skills/` in the workspace.
|
|
|
|
## 5. MCP Tool Extensions
|
|
|
|
Connect external tool services (databases, browser automation, third-party SaaS...) via [Model Context Protocol](https://modelcontextprotocol.io); after connecting, new tools of the form `mcp__service name__tool name` appear in the AI's tool list.
|
|
|
|
- **Config file**: `<data root>/<mode>/data/mcp_servers.json` (can be overridden with `MCP_SERVERS_FILE`);
|
|
- **Master switch**: `MCP_TOOLS_ENABLED` (on by default);
|
|
- Protocol version `2025-06-18`, default 25-second timeout for tool discovery/invocation;
|
|
- **Host mode feature**: you can directly ask the AI to "configure xxx MCP service for me" — the built-in `mcp-tool-config` skill guides it to write the config and make it take effect on its own.
|
|
|
|
## 6. Review Agents (Three)
|
|
|
|
Three independent AIs that check key milestones on your behalf, all configured on the "Review Agents" page in Personal Space; **they reuse the sub agent model library**:
|
|
|
|
| Review Agent | When It Steps In |
|
|
|------------|----------|
|
|
| `auto_approval` Auto-approval | Under the `auto_approval` permission mode, auto-approves when a command is about to write outside the sandbox or triggers a permission denial |
|
|
| `goal_review` Goal review | In goal mode, evaluates whether each round of work achieved the goal |
|
|
| `workflow_review` Workflow review | At workflow review gates, decides whether to pass or reject |
|
|
|
|
Each can be configured with: `model` (leave empty for the model library default), `thinking` (thinking mode), `timeout_seconds`, `max_rounds`, `max_command_timeout`.
|
|
|
|
> Tip: for review agents, choose **cheap but stable** models — they are called frequently with fixed task patterns, so flagship models are unnecessary.
|
|
|
|
## 7. Combinatorial Examples
|
|
|
|
- **Multi-agent + workflow**: after activating the feature-development workflow, the Team Leader directs the role team through stage-by-stage delivery per the process;
|
|
- **Sub agents + Skills**: insert `//frontend-design` before a research task, and the sub agent works with the design guidelines in mind;
|
|
- **MCP + Quick Dock**: when a browser-automation MCP runs a long task, watch real-time progress in the "Background Commands" pane. |