MentorAgent.Declarative 1.0.0-rc.6

MentorAgent.Declarative

Preview Release — MentorAgent is currently in public preview. APIs may change before the stable release.

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

Table of Contents

• What it does
• Getting started
• The YAML format
  • Two format details that cost an afternoon
• 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
  • ConfigurationSection — exposing configuration to a definition
• 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("ShippingAgent", "Answers questions about deliveries")]
public class ShippingAgent
{
    [MentorAction("get_tracking", "Looks up a tracking number")]
    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 MentorAgent.Declarative

Registration

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 the coordinator, which happens on the first message.

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 at startup you get a warning naming the resolved path — 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:

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. Accepted values are codeInterpreter, fileSearch, function, webSearch and mcp; function is the one that binds to a tool of your application. Omit it and loading fails with NotSupportedException — not a validation message naming the line.

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 a tool your application already exposes — a [MentorAction] method, or any other Level-1 tool.

tools:
  - kind: function              # required — see below
    name: get_order_status      # must exist; a typo simply means the agent never gets that tool

The tool name is the snake_case of the C# member, with a trailing Async dropped: GetOrderStatusAsync() → get_order_status. Get it wrong and nothing tells you — the agent simply starts without that tool and then improvises an answer it has no data for.

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
• 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.

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. 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#

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.
        """);
});

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

public sealed class DatabaseAgentSource : IMentorAgentSource
{
    public async Task<IReadOnlyList<AIAgent>> GetAgentsAsync(
        MentorAgentSourceContext context, CancellationToken ct = default)
    {
        // context.ChatClient — the coordinator's client, so usage lands in the metrics
        // context.Tools      — the Level-1 tools, already gated
        …
    }
}

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

Configuration options

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
});

Files are loaded 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 named after the keys — SupportEmail, MaxRefund. 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.

Name a section. Never hand over the whole IConfiguration. The factory loads whatever configuration it is given into the Power Fx engine as variables — one per key, in its constructor. Every key must therefore be a valid Power Fx identifier, and a single one that is not takes the entire factory down before any definition is read. This is not hypothetical: a key literally named ${name}, 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:

[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. The log should show, at Information level:

   [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.
5. Negative check — the gate holds. Name a tool carrying RequiredRoles in the YAML and ask the agent to use it while unauthenticated. It must be refused, the same way a C# specialist is, and no action taken.

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 MentorAgent core package. Installing this one is an explicit decision to pay it.

The reference is pinned to the 1.6.1 line, matching Microsoft.Agents.AI in the core package, so adding it does not move the rest of the library onto a different Agent Framework version.

Requirements

• .NET 10
• MentorAgent (or 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

Related Packages

License

MIT — the full text ships in the repository's LICENSE file.