# 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/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.