Spec — Cambium Agent Model

Document Status

Draft V1

Purpose

This spec defines what an agent IS in Cambium, how agents are created, how they live, how they die, and how their remains nourish the system.

The PRDs define workflows, tasks, and runs. This spec defines the living units that do the work.

Core Concept: Agents as Cells

In Cambium, an agent is the fundamental unit of work execution — the cell of the organism.

An agent is NOT: - just a prompt wrapper - just an API endpoint - just a function

An agent IS: - an entity with identity, capabilities, state, and lifecycle - capable of receiving work, producing output, and signaling its condition - subject to the same governance, health, and immune systems as the rest of the platform - mortal — it can be created, can hibernate, can be decommissioned, and can be composted

Agent Types

1. Internal Executors (default)

Agents that Cambium spawns, manages, and orchestrates directly.

These are the primary agent type. The system creates them, assigns them work, monitors their health, and decommissions them when done.

Examples: - LLM-powered reasoning agents - Script runners (deterministic task execution) - API callers (integration agents) - Data pipeline agents (ETL, transformation) - RAG agents (retrieval-augmented generation) - Graph query agents (Neo4j, knowledge graph traversal) - Loop/polling agents (continuous monitoring)

2. External Agents

Agents that exist outside Cambium but connect to participate in workflows.

These register with Cambium, declare capabilities, and receive work through a defined protocol. Cambium monitors their liveness but does not control their internals.

Examples: - Existing microservices wrapped with Cambium adapter - Third-party AI services - Human-in-the-loop agents (operator as agent) - External tool providers - Other Cambium instances (federation)

Agent Anatomy

Every agent has these components:

interface Agent {
  // Identity
  id: string;                      // unique agent ID
  template_id: string;             // genome — the template this agent was instantiated from
  workspace_id: string;
  name: string;
  kind: "internal" | "external";

  // Capabilities
  capabilities: Capability[];      // what this agent can do
  tools: ToolBinding[];            // what tools this agent has access to
  input_types: string[];           // what input formats it accepts
  output_types: string[];          // what output formats it produces

  // State
  status: AgentStatus;
  health: AgentHealth;
  current_task_id?: string;
  memory_ref?: string;             // reference to agent memory/context store

  // Lifecycle
  genesis_at: string;              // when instantiated
  activated_at?: string;           // when brought online
  last_heartbeat_at?: string;
  decommissioned_at?: string;
  composted_at?: string;

  // Lineage
  parent_template_id?: string;     // if differentiated from another template
  generation: number;              // how many iterations from original template

  // Configuration
  config: AgentConfig;
  resource_budget?: ResourceBudget;
  policies: string[];              // policy IDs bound to this agent

  // Metrics
  tasks_completed: number;
  tasks_failed: number;
  avg_latency_ms: number;
  total_token_burn: number;
  trust_score: number;             // 0.0 - 1.0, influenced by immune layer
}

Agent Status

genesis → activating → active → busy → idle → hibernating → decommissioned → composted

• genesis: template instantiated, not yet configured
• activating: initializing, loading tools, establishing connections
• active: online, ready for work (idle or busy)
• busy: currently executing a task
• idle: active but not currently assigned
• hibernating: dormant, state preserved, not consuming resources
• decommissioned: removed from active pool, awaiting composting
• composted: learnings extracted, agent record archived

Agent Health

healthy → degraded → stressed → critical → unresponsive

Health is determined by: - heartbeat regularity - task success rate - latency trends - error frequency - resource consumption

Capabilities

Agents declare what they can do. Hypha uses capabilities for task routing.

interface Capability {
  id: string;
  name: string;                    // e.g., "text_analysis", "code_generation", "api_call"
  category: string;                // e.g., "reasoning", "execution", "integration", "monitoring"
  confidence: number;              // 0.0 - 1.0, self-assessed or system-assessed
  constraints?: {
    max_input_tokens?: number;
    max_execution_time_ms?: number;
    requires_tools?: string[];
    cost_per_invocation?: number;
  };
}

Capability Matching

When Hypha needs to assign a task node to an agent: 1. Task node declares required capabilities 2. Hypha queries available agents matching those capabilities 3. Selection considers: capability confidence, current health, trust score, load, stigmergic markers 4. If no agent matches, Hypha can request Genesis to instantiate one from a matching template

Genesis: Agent Creation

Genesis is the process of bringing new agents into existence.

Templates (Genomes)

Every agent is instantiated from a template. Templates are the DNA of the system.

interface AgentTemplate {
  id: string;
  name: string;
  description: string;
  version: number;

  // Blueprint
  kind: "internal" | "external";
  agent_type: string;              // e.g., "llm_reasoner", "script_runner", "api_caller", "rag_agent"
  capabilities: Capability[];
  tools: ToolBinding[];
  default_config: AgentConfig;
  resource_budget: ResourceBudget;

  // Lifecycle policies
  auto_hibernate_after_idle_ms?: number;
  max_lifetime_ms?: number;
  auto_decomission_on_failure_count?: number;

  // Lineage
  parent_template_id?: string;
  generation: number;
  mutation_log?: string[];         // what changed from parent template

  // Metadata
  created_at: string;
  created_by: string;
  status: "active" | "deprecated" | "experimental";
}

Genesis Process

1. TEMPLATE SELECTION
   ↓  Hypha or operator selects a template
2. INSTANTIATION
   ↓  New agent record created from template
   ↓  Unique ID assigned
   ↓  Status: genesis
3. CONFIGURATION
   ↓  Environment-specific config applied
   ↓  Tools bound
   ↓  Policies attached
4. DIFFERENTIATION
   ↓  If needed: specialize capabilities for specific role
   ↓  Apply context from current workflow/environment
5. ACTIVATION
   ↓  Agent brought online
   ↓  Heartbeat registration with Pulse Monitor
   ↓  Status: active
   ↓  Lifecycle signal emitted: lifecycle.agent_genesis
6. MONITORING
   ↓  Continuous heartbeat
   ↓  Health tracking
   ↓  Trust scoring by Immune layer

Adaptive Genesis

The system can learn which templates produce effective agents for which task types. Over time: - Templates that produce high-performing agents get higher routing priority - Templates that consistently fail get flagged for review or deprecation - New template variants can be created by mutating successful templates (generation + 1)

This is evolution at the template level, not the agent level.

Composting: Agent Death and Nutrient Extraction

When an agent is decommissioned, its learnings feed back into the system.

Composting Process

1. DECOMMISSION
   ↓  Agent removed from active pool
   ↓  Current tasks reassigned or failed gracefully
   ↓  Status: decommissioned
2. HARVEST
   ↓  Extract performance metrics
   ↓  Extract failure patterns
   ↓  Extract successful strategies
   ↓  Extract tool usage patterns
3. NUTRIENT CREATION
   ↓  Generate compost record:
   ↓    - what worked
   ↓    - what failed
   ↓    - recommendations for template improvement
   ↓    - routing heuristics learned
4. FEEDING
   ↓  Feed nutrients into:
   ↓    - template evolution (improve future agents)
   ↓    - routing heuristics (improve task assignment)
   ↓    - immune patterns (improve anomaly detection)
   ↓    - health baselines (improve threshold calibration)
5. ARCHIVE
   ↓  Agent record archived
   ↓  Status: composted
   ↓  Lifecycle signal: lifecycle.agent_composted

Compost Record

interface CompostRecord {
  id: string;
  agent_id: string;
  template_id: string;

  // Performance summary
  total_tasks: number;
  success_rate: number;
  avg_latency_ms: number;
  total_token_burn: number;
  lifetime_ms: number;

  // Learnings
  failure_patterns: FailurePattern[];
  successful_strategies: string[];
  tool_effectiveness: Record<string, number>;  // tool_id → success rate
  capability_accuracy: Record<string, number>; // capability → actual vs declared confidence

  // Recommendations
  template_improvements: string[];
  routing_hints: RoutingHint[];

  // Metadata
  composted_at: string;
  composted_by: string;  // system or operator
  reason: string;        // why decommissioned
}

Agent Signaling

Through the Stigmergic Environment (primary)

Agents communicate by placing markers in the shared environment. Other agents with receptors for those marker types pick them up.

This is paracrine signaling — local, environment-mediated, not point-to-point.

What agents can signal: - coord.agent_ready — available for work - coord.agent_busy — at capacity - coord.resource_depleted — cannot continue current approach - coord.resource_abundant — has surplus capacity or information - coord.marker_placed — general stigmergic marker (e.g., “this data source is stale”, “this API is slow today”)

Through Hypha (structured)

For formal task-related communication, agents signal through Hypha: - task completion with output - task failure with error - request for additional input - request for tool access - distress signal (cannot complete, need help)

What Agents Cannot Do

• Agents cannot directly invoke other agents (no point-to-point calls)
• Agents cannot modify other agents’ state
• Agents cannot bypass Quorum governance
• Agents cannot suppress their own heartbeat

These constraints maintain the organism’s coherence. An agent that could bypass governance or hide its liveness would be a cancer.

Agent Registration Protocol

Internal Agents

1. Genesis creates agent from template
2. Agent auto-registers with Pulse Monitor
3. Agent capabilities published to Hypha’s routing table
4. Agent begins heartbeat cycle
5. Agent available for task dispatch

External Agents

1. External process calls Cambium registration API
2. Provides: identity proof, capability declaration, heartbeat endpoint
3. Cambium verifies identity (Immune layer performs initial trust assessment)
4. Agent registered with probationary trust score
5. Agent begins heartbeat cycle (Cambium polls external heartbeat endpoint)
6. Trust score adjusts based on behavior over time

Resource Budget

Every agent has a resource budget — the metabolic constraint.

interface ResourceBudget {
  max_tokens_per_task?: number;
  max_tokens_per_hour?: number;
  max_execution_time_ms?: number;
  max_concurrent_tasks?: number;
  max_tool_calls_per_task?: number;
  max_retries?: number;
  cost_ceiling_per_hour?: number;
}

When an agent approaches its budget limits, it emits stress signals. When it exceeds them, Health layer intervenes.

Trust Score

The Immune layer maintains a trust score for every agent.

• Starts at 0.5 for new internal agents (known template)
• Starts at 0.3 for new external agents (unknown quantity)
• Increases with successful task completion, reliable heartbeat, clean behavior
• Decreases with failures, anomalies, policy violations, irregular heartbeat
• Below 0.2: agent quarantined pending review
• At 0.0: agent decommissioned

Trust score influences: - Task routing priority (Hypha prefers higher-trust agents) - Governance requirements (low-trust agents may require approval for actions that high-trust agents can do autonomously) - Resource budget allocation

Open Questions

1. Should templates be immutable (new version = new template) or mutable with version history?
2. What is the maximum number of concurrent agents before the system itself becomes stressed?
3. How should agent memory/context be managed across hibernation cycles?
4. Should there be “stem cell” agents — generic agents that differentiate on demand?
5. How does agent federation work across multiple Cambium instances?