agy_subagents
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AGY_BIN | No | Explicit path to the agy executable. Default: auto-detected (agy / ~/.gemini/bin/agy). | |
| AGY_NO_PROXY | No | Set to 1 to disable proxy forwarding to agy. | |
| AGY_MAX_QUEUE | No | Max queued + active subagents accepted per burst (1–64). | 32 |
| AGY_PROXY_URL | No | Optional proxy URL forwarded to agy. Default: inherits HTTP(S)_PROXY. Set AGY_NO_PROXY=1 to disable. | |
| AGY_STATE_DIR | No | Directory for persisted run state, transcripts, and worktrees. | %LOCALAPPDATA%\codex-agy-subagents |
| AGY_HEAVY_MODEL | No | Default model for tier="heavy" (worker / reviewer). | gemini-4-neon-xhigh |
| AGY_LIGHT_MODEL | No | Default model for tier="light" (explorer / researcher). | gemini-4-hydrogen-xhigh |
| AGY_STAGGER_SEC | No | Minimum delay between consecutive launches (seconds). | 1.5 |
| AGY_MAX_CONCURRENT | No | Max live concurrent agy subprocesses (1–16; 4–6 recommended). | 5 |
| AGY_COOLDOWN_MAX_SEC | No | Max circuit-breaker cooldown duration. | 180 |
| AGY_MAX_OUTPUT_CHARS | No | Max chars returned inline; full output is always saved to output.txt. | 16000 |
| AGY_COOLDOWN_BASE_SEC | No | Base exponential-backoff pause on 429 / auth errors. | 15 |
| AGY_DEFAULT_TIMEOUT_SEC | No | Default per-turn timeout passed to --print-timeout. | 600 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
PRIMARY Antigravity (agy) subagent runtime mirroring Codex native subagents. ALWAYS prefer agy_spawn_agent / agy_wait_agent / agy_send_input / agy_status / agy_close_agent FIRST for all parallelizable subtasks, codebase exploration, research, review, and independent coding tracks; use native Codex spawn_agent only as a fallback when agy_subagents is paused/unavailable or when a task requires Codex-only native tools. Model tiers: tier='light' (explorer/researcher/docs) uses gemini-4-hydrogen-xhigh; tier='heavy' (worker/reviewer/complex coding) uses gemini-4-neon-xhigh. Use isolation='worktree' and exclusive owned_paths for concurrent write tasks. Only the root orchestrator should invoke agy_spawn_agent; never recurse from child subagents.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| agy_spawn_agentA | 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. |
| agy_wait_agentA | Wait for one or more Antigravity subagents to finish (mirrors native Codex wait). Pass wait_for='any' to stream results as each agent finishes, or 'all' to wait for the full batch. Returns completed results, conversation_id, changed_files, scope_violations, branch, and still_running. |
| agy_send_inputA | Send follow-up instructions or review feedback to an existing Antigravity subagent (mirrors native Codex send_input). Preserves full conversation context via --conversation; if the agent is still running, queues the message in its mailbox for the next turn. |
| agy_statusA | Non-blocking status inspection for one agent or the entire Antigravity subagent pool (active count, queue length, live step progress, circuit-breaker cooldown status). |
| agy_close_agentA | Cancel/close an Antigravity subagent (mirrors native Codex close_agent). Terminates any running process tree and optionally removes its isolated Git worktree. |
| agy_healthA | Check Antigravity CLI readiness, proxy configuration, available model IDs, and current concurrency/cooldown pool status without consuming model quota. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool maps to a distinct phase of the subagent lifecycle: spawn, wait, send_input, status, close, health. Descriptions explicitly delineate blocking vs non-blocking and clarify that agy_status is read-only inspection while agy_wait_agent blocks for results, so there is no realistic misselection.
All tools share a uniform agy_ snake_case prefix and readable names. The only inconsistency is style: most use verbs (spawn, wait, send, close) while agy_status and agy_health are noun-style inspection tools, a minor but noticeable deviation.
Six tools cover the complete subagent lifecycle without redundancy, matching the mirrored native Codex primitives almost one-to-one. Nothing feels padded or missing at this scope.
Spawn, wait, follow-up input, status, close, and health give full lifecycle coverage including worktree cleanup and pool diagnostics. Minor gaps: no explicit enumeration of individual agent IDs or metadata beyond the pool aggregate, and no dedicated result-retrieval tool once an agent has already been collected.