MentorAgent Docs
Menu

ConceptPackage: Novior.MentorAgent

How methods become actions

The rules by which MentorAgent turns your methods into actions, names them, turns them on or off, adds up roles and confirmations, and publishes them.

View as Markdown
On this page

MentorAgent reads your classes at startup and decides which methods become actions: the methods that the model may call. The same rules decide six more things about each action: what it is called, which agent it belongs to, whether it is on, when it asks for confirmation, who may run it, and where it is published. This page gives the rules of the actions that your classes declare, each with its name. The areas that 1.4.0 adds, for actions registered in code (fluent), endpoints (endpoint), candidates (candidate), the actions of pages (page), teams from a source or a file (team) and skill sources (skill), are in ACTION-RULES.md with their tests, and their notes are in MentorAgent 1.4.0.

The rules are those of ACTION-RULES.md in the MentorAgent repository (external site). Each rule has a name that never changes and at least one test in the library that fails if the library stops following it. A rule that comes in, changes or is retired is named in the release notes of its version, and a retired name is never used again. The rules on this page are those of MentorAgent 1.4.0.

CaseService.cs
public class TicketService
{
    // An action: public, instance, declared here, with [MentorAction]
    // (scan.marker). The tool is close_ticket (name.snake-case)
    [MentorAction(Description = "Closes a support ticket",
        RequiresConfirmation = true)]
    public Task<string> CloseTicketAsync(string ticket) =>
        Task.FromResult($"Ticket {ticket} closed.");

    // An action too: a [Description] with a text, and no rules
    [Description("Gets the status of a support ticket")]
    public string GetTicketStatus(string ticket) => "Open";

    // Not actions: static, private, or with no marker
    [MentorAction(Description = "Never an action: static")]
    public static string Count() => "3";

    [MentorAction(Description = "Never an action: private")]
    private string Purge() => "Purged.";

    public string Format(string ticket) => $"#{ticket}";

    // Off until a governor turns it on (enabled.off-by-default)
    [MentorAction(Description = "Archives a ticket", Enabled = false,
        RequiresConfirmation = true)]
    public string ArchiveTicket(string ticket) => $"Ticket {ticket} archived.";
}

public class SupportTicketService : TicketService
{
    // Not an action here: GetTicketStatus is inherited, so it is
    // an action of TicketService only (scan.public-instance-declared)
}
RuleWhat it says
scan.assemblies-onceEach assembly in ScanAssemblies is read once. An assembly listed twice is read once, with a warning that names it.
scan.concrete-classesOnly classes that are not abstract are read. Abstract classes, structs and interfaces give no action.
scan.public-instance-declaredOnly public instance methods declared on the class itself become actions. Static, internal, protected and private methods do not. A method that the class inherits is an action of its base class only.
scan.markerA method becomes an action with [MentorAction], whatever its description, or with a [Description] whose text is not blank. With neither, it is not an action.
scan.mentor-action-winsOn a method with both [MentorAction] and [Description], [MentorAction] decides: its description, its confirmation and its roles.
scan.override-keeps-actionAn override of an action is an action of the class that overrides it, with what the base method declares. Class attributes such as [MentorAgent], [MentorTeam] and [MentorPage] do not pass to a derived class.
scan.controllers-are-endpointsSince 1.4.0, a controller is not read: a class that derives from ControllerBase, or carries [Controller] or [ApiController], and not [NonController]. A [MentorAction] on a controller's action is read from its endpoint, with AddMentorAgentServer(), where its authorization and filters run. Up to 1.3.1, the action called the method on an instance from the container.
scan.attributes-not-createdSince 1.4.0, the scan creates none of your attributes: it reads which classes are controllers from the metadata of their attributes, so an attribute whose constructor throws does not stop the application. A class whose attributes name a type that does not load is skipped, with a warning that names it.

The class must also be registered in dependency injection: a method of a class that the container cannot create is left out, with a warning at every new conversation.

RuleWhat it says
kind.one-per-classA class has one kind only. MentorAgent picks the first kind that applies, in this order: [MentorTeam], then [MentorAgent], then [MentorSkill], then a plain class. The methods of a plain class are the coordinator's actions.
kind.page-is-separate[MentorPage] records the page, and does not change the kind of the class. Its methods follow the other rules.
kind.agent-owns-methodsThe methods of a [MentorAgent] class are the actions of that specialist, not the coordinator's.
kind.skill-methods-level1The methods of a [MentorSkill] class are the coordinator's actions, registered once. A skill with no methods gives none.
kind.team-needs-membersA [MentorTeam] class with no [TeamMember] property is left out, with a warning.
kind.member-tools-leave-level1A class listed in [TeamMember(Tools = …)] is that member's toolbox. Its methods are not the coordinator's actions, and neither the Model Context Protocol (MCP) server nor the Agent-to-Agent (A2A) card publishes them. A [MentorSkill] class keeps its methods as the coordinator's actions.
kind.member-tools-same-rulesA member's tool classes follow the scan.* rules, and each tool keeps what its attribute declares.

The levels are explained in The three agent levels.

RuleWhat it says
name.snake-caseAn action is named after its method. A trailing Async, with this exact case, is dropped. Then the name becomes snake case: every capital letter starts a new word, spaces and dashes become underscores, and digits stay.
name.team-toolA team is offered to the coordinator as one tool, named after the team's Name by the same rule.
name.shared-warnedTwo methods with the same action name, compared without regard to case, are named in a warning at startup. One method found twice is not two.
name.called-method-decidesWhen methods share a name, the roles, the confirmation, its text and the page to open are those of the method that the call runs.
Method or teamTool name
CloseCaseAsyncclose_case
GetHTTPStatusget_h_t_t_p_status
Export2Csvexport2_csv
A team named Business Analysis Teambusiness_analysis_team

Options that name tools, such as RequiresApproval and IsReadOnlyAction, use these names. A name shared by two methods is in Common errors.

RuleWhat it says
enabled.off-by-defaultAn action declared [MentorAction(Enabled = false)] is in the catalog, with EnabledByDefault set to false, and nowhere else. It is offered to no agent, described to no model, and not published on the MCP server or on the A2A card. A call to it does not run, until an IMentorActionGovernor turns it on.
enabled.external-decidesWith an IMentorActionGovernor registered, its answer turns an action on or off, and null keeps what the code says. MentorAgent asks the governor when a session builds its tools, on every tools/list of the MCP server, and before every call. A session keeps the tools that it was built with, and MentorAgent refuses a call to an action that was turned off after that. A governor that throws, or does not answer in time, stops the action. An application can register only one governor.

The governor is explained in Turn actions on and off from outside the code.

A confirmation is asked only when RequireConfirmation is on and at least one source wants it: what the action declares, the default for writes, or RequiresApproval. With a governor, its answer takes the place of these sources.

RuleWhat it says
confirm.declared-decidesAn action whose attribute sets RequiresConfirmation to true or false gets what it declares.
confirm.default-for-writesA [MentorAction] that does not set RequiresConfirmation asks for confirmation when RequireConfirmationForWrites is on, which it is by default. It does not ask if the action only reads: ReadOnly = true, or IsReadOnlyAction says so.
confirm.description-only-not-defaultedA method marked with [Description] alone never asks for confirmation by default. The startup warning lists it among the writes that run without confirmation.
confirm.predicate-addsWhen RequiresApproval returns true for an action's name, the action asks for confirmation, and the predicate is asked again at every call. Returning false never takes away a confirmation that the action declares. The governor can take away both.
confirm.master-switchWith RequireConfirmation off, no action of the application asks for confirmation, whatever it declares. The approval that a hosted MCP server asks for comes from the provider and is still shown.
confirm.beats-read-onlyAn action that asks for confirmation is not read-only, whatever ReadOnly or IsReadOnlyAction say.
confirm.unconfirmed-writes-warnedAt startup a warning names the writes that run without confirmation, in two lists: the [MentorAction] methods that opt out, and the methods marked with [Description] alone.
confirm.external-decidesWith a governor, its answer decides whether a call is confirmed. Required asks even if the code does not. None does not ask even if the code does. Code keeps what the code says. A confirmation that the governor adds applies from the next call, and a confirmation that it takes away applies from the next session. The governor does not take away the Confirm of an action policy or the approval of a hosted MCP server. An action whose confirmation is taken away still counts as an action that changes data.

What each declaration does on every channel is in the table Every declaration, on every channel.

Roles and confirmation both apply, and roles come first: a user without the role is refused before anyone is asked to confirm.

RuleWhat it says
roles.any-ofAn action with RequiredRoles runs for a user who holds any one of them, checked with ClaimsPrincipal.IsInRole. Role names are case-sensitive. With no roles there is no check.
roles.signed-inAn action with RequiredRoles needs a signed-in user. Without an AuthenticationStateProvider, or with nobody signed in, it is refused.
roles.checked-before-confirmationMentorAgent checks roles before the confirmation, so a user without the role is never asked to confirm. It checks the roles again when the confirmation comes back. Turning confirmations off does not turn the role check off.
roles.offered-when-allowedThe model is offered only the actions that the user's roles allow, at every level. An action left out is still refused if it is called.
roles.external-replaceWith a governor, the roles that it gives an action replace the code's: null keeps the code's, and an empty list requires none. They decide what is offered, every call, and which MCP callers see and call the action.

How the roles of your sign-in reach RequiredRoles is in Roles from your sign-in.

RuleWhat it says
describe.external-replaceWith a governor, the description that it gives an action replaces the description in the code in everything that a model reads. This covers the tools of every agent, the texts that tool filtering ranks, and the tools/list of the MCP server. The action's name and arguments never change. What the user sees keeps the description in the code: the confirmation box and the bar of the running action. The A2A card, the catalog and the onboarding tour follow the code.
RuleWhat it says
declarative.functions-matchA kind: function entry of a definition reaches its agent only if the session has an action of that name. A name that the application does not have, or an action that is off for the session, is taken away with a warning, and the agent loads without it.
declarative.no-hosted-toolsA definition cannot add a tool of its own. webSearch, codeInterpreter, fileSearch and mcp entries are taken away with a warning, and the agent loads with the application's own tools. If they cannot be taken away, the agent is not loaded.

Agents in YAML are explained in The three agent levels.

RuleWhat it says
surface.coordinator-onlyThe MCP server and the A2A card publish only the coordinator's actions, never a specialist's or a team member's.
surface.mcp-withholds-gatedThe MCP server does not publish an action that asks for confirmation, unless a governor takes the confirmation away. An action with roles is published only with McpCallerPrincipal, and only to the callers who hold one of its roles. An action that is off is not published, unless the governor turns it on.
surface.card-ungated-onlyThe A2A card lists only the coordinator's actions that ask for no confirmation, need no role, and whose class the container can create. A name that two actions share is left off when either of them is gated. The card follows the code only.
surface.governor-sessionThe governor is asked with the session's id on every channel, the same id that the gate's decisions carry. On the MCP server it is a fingerprint of the MCP session.

The MCP server and the A2A server pages show how to publish your actions.

  • Roles, confirmation and governance — Role checks and human-in-the-loop approval for AI agent tools in .NET, enforced in code on every channel and not in the prompt, and what stays in your code.
  • The three agent levels — Actions, specialists and teams: how the three levels of MentorAgent map to Agent Framework, and when to use each one.
  • Attributes — The parameters of MentorAction, MentorAgent, MentorTeam, TeamMember, MentorPage, MentorSkill and MentorExclude, with their defaults and rules.
  • Troubleshooting — Fix common problems with MentorAgent: startup errors, blocked requests, roles, confirmation, local models. And where to get help or report a bug.