Agents — Overview

Agents — Overview

Agents are package-owned runtime artifacts. Product agents live in the K12, SDAC, TAP, and Handbook domain packages; shared, docs-chat, testing, and Reasoning Engine agents remain under src/mastra/agents/** while the monorepo transition continues.

An exported agent is not automatically live. The owning domain or cross-cutting artifact loader must build it and return it under its descriptor registryId. apps/runtime/src/mastra-runtime.ts merges the active loader results selected by MASTRA_TARGET.

Identity and configuration

Keep these identities separate:

Identity	Owner	Used for
Descriptor profileId	Agent source	Current/versioned row in Core.AgentProfiles.
Descriptor registryId	Agent source and loader	Live Mastra registry and HTTP discovery.
Database profile	Core.AgentProfiles	Prompt, alias, model overrides, memory settings, scope, and audit history.

The shared factory loads the current profile on each getAgent() call, recalculates its effective content hash, and reuses the cached build only when that hash still matches. Code defaults remain the fallback when SQL is unavailable or no profile exists.

Source ownership

Surface	Current source
K12	packages/domain-k12/src/agents/**
SDAC	packages/domain-sdac/src/agents/** and packages/domain-sdac/src/agents.ts
TAP	packages/domain-tap/src/agents/**
Handbook	packages/domain-handbook/src/agents/**
Shared and docs chat	src/mastra/agents/shared/**
Reasoning Engine	src/mastra/agents/reasoning-engine/**

Application code should import the shared factory through @maf/platform-runtime/agents/shared/*, not through the transitional raw source path.

Read next

• Agent Framework — lifecycle, loaders, registries, and tests.
• Unified Agent Platform — current descriptor and factory API.
• Prompt Overrides — profile updates, precedence, versioning, and rollback.
• Reasoning Engine Agents — optional Reasoning Engine agent family.

Operator-facing registry, seed, reconcile, and profile routes are documented in Admin API.