Community translations by veiseule.ai — Help improve them on Crowdin
Skip to main content

Субагенты

Подагенты позволяют запускать фоновые задачи, не блокируя основной диалог. Когда вы создаете подагента, он запускается в собственной изолированной сессии, выполняет свою работу и по завершении объявляет результат обратно в чат.

Сценарии использования:

  • Исследовать тему, пока основной агент продолжает отвечать на вопросы
  • Запускать несколько длительных задач параллельно (веб-скрейпинг, анализ кода, обработка файлов)
  • Делегировать задачи специализированным агентам в многоагентной конфигурации

Быстрый старт

Самый простой способ использовать подагентов — попросить агента естественным образом:

"Создай подагента для изучения последних примечаний к выпуску Node.js"

Агент за кулисами вызовет инструмент sessions_spawn. Когда подагент завершит работу, он объявит свои выводы обратно в ваш чат.

Вы также можете явно указать параметры:

"Создай подагента для анализа серверных логов за сегодня. Используй gpt-5.2 и задай тайм-аут 5 минут." Основной агент вызывает sessions_spawn с описанием задачи.

Как это работает

Вызов неблокирующий — основной агент немедленно получает { status: "accepted", runId, childSessionKey }. Создается новая изолированная сессия (agent: :subagent:) в выделенной очереди subagent.

Когда подагент завершает работу, он объявляет свои выводы обратно в чат запрашивающей стороны.Основной агент публикует сводку на естественном языке.Сессия подагента автоматически архивируется через 60 минут (настраивается). Транскрипты сохраняются. У каждого подагента есть собственный контекст и расход токенов. Установите более дешевую модель для подагентов, чтобы снизить затраты — см. Setting a Default Model ниже. Подагенты работают «из коробки» без какой-либо настройки.

Модель: обычный выбор модели целевого агента (если не задано subagents.model) Мышление: без переопределения для подагента (если не задано subagents.thinking)

Конфигурация

Макс. одновременных: 8 Значения по умолчанию:

  • Автоархивация: через 60 минут
  • Задание модели по умолчанию
  • Используйте более дешевую модель для подагентов, чтобы экономить на токенах:
  • { agents: { defaults: { subagents: { model: "minimax/MiniMax-M2.1", }, }, }, }

Задание уровня мышления по умолчанию

Use a cheaper model for sub-agents to save on token costs:

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

Setting a Default Thinking Level

{
  agents: {
    defaults: {
      subagents: {
        thinking: "low",
      },
    },
  },
}

Per-Agent Overrides

In a multi-agent setup, you can set sub-agent defaults per agent:

{
  agents: {
    list: [
      {
        id: "researcher",
        subagents: {
          model: "anthropic/claude-sonnet-4",
        },
      },
      {
        id: "assistant",
        subagents: {
          model: "minimax/MiniMax-M2.1",
        },
      },
    ],
  },
}

Конвертация

Control how many sub-agents can run at the same time:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4, // default: 8
      },
    },
  },
}

Sub-agents use a dedicated queue lane (subagent) separate from the main agent queue, so sub-agent runs don't block inbound replies.

Auto-Archive

Sub-agent sessions are automatically archived after a configurable period:

{
  agents: {
    defaults: {
      subagents: {
        archiveAfterMinutes: 120, // default: 60
      },
    },
  },
}

Archive renames the transcript to *.deleted.<timestamp> (same folder) — transcripts are preserved, not deleted. Auto-archive timers are best-effort; pending timers are lost if the gateway restarts.

The sessions_spawn Tool

This is the tool the agent calls to create sub-agents.

Параметры

Parameter Тип Значение по умолчанию Description
task string (required) What the sub-agent should do
метка string — Short label for identification
agentId string (caller's agent) Spawn under a different agent id (must be allowed)
модель string (optional) Override the model for this sub-agent
thinking string (optional) Override thinking level (off, low, medium, high, etc.)
runTimeoutSeconds number 0 (no limit) Abort the sub-agent after N seconds
очистка "delete" \ "keep" "keep"

Model Resolution Order

The sub-agent model is resolved in this order (first match wins):

  1. Explicit model parameter in the sessions_spawn call
  2. Per-agent config: agents.list[].subagents.model
  3. Global default: agents.defaults.subagents.model
  4. Target agent’s normal model resolution for that new session

Thinking level is resolved in this order:

  1. Explicit thinking parameter in the sessions_spawn call
  2. Per-agent config: agents.list[].subagents.thinking
  3. Global default: agents.defaults.subagents.thinking
  4. Otherwise no sub-agent-specific thinking override is applied

Invalid model values are silently skipped — the sub-agent runs on the next valid default with a warning in the tool result.

Cross-Agent Spawning

By default, sub-agents can only spawn under their own agent id. To allow an agent to spawn sub-agents under other agent ids:

{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // or ["*"] to allow any
        },
      },
    ],
  },
}

Use the agents_list tool to discover which agent ids are currently allowed for sessions_spawn.

Managing Sub-Agents (/subagents)

Используйте слеш-команду /subagents для просмотра и управления запусками субагентов в текущей сессии:

Команда Description
/subagents list List all sub-agent runs (active and completed)
/subagents stop <id\\|#\\|all> Stop a running sub-agent
/subagents log <id\\|#> [limit] [tools] View sub-agent transcript
/subagents info <id\\|#> Show detailed run metadata
/subagents send <id\\|#> <message> Send a message to a running sub-agent

You can reference sub-agents by list index (1, 2), run id prefix, full session key, or last.

/subagents list

````
```
🧭 Subagents (current session)
Active: 1 · Done: 2
1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:...
2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:...
3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:...
```

```
/subagents stop 3
```

```
⚙️ Stop requested for deploy staging.
```
````

/subagents info 1

````
```
ℹ️ Информация о субагенте
Статус: ✅
Метка: журналы исследований
Задача: Изучить последние журналы ошибок сервера и обобщить выводы
Запуск: a1b2c3d4-...
Сессия: agent:main:subagent:...
Время выполнения: 2m31s
Очистка: keep
Результат: ok
```
````

/subagents log 1 10

````
Shows the last 10 messages from the sub-agent's transcript. Add `tools` to include tool call messages:

```
/subagents log 1 10 tools
```
````

/subagents send 3 "Also check the staging environment"

```
Sends a message into the running sub-agent's session and waits up to 30 seconds for a reply.
```

Announce (How Results Come Back)

When a sub-agent finishes, it goes through an announce step:

  1. Итоговый ответ субагента сохраняется
  2. A summary message is sent to the main agent's session with the result, status, and stats
  3. The main agent posts a natural-language summary to your chat

Ответы объявления сохраняют маршрутизацию тредов/тем, где это доступно (треды Slack, темы Telegram, треды Matrix).

Announce Stats

Each announce includes a stats line with:

  • Runtime duration
  • Расход токенов (вход/выход/всего)
  • Estimated cost (when model pricing is configured via models.providers.*.models[].cost)
  • Session key, session id, and transcript path

Announce Status

The announce message includes a status derived from the runtime outcome (not from model output):

  • successful completion (ok) — task completed normally
  • error — task failed (error details in notes)
  • timeout — task exceeded runTimeoutSeconds
  • unknown — status could not be determined

If no user-facing announcement is needed, the main-agent summarize step can return NO_REPLY and nothing is posted. This is different from ANNOUNCE_SKIP, which is used in agent-to-agent announce flow (sessions_send).

Tool Policy

By default, sub-agents get all tools except a set of denied tools that are unsafe or unnecessary for background tasks:

| Denied tool | Reason | |-------------|--------| | sessions_list | Session management — main agent orchestrates | | sessions_history | Session management — main agent orchestrates | | sessions_send | Session management — main agent orchestrates | | sessions_spawn | No nested fan-out (sub-agents cannot spawn sub-agents) | | gateway | System admin — dangerous from sub-agent | | agents_list | System admin | | whatsapp_login | Interactive setup — not a task | | session_status | Status/scheduling — main agent coordinates | | cron | Status/scheduling — main agent coordinates | | memory_search | Pass relevant info in spawn prompt instead | | memory_get | Pass relevant info in spawn prompt instead |

Customizing Sub-Agent Tools

You can further restrict sub-agent tools:

{
  tools: {
    subagents: {
      tools: {
        // deny always wins over allow
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

To restrict sub-agents to only specific tools:

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // deny still wins if set
      },
    },
  },
}

Custom deny entries are added to the default deny list. If allow is set, only those tools are available (the default deny list still applies on top).

Аутентификация

Аутентификация субагента определяется id агента, а не типом сессии:

  • The auth store is loaded from the target agent's agentDir
  • The main agent's auth profiles are merged in as a fallback (agent profiles win on conflicts)
  • The merge is additive — main profiles are always available as fallbacks

Fully isolated auth per sub-agent is not currently supported.

Context and System Prompt

Sub-agents receive a reduced system prompt compared to the main agent:

  • Included: Tooling, Workspace, Runtime sections, plus AGENTS.md and TOOLS.md
  • Not included: SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md

Субагент также получает системный промпт, ориентированный на задачу, который инструктирует его оставаться сосредоточенным на назначенной задаче, выполнить ее и не действовать как основной агент.

Stopping Sub-Agents

Method Effect
/stop in the chat Aborts the main session and all active sub-agent runs spawned from it
/subagents stop <id> Stops a specific sub-agent without affecting the main session
runTimeoutSeconds Automatically aborts the sub-agent run after the specified time

runTimeoutSeconds does not auto-archive the session. The session remains until the normal archive timer fires.

Полный пример конфигурации

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops can spawn sub-agents under "main"
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // sub-agents can't use the browser
      },
    },
  },
}

Ограничения

- Best-effort announce: If the gateway restarts, pending announce work is lost. - No nested spawning: Sub-agents cannot spawn their own sub-agents. - Shared resources: Sub-agents share the gateway process; use maxConcurrent as a safety valve. - Auto-archive is best-effort: Pending archive timers are lost on gateway restart.

See Also

veiseule.ai — Community translations maintained by John Kelly. Improve translations on Crowdin.