Multi-Agent System

Usejarvis runs a hierarchy of AI agents. The primary agent handles your direct requests and, when a task benefits from specialization or parallelism, delegates work to specialist sub-agents. Sub-agents have their own tool access, context, and iteration limits, and are gated by the same authority engine (governed actions are denied outright for sub-agents rather than escalated).

Architecture

Primary Agent (max 200 tool iterations)
  │
  ├─ delegate_task ──→ one specialist, synchronous
  │                     └─ returns result to the primary
  │
  └─ manage_agents ──→ persistent agents, asynchronous
                        spawn → assign → status/collect → terminate

There is also a conversation-tier orchestrator with a persisted task registry behind the Tasks room, so long-running tasks survive and can be resumed.

Specialists

Twelve roles ship in roles/specialists/ (YAML files, loaded at daemon start):

research-analyst
software-engineer
content-writer
data-analyst
financial-analyst
marketing-strategist
project-coordinator
customer-support
hr-specialist
legal-advisor
system-administrator
workflow-default (used internally by the workflow composer)

Edit or add YAML files there to customize roles; changes take effect on the next daemon restart.

Delegation Tools

`delegate_task`

Delegates a single task to one specialist and waits for the result.

Input:
  specialist: string   (one of the role ids above)
  task: string         (full task description)
  context: string      (background information, required)

Returns: string        (the specialist's completed output)

`manage_agents`

Manages persistent agents over a lifecycle. Actions:

Action	Effect
`spawn`	Create a persistent agent from a specialist role, returns `agent_id`
`assign`	Give an agent an async task, returns `task_id`
`status`	Check a task’s state (`running`, `completed`, `failed`)
`collect`	Retrieve a completed task’s result
`list`	List live agents
`terminate`	Shut an agent down

The primary spawns agents, assigns work, keeps responding to you, and collects results when ready. Nothing auto-aggregates; results are pulled with collect.

Iteration Limits

Primary agent: 200 tool iterations per turn
Sub-agents: 100 iterations, deliberately lower to keep them focused

A sub-agent that hits its limit terminates with reason max_iterations and returns what it has.

Context Isolation

Sub-agents receive a scoped tool registry and their own message history. Tool chatter inside a turn is ephemeral: only your message and the final assistant response are persisted to conversation history, which keeps long sessions lean.

Authority

Sub-agent actions run through the authority engine like everything else. Governed actions (payments, emails, and so on) are denied for sub-agents rather than routed to approval; authority stays with the top-level agent. A parent can pass a temporary grant for a specific category for the duration of a task.