> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent 与 subagent

Step Code 可以将任务派给子代理：四个内置角色各司其职，自定义 Agent 使用 Markdown 文件定义，workflow 则用于编排多代理并行。

## 内置 agent

| 角色        | 职责        | 工具范围                                                     |
| --------- | --------- | -------------------------------------------------------- |
| `general` | 通用实现任务    | 全部工具                                                     |
| `explore` | 只读仓库侦察    | `read_file`、`find_files`、`search_files`、`list_directory` |
| `review`  | 正确性与回归审查  | 只读工具和命令执行                                                |
| `planner` | 调查并制定实施计划 | 只读工具和命令执行                                                |

子代理不直接与用户对话，结果返回主代理。带命令执行能力的角色不等于系统层面只读；其行为仍取决于工具权限。

## 自定义 agent

使用 Markdown frontmatter 定义角色，正文作为系统指令：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
---
name: db-migrator
description: 设计可回滚的数据库迁移方案并审查迁移脚本
tools: read_file, run_command, edit_file
---

先检查现有迁移约定，再制定方案。所有迁移必须提供回滚步骤。
未经明确授权，不连接生产数据库，不执行生产迁移。
```

| 项目    | 说明                              |
| ----- | ------------------------------- |
| 用户目录  | `~/.stepcode/agent/agents/*.md` |
| 项目目录  | `.stepcode/agents/`             |
| 必填字段  | `name`、`description`            |
| 可选字段  | `tools`、`model`                 |
| 同名优先级 | 项目覆盖用户，用户覆盖内置                   |

`tools` 可以使用数组或逗号分隔列表。项目角色需显式纳入发现范围，调用时通过 `agentScope: "both"` 启用，并按提示确认。

## subagent 工具

### single、parallel 与 chain

| 模式       | 行为                               |
| -------- | -------------------------------- |
| single   | 一个角色处理一个任务                       |
| parallel | 多个任务并行执行                         |
| chain    | 顺序执行，后续任务通过 `{previous}` 引用前一步结果 |

任务批次并行上限为 8，默认执行并发为 4。调度仍受当前权限策略约束。子代理不再递归创建子代理。

您可以通过自然语言授权主代理使用这些能力：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请并行委派两个只读任务：一个检查 API 错误处理，一个检查对应测试覆盖。分别返回证据和建议，由主代理汇总，不修改文件。
```

### 后台 lane

设置 `run_in_background: true` 创建后台 lane，立即返回 lane ID / alias，完成时通过通知消息送达。`agent_send` 支持 `reply`（排队或立即插入）和 `stop`，可按 `agent_id`、`alias`、`group` 或 `all` 寻址。

后台任务仍依赖 Step Code 进程，不等于独立的系统守护服务。

## workflow 与 ultraloop

workflow 在无网络、无文件系统的沙箱 VM 中运行 JavaScript 编排脚本，提供 `phase()`、`parallel()`、`pipeline()`、`agent()` 和 `iterate()` 原语。运行记录保存在项目 `.stepcode/workflows/runs/`，支持断点续跑，使用 `/workflows` 查看已保存的 workflow 与近期运行。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ultraloop 按模块审查测试覆盖。各子代理只检查分配的目录，返回缺失场景；主代理去重并给出补测计划。
```

多代理需要显式授权：在消息中使用 `ultraloop` 或 `ultracode`，或使用 `/ultraloop on` 开启会话级授权、`/ultraloop off` 关闭。单条消息的授权不自动延续，也不从任务规模推断。未授权调用仅被记录，不会在执行层拦截，执行约束由提示词承担。

`STEP_DISABLE_WORKFLOW=1` 禁用注册。workflow 编排脚本的受限运行环境不等于执行子任务的进程已被系统隔离；授权约定也不能替代操作系统权限控制。

## 上下文隔离与安全

* 子代理拥有独立上下文和用量，主代理主要接收结果摘要。
* 默认工作目录可能与主代理相同，独立上下文不会自动隔离文件修改。
* 并行写入时应划分互不重叠的文件，或明确安排独立 Git worktree。
* Git worktree 只隔离工作树，不限制其他目录、网络或凭据访问。
* 完成后先检查差异和测试，再合并结果；未合并改动不要直接清理。

默认规模为 medium（约 15 个 Agent 以内），除非明确要求扩大。每个子代理独立消耗 token，主上下文只收结论。

## 下一步

* [Agent Skills](/docs/zh/step-code/customization/skills)
* [插件](/docs/zh/step-code/customization/plugins)
* [常见使用案例](/docs/zh/step-code/guides/use-cases)