Agent Orchestration

Agent Orchestration

Decision

The first expansion stage remains a local, deterministic job pipeline. The existing SQLite database, config/module_registry.json, config/agent_registry.json, and JSONL logs are the correct core. An LLM does not decide which job receives write access.

LangGraph is a later optional adapter layer if multiple specialized models genuinely require saved state, dynamic routing, or parallel steps. Fixed workflows and dynamic agents are different tools; routers, subagents, and skills should be introduced only where their additional complexity is measurable.

Local Funnel

input import
  -> evidence fingerprint
  -> deterministic extraction
  -> optional analysis jobs
  -> evidence-bound relationship candidates
  -> human review gate
  -> report/export

Every arrow is a persistent event with case ID, input hash, and producer. Agents never mutate the case database directly on behalf of one another.

Roles

• VektorZero validates and normalizes local input.
• SignalForge produces outlier candidates from transparent comment features.
• GlyphWatch processes only explicitly selected local image evidence after model confirmation.
• SpectreNet produces evidence-bound relationship candidates.
• CaseForge creates review work; subsequent decisions follow configurable human gates.
• BlackArchive renders approved local exports.

The machine-readable source of truth is config/agent_registry.json, exposed locally at GET /api/agents.

Integration Stages

Stage A: No Agent Framework

• agent_jobs, agent_job_events, and the operator-initiated job_worker form the local job ledger. The older processing_jobs table remains the human-readable processing timeline.
• A local worker accepts only approved topics from the registry.
• A job can be queued, running, completed, failed, cancelled, or needs_review.
• Idempotency key: case_id + topic + input_hash + configuration_version.

This stage is implemented and covers most deterministic module chains.

Stage B: Local Model Services

• Serve models behind explicitly versioned local HTTP or process adapters.
• Give every adapter narrow input/output schemas and no direct database rights.
• Keep write authority in the local coordinator, which validates every response against its schema.
• Map model-service failure to failed or needs_review; alternative execution paths must be separately configured, visible adapters.

Stage C: Optional LangGraph Subgraphs

• Use only when a step genuinely needs dynamic tool selection or parallel specialists.
• Keep allowed tools, context, and human gates under one controlling graph.
• Give subgraphs only minimal case-scoped context; never pass vault keys, passphrases, or global database rights.
• Store checkpoint references locally and log them like other processing runs.

Configurable Operating Rules

• The local runtime currently has no active external adapter. Automated runs, additional agent types, and connections are introduced through separate, versioned adapters.
• Every adapter explicitly defines permissions, topics, schemas, schedules, failure handling, and logging in its registry or dedicated configuration.
• Model responses should include evidence IDs and model revisions.
• Review, export, and model-download approvals follow the editable human gates in the registry.
• Enable new agents only after registry validation, unit tests, and a real local run.

The authoritative editable contract remains AGENT_COORDINATION.md.