Subagents for programs
A subagent is a helper the main run starts for one job. The agent definition format and the built-in subagents are on the subagents guide. This page lists what a program can control from the command line.
Agent flags
| Flag | Effect |
|---|---|
--agent <name> | Run the main session as this custom agent, from .syntic/agents, ~/.syntic/agents or --agents. |
--agents <json> | Extra agent definitions for this run, as a JSON object or a file holding one: {"name": {"prompt": "...", "tools": [...]}}. |
--append-subagent-system-prompt <text> | Adds this text at the end of each subagent’s system prompt. |
--append-subagent-system-prompt-file <file> | The same, read from a file. When both are given, the file’s text comes first. |
syntic -p "review the staged changes" \
--agents '{"reviewer": {"prompt": "You review diffs for bugs.", "tools": ["Read", "Grep"]}}' \
--agent reviewerWhat a program can do
- Let the main run start subagents on its own, as the subagents guide describes.
- Limit the whole run with
--max-turnsand--max-budget-usd. These limits apply to the main run and the work it does, so they bound subagents too. - Keep subagent permission questions inside the run’s rules. A non-interactive run refuses any call that would need approval, so choose the mode and allow rules before the run starts. See Permissions for programs.
Subagent tool and MCP access
A subagent’s tools and MCP servers come from its agent file. A subagent that defines its own MCP servers does not need them shared with the main run. See MCP for programs.
Limits
- Subagent tool calls and results are always in the stream, keyed by
parent_tool_use_id. Their text and reasoning are left out unless you add--forward-subagent-text(or setSYNTIC_FORWARD_SUBAGENT_TEXT=1). See Streaming output. - How deep subagents nest is set with
SYNTIC_MAX_SUBAGENT_DEPTH(1 to 8), and how many run at once withSYNTIC_MAX_CONCURRENT_SUBAGENTS(1 to 256, default 20). There is no command-line flag for either. Bound the whole run with--max-turnsand--max-budget-usd.
Related
- Permissions for programs for the rules a subagent’s calls must pass.
- Streaming output for the messages a run prints.