Sub-agents

Start from a fresh project

This guide is self-contained. Create an empty Ayjnt project, then replace the starter agent with the files shown below. Run commands from the new project directory unless a step says otherwise.

bunx ayjnt new try-sub-agents --empty
cd try-sub-agents
bun install

# remove agents/alive once you are ready to add the guide's files

Delegate durable responsibilities

Use native this.subAgent(ChildClass, name) when one root entity owns an open-ended set of children such as chats, documents, sessions, projects, or orchestration workers.

export class Orchestrator extends Agent {
  async research(topics: string[]) {
    return Promise.all(topics.map(async (topic, index) => {
      const child = await this.subAgent(Researcher, `research-${index}`);
      return child.search(topic);
    }));
  }
}

export class Researcher extends Agent {
  async search(topic: string) {
    return { topic, findings: [] };
  }
}

Lifecycle and access

• Export child classes from the worker entry so the runtime can discover them.
• Children have isolated SQLite but run as facets co-located with the parent.
• Use parentAgent() for child-to-parent RPC.
• Use hasSubAgent() and listSubAgents() for registry-backed access control.
• abortSubAgent() stops execution but preserves storage; deleteSubAgent() permanently removes it.

Run it and verify the result

Create two child names and list them from the parent. Each child should return its own isolated state.

bun run build
bun run dev

# the local app is now available at http://localhost:8787