Agent Prompt Overrides

Overview

Standard profiled agents keep complete fallback prompts in code and may override their behavior with the current row in Core.AgentProfiles. Profiles are versioned environment state; descriptors and loaders remain code-owned.

Profile model

The deployed table source is db/sqlproj/Mastra.CoreDb/model/Tables/Core.AgentProfiles.sql. Important fields include:

Concern	Columns
Identity and grouping	AgentId, AgentAlias, Domain, FunctionalGroup, ProjectScope
Behavior	SystemPrompt, LlmOverridesJson, MemoryEnabled, OmDeploymentName, OmScope
Versioning	ProfileHash, VersionNumber, IsCurrent, effective timestamps
Provenance	CreatedBy, SourceSystem, RequestId, notes/metadata and audit timestamps
Retirement	RetiredAtUtc, RetiredBy, RetirementReason

AgentId matches the descriptor profileId, not necessarily its runtime registryId. The filtered unique index permits one current row per AgentId. Current list/get operations exclude retired rows.

The runtime service has idempotent compatibility DDL for a missing or older table, but the Core DACPAC is the preferred deployment owner.

Precedence and live behavior

At agent build time:

1. Descriptor defaults define identity, fallback name/prompt, tools/browser, preferred model type, project scope, and default memory policy.
2. A current database profile can replace the name and prompt, set supported LLM overrides, and enable/disable memory.
3. Shared capability and parameter data resolve the deployed model.
4. Caller-provided instructions/options remain request-time input and must not be silently replaced by the build-time prompt.

getAgent() reads the profile and recalculates an effective content hash every time. A matching hash reuses the cached build; a changed prompt or override rebuilds it. Direct SQL edits therefore do not rely solely on a correctly updated stored ProfileHash.

The K12 annex profile POST path additionally replaces the live registered agent when the Mastra instance supports removeAgent/addAgent. Other profiled agents pick up changes the next time their getter is used.

Supported override payload

The authoritative input schema is src/mastra/schemas/agent-profiles.schema.ts, re-exported from @maf/platform-runtime/schemas/agent-profiles.schema.

{
  "agentId": "example-review",
  "agentAlias": "Example Review Agent",
  "domain": "Example",
  "functionalGroup": "Review",
  "projectScope": ["testing"],
  "systemPrompt": "Review the supplied evidence and return structured findings.",
  "llmOverrides": {
    "deploymentName": "gpt-5-deployment",
    "modelName": "gpt-5",
    "temperature": 0.2,
    "topP": 0.9,
    "frequencyPenalty": 0,
    "presencePenalty": 0,
    "maxOutputTokens": 3000,
    "reasoningEffort": "medium"
  },
  "memoryEnabled": false,
  "createdBy": "operator@example.com",
  "sourceSystem": "admin-dashboard"
}

reasoningEffort accepts none, minimal, low, medium, high, or xhigh; provider normalization removes or adjusts settings unsupported by the selected deployment. When supplied, llmOverrides must contain at least one recognized field.

HTTP workflow

Runtime admin routes are protected by the admin proxy guard when the deployment requires it. Browser code should call the Admin UI BFF rather than sending the runtime proxy secret itself.

Method	Runtime path	Purpose
GET	/admin/agent-profiles	List current profiles; supports scope and domain.
GET	/admin/agent-profiles/{agentId}/current-prompt	Read the prompt plus stored/effective hashes and overrides.
GET	/admin/agent-profiles/{agentId}/history	Read all versions.
POST	/admin/agent-profiles	Validate and version a profile.
GET	/admin/agents/registry	Compare target-aware descriptors and profiles.
POST	/admin/agents/seed	Seed selected missing profiles; supports dryRun.
POST	/admin/agents/reconcile	Seed missing and retire known obsolete profiles; supports dryRun.

Example operator call to the direct runtime route:

curl -X POST "$MASTRA_BASE_URL/admin/agent-profiles" \
  -H "X-Mastra-Admin-Proxy-Secret: $ADMIN_PROXY_SHARED_SECRET" \
  -H "x-actor-id: operator@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "example-review",
    "systemPrompt": "Review evidence conservatively and cite the supplied record IDs.",
    "llmOverrides": {"temperature": 0.2, "maxOutputTokens": 3000},
    "createdBy": "operator@example.com"
  }'

The Admin MCP server exposes equivalent profile reads and the admin-update-agent-profile mutation. It is a separate transport over the same service-level rules.

Versioning and rollback

upsertProfile() hashes normalized behavioral content. Identical content returns the existing current row. A changed profile expires the current version and inserts the next version in one transaction.

Rollback does not reactivate an old database row. Read history and submit the desired historical prompt/settings as a new current version. This preserves the append-only audit trail and follows the normal cache invalidation path.

Dynamic prompt composition

Request-specific context belongs in the owning domain layer. For example, K12 annex modules build replacement values from the EOP snapshot in packages/domain-k12/src/k12-annex-prompt-replacements.ts. Dynamic agents use the shared factory's profile/model resolution, then compose request context into a short-lived agent. Do not place domain-specific placeholder logic in the shared profile service.

Troubleshooting

If an override is not visible:

1. Confirm the descriptor profileId matches the database AgentId.
2. Read /admin/agent-profiles/{agentId}/current-prompt and compare profileHash with effectiveHash.
3. Confirm the descriptor is applicable to the active project and its loader is included in MASTRA_TARGET.
4. Check /agents.json for the registryId—not the profile ID.
5. Validate the chosen deployment in the Core model capability/parameter data.
6. Enable AGENT_PROFILES_DEBUG=true, MASTRA_DEBUG_AGENT_FACTORY=true, and MASTRA_DEBUG_AGENT_PROMPT=true for source-level evidence.

An empty Admin UI list can also be a BFF fallback/auth/environment issue. Use the target-aware registry dry run to distinguish missing seed data from an agent that is not applicable to that deployment.

Verification

npm run test:agents
npm run test:admin
npm run test:contracts

Profile schema or route changes also require npm run contracts:check and the matching Bruno validation.

Related

• Agent Framework
• Unified Agent Platform
• Admin API