AgentFlow Integration

SOMA integrates with AgentFlow as a bidirectional intelligence layer. It consumes execution data from agents, processes it through its worker pipeline, and feeds ratified policies back to agents via the Policy Bridge. This creates a closed-loop feedback system where agent behavior informs organizational policy, which in turn constrains future agent behavior.

What SOMA Consumes

SOMA ingests three event types from AgentFlow, each providing a different level of detail.

ExecutionEvent

Summarized metrics from a single agent run. Lightweight, emitted by every AgentFlow execution.

interface ExecutionEvent {
  type: 'execution';
  agentId: string;
  executionId: string;
  status: 'completed' | 'failed';
  duration: number;           // milliseconds
  toolCalls: number;
  timestamp: string;          // ISO 8601
  metadata?: Record<string, unknown>;
}

The Harvester creates one execution entity in L1 per ExecutionEvent. These form the bulk of raw data in the archive layer.

PatternEvent

Process mining patterns detected by AgentFlow's pattern detector. Higher-level than individual executions.

interface PatternEvent {
  type: 'pattern';
  patternId: string;
  patternType: 'bottleneck' | 'failure_cluster' | 'tool_preference' | 'delegation_chain';
  agentIds: string[];
  confidence: number;
  description: string;
  evidence: string[];         // Execution IDs
  timestamp: string;
}

The Harvester creates insight entities in L1 from pattern events. These become candidates for the Synthesizer's cross-agent analysis.

ExecutionGraph

The richest data structure — a full directed graph of an agent's execution with nodes (steps), edges (transitions), and trace events. This is what enables decision extraction without adapter changes.

interface ExecutionGraph {
  id: string;
  agentId: string;
  nodes: GraphNode[];         // tool, subagent, decision nodes
  edges: GraphEdge[];         // sequential, branched, retried edges
  traceEvents: TraceEvent[];  // timestamped events including optional decision traces
  metadata: {
    startTime: string;
    endTime: string;
    status: 'completed' | 'failed';
  };
}

The Harvester's ingestGraph() method walks the graph structure and infers decisions:

Node/Edge Type	Inferred Decision	Data Extracted
tool node	tool_choice	Tool name, duration, outcome, metadata
branched edge	branch	Selected path, sibling alternatives
retried edge	retry	Retry count, final outcome
subagent node	delegation	Target subagent, parent agent
Failed terminal node	failure	Error message, path from root

Decision IDs are stable (graph_id-node_id), making re-ingestion idempotent. Any framework that produces an ExecutionGraph gets decision extraction automatically — no adapter changes required.

What SOMA Adds

DecisionTraceData Type

For frameworks that want to provide richer decision data than what graph structure inference captures, SOMA defines the DecisionTraceData type in agentflow-core:

interface DecisionTraceData {
  type: 'decision';
  decisionType: 'tool_choice' | 'branch' | 'retry' | 'delegation' | 'failure';
  choice: string;
  alternatives?: string[];
  rationale?: string;         // Optional: why this choice was made
  confidence?: number;
  metadata?: Record<string, unknown>;
}

Agents emit this as a trace event:

agent.trace({
  type: 'decision',
  data: {
    type: 'decision',
    decisionType: 'tool_choice',
    choice: 'fetch-data',
    alternatives: ['cache-lookup', 'direct-query'],
    rationale: 'Cache miss detected, fetching fresh data',
    confidence: 0.9,
  } satisfies DecisionTraceData,
});

This is opt-in. Graph-inferred decisions work without it. DecisionTraceData adds alternatives and rationale fields that cannot be inferred from structure alone.

PolicySource Implementation

The Policy Bridge implements AgentFlow's PolicySource interface, making SOMA a drop-in policy provider:

import { PolicyBridge } from '@soma/policy-bridge';

const bridge = new PolicyBridge(vault);

const agent = new Agent({
  name: 'agent-alpha',
  policySource: bridge,   // SOMA feeds policies to this agent
  guards: [retryGuard, payloadGuard],
});

When agents query for policies:

• L4 canon entries become severity: 'error' policies (block execution)
• L3 emerging entries become severity: 'warning' policies (log but allow)

Dashboard Pages

SOMA adds two pages to the AgentFlow Dashboard:

1. Intelligence Tab — Per-agent view with health card, insights with layer badges, guard policies
2. Governance Page — Global view with layer bar, pending proposals, approve/reject workflow, canon list

See the Dashboard guide for details.

soma-report.json

SOMA generates a soma-report.json file consumed by the dashboard and external tooling:

{
  "generated": "2026-03-21T09:30:00.000Z",
  "layers": {
    "archive": 298,
    "working": 12,
    "emerging": 19,
    "canon": 8
  },
  "agents": [
    {
      "id": "agent-alpha",
      "runs": 42,
      "failures": 2,
      "failureRate": 0.048,
      "status": "healthy",
      "lastSeen": "2026-03-21T09:27:00.000Z"
    }
  ],
  "insights": [
    {
      "id": "retry-heavy-agents",
      "type": "archetype",
      "layer": "emerging",
      "confidence": 0.82,
      "status": "pending",
      "summary": "6 agents exhibit retry counts above threshold"
    }
  ],
  "policies": [
    {
      "id": "canon-max-retry-count",
      "type": "policy",
      "layer": "canon",
      "status": "enforcing",
      "severity": "error"
    }
  ],
  "governance": {
    "pending": 4,
    "promoted": 6,
    "rejected": 2
  }
}

Closed-Loop Feedback

The integration creates a continuous feedback loop between agent execution and organizational governance:

The Loop in Detail

1. Agents execute tasks — AgentFlow runs agents that emit ExecutionEvent, PatternEvent, and ExecutionGraph data.

2. Harvester ingests traces — Raw events and graph-inferred decisions are written to L1 (archive).

3. Synthesizer detects patterns — Cross-agent analysis of L1 data produces L3 proposals with confidence scores and evidence chains.

4. Human reviews proposals — Via the CLI (soma governance promote/reject) or Dashboard. This is the critical gate — no auto-promotion.

5. Ratified policies enter canon — Promoted proposals become L4 entries with mandatory semantic weight.

6. Policy Bridge serves agents — Agents query with enforce intent and receive L4 policies. The PolicySource interface integrates directly with AgentFlow's guard system.

7. Guards constrain behavior — L4 policies become guards that block (error) or warn (warning) on policy violations.

8. Constrained agents execute — Agents run with the new constraints, producing new traces, and the loop repeats.

What This Achieves

• Organizational learning — The system learns from agent behavior at scale, not just individual agent tuning
• Human oversight — Machine-detected patterns require human judgment before becoming constraints
• Evidence-based governance — Every L4 policy traces back to specific L1 traces through the evidence chain
• Progressive constraint — New constraints emerge from observed patterns rather than being predefined
• Feedback isolation — Workers have guards preventing self-processing (Synthesizer excludes synthesized tags, Cartographer blocks self-references, Reconciler checks for existing merges)