SDKSubagents for programs

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

FlagEffect
--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 reviewer

What a program can do

  • Let the main run start subagents on its own, as the subagents guide describes.
  • Limit the whole run with --max-turns and --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 set SYNTIC_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 with SYNTIC_MAX_CONCURRENT_SUBAGENTS (1 to 256, default 20). There is no command-line flag for either. Bound the whole run with --max-turns and --max-budget-usd.