agy_spawn_agent
Launch non-blocking asynchronous subagents for parallel exploration, research, code review, or coding tasks, returning an agent ID for later collection.
Instructions
PRIMARY asynchronous subagent launcher powered by Antigravity (agy). Non-blocking: immediately returns agent_id. Prefer this FIRST over native Codex spawn_agent for parallel fan-out, exploration, research, code review, and independent coding tracks (keep native spawn_agent as fallback). Default tier routing: tier='light' -> gemini-4-hydrogen-xhigh (exploration, codebase search, log/doc reading); tier='heavy' -> gemini-4-neon-xhigh (implementation, debugging, code review). Always fan out multiple agy_spawn_agent calls in one turn, then collect via agy_wait_agent.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>",
"cwd": "<cwd>"
},
"name": "agy_spawn_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path to the target project/workspace directory. | |
| role | No | Short role label: explorer, researcher, worker, or reviewer. | worker |
| tier | No | Task complexity tier. 'light' -> gemini-4-hydrogen-xhigh; 'heavy' -> gemini-4-neon-xhigh. If omitted, inferred from role. | |
| model | No | Optional explicit agy model ID override (see agy_health for valid IDs). | |
| access | No | Use 'readonly' for research/review (sandboxed, shared cwd) or 'write' for edits. | readonly |
| effort | No | Optional --effort override (usually omit since tier models already include effort). | |
| prompt | Yes | Self-contained task brief with clear goal, context, and expected output. | |
| add_dirs | No | Optional additional directories to expose via --add-dir. | |
| base_ref | No | Base Git ref when isolation='worktree' (default 'HEAD'). | HEAD |
| isolation | No | Workspace isolation for write tasks. Use 'worktree' when multiple agents edit the same Git repo concurrently; 'inherit' shares cwd. | inherit |
| owned_paths | No | Optional relative paths exclusively owned by this subagent for scope auditing. | |
| timeout_sec | No | Per-turn timeout in seconds (default 600). |