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",
  lifecycle: "ephemeral"
})

Parameters

Agent lifecycles

Persistent agents

Persistent child agents are useful for specialists that should stay available for follow-up questions. Stop them explicitly when done.

const { agent_id } = await agent_spawn({
  prompt: "Set up a TypeScript linting environment",
  description: "Lint Setup",
  lifecycle: "persistent"
})

send_message({ to: agent_id, message: "Also add test coverage guidance" })

agent_stop({ agent_id })

Ephemeral agents

Ephemeral child agents are one-shot workers. Use them for focused checks, parallel investigation, or independent summaries where you only need the final report.

agent_spawn({
  prompt: "Run the test suite and report failures",
  description: "Test Runner",
  lifecycle: "ephemeral",
  tools: ["bash", "read_file", "glob"]
})

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.

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 persistent child agents for specialists that should stay available for follow-up questions.
• Use ephemeral child agents for bounded analysis, test runs, or summaries.
• Use expects_response: false for 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", lifecycle: "ephemeral" })
agent_spawn({ prompt: "Review src/db/ for likely performance bottlenecks.",
              description: "DB Review", lifecycle: "ephemeral" })
agent_spawn({ prompt: "Find untested code paths in src/. Report coverage gaps.",
              description: "Coverage Review", lifecycle: "ephemeral" })