Agent System

The Agent System

Here is the thing about autonomous agents that the industry gets catastrophically wrong: they treat autonomy as a feature to be added. A checkbox on a product page. Obsidian treats autonomy as a structural property — something that emerges from the intersection of capability, constraint, and purpose.

An Agent in Obsidian is not a chatbot with a to-do list. It is a stateful, sovereign worker that discovers work, claims it, executes it, and reports results — all within the boundaries established by the Constitution .

System Architecture

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   WARDEN     │   │  INQUISITOR  │   │   COURIER    │
│  (Watchdog)  │   │  (Auditor)   │   │ (Messenger)  │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       ▼                  ▼                  ▼
┌────────────────────────────────────────────────────┐
│                  AGENT REGISTRY                     │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
│  │Worker A│ │Worker B│ │ DevOps │ │  SRE   │ ...  │
│  └────────┘ └────────┘ └────────┘ └────────┘      │
└────────────────────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────┐
│                    THE VAULT                        │
│  Sessions │ Memory │ Tasks │ Contacts (Graph)      │
└────────────────────────────────────────────────────┘

What Makes an Agent

An agent is a stateful, autonomous worker with five essential properties:

1. Identity — a unique configuration that defines who this agent is
2. Skills — specific capabilities and domain expertise
3. Discovery — the ability to find and claim work without being told
4. Memory — persistent context across tasks and sessions
5. Communication — connections to other agents via the mail system

This is not a microservice with opinions. This is a genuine autonomous executor. The distinction matters because it determines everything about how the system scales, fails, and recovers.

Agent Lifecycle

┌────────┐     ┌────────┐     ┌────────┐     ┌────────┐
│ SPAWN  │────▶│ READY  │────▶│ ACTIVE │────▶│  IDLE  │
└────────┘     └────────┘     └────────┘     └────────┘
                    │              │              │
                    ▼              ▼              ▼
               ┌────────┐    ┌────────┐    ┌──────────┐
               │ ERROR  │    │ STUCK  │    │ SHUTDOWN │
               └────────┘    └────────┘    └──────────┘

Every agent moves through these states with the inevitability of a state machine, because that is exactly what it is. SPAWN initializes configuration. READY means the agent is armed and watching. ACTIVE means it is executing. IDLE means it has finished and is hunting for more work.

The failure states are where the design philosophy gets interesting. ERROR is recoverable — the agent knows what went wrong and can try again. STUCK is detected by the Warden when an agent stops responding, because agents do not self-diagnose death. SHUTDOWN is graceful termination — the agent wraps up, persists state, and exits cleanly.

Standard Workers

Standard agents are the workhorses. They perform domain-specific tasks based on their specialization: frontend development, backend services, infrastructure management, data engineering, security auditing, documentation, testing, or general-purpose work.

Each worker declares its domain, skills, and the file patterns it prefers to work on. A frontend specialist claims *.tsx and *.css files. A DevOps specialist claims Dockerfile and terraform/**. The system matches work to workers based on these declarations — not through a central scheduler, but through constitutional consensus about who is best equipped for the task.

Worker configuration is declarative. Skills, capabilities, resource limits, and behavior preferences are defined in YAML. The agent reads its own configuration and operates within those bounds:

agent:
  id: "worker-alpha"
  type: "worker"
  domain: "frontend"
  skills: ["typescript", "react", "css", "accessibility"]
  capabilities:
    can_read_files: true
    can_write_files: true
    can_execute_commands: true
    can_spawn_agents: false
  limits:
    max_concurrent_tasks: 3
    max_memory_mb: 512
    max_execution_time_minutes: 30
  behavior:
    work_discovery: "pull"
    heartbeat_interval_seconds: 30

Special Agent Roles

Not all agents are equal, but every agent is sovereign. The special roles — the Warden , the Inquisitor, the Courier — have elevated responsibilities, not elevated authority. They serve the system, not the other way around.

The Inquisitor

The compliance and quality watchdog. It audits agent behavior on a schedule: code quality every four hours, security scans daily at midnight, Constitutional Compliance checks every thirty minutes. It maintains quality thresholds — minimum 80% test coverage, maximum cyclomatic complexity of 10, zero tolerance for hardcoded secrets in source.

The Inquisitor does not write code. It does not deploy. It watches, and when something violates the constitutional standards, it blocks, notifies, or reports. This is Safety Through Boundaries made operational.

The Courier

The knowledge distributor. While other agents execute tasks, the Courier ensures that everyone knows what everyone else is doing. It generates session summaries, detects patterns across work streams, cross-references related information, and pushes relevant context to agents who need it.

The Courier is the system’s storyteller — it synthesizes raw activity into narrative context that makes the next decision better than the last. This is not optional. A system without knowledge distribution is a system where every agent is perpetually reinventing context from scratch.

The Warden Chain

The Warden watches all agents. But who watches the Warden?

┌──────────────┐
│   SENTINEL   │  ← Watches everything, including Warden
│   (Level 3)  │    External process, minimal footprint
└──────┬───────┘
       │ monitors
       ▼
┌──────────────┐
│    SCOUT     │  ← Watches Warden, lightweight
│   (Level 2)  │    Can revive Warden if stuck
└──────┬───────┘
       │ monitors
       ▼
┌──────────────┐
│    WARDEN    │  ← Watches all agents
│   (Level 1)  │    Primary health monitor
└──────┬───────┘
       │ monitors
       ▼
┌──────────────────────────────────────────┐
│            ALL OTHER AGENTS              │
│  Workers, Inquisitor, Courier, etc.      │
└──────────────────────────────────────────┘

The Warden Chain is defense in depth applied to monitoring itself. The Sentinel — an external process with minimal footprint — watches even the Warden. This is not paranoia. This is what Constitution Principle 1 means in practice: failures are inevitable, design for survival.

DevOps and SRE Agents

The DevOps Agent handles deployment across environments — auto-deploying to development and staging, requiring human approval for production. It supports rolling, blue-green, and canary deployment strategies. The SRE Agent monitors SLOs, detects incidents automatically, and executes runbook playbooks when things go wrong.

Both agents demonstrate a critical Obsidian pattern: automated execution with human gates. Development deploys are boring. Production deploys require approval from the Release Agent and the SRE Agent. Automation handles the 99% case. Humans handle the decisions that should never be automated.

Capability Matrix

Not every agent can do everything. Capabilities are declared, not assumed — this is Constraint Inheritance in action:

The Inquisitor cannot write files. The Courier cannot execute commands. The Warden cannot be spawned by other agents. Every restriction is intentional. Every permission is earned through the agent’s constitutional role. This matrix is not a limitation — it is the architecture’s immune system.