Skip to main content

K12 Agents

Overview​

K12 agents use profile-based configuration from Core.AgentProfiles, so prompts and supported model overrides can change without a code deployment. Runtime descriptors remain the fallback and define stable registry/profile identities.

EOP agents​

EOP editing uses the scenario-specific district, facility, functional-annex, hazard-annex, and suggest-role agents defined in packages/domain-k12/src/agents/k12-safety-agent.ts. eop-k12-safety-agent remains the compatibility registry key for the main k12-safety-agent profile.

These agents retain role-aware annex editing. The QRG cutover described below does not change that EOP editing behavior.

Category-first QRG agents​

QRG uses exactly two profile-backed agents. The workflow resolves its exact General User Tag Categories from the compiled EOP snapshot, or from an explicit category-ID override, and never infers groups or maps role tags.

Code: packages/domain-k12/src/agents/qrg-agents.ts

Category Guide Generator​

  • Registry ID: qrg-category-guide-generation-agent
  • Profile ID: qrg-category-guide-generation
  • Purpose: Decide whether one annex/category pair warrants a guide and, when it does, generate BEFORE, DURING, and AFTER content.
  • Accessor: getQrgCategoryGuideGenerationAgent(params)

The category name and description are semantic anchors for tone and operational scope. The exact category ID remains authoritative. The agent cannot add categories or infer roles. One fresh agent is built per annex/category target with the annex name, deterministic annex classification, category context, and DISTRICT/FACILITY scope substituted into the profile prompt.

Category Guide Editor​

  • Registry ID: qrg-category-guide-editor-agent
  • Profile ID: qrg-category-guide-editor
  • Purpose: Edit one section of an existing category-specific guide without changing its audience.
  • Accessor: getQrgCategoryGuideEditorAgent()

Editing requests must carry exactly one General User Tag Category. Legacy role metadata can still be present in the document response, but category-first editing ignores it.

Retired QRG profiles​

The K12 seed explicitly retires these profiles:

  • qrg-category-classification
  • qrg-group-extraction
  • qrg-role-mapping
  • qrg-content-generation
  • qrg-editor
  • k12-qrg-generator

Historical rows remain queryable for audit. They are marked non-current and are not registered at runtime.

Generation flow​

Annex classification is deterministic from the annex name. The former category classifier, group extractor, and role mapper are not part of the workflow.

Configuration and registration​

The runtime source of truth is loadK12ArtifactsCore() in packages/domain-k12/src/loader-core.ts. It builds:

  • seven unique annex registry agents: legacy, district, facility, functional, hazard, functional suggest-role, and hazard suggest-role;
  • the two QRG agents below;
  • the turn-based conversation evaluator;
  • the browser EOP evaluation agent when browser artifacts are enabled.

The normal loader therefore attempts 11 agents with browser artifacts and 10 without them. Agent builds use Promise.allSettled; an individual build failure is logged and omitted instead of preventing every K12 artifact from loading.

AgentRegistry keyProfile ID
QRG Category Guide Generatorqrg-category-guide-generation-agentqrg-category-guide-generation
QRG Category Guide Editorqrg-category-guide-editor-agentqrg-category-guide-editor
Turn-Based Conversation Evaluatork12_turn-based-conversation-evaluator-agentk12-turn-based-conversation-evaluator

packages/domain-k12/src/agents/index.ts also exposes buildK12Agents() for direct/compatibility callers, but the runtime loader above owns deployed registration.

The deployment seed source is db/seed-data/domains/k12.json. The environment seed SQL is generated at db/sqlproj/seeds/k12/seed_agent_profiles.sql and is invoked by db/sqlproj/seeds/_run_by_env.sql for K12-capable environments.

Prompt behavior​

  • Prompt profiles are resolved by profile ID from Core.AgentProfiles.
  • The generator receives exact annex/category/scope substitutions and returns should_generate, recommendation_reason, and three phase strings.
  • The editor receives one exact category plus current guide content and organization context.
  • Both agents prohibit inferred roles/categories and unsupported procedures.
  • Profile hash changes cause the shared agent factory to rebuild agents.

Where to look​

  • Agent descriptors and factories: packages/domain-k12/src/agents/qrg-agents.ts
  • Generator prompt and decision schema: packages/domain-k12/src/qrg-prompts.ts
  • Generation workflow: packages/domain-k12/src/qrg-generation.workflow.ts
  • Editing workflow: packages/domain-k12/src/qrg-editing.workflow.ts
  • Runtime registration: packages/domain-k12/src/loader-core.ts
  • Seed profiles: db/seed-data/domains/k12.json
  • Tests: packages/domain-k12/tests/agents/ and packages/domain-k12/tests/workflows/