Synchronous single agent call (BLOCKING, 30-120s).

⚠️ STOP: Choose the Right Tool First

Decision Tree:

1. Need to run explore/researcher? → Use call_agent_async (NEVER this tool)

2. Need multiple agents in parallel? → Use call_agent_async × N, NOT call_agents_batch

3. Need advisor advice or must verify result immediately? → Use this tool

Why async for search agents?

• explore/researcher may take 30-120s each

• Blocking wastes your time waiting

• Async lets you continue working while agents search

Available Agents

• advisor: Read-only consultation agent. High-IQ reasoning specialist for debugging hard problems and high-difficulty architecture design.

• researcher: Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples.

• explore: Contextual grep for codebases. Answers "Where is X?", "Which file has Y?", "Find the code that does Z".

• frontend-ui-ux-engineer: A designer-turned-developer who crafts stunning UI/UX even without design mockups. Code may be a bit messy, but the visual output is always fire.

• document-writer: A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides.

Agent → Tool Mapping

Start agent task in background (NON-BLOCKING). Returns task_id immediately.

✅ Recommended for explore/researcher

Workflow:

1. call_agent_async → get task_id instantly

2. Continue your work (read files, think, etc.)

3. get_agent_result(task_id, block=true) when ready

Why async is better:

• No wasted waiting time

• Can launch multiple searches in parallel

• Check results when YOU need them

Parallel search pattern:

call_agent_async(explore, "Find X") → task_1
call_agent_async(researcher, "Find Y") → task_2
... do other work ...
get_agent_result(task_1, block=false)
get_agent_result(task_2, block=false)
... do other work ...
get_agent_result(task_1, block=true)
get_agent_result(task_2, block=true)

Get result from async agent task.

Parameters:

• task_id: The task ID from call_agent_async

• block: If true, wait for completion (default: false)

• timeout: Max wait time in ms when blocking (default: 300000 = 5min)

Returns task status and result if completed.

Execute multiple agents in PARALLEL (BLOCKING until ALL complete).

⚠️ Usually NOT what you want

Prefer call_agent_async × N instead:

• Async returns immediately, you can continue working

• Batch blocks until the SLOWEST agent finishes

• If one agent takes 2min, you wait 2min doing nothing

Only use batch when:

• You MUST have ALL results before ANY next step

• Results are interdependent (rare)

• You're okay blocking for potentially minutes

Example (usually wrong):

{ "calls": [{ "agent": "explore", ... }, { "agent": "researcher", ... }] }

↑ This blocks until both finish. Use call_agent_async × 2 instead.

Example (correct use case): Comparing outputs from multiple agents where you need all results simultaneously.