Skip to content

Agent configuration schema (v2)

Overview

Workflow agent configuration uses a normalized hierarchical schema (v2) with Pydantic validation, backward-compatible migration from the legacy flat format, and typed models. Config is stored in the DB as before (flat JSONB and columns); at load time it is migrated to v2 and validated.

Structural improvements

  • Single casing: PascalCase for schema keys (Version, Metadata, Thresholds, Agents, Embeddings, Features, Prompts, Execution).
  • Nested agents: Instead of flat keys like RankAgent_provider, RankAgent_temperature, config is structured as Agents.RankAgent.Provider, Agents.RankAgent.Temperature, etc. Each agent has required fields: Provider, Model, Temperature, TopP, Enabled.
  • Optional per-agent Effort: Agents.<name>.Effort (flat key {Agent}_effort) sets the reasoning-effort tier. None — the value every shipped preset and every pre-existing config carries — means "provider default", so the field validates cleanly when absent. Which tiers a model accepts comes from config/model_capabilities.json (or, for Codex, its live model/list), enforced at the config write boundary; see Cloud Model Reference.
  • Dedicated sections:
  • Thresholds: MinHuntScore, RankingThreshold, SimilarityThreshold, JunkFilterThreshold.
  • Agents: All LLM agents (RankAgent, ExtractAgent, SigmaAgent, and sub-agents: CmdlineExtract, ProcTreeExtract, HuntQueriesExtract, RegistryExtract, ServicesExtract, ScheduledTasksExtract, NetworkIndicatorExtract).
  • Embeddings: Sigma only (Sigma similarity). OsDetection was removed 2026-06-22 — platform detection is deterministic/entity-driven and loads no embedding model.
  • Features: SigmaFallbackEnabled, CmdlineAttentionPreprocessorEnabled, ProcTreeAttentionPreprocessorEnabled. (Rank Agent enablement is controlled via Agents.RankAgent.Enabled. The OSDetectionFallback agent was removed; any stale Agents.OSDetectionFallback entries are stripped automatically by the v1→v2 migration.)
  • Prompts: Per-agent prompt/instructions for prompt-bearing agents. ExtractAgent is excluded because it supplies only model/provider fallback configuration.
  • Execution: ExtractAgentSettings.DisabledAgents, OsDetectionSelectedOs.
  • Naming normalization: All QA agent names (RankAgentQA, CmdLineQA, CmdlineQA, ProcTreeQA, HuntQueriesQA, RegistryQA, ServicesQA, ScheduledTasksQA) are automatically removed by the migration. The QA agent subsystem was fully removed in v7.2.0 (commit b9645305, 2026-05-22; released 2026-05-29); see QA Loops for what replaced it.
  • No unknown keys: Schema validation forbids unknown root keys; validation errors are explicit.

Backward compatibility

  • Read: DB rows (or preset JSON) are always passed through load_workflow_config(). If the payload is v1 (or legacy flat), it is migrated to v2 and validated. The API response is built from the v2 model in legacy shape (flat agent_models, etc.) so the UI and other consumers are unchanged.
  • Write: PUT and preset apply still accept the legacy flat shape. Config is persisted as flat in the DB. Optional: future endpoints can accept v2 JSON and normalize before persist.
  • Legacy consumers: WorkflowConfigV2.flatten_for_llm_service() produces the flat key format expected by LLMService, SigmaGenerationService, and the workflow. No change to those call sites until they are refactored to use nested config.

Compatibility retirement criteria

Keep the legacy prompt/config compatibility paths until all of these are true:

  • No active or historical agentic_workflow_config rows contain v1 flat root keys, QA agent keys, role-only extractor prompts, objective, user_template, or double-encoded prompt JSON.
  • Every committed preset and exported customer preset imports through the v2 UI-ordered path without invoking migrate_v1_to_v2() legacy-key consumption.
  • LLMService, SigmaGenerationService, and workflow execution read nested WorkflowConfigV2 data directly instead of flatten_for_llm_service().
  • Regression tests covering parsePromptParts(), _backfill_ui_ordered_sub_agents(), and v1-to-v2 migration are updated to assert rejection or cleanup of the retired shapes.

Until those checks pass, these paths are compatibility boundaries, not removable dead code.

Modules

Module Role
src.config.workflow_config_schema Pydantic models (AgentConfig, WorkflowConfigV2, ThresholdConfig, etc.).
src.config.workflow_config_migrate migrate_v1_to_v2(raw) — legacy flat → v2 dict; logs deprecation for legacy keys.
src.config.workflow_config_loader load_workflow_config(raw) — migrate, validate, return WorkflowConfigV2. config_row_to_flat_agent_models(row) for legacy callers.

Version and validation

  • Version field: v2 config must have Version: "2.0". v1 or missing version triggers migration.
  • Validation: Required sections and types are enforced. Invalid types or missing required agent fields raise Pydantic ValidationError.
  • Feature/agent gating: If an agent is disabled (for example, Agents.RankAgent.Enabled is false), that agent must not execute (enforced by workflow logic; schema documents the contract).

Example and presets

  • Quickstart presets: config/presets/AgentConfigs/quickstart/*.json are committed v2 presets ready for import via the UI "Import from file" dialog. The loader migrates v1 -> v2 on load, so older exported presets also work.

ExtractAgent

ExtractAgent is the parent config; sub-agents (CmdlineExtract, ProcTreeExtract, HuntQueriesExtract, RegistryExtract, ServicesExtract, ScheduledTasksExtract, NetworkIndicatorExtract) inherit provider/model from ExtractAgent when not configured. The schema types Agents.ExtractAgent explicitly; fallback behavior is implemented in the workflow and LLMService. It has no key in the v2 Prompts section.

Last updated: 2026-08-13 Last reviewed: 2026-09-01