Sub-agents & Teams
AFK supports parallel and hierarchical agent work. A parent agent can start focused child agents, send follow-up messages, and collect results while the browser keeps the work visible to the team.
Spawning a sub-agent
Use agent_spawn to start a child agent. It returns immediately with an agent_id, so the parent can continue working while the child runs.
agent_spawn({
prompt: "Review the auth module for security issues",
description: "Auth Review",
agent_type: "reviewer",
isolation: "worktree"
})Parameters
| Parameter | Default | Description |
|---|---|---|
prompt | — | The task description for the child agent. |
description | — | Short human-readable label shown in the UI. |
agent_type | — | Optional named agent persona to use. |
tools | All tools | Optional allowlist restricting which tools the child can call. |
isolation | none | none shares the parent's current active workspace, including a worktree entered after session startup; worktree gives the child a distinct isolated git worktree when supported by the session environment. |
Follow-up and completion
Every child agent remains available for follow-up messages after its initial assignment. Ask it to extend or clarify its work with send_message, and stop it explicitly when it is no longer needed.
const { agent_id } = await agent_spawn({
prompt: "Set up a TypeScript linting environment",
description: "Lint Setup"
})
send_message({ to: agent_id, message: "Also add test coverage guidance" })
agent_stop({ agent_id })Messaging between agents
Use send_message to send follow-up work, request status, or hand off context to another running session or child agent that belongs to the same account or organisation context.
Child agents must send findings and final reports to their parent with send_message; a reply in the child's own conversation is not a report to the parent. By default, relayed messages expect a response. Set expects_response: false for final reports, acknowledgements, or status updates so informational messages do not create unnecessary reply loops.
send_message({
to: reviewerAgentId,
message: "Review the changes in src/auth and report blockers."
})
send_message({
to: parentAgentId,
message: "Finished analysis; no blockers found.",
expects_response: false
})Team coordination
AFK treats long-running sessions and child agents as visible teammates, not hidden background jobs. The dashboard and session tree show spawned work, status, active tool activity, and ownership context so teams can supervise progress and pick up context later.
- Use child agents for specialists, bounded analysis, test runs, or summaries, then follow up with
send_messageas needed. - Use
expects_response: falsefor status updates and final reports. - In organization contexts, visibility follows the configured org and session ownership rules.
Top-level session spawning
session_spawn creates a completely independent top-level session, not a child agent. It uses the normal spawn flow and shows up as a separate session in the dashboard.
session_spawn({
task: "Migrate the users table to add soft-delete",
project_path: "/home/user/projects/myapp",
mode: "auto",
isolation: "worktree"
})Example: parallel file analysis
// Spawn three focused workers concurrently
agent_spawn({ prompt: "Audit src/ for security issues. Report findings.",
description: "Security Audit" })
agent_spawn({ prompt: "Review src/db/ for likely performance bottlenecks.",
description: "DB Review" })
agent_spawn({ prompt: "Find untested code paths in src/. Report coverage gaps.",
description: "Coverage Review" })