Novior.MentorAgent.Declarative 1.3.0

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Novior.MentorAgent.Declarative --version 1.3.0
                    
NuGet\Install-Package Novior.MentorAgent.Declarative -Version 1.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Novior.MentorAgent.Declarative" Version="1.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Novior.MentorAgent.Declarative" Version="1.3.0" />
                    
Directory.Packages.props
<PackageReference Include="Novior.MentorAgent.Declarative" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Novior.MentorAgent.Declarative --version 1.3.0
                    
#r "nuget: Novior.MentorAgent.Declarative, 1.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Novior.MentorAgent.Declarative@1.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Novior.MentorAgent.Declarative&version=1.3.0
                    
Install as a Cake Addin
#tool nuget:?package=Novior.MentorAgent.Declarative&version=1.3.0
                    
Install as a Cake Tool

Novior.MentorAgent.Declarative

New package IDs. From 1.0.0 the packages, their namespaces and their assemblies are Novior.MentorAgent.*; up to 1.0.0-rc.15 they were MentorAgent.*. See Migrating from the MentorAgent.* packages in the Novior.MentorAgent README.

Optional package. Install it only if you want to define specialist agents in YAML files instead of C# classes. Everything MentorAgent does works without it.

Define a Level-2 specialist in a text file, drop it next to your application, and the assistant can hand off to it — no new class, no [MentorAgent] attribute, no recompile of the agent's behaviour.

Built on the Agent Framework's declarative agent factory (Microsoft.Agents.AI.Declarative).


Package Family

Package Install when
Novior.MentorAgent Blazor Server app
Novior.MentorAgent.Server Web API / headless backend, or Blazor Auto server-side project
Novior.MentorAgent.Blazor Blazor WASM / Blazor Auto client project
Novior.MentorAgent.Abstractions Never directly — it arrives with any of the above
Novior.MentorAgent.Declarative ← you are here You want YAML-defined agents. Add it alongside Novior.MentorAgent or Novior.MentorAgent.Server

Table of Contents


What it does

MentorAgent's three-level agent model has a coordinator (L1) that can hand off to specialists (L2). Normally a specialist is a C# class:

[MentorAgent(Name = "ShippingAgent", Description = "Answers questions about deliveries")]
public class ShippingAgent                      // register it: builder.Services.AddScoped<ShippingAgent>();
{
    [MentorAction(Description = "Looks up a tracking number")]   // tool name: get_tracking
    public string GetTracking(int orderId) => /* … */;
}

This package adds a second way to declare the agent — its name, its instructions, its model settings and which tools it may use — as a file:

kind: Prompt
name: ShippingAgent
description: Answers questions about deliveries and shipping costs
instructions: |
  You handle shipping questions only. Use the available tools to look up real orders;
  never invent a tracking number. If the question is not about shipping, say so and stop.
model:
  options:
    temperature: 0.2
tools:
  - kind: function
    name: get_order_status
  - kind: function
    name: get_all_orders

Both kinds end up in the same handoff graph, so route_to_specialist reaches them identically and the user cannot tell which is which.


Getting started

Installation

dotnet add package Novior.MentorAgent.Declarative

Registration

using Novior.MentorAgent.Declarative;   // AddMentorAgentDeclarative
using Novior.MentorAgent.Extensions;    // AddMentorAgent

builder.Services.AddMentorAgentDeclarative(o => o.Directory = "Agents");

builder.Services.AddMentorAgent(o =>
{
    o.ChatClient     = chatClient;
    o.AppName        = "ShopFlow";
    o.ScanAssemblies = [typeof(Program).Assembly];
});

Order does not matter — MentorAgent asks every registered agent source while it builds a coordinator. A coordinator is built lazily for each session scope (each Blazor circuit, each SignalR connection to Novior.MentorAgent.Server, each SSE request), on its first message, or once at startup when WarmUpAtStartup is on. So the definitions are read again for every new scope. An edited file reaches new sessions without a restart, existing sessions keep the agents they were built with, and the log lines shown under How to test it appear then, not when the application starts.

Make sure the files reach the output folder

A definition that is not copied is the most common way this feature appears not to work. In your .csproj:

<ItemGroup>
  <Content Include="Agents\**\*.agent.yaml" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

If the directory is missing you get a warning naming the resolved path, [MentorAgent:Declarative] Directory '…' does not exist., when a coordinator is built: on a session's first message, or at startup with WarmUpAtStartup. That message exists because the failure is otherwise silent.


The YAML format

The schema comes from the Agent Framework, not from MentorAgent. The fields that matter in practice:

Field Meaning
kind Prompt for a prompt-based agent. Required
name The specialist's name. This is what appears in handoff logs — keep it stable
description What this specialist is for. The coordinator reads it to decide when to route here
instructions The agent's system prompt, used exactly as written. Use a \| block for multiple lines. MentorAgent adds nothing to it, including the grounding rule its generated specialist prompts carry, so write your own: state only facts a tool returned; if nothing provides what is asked, say so, and never estimate or invent a number, a name, a date or a status. Without it, a specialist asked for a figure its tools cannot return may make one up
model.options temperature, topP, and other per-agent model settings
tools Names of tools this agent may call — each entry needs kind and name, see below
outputSchema Optional JSON-schema-style shape for a typed answer

description is worth care: it is the coordinator's only basis for choosing this agent over another. "Handles orders" competes badly with "Handles orders, shipping and returns for existing customers".

Two format details that cost an afternoon

Neither is in the Agent Framework guide, and both fail in a way that points somewhere else.

Every tools entry needs kind. The reader accepts codeInterpreter, fileSearch, function, webSearch and mcp, but function is the only one MentorAgent keeps: it binds to a tool of your application. Omit kind and loading fails with NotSupportedException — not a validation message naming the line.

The other four are not names of your tools, and they do not add anything. The Agent Framework would turn them into provider-hosted tools (web search, code interpreter, file search, or a remote MCP server at whatever endpoint the file gives), configured by the file alone. MentorAgent removes them from the agent when it loads and logs a warning naming them:

[MentorAgent:Declarative] 'shipping.agent.yaml': removed web_search. A definition file can only use the application's own tools (`kind: function`); web search, code interpreter, file search and MCP servers are configured by the host, through MentorOptions.HostedTools and McpServers.

The agent still loads, with its function tools only, and an IMentorAgentSourceObserver receives each tool removed as hosted-tool-removed, with Tool set. If those tools cannot be taken out, the whole agent is skipped with an error instead, and reported as foreign-tools. To give the assistant these capabilities, configure them in the host (MentorOptions.HostedTools, McpServers), where the host's own controls apply.

Folded scalars (>) are not supported by this reader. Use |, or a single line. With > the parse error reports the end of the file, so you will look everywhere except at the block that caused it:

description: >                     # ✗ parse error, blamed on the last line of the file
  Handles shipping and delivery.

description: |                     # ✓
  Handles shipping and delivery.

description: Handles shipping.     # ✓

Tools: named, not defined

A tools: entry names a tool; it does not create one. The name must match one of your application's Level-1 methods: a public instance method with [MentorAction] or [Description] on a class in ScanAssemblies that is registered in DI, including a [MentorSkill] class. That is the whole list the factory is given. The methods of a C# [MentorAgent] specialist, MCP client tools, [MentorTeam] tools and the built-in tools (navigation, memory, UI actions) are not in it, so an entry naming one of them is taken away (see below).

tools:
  - kind: function              # required — see below
    name: get_order_status      # must match exactly; a name that matches no action is taken away, with a warning

The tool name is the snake_case of the C# member, with a trailing Async dropped: GetOrderStatusAsync() → get_order_status, matched exactly and case-sensitively. For a name that matches none of the tools it is given, the Agent Framework creates a declaration-only function of that name, with no code behind it. MentorAgent takes it away from the agent with a warning, and the agent loads without it:

[MentorAgent:Declarative] 'shipping.agent.yaml': removed get_order_statu. No action of this application has that name in this session — unknown, or off for this session — so nothing would run behind it. A `kind: function` entry must name one of the application's actions exactly.

The tools a definition is given are the session's: an action that is off for the session ([MentorAction(Enabled = false)], or turned off by an IMentorActionGovernor) is taken away the same way, so its name reaches no model. An IMentorAgentSourceObserver receives either as tool-not-found, with Tool set. The specialist still loads, but without the tool it has no data to answer with: check every name against your [MentorAction] / [Description] methods.

This is the design point of the whole package. MentorAgent hands the factory the application's real tool list, already wrapped in its gate, so a YAML agent calling create_order still hits:

  • RequiredRoles — the role check, exactly as a C# specialist does: the tool is offered to the agent's model only in a turn whose user holds one of its roles
  • human approval — the confirmation banner, if the tool requires one
  • action feedback, per-tool metrics and tracing

An agent defined in a file therefore has no capability your application did not already have, and no shortcut around the controls on it. That holds for the other kind values too: webSearch, codeInterpreter, fileSearch and mcp entries would add provider-hosted tools outside your list, so MentorAgent removes them with a warning (see Two format details that cost an afternoon).


Security — a definition file is code

Read this before pointing Directory anywhere.

A definition chooses the model, writes the system instructions, and names the tools the agent may call. Anyone who can write that file can rewrite the assistant's persona and widen which tools it reaches for. That makes it code, whatever its file extension says.

  • Load only from deploy-time locations. An application directory or an embedded resource. Never an upload folder, never a user-writable path, never a path built from request input.
  • Review definitions like source. Put them in version control and through the same review as a .cs file.
  • The gate still holds. A file cannot invent a tool or bypass a role check — that is enforced, not advisory. A kind: function entry resolves only against your own, gated tools, and a webSearch, codeInterpreter, fileSearch or mcp entry is removed with a warning, so a file cannot add web search, a code interpreter or an MCP server of its own choosing. But it can instruct the agent to try things, so the controls on your tools remain the thing that actually stops it.

The second point is the one people skip: YAML feels like configuration, and configuration feels safe to let more people edit.


When to use YAML and when to use C#

YAML C# [MentorAgent]
Change an agent's instructions Edit a file Recompile
New tool / new logic Not possible — tools stay in C# Where it belongs
Compile-time checking None; a bad tool name is silent Full
Who can author it Anyone who can edit a reviewed file Developers
Fits when Wording and routing get tuned often The agent has real behaviour

A good rule: behaviour in C#, phrasing in YAML. If you find yourself wanting a loop or a branch in a definition file, that agent wants to be a class.

You can mix freely — both kinds coexist in the same handoff graph.


Loading definitions from somewhere else

Definitions do not have to be files. Pass them as strings for agents stored in a database, a configuration service, or a test:

builder.Services.AddMentorAgentDeclarative(o =>
{
    o.Definitions.Add("""
        kind: Prompt
        name: FaqAgent
        description: Answers frequently asked questions about the shop
        instructions: Answer briefly, in the user's language. Say so when you do not know.
        """);
});

To ship definitions inside the assembly, the safest deploy-time location, embed them and pass their text as inline definitions:

<ItemGroup>
  <EmbeddedResource Include="Agents\**\*.agent.yaml" />
</ItemGroup>
builder.Services.AddMentorAgentDeclarative(o =>
{
    var asm = typeof(Program).Assembly;
    foreach (var name in asm.GetManifestResourceNames()
                            .Where(n => n.EndsWith(".agent.yaml", StringComparison.Ordinal))
                            .Order(StringComparer.Ordinal))
    {
        using var reader = new StreamReader(asm.GetManifestResourceStream(name)!);
        o.Definitions.Add(reader.ReadToEnd());
    }
});

For a fully custom source — one that hits your own store, or refreshes on a schedule — implement IMentorAgentSource from the Novior.MentorAgent package directly and register it. AddMentorAgentDeclarative is one implementation of that interface, not a privileged path:

using Novior.MentorAgent.Core;       // IMentorAgentSource, MentorAgentSourceContext
using Microsoft.Agents.AI;    // AIAgent

public sealed class DatabaseAgentSource : IMentorAgentSource
{
    // Called once per coordinator build, i.e. once per session, not once per process.
    // Cache here if reading your store is expensive.
    public async Task<IReadOnlyList<AIAgent>> GetAgentsAsync(
        MentorAgentSourceContext context, CancellationToken ct = default)
    {
        // context.ChatClient — your MentorOptions.ChatClient wrapped only in the token meter
        //                      (not the coordinator's pipeline), so usage lands in the metrics
        // context.Tools      — the Level-1 tools, already gated
        …
    }
}

builder.Services.AddSingleton<IMentorAgentSource, DatabaseAgentSource>();

Configuration options

Option Type Default Description
Directory string? null Folder to scan, absolute or relative to the app base directory. Deploy-time paths only
SearchPattern string "*.agent.yaml" File pattern inside Directory
Recursive bool false Scan subdirectories too
Definitions IList<string> empty YAML supplied inline, loaded in addition to Directory
ConfigurationSection string? null Name of the configuration section the YAML may reference. null exposes nothing

SearchPattern and Recursive — what the scan is allowed to reach

Both defaults are deliberately narrow, and widening them is a decision worth making on purpose rather than by accident:

builder.Services.AddMentorAgentDeclarative(o =>
{
    o.Directory = "Agents";

    // Default "*.agent.yaml", not "*.yaml". A deployment folder holds other YAML — a CI file,
    // a Helm values file — and reading one of those as an agent definition would at best fail
    // loudly. Widen it only if your definitions genuinely do not carry the suffix.
    o.SearchPattern = "*.agent.yaml";

    // Default false. A nested folder is exactly where a definition gets added without review,
    // and a definition file is code: it picks the model, writes the instructions and names the
    // callable tools. Turn it on when your layout needs it, not "just in case".
    o.Recursive = true;    // now Agents/support/*.agent.yaml is loaded too
});

Inline Definitions are loaded first (named inline[0], inline[1], … in the log and as the Name of what an IMentorAgentSourceObserver is told was left out; a file is named by its file name), then files in a stable order (sorted by path), so two definitions declaring the same agent name resolve identically on every machine rather than depending on the file system's enumeration order. A missing Directory is warned about — almost always a CopyToOutputDirectory miss, where the assistant otherwise starts fine and is simply missing a specialist nobody thinks to look for.

ConfigurationSection — exposing configuration to a definition

Default null: no configuration reaches the YAML at all, and the definitions are self-contained. Set it to expose one section, so a definition can reference values instead of hardcoding them:

// appsettings.json
{
  "AgentSettings": {
    "SupportEmail": "help@contoso.com",
    "MaxRefund": "250"
  }
}
builder.Services.AddMentorAgentDeclarative(o =>
{
    o.Directory            = "Agents";
    o.ConfigurationSection = "AgentSettings";   // only AgentSettings:* reaches the YAML
});

The values arrive as Power Fx variables, one per key, named by the key's full configuration path: AgentSettings:SupportEmail, AgentSettings:MaxRefund, plus one for the section AgentSettings itself. MentorAgent enumerates the section with AsEnumerable(), which does not make paths relative, and loads the values into the engine it hands the Agent Framework's factory: from Agent Framework 1.23 the factory itself loads only keys a definition names through Env and the host lists as allowed. How a definition references them is part of the Agent Framework's declarative schema, not something MentorAgent defines, so check the framework's documentation for the expression syntax before relying on it.

Every value arrives as text, as configuration keeps it. Power Fx reads a number written as text with the culture of the process: with the Italian culture, Value("0.3") gives 3.

Name a section. Never hand over the whole IConfiguration. MentorAgent loads the section into the Power Fx engine as variables — one per key — before the factory is built. A single key that Power Fx rejects as a name (in the version this package uses, an empty or whitespace-only key) takes every definition down before any is read. The exception does not say which key it was: Power Fx's message is the fixed text Invalid name: ${name}. The placeholder is never filled in, so do not look for a key literally named ${name}. This is not hypothetical: a key contributed by an unrelated configuration provider produced

ArgumentException: Invalid name: ${name}

and no agents loaded at all. Naming one section bounds the blast radius to keys you control.

MentorAgent catches that failure and logs the cause rather than letting it surface as a generic startup error, then returns no agents; an IMentorAgentSourceObserver receives every definition as invalid-configuration:

[MentorAgent:Declarative] The agent factory rejected the configuration exposed to YAML
(AgentSettings). Every key in it becomes a Power Fx variable and must be a valid identifier.
Narrow MentorDeclarativeOptions.ConfigurationSection, or leave it null.

If you see it, the fix is a narrower section — or null, which is the right setting unless you actually need substitution.


How to test it

  1. Put shipping.agent.yaml in an Agents folder, with CopyToOutputDirectory.
  2. Start the app and send a first message (or set WarmUpAtStartup = true, which builds a coordinator at startup). The log should then show, at Information level (the tool count is every Level-1 tool handed to the factory, not the number the file names):
    [MentorAgent:Declarative] Agent 'ShippingAgent' loaded from shipping.agent.yaml (12 tool(s) available to it).
    [MentorAgent] Handoff: declarative agent 'ShippingAgent' added to workflow.
    
  3. Ask something in that agent's area — "where is order 1001?". The answer should come back through it.
  4. Negative check — a bad file does not take the app down. Break the YAML deliberately: you get 'shipping.agent.yaml' could not be loaded — skipped, and everything else still starts. The log also writes [MentorAgent] Agent source Novior.MentorAgent.Declarative.DeclarativeAgentSource left out: shipping.agent.yaml (invalid-definition)., and an IMentorAgentSourceObserver receives it as invalid-definition, with the factory's message in Detail.
  5. Negative check — the gate holds. Name a tool carrying RequiredRoles in the YAML and ask the agent to use it while unauthenticated. The agent's model is not offered the tool and says it cannot do it here, the same way a C# specialist does, and no action is taken; a call made anyway is refused.

Why a separate package

Microsoft.Agents.AI.Declarative brings the Power Fx interpreter (YAML expressions are Power Fx), the Agents object model in three assemblies, Microsoft.ML.Tokenizers and several more.

That is a fair price for file-based authoring and pure overhead for everyone else, so it stays out of the Novior.MentorAgent core package. Installing this one is an explicit decision to pay it.

The reference is Microsoft.Agents.AI.Declarative 1.27.0-rc1, on the same 1.27 line as Microsoft.Agents.AI 1.27.0 in the core package, so adding it does not move the rest of the library onto a different Agent Framework version. The declarative package is still a prerelease upstream.


Requirements

  • .NET 10
  • Novior.MentorAgent (or Novior.MentorAgent.Server) configured with a ChatClient — declarative agents need one, and are skipped with a warning without it
  • A provider supporting the model options you use in the definitions

Package Purpose
Novior.MentorAgent Blazor Server — full AI assistant
Novior.MentorAgent.Server Any ASP.NET Core app — headless AI backend
Novior.MentorAgent.Blazor Blazor WASM — SignalR client
Novior.MentorAgent.Abstractions Shared contracts and UI components

License

Apache License 2.0 — the full text is in the LICENSE file inside this package, with the copyright notice in NOTICE. Versions up to and including 1.0.0-rc.14 were released under the MIT License, which still applies to them.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.4.0 0 11/18/2026
1.3.1 94 11/14/2026
1.3.0 105 11/11/2026
1.2.0 128 10/27/2026
1.1.0 122 10/21/2026
1.0.0 120 10/13/2026

1.3.0 - 2026-11-05

### Added

- ACTION-RULES.md lists the rules by which a method becomes an action, how actions are named, and how roles and
 confirmations add up. Each rule has a name that does not change and at least one test that fails when the rule does;
 a rule that comes in, changes or is retired is named in the release notes of its version. The rules of 1.3.0:
 `scan.assemblies-once`, `scan.concrete-classes`, `scan.public-instance-declared`, `scan.marker`,
 `scan.mentor-action-wins`, `scan.override-keeps-action`, `kind.one-per-class`, `kind.page-is-separate`,
 `kind.agent-owns-methods`, `kind.skill-methods-level1`, `kind.team-needs-members`, `kind.member-tools-leave-level1`,
 `kind.member-tools-same-rules`, `name.snake-case`, `name.team-tool`, `name.shared-warned`,
 `name.called-method-decides`, `confirm.declared-decides`, `confirm.default-for-writes`,
 `confirm.description-only-not-defaulted`, `confirm.predicate-adds`, `confirm.master-switch`,
 `confirm.beats-read-only`, `confirm.unconfirmed-writes-warned`, `roles.any-of`, `roles.signed-in`,
 `roles.checked-before-confirmation`, `roles.offered-when-allowed`, `surface.coordinator-only`,
 `surface.mcp-withholds-gated` and `surface.card-ungated-only`.

- An action can ship off, and the application can turn its actions on and off from outside its code.
 `[MentorAction(Enabled = false)]` keeps an action in the catalogue (`MentorActionInfo.EnabledByDefault` is false)
 and nowhere else: no agent is offered it, no model reads about it, the MCP server does not list it, the A2A card
 does not show it, and a call to it does not run. An `IMentorActionGovernor`, registered with
 `AddMentorActionGovernor<T>()`, answers for each action whether it is on, and can turn on one the code ships off:
 registering one gives whoever implements it the power to widen what the code allows. It is asked once as a session
 builds its tools, on every `tools/list` of the MCP server and before every call, with the session's id; a session
 keeps the tools it was built with, and a call to an action turned off meanwhile is refused. There can be one: a
 second registration throws. A governor that throws, or does not answer within `ActionPolicyTimeout`, stops the
 action. The A2A card follows the code only, so an action turned on from outside is not on it. New reason codes:
 `disabled` (`Denied`) and `governor-failed` (`PolicyFailed`). New rules: `enabled.off-by-default`,
 `enabled.external-decides` and `surface.governor-session`; `surface.mcp-withholds-gated` and
 `surface.card-ungated-only` now also leave out an action that is off.

- The governor can also give an action its roles: `IMentorActionGovernor.GetRequiredRolesAsync` answers in place of
 `[MentorAction(RequiredRoles = ...)]`, with `null` for the code's roles and an empty list for none. The answer
 decides whom the action is offered to, the check at every call, before a confirmation and again after it, and which
 MCP callers see and call it: an action the MCP server withheld only for its roles is published once the governor
 requires none. `MentorActionDecision.RolesFromOutside` says when the roles came from the governor. New rule:
 `roles.external-replace`; `roles.checked-before-confirmation` now checks the governor's roles when it gives them.

- The governor can also decide whether the user confirms an action: `IMentorActionGovernor.GetConfirmationAsync`
 answers `MentorConfirmationChoice.Code` for the code's confirmation, `Required` to ask even if the code does not,
 and `None` not to ask even if the code does — declared, by default for writes, or by `RequiresApproval`. A
 confirmation added counts from the call, one taken away from the next session, and in Native mode no auto-approval
 rule lets a required one through. A policy's `Confirm` still asks, a hosted MCP server's approval still comes from
 its provider, and with `RequireConfirmation` off nobody is asked. An action whose confirmation is taken away still
 counts as one that changes data. The MCP server publishes an action that asks for confirmation once the governor
 takes it away, and withholds one it requires. `MentorActionDecision.ConfirmationFromOutside` says when the governor
 changed whether a call is confirmed. New rule: `confirm.external-decides`; `confirm.predicate-adds` and
 `surface.mcp-withholds-gated` now say what the governor can take away.

- The governor can also rewrite the description the model reads: `IMentorActionGovernor.GetDescriptionAsync` answers
 in place of the code's, with `null` or a blank text for the code's. It is asked as a session builds its tools and
 on every `tools/list` of the MCP server, and the answer is what the coordinator, the specialists and the team
 members read, what tool filtering ranks, and what `tools/list` shows; the action's name and argument schema never
 change, and the code's `ProactiveHint` still follows the description. What the user sees keeps the code's
 description: the confirmation banner, the bar of the running action and `MentorActionDecision.DisplayName`. On a
 call to the MCP server the policies are asked with the code's description. New rule: `describe.external-replace`.

- An `IMentorAgentSource` says what it loaded and what it left out, and when it is asked is a promise. A source is
 asked whenever a coordinator is built: at least once per session — once per Blazor circuit, MAUI app scope or hub
 connection, and at every request on `/mentor/chat` and every task over A2A — and `MentorAgentSourceContext.SessionId`
 names the session, as `MentorActionRequest.SessionId` does. MentorAgent now calls `IMentorAgentSource.LoadAsync`,
 which returns a `MentorAgentSourceResult`: the agents, and a `MentorAgentRejection` (`Name`, `ReasonCode`, `Detail`,
 `Tool`) for each definition left out or tool taken away. Its default body returns the agents of `GetAgentsAsync`, so
 an existing source works unchanged. An `IMentorAgentSourceObserver`, registered with
 `AddMentorAgentSourceObserver<T>()`, receives a `MentorAgentSourceReport` for each source every time a coordinator
 is built, also when the source loaded nothing; a source that throws is reported as `source-failed`, with the
 exception's type and never its message. The reason codes, in `MentorAgentRejectionReasons`: `invalid-definition`,
 `not-an-agent`, `foreign-tools`, `invalid-configuration`, `source-failed`, `tool-not-found` and
 `hosted-tool-removed`. **Novior.MentorAgent.Declarative** reports every definition it does not load and every tool
 it takes away. New rules: `declarative.functions-match` and `declarative.no-hosted-tools`.

- `MentorRuntimeOptions.Changeable` lists the options that can be changed while the application runs, and from when
 a change applies (`MentorOptionReadAt`). From the next turn of every session: `Language`, `RateLimitPerUser`,
 `RateLimitWindowSecs`, `ConfirmationMessage`, `ConfirmationTimeout`, `ActionPolicyTimeout`, `EnableActionFeedback`,
 `EnableGenerativeCards`, `EnableSafetyCheck` and `CheckAnnouncedActions`. From the sessions that begin after the
 change: `MentorshipLevel`,
 `ProactiveNextSteps`, `EnableRichResponses`, `RefuseOutOfScope`, `ToolFilterMaxTools` and `MaxSessionMessages`. To
 change one, assign it on the `IOptions<MentorOptions>` value, replacing a collection rather than changing it in
 place. Every other option is read before the application starts: set it there. Each option listed has a test that
 changes it on a running application, and every option declares when it is read, so a new one cannot ship without
 the decision.

- After a turn in which the coordinator called no tool, MentorAgent asks a model whether its reply announces an action
 ("I'm registering the note…") or reports one as done when nothing ran (`MentorOptions.CheckAnnouncedActions`, on by
 default). If it does, the coordinator gets one more request in the same turn, with the same tools, told to call the
 tool now or to say that it was not done. The question names the tools the model was sent, and the answer names the
 one that does the action: the second request then says that this tool is there to call now. The instruction is that
 request's last message, read after the reply it is about, and never stored. A call to an action of the application
 the agent was not given (one that is off for the session) runs nothing, and the turn is checked as one in which
 nothing ran. The call is never required and passes the gate as any other, the reply
 already shown is not held back, and the second reply is not checked again. The question goes to
 `ClassifierChatClient`, or to `ChatClient` without one: a few hundred tokens after every reply that called no tool,
 so a small deployment there is worth configuring. Its verdict is logged at Information for every reply it checks,
 with the time and the tokens it took. On Path A with the history kept by MentorAgent; not with
 `UseServiceManagedHistory` nor with a pre-built `Agent` (BUG-220).

- A call the model makes to an action of the application that the coordinator was not given in the turn — one that
 is off, or another agent's — reaches no gate and runs nothing. `IMentorActionObserver` now receives its one
 decision, `Denied` with the new reason code `not-offered`, and the call's span says the same, in Blocking and in
 Native mode, with `CheckAnnouncedActions` on or off. A call the coordinator was given keeps the decisions of its
 gate, and only those.

- One instance of the application can tell which tenant a request belongs to. `IMentorTenantResolver`, registered with
 `services.AddMentorTenantResolver<T>()` (one per application), names it from the caller, the surface and the
 request's services; `IMentorTenant.Id` reads it, in an action, a policy or the governor, and
 `IMentorTenant.GetIdAsync()` resolves it first in a scope that had no turn yet. It is asked when a turn
 starts — in a Blazor circuit, on the hub, on `/mentor/chat`, in an A2A task — and for every `tools/list` and
 `tools/call` of the MCP server, where each call reads its own. A request is never served without a tenant: a resolver
 that throws, or answers `null`, empty or white space, refuses it before the model or the action, and a turn whose
 tenant is not the one its conversation began with is refused too. Without a resolver there is one tenant, as before,
 and `IMentorTenant.Id` is `null`.

- With an `IMentorTenantResolver`, two tenants on one instance share no memory, no rate limit and no conversation.
 `MentorMemoryService.GetUserIdAsync()` — the key of the memory and of `RateLimitPerUser` — is the tenant's own
 (`tenant:<id>/<the user's key>`), the shared anonymous bucket included, and so is the MCP server's per-caller
 allowance. A session snapshot names its tenant and is restored for that tenant only: one of another tenant, one that
 names none where a resolver is registered, and one that names a tenant where none is, are refused before the
 conversation changes (a 400 on `/mentor/session`). The history MentorAgent keeps is a coordinator's own, as before; a
 single `ChatHistoryProvider` instance with a resolver registered is reported at start-up, since it serves every tenant
 — `ChatHistoryProviderFactory` runs in the conversation's scope, where `IMentorTenant` reads the tenant. Without a
 resolver every key and every snapshot is as before.

- With an `IMentorTenantResolver`, every metric names its tenant: the `mentoragent.tenant` tag is on the four counters
 (`mentoragent.turns`, `mentoragent.tool_calls`, `mentoragent.errors`, `mentoragent.guardrail_blocks`) and on the
 `mentor.turn` span, the MCP server's calls included, so the whole instance is read per tenant from OpenTelemetry. The
 token & cost dashboard and `GET /mentor/admin/metrics` show the figures of the reader's tenant only: tokens, cost,
 turns, errors, guardrail blocks and top actions. A reader whose tenant the resolver does not name sees none (a 403
 on the endpoint). `IMentorMetrics.GetSnapshot(string? tenant)` and `IMentorMetricsStore.QueryAsync(string? tenant,
 CancellationToken)` are new, with defaults that keep existing implementations working. A custom `IMentorMetrics`
 shows a tenant nothing rather than the instance's figures (a 204 on the endpoint). A store is asked for a tenant only
 when it implements the new overload. A tenant's figures are kept in RAM since the process started; the store saves
 and seeds the instance's. Without a resolver the series, the dashboard and the endpoint are as before.

- With an `IMentorTenantResolver`, retrieval and the logs know the tenant. `MentorRagRequest.TenantId` gives a RAG
 source the turn's tenant; MentorAgent filters nothing, so a source that holds several tenants' documents returns
 that tenant's. A source that implements only the `(query, maxResults)` overload never sees it, and a Warning says
 so at its first search with a tenant. Every log line of a turn, the application's own code in the turn included,
 and of a call to the MCP server is written in a log scope with one pair, `mentoragent.tenant`, the key of the
 metrics and the span; a provider that includes scopes shows it. Without a resolver nothing changes.

- `MentorOptions.RagNoResultsNotice` (off by default) tells the model when the knowledge-base search of a turn kept no
 document — none returned, or every one below `RagMinScore`: a question the documents would cover is answered "not
 found in the documents" rather than from memory, and a message that needs no document, such as a greeting or an
 action, is answered as usual. The text is MentorAgent's, in the language of the turn, in that request's
 instructions only. It is not given after a search that failed, nor without a source.

- A knowledge-base search that fails can be monitored. With `EnableObservability` it is counted on
 `mentoragent.rag_failures`, tagged with the source (`mentoragent.rag.source`, its type's full name) and the
 exception's type (`mentoragent.error.type`), never its message, and with `mentoragent.tenant` when a resolver is
 registered; a Stop during the search is not counted. Each search has a `mentor.rag.search` span, with the source,
 and the status Error when it failed. The Warning names the source: "The search of … failed — RAG context skipped.".

- `IMentorRagSource.OnConversationChangedAsync` tells a source that the session's conversation changed, so one that
 keeps state for it clears it: `MentorConversationChange.Reason` is `Reset` (New conversation), `Restored` (a saved
 conversation took its place) or `Replaced` (a restored conversation the service no longer knew was replaced,
 BUG-110), with the session's id and its tenant. The default does nothing, so an existing source works unchanged. It
 is called with `UseRag` on, on the instance the session searches with, bounded by `SafetyCheckTimeout`; a source
 that throws or does not answer in time is logged as a warning, and the conversation changes anyway.

- `MentorVectorStoreRagSource<TRecord>`, a knowledge-base source over any collection of
 `Microsoft.Extensions.VectorData` (pgvector, Qdrant, Azure AI Search, an in-memory one), registered with
 `services.AddMentorVectorStoreRag(sp => collection, new MentorVectorStoreRagOptions<TRecord> { Content = … })`.
 The options say what of a record is the document, its title, its link and its metadata, and which records a request
 may see (`Filter`, given the `MentorRagRequest` with its tenant and user). Scores are read as similarities whatever
 the collection's distance function: with `CosineDistance`, the Postgres default, the source uses 1 − distance, so
 `RagMinScore` keeps the nearest documents. The function comes from `DistanceFunction` or from the record's
 `[VectorStoreVector]` attribute; when neither names one, or it is a Euclidean, Manhattan or Hamming distance,
 registering the source fails. The message is embedded once per turn with `MentorOptions.EmbeddingGenerator` and
 shared with routing, tool filtering and memory, or with a generator of the source's own; without either, the
 collection embeds the text itself. `DefaultMinScore` is 0.5. With a tenant resolver and no `Filter`, the first
 search with a tenant is logged as a warning. `Novior.MentorAgent` now references
 `Microsoft.Extensions.VectorData.Abstractions` 10.10.0, which Agent Framework already brought.

- A provider that ignores `tool_choice: "required"` is reported. `RequireLookupForRecordQuestions` and
 `RequireActionForChangeRequests` require the first call of the turn with `ChatToolMode.RequireAny`; a provider that
 answers such a request without any call — Ollama ignores `tool_choice` — makes them do nothing, and the first time
 it does a warning says so, once per provider client: "The provider answered a request that required a tool call
 (tool_choice: required) without calling one: …". A call to a tool the request did not offer is still a call, and a
 streamed reply is looked at as it goes by, nothing held back. The README has a recipe for llama-server and vLLM.

- `CoordinatorSampling` (`MentorSamplingOptions`): the coordinator's sampling — `Temperature`, `TopP`, `TopK`,
 `MaxOutputTokens`, `FrequencyPenalty`, `PresencePenalty`, `Seed` — on every request of its turns, the forced first
 call and the follow-ups of the tool loop included. The option unset, and each value left null, is the provider's
 own; in configuration, `Mentor:CoordinatorSampling:Temperature` and so on. The classifiers call the provider directly
 and keep their own settings: those that ask for temperature 0 still do, the others keep the provider's default, as
 before. A negative temperature, a top-p outside (0, 1], or a top-k or output limit below 1 stops the application at
 startup. Stop sequences are not offered: one that also occurs in a tool call's arguments would cut the call short.

- `WarmUpChatModel`: with `WarmUpAtStartup`, the warm-up also sends the coordinator's model one minimal request, so
 the first turn does not pay for opening the connection, the provider's empty prompt cache or a local model still
 loading. Every start costs one request per client — `ChatClient`, and `StrongChatClient` when it is set — with the
 coordinator's instructions, tools and sampling, no call allowed (`ChatToolMode.None`), one short user message and at
 most 16 output tokens. It goes straight to the provider client: no history, no memory, no turn on the dashboard;
 the warm-up's log line gives its time and tokens. A request that fails is a warning, and the application carries
 on; without `WarmUpAtStartup` the option has no effect, and a startup warning says so.

- `MentorEvaluator.RunConversationsAsync`: whole conversations (`EvalConversation`, `EvalTurn`) through the mentor
 itself — the orchestrator, streaming, with its tools, filters, roles, RAG, memory and the history from one turn to
 the next — each in a session of its own. A turn can require tools (`ExpectTools`: "at turn 2 it must call X"),
 forbid others (`ForbidTools`), and set a token budget, a limit on the time to the first token and an expectation
 for the judge. Its result adds `ToolsCalled`, read from the tool gate, `TimeToFirstToken`, `TurnDuration`,
 `Conversation` and `Turn`; its tokens are those of its own session, exact while other sessions talk. **Every
 confirmation is answered no by default: an evaluation does not write data on its own.**
 `MentorEvalOptions.ApproveConfirmations` answers yes, and `PrepareSession` sets the conversation's user or page
 before its first turn. `RunAsync` is unchanged; `SystemInstructions`, `Checks` and `Evaluators` stay its own.

- `EvalTurn.ExpectRefusal`: a conversation turn can expect the mentor to refuse — `EvalRefusal.OutOfScope`
 (`RefuseOutOfScope`), `EvalRefusal.Guardrail` (the safety check, the host's `InputGuardrail`, or the model refusing
 to answer) or `EvalRefusal.Any`. That refusal, shown to the user as an error, then passes the turn and the
 conversation goes on; a turn that was answered, refused the other way or failed, fails, and its notes say which. A
 safety check that could not run, a message too long, the rate limit and a missing tenant are not refusals: they stay
 errors. Without the expectation a refusal fails the turn as before. `MentorEvalResult.Refusal` reports the refusal a
 turn showed, expected or not.

- A `dotnet new` template in the repository, `templates/mentoragent-blazor`: a Blazor Server helpdesk with a
 MentorAgent assistant and three actions — `list_open_tickets`, `assign_ticket` with a confirmation, `close_ticket`
 with a confirmation and the `Agent` role — the model from the configuration with its key in the user secrets, and a
 test sign-in with two users, one without the role. Its test project runs the assistant with a scripted model through
 `RunConversationsAsync`: a support agent who confirms closes a ticket, without a yes the ticket stays open, and
 without the role the action is not offered. It is installed from a clone of the repository, not from NuGet:
 `dotnet new install templates/mentoragent-blazor`, then `dotnet new mentoragent-blazor -n Helpdesk`.

### Changed

- An `IMentorRagSource` that answers with no list (`null`) fails at once, with a message that says a source finding
 nothing returns an empty list, instead of a `NullReferenceException` later on. The turn goes on without documents,
 as before.

- **Novior.MentorAgent.Declarative:** a `kind: function` entry that names no action of the session — unknown to the
 application, or off for the session — is taken away from the agent, with a warning, and the agent loads without it.
 The Agent Framework used to give the agent a function of that name with nothing behind it: the model could call it,
 nothing ran, and the agent stopped without a word in the log. An action that is off is therefore described to no
 model through a definition that names it either.

- Every package is now checked at pack time against the public API of 1.2.0, so 1.3.0 cannot break code built
 against 1.2.0 by accident. An intended break is listed in this file as Breaking.

- The family moves onto the Microsoft Agent Framework 1.27.0 line (`Microsoft.Agents.AI` and
 `Microsoft.Agents.AI.Workflows` 1.27.0). **Novior.MentorAgent.Declarative:** `Microsoft.Agents.AI.Declarative` moves
 to 1.27.0-rc1, on the same line. The two breaking changes of Agent Framework 1.27 are in parts MentorAgent does not
 use: `AddFoundryResponses` for hosted Foundry applications, and the redirect callbacks of `DefaultHttpRequestHandler`.

- The packages' description and tags say what MentorAgent is: AI agents in a .NET application under your rules —
 roles, confirmations, cost control. The tags of `Novior.MentorAgent`, `.Server` and `.Blazor` now include
 `ai-governance`, `governance`, `authorization`, `roles`, `approval` and `human-in-the-loop`; the `mentor` tag, which
 found only namesakes, is gone from all five packages.

### Fixed

- When a restored conversation the service no longer knew was replaced by a new one (BUG-110), the knowledge-base
 search kept the recent messages of the conversation that was gone: the first search of the new one was given the
 message of the turn that had failed. They are now cleared, as on a reset or a restore.

- The turn's vector of the message (`IMentorQueryEmbedding`) was kept on its text alone (BUG-229): a knowledge-base
 source that embeds the message with a model of its own was handed the vector of `MentorOptions.EmbeddingGenerator`,
 or routing, tool filtering and memory were handed the source's, whichever asked first in the turn. Each generator
 now gets the vector it makes, still computed once per turn, compared by reference; at most four generators are
 remembered, the oldest dropped first, so one built for every call cannot make the cache grow.

### Security

- **Novior.MentorAgent.Server:** BUG-230 (S1): `GET /mentor/chat` ran a turn for any request the browser sent with the
 sign-in cookie, and with cookie authentication (`SameSite=Lax`) that includes a link clicked on another site: one
 link ran a turn as the signed-in user, with the link author's question, even with `RequireAuthorization`. Both
 `GET` and `POST /mentor/chat` now answer `403` before the turn when the browser's Fetch Metadata says another site
 started the request (`Sec-Fetch-Site` `cross-site` or `same-site`, `Sec-Fetch-Mode` not `cors`), and log a warning
 `chat.cross-site-refused` without the question. Your own page's calls, clients without Fetch Metadata and `cors`
 requests work as before. With a `SameSite=None` cookie, or for browsers that send no Fetch Metadata, add a check
 of your own: the Server README says how.

The full history is in CHANGELOG.md, inside this package.