AI Architecture — The Onoots Swarm

Onoots runs an 8-agent AI swarm. Each agent owns a domain, reacts to business events (a published listing, a new lead…), and runs as a durable Temporal workflow. Every outbound action first passes through one hard gate — the Compliance Guardian — which combines the brokerage’s autonomy policy with a live compliance scan before anything reaches the outside world.

The swarm is opt-in. Every agent ships disabled by default — a Broker explicitly enables each one from the swarm panel (kill-switch).

Agent roster

The canonical kinds are defined in lib/swarm/types.ts (AI_AGENT_KINDS):

Agent	Status	What it does
Onoots Marketer	🟢 Live (M1)	Generates listing content and publishes to social media (via Ayrshare).
Onoots Qualifier	🟢 Live (M2)	Buyer concierge in the lead chat — answers inbound messages, scores and routes leads.
Onoots Compliance Guardian	🟢 Live (M0)	The hard gate. Not a worker — it evaluates every action and decides allow / prepare / escalate / block.
Onoots Scheduler	🟢 Live (D1)	Books a showing when a buyer requests one (Guardian-gated by `schedule_showing`).
Onoots Nurture	🟢 Live (Dreams)	Matches each new listing against the global Dreams registry (AI scoring) and emails matching dreamers; drip / re-engagement messaging planned.
Onoots Deal Concierge	🟢 Live (D2)	Reacts to deal stage changes & signed documents — chases pending signatures and records closes as notes in the deal thread.
Onoots Listing Onboarder	🟢 Live (D3)	Agents and owners submit a property draft; the AI writes a fair-housing-safe listing description; a broker approves to publish. (Photos/3D via Media Studio.)
Onoots Orchestrator	🟢 Live (D4)	Per-lead lifecycle supervisor — detects stalled deals/leads (no progress) and nudges, alongside the reactive agents.

The Compliance Guardian — the hard gate

The Guardian (lib/swarm/guardian.ts) is infrastructure, not a worker. Every agent calls it before acting. It fuses two inputs — the resolved autonomy level for the act and a compliance scan (fair-housing / PII flags) — into a single verdict:

Decision	When	Outcome
`block`	A compliance flag with `block` severity (overrides everything)	Action is blocked. Anchored on-chain + audited.
`escalate`	Autonomy level = `human_licensed_only`	A license-verified human must act. AI may draft only.
`prepare`	Level = `ai_prepare_human_approve`, or `full_auto` with a `warning` flag	AI drafts; a human approves before it executes.
`allow`	Level = `full_auto` and no warnings/blocks	Executes. Anchored on-chain + audited.

allow and block — the legally meaningful outcomes — are anchored on-chain (Polygon). prepare and escalate are recorded to the audit log only.

Autonomy levels

Each act resolves to one of three levels (lib/autonomy/types.ts), from least to most restrictive:

Level	Meaning
`full_auto`	The AI performs the act with no human in the loop.
`ai_prepare_human_approve`	The AI prepares the work; a human clicks approve.
`human_licensed_only`	Only a licensed human may perform it; the AI may draft only.

The level is jurisdiction-aware: it resolves through a chain — zone override → brokerage policy → region preset → country preset → global default — so the floor always matches local real-estate law.

Acts catalog

The swarm’s capabilities are modeled as granular acts (AUTONOMY_ACTS), not as one blob per agent. The global default level for each act keeps marketing/intake automatic while anything touching offers, advice, or signatures defers to a licensed human:

Act	Owner	Default level
`post_social`	Marketer	`full_auto`
`reply_lead`	Qualifier	`full_auto`
`score_claim_lead`	Qualifier	`full_auto`
`schedule_showing`	Scheduler	`full_auto`
`nurture_outreach`	Nurture	`full_auto`
`advance_stage`	Deal Concierge	`full_auto`
`chase_signatures`	Deal Concierge	`full_auto`
`send_valuation`	—	`ai_prepare_human_approve`
`draft_offer`	—	`ai_prepare_human_approve`
`record_close`	Deal Concierge	`ai_prepare_human_approve`
`present_offer`	—	`human_licensed_only`
`fiduciary_advice`	—	`human_licensed_only`
`sign_listing`	—	`human_licensed_only`

How an action flows


  business event (listing.published, inbound message…)
        │  written to the swarm_events outbox
        ▼
  Temporal worker picks it up → invokes the agent (Marketer / Qualifier…)
        │
        ▼
  🛡️ Compliance Guardian  →  allow · prepare · escalate · block
        │
        ├─ allow     → execute (e.g. post to social) + anchor on-chain
        ├─ prepare   → draft saved for human approval
        ├─ escalate  → routed to a licensed human
        └─ block     → not executed, anchored + audited
        │
        ▼
  swarm_actions (audit) · credits / billing metered

Stack

Anthropic Claude (claude-sonnet-4-5 / claude-haiku-4-5) — the reasoning behind each agent.
Temporal Cloud — durable workflow execution for the swarm (swarm/ worker + relay).
Supabase (Postgres + RLS) — events outbox, agent registry, audit trail.
Polygon — on-chain anchoring of legally meaningful Guardian verdicts.