Novior.MentorAgent.Declarative
1.3.0
Prefix Reserved
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
<PackageReference Include="Novior.MentorAgent.Declarative" Version="1.3.0" />
<PackageVersion Include="Novior.MentorAgent.Declarative" Version="1.3.0" />
<PackageReference Include="Novior.MentorAgent.Declarative" />
paket add Novior.MentorAgent.Declarative --version 1.3.0
#r "nuget: Novior.MentorAgent.Declarative, 1.3.0"
#:package Novior.MentorAgent.Declarative@1.3.0
#addin nuget:?package=Novior.MentorAgent.Declarative&version=1.3.0
#tool nuget:?package=Novior.MentorAgent.Declarative&version=1.3.0
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 wereMentorAgent.*. 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
- Getting started
- The YAML format
- Tools: named, not defined
- Security — a definition file is code
- When to use YAML and when to use C#
- Loading definitions from somewhere else
- Configuration options
- How to test it
- Why a separate package
- Requirements
- Related Packages
- License
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
.csfile. - The gate still holds. A file cannot invent a tool or bypass a role check — that is enforced, not advisory. A
kind: functionentry resolves only against your own, gated tools, and awebSearch,codeInterpreter,fileSearchormcpentry 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
- Put
shipping.agent.yamlin anAgentsfolder, withCopyToOutputDirectory. - 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. - Ask something in that agent's area — "where is order 1001?". The answer should come back through it.
- 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 anIMentorAgentSourceObserverreceives it asinvalid-definition, with the factory's message inDetail. - Negative check — the gate holds. Name a tool carrying
RequiredRolesin 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(orNovior.MentorAgent.Server) configured with aChatClient— declarative agents need one, and are skipped with a warning without it- A provider supporting the model options you use in the definitions
Related Packages
| 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 | Versions 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. |
-
net10.0
- Microsoft.Agents.AI.Declarative (>= 1.27.0-rc1)
- Novior.MentorAgent (= 1.3.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
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.