Skip to main content
Agents can call other agents to delegate work and collect results. This enables multi-agent workflows like planner → developer → reviewer pipelines.

​
Use Case

A planner agent triages an issue and creates an implementation plan. It calls a dev agent to implement it, then calls a reviewer agent to review the PR.

​
al-subagent: Fire a call

Pass context to another agent via stdin: 
echo "Implement the fix for issue #42 on acme/app" | al-subagent dev
Response: 
{"ok": true, "callId": "abc123"}
The call is non-blocking — the calling agent continues working immediately.

​
al-subagent-check: Non-blocking status

Check if a call has finished without waiting: 
al-subagent-check abc123
Response: 
{"status": "pending"}
{"status": "running"}
{"status": "completed", "returnValue": "PR #17 opened."}
{"status": "error", "error": "timeout"}

​
al-subagent-wait: Block until done

Wait for one or more calls to complete: 
al-subagent-wait abc123 --timeout 600
al-subagent-wait abc123 def456 --timeout 300
Response: 
{
  "abc123": {"status": "completed", "returnValue": "PR #17 opened."},
  "def456": {"status": "completed", "returnValue": "All tests pass."}
}
Default timeout: 900 seconds. Polls every 5 seconds.

​
al-return: Send back a result

The called agent uses al-return to send a value back to the caller: 
al-return "PR #17 opened. Ready for review."

​
Multi-call Pattern

Fire several calls, continue working, then collect all results: 
# Fire calls
DEV_ID=$(echo "Implement fix for #42" | al-subagent dev | jq -r .callId)
REVIEW_ID=$(echo "Review PR #17" | al-subagent reviewer | jq -r .callId)

# ... do other work while they run ...

# Collect results
RESULTS=$(al-subagent-wait "$DEV_ID" "$REVIEW_ID" --timeout 600)
echo "$RESULTS" | jq ".\"$DEV_ID\".returnValue"
echo "$RESULTS" | jq ".\"$REVIEW_ID\".returnValue"

​
Complete Example: SKILL.md

Here’s a planner agent that delegates to dev and reviewer: 
# Planner Agent

You orchestrate development workflows. When triggered, you assess the issue,
create an implementation plan, and delegate to other agents.

## Workflow

1. Read the issue from the webhook trigger or search for labeled issues
2. Assess the issue — is it clear enough for development?
3. If not, comment asking for clarification and stop
4. Write an implementation plan as a comment on the issue
5. Call the dev agent:
echo “Implement the plan in comment #N on issue #M in owner/repo” | al-subagent dev 
6. Wait for dev to finish:
RESULT=(al−subagent−wait"(al-subagent-wait "CALL_ID” —timeout 1800) 
7. If dev succeeded, call the reviewer:
echo “Review PR #P on owner/repo” | al-subagent reviewer 
8. Comment on the issue with the final status

​
Rules

  • No self-calls — an agent cannot call itself (the call is rejected)
  • Call depth limit — chains like A → B → C are allowed up to maxCallDepth (default: 3)
  • Queuing — if all runners for the target agent are busy, the call is queued (up to workQueueSize, default: 100)
  • No reruns — called agents do not re-run. They respond to the single call.
  • Gateway required — call commands require the gateway. They return errors if GATEWAY_URL is not set.

​
What the Called Agent Sees

The called agent receives a <skill-subagent> block in its prompt with:
  • The name of the calling agent
  • The context string passed via stdin
The called agent’s SKILL.md should handle this trigger type: 
## Trigger handling

- **Agent call**: The `<skill-subagent>` block contains context from the calling agent.
  Do what was requested and use `al-return` to send back results.

​
Next steps