Novior.MentorAgent.Declarative
1.4.0
Prefix Reserved
dotnet add package Novior.MentorAgent.Declarative --version 1.4.0
NuGet\Install-Package Novior.MentorAgent.Declarative -Version 1.4.0
<PackageReference Include="Novior.MentorAgent.Declarative" Version="1.4.0" />
<PackageVersion Include="Novior.MentorAgent.Declarative" Version="1.4.0" />
<PackageReference Include="Novior.MentorAgent.Declarative" />
paket add Novior.MentorAgent.Declarative --version 1.4.0
#r "nuget: Novior.MentorAgent.Declarative, 1.4.0"
#:package Novior.MentorAgent.Declarative@1.4.0
#addin nuget:?package=Novior.MentorAgent.Declarative&version=1.4.0
#tool nuget:?package=Novior.MentorAgent.Declarative&version=1.4.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
- Teams in YAML —
*.team.yaml - 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 at compile time; a tool name the session does not have is taken away with a warning when the agent loads | 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 for the agents under the coordinator:
// one id per call (BUG-225), the token meter and metrics, the role filter on the
// tools (BUG-205). Not the coordinator's pipeline: no routing, no safety checks
// context.Tools — the Level-1 tools, already gated
…
}
}
builder.Services.AddSingleton<IMentorAgentSource, DatabaseAgentSource>();
Teams in YAML — *.team.yaml
A team of agents that discuss a task and reach a verdict can be written in a file too, next to the agents: every
*.team.yaml file of Directory, and every entry of TeamDefinitions, gives one team. It is the team an
IMentorTeamSource gives in code (see the core README, Teams from a source), checked the same way, and it works as
a [MentorTeam] class does: the coordinator gets a tool named after it in snake_case, and the members discuss until
a verdict.
kind: Team # optional
name: Order Review
description: Reviews an order before anything is done with it.
approver: Approver # the member whose verdict ends the discussion
maxIterations: 6 # optional, 10 by default
triggerOn: [review, check] # optional
handoffTo: [ShippingAgent] # optional
members:
- role: Clerk
instructions: |
Look at the order and say what you see.
tools: [get_order] # the session's actions, by name
- role: Approver
instructions: Decide, with [TEAM:APPROVED] or [TEAM:REJECTED].
A member's tools are names of the actions the session already has, as in an agent's definition: a name it does not
have, or one that is off, is taken away and reported, and each tool runs through the gate with its roles and its
confirmation. A file cannot add a capability.
A file that does not hold is left out, never half-read. The YAML is read with YamlDotNet's node model, and every key
is checked: YAML the parser refuses, a key written twice, an unknown key (a misspelt membres), a list where a text
goes, two documents in one file. The team is left out with invalid-definition and where the fault is — line 2, column 1: unknown key 'membres' in a team — in the log and in IMentorAgentSourceObserver.OnTeamsLoaded. A team whose
name the code already uses, or without members, is left out by the core with its own reason. The rule is
team.from-yaml in ACTION-RULES.md.
The files come from the same Directory as the agents, with a pattern of their own; teams that live elsewhere, in a
database say, are given inline:
builder.Services.AddMentorAgentDeclarative(o =>
{
o.Directory = "Agents"; // Agents/*.agent.yaml and Agents/*.team.yaml
o.TeamSearchPattern = "*.team.yaml"; // the default
o.TeamDefinitions.Add(teamYamlFromStore); // one team each, in addition to the files
});
A file the teams' pattern matches is never read as an agent, even when SearchPattern is widened to *.yaml.
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 |
TeamSearchPattern |
string |
"*.team.yaml" |
File pattern of the team definitions inside Directory. A file it matches is never read as an agent |
TeamDefinitions |
IList<string> |
empty | Team definitions supplied inline, one team each, 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 team files are read with YamlDotNet 18.1.0 (MIT), its node model only, which brings no dependency of its own. An application that references an older YamlDotNet itself gets NuGet's downgrade error (NU1605) until it references 18.1.0 or later.
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.4.0)
- YamlDotNet (>= 18.1.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.4.0 - 2026-11-18
### Added
- Actions registered in code, without attributes:
`options.Actions.Add<OrderActions>(nameof(OrderActions.CancelOrderAsync), action => action.Describe("…").RequireRoles("Manager").RequireConfirmation())`.
A registered action is one of the coordinator's actions, like a `[MentorAction]` method: its roles, its confirmation
and the default for writes, the `IMentorActionGovernor`, `/mcp` and the A2A card apply to it the same way. The builder
declares what the attribute does: `Describe`, `Category`, `RequireConfirmation`, `ReadOnly`, `RequireRoles`, `Off`,
`NavigateTo`, `Hint`. A mistake stops the application when it starts, naming the method: a method that is not
there, overloaded, static or generic, a registration without a description, a method registered twice or already an
action by its attributes. New rules in ACTION-RULES.md: `fluent.coordinator-action`, `fluent.method-must-exist`,
`fluent.declared-decides`, `fluent.description-required`, `fluent.no-double`.
- Commands and queries as actions: a type of its own and its handler, registered with
`options.Actions.AddCommand<CancelOrder, CancelOrderHandler>(action => action.Describe("…"))` or `AddQuery<…>`. The
handlers implement `IMentorCommandHandler<TCommand>`, `IMentorCommandHandler<TCommand, TResult>` or
`IMentorQueryHandler<TQuery, TResult>`, new in Novior.MentorAgent.Abstractions. The action is named after the type in
snake case, its parameters are the type's public properties, a query is always read-only and a command is a write;
roles, confirmations, the governor, the policies, `/mcp`, the A2A card and team members apply as to a method
registered in code. In the catalogue its origin is `command` or `query` (`MentorActionOrigins.Command`, `Query`), one
registration per type, and its `Method` is the handler's `HandleAsync`. The builder's new `Name(…)` gives any action
registered in code another name. New rules in ACTION-RULES.md: `fluent.command`, `fluent.query`,
`fluent.message-checked`, `fluent.message-trace`.
- `MentorChatKeys.ModelNotCalled` (`"mentoragent.model_not_called"`): the key an application's own `IChatClient` sets
in the `AdditionalProperties` of a response it answered without a model, and of each streaming update, with the
cause as the value (`ai_switch`, `budget`, an open string). A turn none of whose requests reached a model is not
checked for an announced action, and a line at Debug says why; a missing or zero `Usage` decides nothing.
- `IMentorActionCatalog.GetRegistrations()`: where the actions come from, one `MentorActionRegistration` per origin and
class — its `Origin`, its `Source` (the class), the actions it gives and what it left out (`Rejected`, by the rule's
name). `MentorActionOrigins` holds the codes, `attribute` and `fluent` today: an open list that later versions extend.
Every `MentorActionInfo` now names its `Origin` and its `RegistrationId`. The new member has a default
implementation, so a catalogue the application wrote itself compiles as before and returns none.
- `MentorActionInfo.Method`: the application's method an action runs, for the origins `attribute`, `fluent` and
`candidate`, to read its parameters and attributes; `null` for an endpoint declared as an action, whose parameters
are the route's, the query's and the body's, and for any other origin. It is left out of JSON.
- The pages in `GetRegistrations()`: after the registrations of the code, one per page that declared UI actions, of
the new origin `MentorActionOrigins.Page` (`page`), with `Id` `page:<page>` and the names its pages declared since
the application started, in every session. A page declares from the browser, so only names are kept, within the
limits of `MentorPageActionLimits` (64 actions per page, 200 pages, tool-shaped action names, page names of 1 to
128 characters without control or format characters); what goes beyond them is in `Rejected`. The new
`MentorActionRegistration.Revision` grows when a page changes, and is 0 for the registrations of the code. New
rules in ACTION-RULES.md: `page.gated`, `page.trace-names-only`, `page.union-since-start`, `page.name-shape`,
`page.limit`.
- Endpoints as actions (Novior.MentorAgent.Server): `app.MapPost("/orders/{id}/cancel", …).WithMentorAction(a =>
a.Describe("Cancels an order"))`, or `[MentorAction]` on a controller's action, makes the endpoint one of the
coordinator's actions without writing it again. The action runs the endpoint itself, in the process, as the user
of the turn: the endpoint's authorization first, then its filters, its binding and its validation. The model gives
the route values, the query values and one JSON body; an answer of 400 or more is a failed action, with its status.
`GET` and `HEAD` read; the other verbs write, and ask for a confirmation by default. The application's middleware
before routing (rate limiting, CORS) does not run for these calls. They are not published on `/mcp` nor on the A2A
card. `MentorActionOrigins.Endpoint` (`endpoint`) is their origin, and in `GetRegistrations()` each endpoint is a
registration of its own, named by its verb and route (`endpoint:POST /orders/{id:int}/cancel`). A declaration the
action cannot honour stops the application when it starts, naming the endpoint; the Server's README lists each
message and its fix. New rules in ACTION-RULES.md: `endpoint.declared`, `endpoint.authorization-first`,
`endpoint.runs-the-pipeline`, `endpoint.verb-default`, `endpoint.not-published`, `endpoint.trace`,
`scan.controllers-are-endpoints`.
- The AutoMentor's candidates: with `options.AutoMentor.Enabled` and the namespaces of the perimeter in
`options.AutoMentor.Namespaces`, the public methods of the services there become actions of the coordinator of the
new origin `MentorActionOrigins.Candidate` (`candidate`). A candidate starts off and asks for a confirmation: it is
offered to no model until an `IMentorActionGovernor` turns it on. `[MentorExclude]`, on a class or a method, keeps
it out. Nothing outside the perimeter becomes an action, whatever a governor says. `GetRegistrations()` lists one
registration per class, with its candidates and, in `Rejected`, the methods a rule left out. New rules in
ACTION-RULES.md, area `candidate`: `candidate.opt-in`, `candidate.in-perimeter`, `candidate.shape`,
`candidate.excluded`, `candidate.not-yet-an-action`, `candidate.di-resolvable`, `candidate.schema`, `candidate.name`,
`candidate.off-and-confirmed`, `candidate.never-outside`, `candidate.trace`. A candidate's description is the
`<summary>` of its XML documentation comment, from the `.xml` file next to its assembly
(`candidate.described-by-xml`), and its roles are those of its `[Authorize(Roles = …)]`
(`candidate.roles-from-authorize`). README: «Candidates from your services».
- An endpoint's action takes its roles from the endpoint's authorization: `[Authorize(Roles = …)]`, `RequireRole`, a
policy by name, the fallback policy. It is offered only to a user who holds one of them, and a user without them is
refused before any confirmation; roles declared on the action replace them. Roles asked together give none, with a
line in the log, and the endpoint still refuses the call. A policy named and not registered stops the application
when it starts, naming the endpoint. New rule in ACTION-RULES.md: `endpoint.roles-from-authorization`.
- `MentorPreferredSkillsSource`: wrap an `AgentSkillsSource` in it, in `SkillSources`, and its skills replace the
application's own of the same name, and the other sources', with a log line naming each; the console of an
integration that manages the assistant's skills is the case. Without it nothing changes: the application's skills
win, then the first source registered. New rule in ACTION-RULES.md, area `skill`: `skill.name-precedence`.
- `MentorLiveSkillsSource`: wrap an `AgentSkillsSource` in it, in `SkillSources`, and `SkillsRefreshInterval` never
caches it: it is asked at every session, so a skill it withdraws is gone for the next one, while the other sources
keep their cache. With an interval each source is now cached on its own rather than the whole list. Without an
interval nothing changes. New rule in ACTION-RULES.md, area `skill`: `skill.live-source`.
- **Novior.MentorAgent.Declarative:** teams in YAML. Every `*.team.yaml` file of the folder (`TeamSearchPattern`)
and every `TeamDefinitions` entry gives a team, with the fields of `MentorTeamDefinition`, checked as any
`IMentorTeamSource`'s is. A file that does not hold is left out with `invalid-definition` and the line and column
of the fault; an unknown key or a key written twice is a fault. A team file is never read as an agent, even by a
wider `SearchPattern`. New rule in ACTION-RULES.md: `team.from-yaml`.
- **Novior.MentorAgent.Declarative** now depends on **YamlDotNet 18.1.0** (MIT), which reads the team files. An
application that gets an older YamlDotNet through another package moves to 18.1.0 with this version; one that
references an older version itself gets NuGet's downgrade error (NU1605) until it references 18.1.0 or later. If
your code uses YamlDotNet, read its release notes for the versions in between.
- Teams from a source: an `IMentorTeamSource` (`AddMentorTeamSource<T>()`) gives teams that are not written in C#,
as `MentorTeamDefinition`s with the fields of `[MentorTeam]` and `[TeamMember]`, a member's tools named as the
session's actions, and an `Approver`, the member whose verdict ends the discussion. It is asked each time a
coordinator is built, and its teams join it as the ones written in C# do. What does not hold is left out with its
reason, reported to `IMentorAgentSourceObserver.OnTeamsLoaded` (a new method with an empty default) and in the log;
new reason codes `name-taken` and `no-members`. A member's tools, of a source's team or of one written in C#, may be
writes: each keeps its roles and its confirmation, through the gate once. New rules in ACTION-RULES.md, area `team`:
`team.from-source`, `team.member-tools`, `team.approver`, `team.rejected-with-reason`.
- `MentorActionDecision.TenantId`: the tenant of the call, the one the `IMentorTenantResolver` resolved for the turn or,
on the MCP server, for the request; `null` without a resolver. An observer of several tenants now tells the same user
in two of them apart.
### Changed
- `CheckAnnouncedActions` also checks a turn that called tools. A model could read a record and then write that it
had taken it in charge without calling the tool that does it; the check skipped every turn with a call, so it did
not see it. Now the question also names the tools the turn called, and only an action none of them did counts: a
reply that reports what they did or returned, or the state of the records they read, is not one. The second request
then says that this action did not run. A turn that handed the request to a specialist, a team or a remote agent,
used a hosted tool or waits for an approval is still not checked. The cost, measured on gpt-4.1 over 18 turns that
read records, with the question on the main deployment: one more call of about 440 tokens (386 to 643) in each turn
with a call, 0.5 to 0.7 s while the provider answered in its usual time, after the reply has reached the user; no
reply was flagged by mistake.
- The support policy is the one of 1.3.1 (see its section below): only the latest minor version gets fixes, and the
security fixes promised for earlier minor versions are withdrawn.
- Every package is now checked at pack time against the public API of 1.3.1, so 1.4.0 cannot break code built
against 1.3.1 by accident. An intended break is listed in this file as Breaking.
- `ScanAssemblies` no longer reads controllers (`scan.controllers-are-endpoints`). A `[MentorAction]` on a
controller's action used to become an action that called the method on an instance from the container, past the
endpoint's `[Authorize]` and filters, and failed when the controller was not registered as a service. It is now
read from the controller's endpoint and runs the endpoint, with `AddMentorAgentServer()`. Which classes are
controllers is read from the attributes' metadata, without creating them: an attribute of the application whose
constructor throws, or whose type does not load, does not stop it (`scan.attributes-not-created`).
- The `dotnet new` template in the repository, `templates/mentoragent-blazor`, creates its project on
Novior.MentorAgent 1.4.0.
- On Path A the coordinator calls a page's UI actions through the gate, like every other action: the action policies
and their before-action hook are asked about them, `IMentorActionObserver` receives their decisions (with the
action's description as `DisplayName`), they get a span and Stop reaches them. Up to 1.3.0 they ran in a loop of
their own below the agent, which none of these saw. A UI action still asks for no confirmation and needs no role of
its own, and the widget shows its start and end as before; a policy that decides about every tool now decides about
UI actions too. After `navigate_to` the next request of the same turn offers the actions of the page now shown. A
model that keeps calling UI actions is stopped by the run's cap, as for the application's own actions: 40 calls in a
turn, the default `MaximumIterationsPerRequest` of the agent's function-invoking client, which MentorAgent does not
change and offers no option for; up to 1.3.0 the loop of the UI actions stopped at 10.
- `MentorActionRequest.Kind` and `MentorActionDecision.Kind` (`MentorActionKind.Server` or `UI`), and
`MentorActionDecision.PageName`: a policy and an observer tell a UI action from an action of the application, and
know the page. A UI action with the name of an action of the application that is off is the page's: that action's
roles, confirmation and governor do not apply to it. New rule in ACTION-RULES.md: `page.kind`.
- The action policies decide whether a page's UI action is offered, as for the application's actions: one
`IsAllowedAsync` does not allow at `Offer` is left out of the turn's requests, the actions of a page `navigate_to`
opens during the turn included — asked about with the page's name, even when its actions have the names of the
page left — and a call to it anyway is refused at the gate. One left out stays out for the rest of the turn. New
rule in ACTION-RULES.md: `page.offered`.
- What the action policies decide about the offer since 1.3.1 (see its section) is a rule in ACTION-RULES.md:
`policy.offered-to-agents`. Every agent of the turn is offered only the application's actions the policies allow,
a member of a team read from a `*.team.yaml` file as one written in C#, and a call to one left out is refused at
the gate as `not-offered`.
### Fixed
- After a navigation the next request of the turn no longer offers the UI actions of the page being left
(BUG-234). Blazor disposes that page only after the next one has initialized, and `navigate_to` does not wait for
a page without UI actions, so the request after `navigate_to`, or after an action whose `NavigateTo` opens another
page, still offered them, and a call to one ran its handler on a page going away. They are now taken back before
the navigation is asked for, in a turn with a Blazor circuit; over the hub, SSE and A2A the page's actions still
come with the client's snapshot. New rule in ACTION-RULES.md: `page.left-not-offered`.
The full history is in CHANGELOG.md, inside this package.