Skip to main content

AgentFlow Integration

Integrate SOMA with AgentFlow to provide comprehensive execution visibility and operational control across your agent infrastructure.

Overview​

AgentFlow is an execution observability framework that can monitor and control SOMA workers alongside other agent systems. This integration provides:

  • Unified monitoring: See SOMA worker executions alongside other agent traces
  • Manual triggers: Start SOMA workers directly from the AgentFlow dashboard
  • Enhanced visibility: Detailed execution traces with operational context
  • Operational intelligence: Multi-layer dashboard combining execution and organizational data

Architecture Integration​

Prerequisites​

  • SOMA: Installed and configured with trace output enabled
  • AgentFlow: Installed with external features support
  • File access: AgentFlow must be able to read SOMA trace directory (~/.soma/traces)

Configuration Steps​

1. Enable SOMA Trace Output​

Ensure SOMA workers are configured to output execution traces:

# Check if trace directory exists
ls -la ~/.soma/traces/

# If not, create it
mkdir -p ~/.soma/traces/

# Test trace output
soma harvest --dry-run --trace

2. Configure AgentFlow​

Create or update your AgentFlow configuration (agentflow.config.json):

{
  "// SOMA Integration": "Complete visibility and control setup",

  "discoveryPaths": [
    "~/.soma/traces"
  ],

  "aliases": {
    "soma-harvester": "SOMA Harvester",
    "soma-synthesizer": "SOMA Synthesizer",
    "soma-reconciler": "SOMA Reconciler",
    "soma-cartographer": "SOMA Cartographer"
  },

  "agentDetection": {
    "pathPatterns": {
      ".soma/": "soma-worker"
    },
    "filePatterns": {
      "soma-(.+)\\.json$": "soma-${match}",
      "harvester-(.+)\\.json$": "soma-harvester",
      "synthesizer-(.+)\\.json$": "soma-synthesizer"
    }
  },

  "externalCommands": {
    "globalTimeout": 600000,
    "globalCwd": "~/soma",
    "maxConcurrentExecutions": 2,

    "commands": {
      "soma-harvest": {
        "name": "SOMA Harvester",
        "command": "soma",
        "args": ["harvest"],
        "description": "Scan inbox and ingest new documents",
        "category": "SOMA Workers",
        "timeout": 120000,
        "allowConcurrent": false
      },

      "soma-synthesize": {
        "name": "SOMA Synthesizer",
        "command": "soma",
        "args": ["synthesize"],
        "description": "Generate insights through LLM analysis",
        "category": "SOMA Workers",
        "timeout": 180000,
        "allowConcurrent": false
      },

      "soma-reconcile": {
        "name": "SOMA Reconciler",
        "command": "soma",
        "args": ["reconcile"],
        "description": "Merge duplicates and resolve conflicts",
        "category": "SOMA Workers",
        "timeout": 240000,
        "allowConcurrent": false
      },

      "soma-cartograph": {
        "name": "SOMA Cartographer",
        "command": "soma",
        "args": ["cartograph"],
        "description": "Generate embeddings and discover patterns",
        "category": "SOMA Workers",
        "timeout": 300000,
        "allowConcurrent": false
      },

      "soma-status": {
        "name": "SOMA Health Check",
        "command": "soma",
        "args": ["status", "--detailed"],
        "description": "Check vault and worker operational status",
        "category": "SOMA Diagnostics",
        "timeout": 30000,
        "allowConcurrent": true
      }
    }
  }
}

Usage​

1. Start AgentFlow​

# Start with SOMA integration
agentflow start --data-dir ~/.soma/traces

# Or using config file
agentflow start

2. Access SOMA Views​

Navigate to the AgentFlow dashboard at http://localhost:3000 and explore:

  • SOMA Intelligence: Enhanced trace details with vault context
  • SOMA Governance: Agentic governance controls and meta-learning
  • SOMA Activity: Real-time operational intelligence dashboard
  • External Commands: Manual SOMA worker triggers

3. Monitor Executions​

All SOMA worker executions will appear in:

  • Traces page: Alongside other agent executions
  • Analytics: Performance metrics and success rates
  • Real-time feed: Live execution updates

4. Manual Operations​

Use the External Commands interface to manually trigger:

  • Individual SOMA workers (harvest, synthesize, reconcile, cartograph)
  • Health checks and diagnostics
  • Custom operational workflows

Operational Workflows​

Daily Operations​

  1. Morning Health Check:

    • Dashboard → External Commands → SOMA Health Check
    • Review overnight execution traces
    • Check vault status and metrics

  2. On-Demand Processing:

    • Dashboard → External Commands → SOMA Harvester (when new content arrives)
    • Monitor execution progress in real-time
    • Review trace details for optimization

  3. Scheduled Processing:

    • Use AgentFlow's scheduling features to automate SOMA workflows
    • Set up alerts for failed executions
    • Generate operational reports

Monitoring Workflow​

  1. Performance Tracking:

    Dashboard → Analytics → Agent Performance → Filter: soma-*

  2. Execution History:

    Dashboard → Traces → Filter: soma → Sort by time

  3. Error Analysis:

    Dashboard → Traces → Status: failed → Agent: soma-*

Troubleshooting​

SOMA Traces Not Appearing​

Check trace output:

# Verify SOMA is generating traces
ls -la ~/.soma/traces/
soma harvest --dry-run --verbose

Verify AgentFlow discovery:

# Test discovery manually
agentflow scan --data-dir ~/.soma/traces

External Commands Failing​

Test SOMA CLI directly:

# Test commands AgentFlow will use
soma status
soma harvest --help

Check permissions:

# Ensure AgentFlow can access SOMA
chmod 755 ~/.soma/traces/
ls -la $(which soma)

Integration Issues​

Verify compatibility:

# Check versions
soma --version
agentflow --version

# Test configuration
agentflow config validate

Advanced Features​

Custom Enhancement​

AgentFlow can enhance SOMA traces with additional operational context:

{
  "traceEnhancement": {
    "soma-workers": {
      "enabled": true,
      "includeVaultMetrics": true,
      "includeOperationalContext": true
    }
  }
}

Multi-Environment Setup​

Different configurations for development/production:

{
  "development": {
    "discoveryPaths": ["./dev-soma/traces"],
    "externalCommands": {
      "globalCwd": "./dev-soma"
    }
  },

  "production": {
    "discoveryPaths": ["~/.soma/traces"],
    "externalCommands": {
      "globalCwd": "~/soma-prod"
    }
  }
}

Performance Optimization​

For high-volume environments:

{
  "externalCommands": {
    "maxConcurrentExecutions": 4,
    "commands": {
      "soma-parallel-harvest": {
        "command": "soma",
        "args": ["harvest", "--parallel", "4"],
        "allowConcurrent": true
      }
    }
  }
}

Security Considerations​

  • Command allowlist: Only pre-configured SOMA commands can be executed
  • Sandboxed execution: Commands run with limited privileges
  • Audit logging: All command executions are logged
  • Access control: Configure AgentFlow authentication as needed

Next Steps​

The AgentFlow integration transforms SOMA from a standalone tool into a fully observable component of your agent infrastructure.