← Back to WorkSphere

Superagent Architecture

> One Intelligent Agent. Many Skills. Orchestrated for Real Work.

Integration Boundary
Protocol · Session · UI
Protocol Adapter
Normalizes HTTP, WebSocket, CLI, and chat channels into a unified internal format. Exposes /chat (plain string) and /intent (structured: plan + per-domain results + synthesis).
Session Lifecycle
Creates, maintains, and cleanly closes sessions per user. Session turns capped at 50 and persisted via the Memory subsystem. User identity threads through all downstream subsystems.
sessions/{uid}.json
max_turns: 50
Mission Control UI
Intent-first workspace — not a chatbot. Autonomy dial (Guided / Supervised / Auto), live execution grid, domain result cards, and run log.
localhost:8000
/observatory
Resolved session payload
Core Runtime Engine
All LLM calls routed through Reasoning Router
Context Manager
Always-on enrichment: loads user profile, role, permissions, and cost centre before any LLM call fires. Owns system-wide guardrail enforcement. Background refresh loop.
context/{uid}.json
permissions
guardrails[]
Intent Engine
LLM-powered NLU. Reads enriched context before interpreting. Resolves composite utterances into a structured ResolvedIntent: action, target domains, extracted params. Hard error boundary — ambiguity never passes downstream.
resolved guardrail_block out_of_scope clarification
Skill Planner
Queries the Registry for available skills, then uses LLM to build an ExecutionPlan — an ordered dependency graph where each step declares depends_on[] for correct sequencing and parallelisation.
Returns ExecutionPlan
Dispatcher
Walks ExecutionPlan in depends_on order → dispatches each step to its domain orchestrator → tracks state in completed{} → retries with configurable backoff → synthesises a unified response via LLM.
Dispatch
Routes each plan step to its registered domain orchestrator by domain key
State Track
Maintains completed{} map; resolves depends_on ordering
Retry / Backoff
Per-step retry up to max_retries with linear backoff. No replanning.
Synthesize
LLM call assembles all domain outputs into one coherent response
Infrastructure Services
Registry
YAML-persisted catalog of domain orchestrators: skills (T/A), tool declarations, guardrails. Source of truth for Planner and Observatory.
registry/skills.yaml
Reasoning Router
Every LLM call in the system — from intent understanding through plan generation to final synthesis — is scored for complexity and routed to the appropriate model tier. Subsystem hints override auto-scoring for known call types.
SIMPLE MEDIUM COMPLEX REASONING
Memory
Filesystem-backed JSON. Three stores: session turns (capped at 50), episodic user context, in-flight work state. No external database.
sessions/
context/
work/
Observatory
Per-trace audit log. Captures every subsystem decision — intent resolved, guardrail blocked, step failed — with timestamps and detail. Powers the admin UI at /observatory.
traces/{id}.json
ExecutionPlan steps + prior_results
Domain Orchestrators & Skills
T = Tasker (singular, structured, repeatable goal)  /  A = Automator (initiates cross-system or multi-step workflow)  /  COL = Collaborator (human-paired, learns and refines)
Human Resources
TGet PTO Balance
TGet Payslip Summary
ASubmit Leave Request
TGet Benefits Summary
Workday · Payroll API · Benefits API
IT Help
ARaise IT Ticket
TCheck Ticket Status
ARequest Password Reset
TLookup Asset
ServiceNow · LDAP · CMDB
Facilities
ABook Meeting Room
TCheck Room Availability
ARequest Visitor Pass
TFind Hot Desk
EMS API · Desk Booking · Building Mgmt
Catering
AOrder Event Catering
AOrder Team Lunch
TCheck Menu / Availability
Min. 48h notice for >10 pax
Catering API · Vendor API
Finance
ARaise Purchase Order
TCheck Cost Centre Budget
ASubmit Expense Report
TGet Spend Summary
SAP · Coupa · Concur
via MCP / A2A / REST
Systems of Record & Vendors
Each domain orchestrator owns its connector — no shared API client
Domain orchestrators reach systems of record via MCP tool calls, A2A agent handoffs, or direct REST — depending on what the target system exposes. Tasker skills execute singular, repeatable actions against a single system. Automator skills initiate workflows that may span approvals, state changes, or downstream processes across multiple systems.
WorkdayHR · Payroll · Benefits
ServiceNowIT Tickets · Asset CMDB
SAP / CoupaFinance · PO · Spend
ConcurExpense Reports
LDAP / ADIdentity · Auth · Password
EMS / OutlookRoom Booking · Calendar
Compass GroupCatering · Vendor
Building MgmtDesk · Visitor · Facilities
Local Knowledgeknowledge.yaml · FAQ
+ Extendyour_api_here