> ## Documentation Index > Fetch the complete documentation index at: https://platform.stepfun.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Agents and subagents Step Code delegates tasks to four built-in roles, supports custom agents defined in Markdown, and uses workflow to coordinate agents in parallel. ## Built-in agents | Role | Responsibility | Tools | | - | - | - | | `general` | General implementation tasks | All tools | | `explore` | Read-only repository exploration | `read_file`, `find_files`, `search_files`, `list_directory` | | `review` | Correctness and regression review | Read-only tools and command execution | | `planner` | Investigation and implementation planning | Read-only tools and command execution | Subagents return results to the main agent rather than talking directly to the user. Roles with command execution can perform writes, subject to tool permissions. ## The subagent tool ### single, parallel, and chain | Mode | Behavior | | - | - | | single | One role handles one task | | parallel | Multiple tasks run concurrently | | chain | Tasks run sequentially; `{previous}` references the prior result | Authorize delegation in natural language: ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}} Delegate two read-only tasks in parallel: one checks API error handling, the other checks test coverage. Return evidence and suggestions separately, then summarize them in the main agent. Do not modify files. ``` ### Background tasks The subagent tool accepts `run_in_background`. A background task returns a channel ID immediately and posts a notification with a summary, usage, and the sub-session path when it finishes. The Step Code process must remain running while tasks are active. `agent_send` operates on background tasks by channel ID: | Action | Effect | | - | - | | `reply` | Send a follow-up instruction to a background task; single-mode tasks only. Start a new subagent call for other modes | | `stop` | Stop a task | | `status` | Check task state; omit the channel ID to list every background task in the session | Background tasks are limited to 8 concurrent channels and stop automatically after 10 minutes idle. Only the 16 most recent finished tasks are kept; the sub-session paths of older tasks are in their completion notifications. To run every subagent task in the foreground, set `[subagent] background = false` in `config.toml`; see [Configuration files](https://platform.stepfun.ai/docs/en/step-code/configuration/files.md). ## Workflow and ultraloop Workflow executes JavaScript orchestration in a sandbox VM without network or filesystem access. Primitives include `phase()`, `parallel()`, `pipeline()`, `agent()`, and `iterate()`. Run records are stored in `.stepcode/workflows/runs/` and support resuming. Use `/workflows` to inspect saved workflows and recent runs. ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}} ultraloop Audit test coverage by module. Each subagent checks only its assigned directory and reports missing scenarios. The main agent deduplicates findings and proposes a testing plan. ``` Multi-agent calls require explicit authorization. This requirement is enforced through instructions; unauthorized calls are logged but not blocked at the execution layer. Include `ultraloop` or `ultracode`, or enable session-level authorization with `/ultraloop on` and disable it with `/ultraloop off`. Single-message authorization does not carry forward and is not inferred from task size. `STEP_DISABLE_WORKFLOW=1` disables registration. See [Common use cases](https://platform.stepfun.ai/docs/en/step-code/guides/use-cases.md) for examples of multi-agent tasks. `/ultracode [on|off|status|help]` manages multi-agent collaboration, with `/ultraloop` as an alias; `/workflows` shows workflows and run records. The switch persists per session: restoring the same session restores its state, and a new session without saved state defaults to off. ## Custom agents Use Markdown frontmatter for metadata and the body for system instructions: ```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}} --- name: db-migrator description: Design reversible database migrations and review migration scripts tools: read_file, run_command, edit_file --- Inspect existing migration conventions before planning. Every migration must include rollback steps. Do not connect to production databases or run production migrations without explicit authorization. ``` | Item | Description | | - | - | | User directory | `~/.stepcode/agent/agents/*.md` | | Project directory | `.stepcode/agents/` | | Required fields | `name`, `description` | | Optional fields | `tools`, `model` | | Same-name precedence | Project overrides user; user overrides built-in | `tools` accepts an array or comma-separated list. Include project roles explicitly with `agentScope: "both"` when calling the tool, and confirm when prompted. See [Agent Skills](https://platform.stepfun.ai/docs/en/step-code/customization/skills.md) for defining specialized workflows. See [Plugins and packages](https://platform.stepfun.ai/docs/en/step-code/customization/plugins.md) for distributing agents through plugins. ## Context isolation and safety The sandbox VM restricts only the workflow orchestration script. Subtask processes remain subject to OS permissions. * Subagents have independent context and token usage; the main agent primarily receives summaries. * Subagents may share the main agent's working directory, so file changes affect the same working tree. * Assign disjoint files for parallel writes, or explicitly arrange separate Git worktrees. * Worktrees isolate working trees, not access to other directories, networks, or credentials. * Review diffs and tests before integrating results. Do not clean up unmerged work blindly. The default scale is medium, approximately up to 15 agents, unless explicitly expanded. See [Permissions and safety](https://platform.stepfun.ai/docs/en/step-code/guides/permissions.md) for shared approval and access rules. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.