Multi-Agent Orchestration

Build teams of specialized AI agents that collaborate through shared workspace, sessions, and cron-driven heartbeats.

Core Architecture

InvestSarva sessions = independent agents. Each session has its own history, context, and identity.

sessions_spawn  → Create isolated sub-agent sessions
sessions_send   → Send messages between agents  
sessions_list   → Monitor active agents
cron            → Schedule heartbeats and recurring tasks

Creating an Agent

1. •Define identity — Write a SOUL-style task prompt with role, personality, and responsibilities
2. •Spawn session — Use sessions_spawn with the task description
3. •Set heartbeat — Use cron for periodic wake-ups (stagger by 2-5 min to avoid collisions)

Agent Design Pattern

Task prompt should include:
- WHO: Name, role, personality traits
- WHAT: Specific responsibilities and domain
- HOW: Tools to use, files to read/write, output format
- MEMORY: Which files to check on wake (memory/WORKING.md, daily notes)
- COMMS: How to report back (sessions_send, file updates, channel messages)

Coordination Patterns

Pattern 1: Hub-and-Spoke (Recommended Start)

Main agent (you) delegates to specialists, collects results.

• •Spawn sub-agents for specific tasks
• •They write results to files or send back via session
• •Main agent synthesizes

Pattern 2: Shared Workspace

All agents read/write to common files:

• •memory/WORKING.md — Current task state per agent
• •memory/mission-control.json — Task board (inbox/assigned/in_progress/review/done)
• •Daily notes for activity logging

Pattern 3: Cron-Driven Heartbeats

Each agent wakes on schedule, checks for work, acts or sleeps:

Agent A: */15 offset :00  — Check tasks, do work
Agent B: */15 offset :02  — Check tasks, do work  
Agent C: */15 offset :04  — Check tasks, do work

Task Flow

Inbox → Assigned → In Progress → Review → Done

Track in memory/mission-control.json:

{
  "tasks": [
    {"id": 1, "title": "...", "status": "in_progress", "assignee": "agent-label", "created": "ISO", "comments": []}
  ]
}

Best Practices

1. •Start small — 2-3 agents max, add more only when needed
2. •Stagger heartbeats — 2-5 min apart to avoid API spikes
3. •Use cheaper models for routine heartbeats (model param in cron/spawn)
4. •File > memory — Agents forget between sessions; always write state to files
5. •Isolated sessions for cron — One-shot, do work, terminate. Keeps costs down.
6. •Daily standup — Schedule a cron to compile agent activity summaries

Quick Reference

Scaling Checklist

• • Each agent has distinct SOUL (role + personality)
• • Heartbeats staggered (not all at :00)
• • Shared task tracking file exists
• • Daily standup cron configured
• • Memory files documented (which agent writes where)
• • Cost monitoring in place (session_status)

See references/mission-control-guide.md for the full case study on 10-agent orchestration.