K12 Agents

Overview

K12 agents power the Emergency Operation Plan (EOP) editing and Quick Reference Guide (QRG) generation workflows. These agents use profile-based configuration managed in the Core.AgentProfiles database table, allowing runtime prompt updates without code deployment.

K12 Safety Agent (EOP)

The main agent for Emergency Operation Plan editing and content generation.

• Registry ID: eop-k12-safety-agent
• Profile ID: k12-safety-agent
• Purpose: Main agent for EOP (Emergency Operation Plan) editing and content generation
• Default name: K12-EOP-safety-agent
• Default prompt: "You are Eddy, the assistant that helps to edit and create EOPs (Emergency Operating Plans). Help users write and adjust sections for the named district plan and section. Return responses in JSON with explanation, is_edit, new_edition/answer fields as required."
• Code: packages/domain-k12/src/agents/k12-safety-agent.ts
• Accessor function: getK12SafetyAgent()

Features

• Profile-based prompt management via database
• LLM model override support
• Automatic rebuilding on profile hash changes
• Caching for performance
• Dynamic prompt placeholders for district/facility context

Usage Example

import { configureK12SafetyAgent, getK12SafetyAgent } from 'packages/domain-k12/src/agents/k12-safety-agent.ts';
import { createAzureInferenceChatModel, getAzureInferenceChatModel } from 'src/mastra/providers/azure-ai-inference.ts';

// Configure dependencies
configureK12SafetyAgent({ getAzureInferenceChatModel, createAzureInferenceChatModel });

// Get singleton instance
const agent = await getK12SafetyAgent();

QRG (Quick Reference Guide) Agents

All QRG agents use the profile service for database-managed prompts and follow the scoped naming pattern QRG-{name}. These agents work together to generate comprehensive Quick Reference Guides from Emergency Operation Plans.

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

1. Category Classification Agent

• Registry ID: qrg-category-classification-agent
• Profile ID: qrg-category-classification
• Purpose: Classifies annex categories from EOP documents
• Default prompt: Defined in CATEGORY_CLASSIFICATION_PROMPT
• Accessor: getCategoryClassificationAgent()

This agent analyzes Emergency Operation Plan annexes and categorizes them into standardized emergency types (e.g., fire, lockdown, weather events, medical emergencies).

2. Group Extraction Agent

• Registry ID: qrg-group-extraction-agent
• Export alias: qrg-groups-extraction-agent (used in buildK12Agents() return object)
• Profile ID: qrg-group-extraction
• Purpose: Extracts groups/audiences from annexes
• Default prompt: Defined in SEARCH_GROUPS_PROMPT
• Accessor: getGroupExtractionAgent()

Identifies distinct audience groups mentioned in the EOP (e.g., "Teachers", "Bus Drivers", "Students", "Administration") that need role-specific guidance.

3. Role Mapping Agent

• Registry ID: qrg-role-mapping-agent
• Profile ID: qrg-role-mapping
• Purpose: Maps groups to K12 role IDs
• Default prompt: Defined in ROLE_MAPPING_PROMPT_TEMPLATE
• Accessor: getRoleMappingAgent(availableRoles) -- requires an availableRoles parameter

Maps extracted audience groups to standardized K12 role tags stored in the MOEOP system for consistent categorization across districts.

warning

Unlike the other QRG agents, getRoleMappingAgent() is not a simple cached accessor. It calls factory.buildFresh() each time and injects the role list into the system prompt. Always pass the current role list.

Prompt injection & input shape (current behavior):

• The system prompt is loaded from Core.AgentProfiles and must include the {data} placeholder.
• {data} is replaced with a JSON object shaped as: {"data": [{"id": "<uuid>", "name": "Role Name"}]}
• The user message sent to the agent is only a comma-separated list of group names (for example: "ERT,Teachers,Administrators").
• If the database prompt omits {data}, the model will not receive the role list and cannot map to valid UUIDs.

Role source: The injected role list is derived from organization-visible K12 role tags (IAM includeOrganizationIds) and falls back to EOP-scoped tags when organization tags are unavailable.

4. Content Generation Agent

• Registry ID: qrg-content-generation-agent
• Export alias: qrg-generation-agent (used in buildK12Agents() return object)
• Profile ID: qrg-content-generation
• Purpose: Generates QRG content blocks (BEFORE, DURING, AFTER phases)
• Default prompt: Defined in GENERATION_PROMPT_TEMPLATE
• Accessor: getQrgGenerationAgent(params) -- requires dynamic context parameters

Generates action-oriented guidance organized into three temporal phases:

• BEFORE: Preparatory actions and preventive measures
• DURING: Immediate response actions during the emergency
• AFTER: Recovery actions and follow-up procedures

warning

Like the Role Mapping agent, getQrgGenerationAgent() builds a fresh agent each time with injected context. It requires { category, groupName, qrgType, allGroups } parameters that are substituted into the system prompt via {category}, {group_name}, {qrg_type}, and {other_group_names} placeholders.

5. QRG Editor Agent

• Registry ID: qrg-editor-agent
• Profile ID: qrg-editor
• Purpose: Edits existing QRG content based on user instructions
• Default prompt: "You are an AI assistant specialized in editing Quick Reference Guides (QRGs) for emergency response procedures. Your role is to help users modify QRG content sections (BEFORE, DURING, AFTER phases) while maintaining clear, actionable guidance and consistent formatting."
• Accessor: getQrgEditorAgent()

Handles user-requested modifications to generated QRG content while maintaining consistency and actionability.

Agent Patterns & Configuration

K12 agents follow these important patterns:

Dependency Configuration

All K12 agents must be configured with dependencies before use. buildK12Agents() handles this automatically by calling per-agent configure functions:

• configureK12SafetyAgent(deps) -- K12 Safety Agent
• configureQRGCategoryAgent(deps) -- Category Classification
• configureQRGGroupsAgent(deps) -- Group Extraction
• configureQRGRoleMappingAgent(deps) -- Role Mapping
• configureQRGGenerationAgent(deps) -- Content Generation
• configureQRGEditorAgent(deps) -- QRG Editor

QRG agents also export a single configureQrgAgents(deps) function that sets global dependencies for all QRG agents. The per-agent configure functions (used by buildK12Agents()) are convenience wrappers.

Profile-Based Prompts

• Prompts originate from Core.AgentProfiles — agent prompts and LLM overrides are fetched at runtime via agentProfilesService.getCurrent(profileId). When present, the SQL-stored profile can override systemPrompt, agentAlias, and llmOverrides.
• Agent caching & rebuilds — getK12SafetyAgent() uses a small in-memory cache keyed by profileHash. When an agent profile changes, the code detects it and rebuilds the agent.
• See Database: Agents & prompt management for comprehensive documentation on how the profile system works.

LLM Overrides

Agent profile overrides are loaded with agentProfilesService.getCurrent('k12-safety-agent') and include:

• systemPrompt (string)
• agentAlias (string)
• llmOverrides (temperature, topP, frequencyPenalty, presencePenalty, maxOutputTokens)

Numeric knobs (temperature, topP, frequencyPenalty, presencePenalty, maxOutputTokens) and model/deployment overrides can be supplied via the agent profile and are applied using the azure-ai-inference model creation helpers.

Dynamic Prompt Placeholders

K12 agents support dynamic placeholders that are replaced with district/facility data from the MOEOP API:

• Annex Context: {block}, {section}, {text}
• Roles: {list_of_roles}
• District Info: {district_name}, {district_website}, {district_full_address}, etc.
• Facility Info: {facility_name}, {facility_website}, {facility_full_address}, etc.

For complete documentation on agent prompt management, see Database: Agents & prompt management.

Additional Features

• Profile-backed prompts — K12 agents resolve prompt and model settings through the shared profile service in Core.AgentProfiles.
• Scenario-specific EOP agents — the EOP builder now exposes separate district, facility, functional annex, hazard annex, and suggest-role agent profiles in addition to the legacy k12-safety-agent profile.

Agent Registry Keys

When accessing agents from buildK12Agents(), use these keys:

Agent	Registry key	Descriptor ID	Profile ID
K12 Safety (EOP)	eop-k12-safety-agent	eop-k12-safety-agent	k12-safety-agent
K12 Safety (alias)	k12-safety-agent	(same agent instance)	(same)
Category Classification	qrg-category-classification-agent	qrg-category-classification-agent	qrg-category-classification
Group Extraction	qrg-groups-extraction-agent	qrg-group-extraction-agent	qrg-group-extraction
Role Mapping	qrg-role-mapping-agent	qrg-role-mapping-agent	qrg-role-mapping
Content Generation	qrg-generation-agent	qrg-content-generation-agent	qrg-content-generation
QRG Editor	qrg-editor-agent	qrg-editor	qrg-editor

note

• The K12 Safety Agent is registered under two keys (eop-k12-safety-agent and k12-safety-agent) -- both point to the same agent instance.
• Two QRG agents have export aliases that differ from their descriptor IDs: Group Extraction (qrg-groups-extraction-agent vs qrg-group-extraction-agent) and Content Generation (qrg-generation-agent vs qrg-content-generation-agent).
• The registry key is what you use to access agents from the buildK12Agents() return object. The descriptor ID is used internally for agent registration. The profile ID is used for Core.AgentProfiles lookup.

Debugging Tips

Agent Behavior Issues

• If the agent is using unexpected system messages, check Core.AgentProfiles rows and the k12-safety-agent logs (debug enabled via K12_DEBUG_AGENT_OVERRIDES=true).
• Turn on debug logs with K12_DEBUG_AGENT_OVERRIDES=true to get details about profile loading and override application.

LLM Parameter Issues

• If LLM parameter changes don't take effect, confirm the agentProfiles record includes numeric llmOverrides and that the configured Azure model exposes withSettings.
• If model-level settings don't apply, verify the selected model exposes a withSettings method (the agent tries to call it to apply numeric overrides).

Profile Hash Changes

• Profile hash changes trigger automatic rebuilds (logged in debug mode)
• Check logs for [agent-name] prefixed messages

Where to Look in the Repo

• Agent implementation: packages/domain-k12/src/agents/k12-safety-agent.ts (agent builder, LLM overrides, profile loading)
• QRG agents: packages/domain-k12/src/agents/qrg-agents.ts
• Registration & barrels: packages/domain-k12/src/agents/index.ts and packages/domain-k12/src/runtime.ts
• Tests: packages/domain-k12/tests/agents/, packages/domain-k12/tests/tools/

Next Steps

K12 Tools

Tools used by K12 agents

K12 Workflows

Workflows orchestrating K12 agents

Agent Prompt Overrides

How agent configuration works

Database: Agent Profiles

Agent profile management