A2A server

Use this page to let other AI agents find your .NET agent and call it with the Agent-to-Agent (A2A) protocol. The A2A server publishes an agent card, a JSON document that describes your agent, at /.well-known/agent-card.json. Other agents send their requests, called tasks, to /a2a. MentorAgent runs each task as a full turn, with your model and your actions.

Choose it when another program should send questions to your agent in natural language: another MentorAgent host, any other A2A agent, or an orchestrator (a program that splits a job among several agents).

• The whole agent, not single methods. A task goes through your model, prompt, specialists, teams and documents, and costs a turn on your model. To publish single methods for a client whose own model chooses, see Model Context Protocol (MCP) server.

• Answers come from tools. The caller is a program that cannot tell a looked-up figure from an invented one. So on a task:

  1. MentorAgent tells the model to call a tool first and to state only what a tool returned.
  2. If the reply uses no tool that returns data, MentorAgent discards it and asks the model again, this time requiring a tool call. A navigation, a UI action, a memory write and a MentorAgent skill do not count as such a tool.
  3. If the second reply returns no data either, the classifier model judges whether it states something about your records, such as a figure or that an entry does not exist. If it does, the caller gets NOT GROUNDED: … instead.

  A reply that states no data, such as a policy read from a MentorAgent skill or your documents, is returned as it is.

• One reply per task. The caller gets the complete reply in one message when the turn ends, not a stream of tokens. A turn that produces no reply closes the task as failed.

• No forwarding. A task that arrives over A2A is never passed on to the remote agents of this host. So two hosts can call each other without an endless loop. A chain of three MentorAgent hosts does not work: point the first host directly at the third one.

Any kind of host can serve tasks, such as a Blazor Server app or a backend. To call other A2A agents from your agent, see MCP and A2A clients.

dotnet add package Novior.MentorAgent.Server

<ItemGroup>
  <PackageReference Include="Novior.MentorAgent.Server" Version="1.2.0" />
</ItemGroup>

<ItemGroup>
  <PackageVersion Include="Novior.MentorAgent.Server" Version="1.2.0" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="Novior.MentorAgent.Server" />
</ItemGroup>

#:package Novior.MentorAgent.Server@1.2.0

Novior.MentorAgent.Server brings Novior.MentorAgent and the A2A SDK for ASP.NET Core (1.0.0-preview3) with it. Add it to a Blazor Server app too: you do not need the hub for A2A. Neither package includes a model provider package. The code on this page uses OpenAI, so add its package too:

dotnet add package Microsoft.Extensions.AI.OpenAI --version 10.6.0

For another provider, see Model providers.

1. Keep the model key out of the source code:

   Terminal

   dotnet user-secrets init
   dotnet user-secrets set OpenAI:Key <your-key>

2. Write the actions as usual. These are the same three as on the MCP server page:

   CaseTools.cs

   public class CaseTools(ICaseStore store, ICaseQueue queue)
   {
       // For every caller. ReadOnly: MCP clients are told that it only reads
       [MentorAction(
           Description = "Gets the status of a support case",
           ReadOnly = true)]
       public Task<string> GetCaseStatus(string caseNumber)
           => store.GetStatusAsync(caseNumber);
   
       // Needs a signed-in user with the role
       [MentorAction(
           Description = "Lists the open cases assigned to a team",
           RequiredRoles = ["Supervisors"],
           ReadOnly = true)]
       public Task<IReadOnlyList<string>> ListTeamCases(string team)
           => queue.ListOpenCasesAsync(team);
   
       // Needs a person to confirm it
       [MentorAction(
           Description = "Closes a support case with a resolution",
           RequiresConfirmation = true)]
       public Task CloseCase(string caseNumber, string resolution)
           => store.CloseAsync(caseNumber, resolution);
   }

3. Turn the server on, register it and map the endpoints in Program.cs:

   Program.cs

   // AddMentorAgent, AddMentorAgentA2A, MapMentorAgentA2A
   using Novior.MentorAgent.Extensions;
   using Novior.MentorAgent.Models;   // AgentCardInfo
   using Microsoft.Extensions.AI;     // AsIChatClient
   using OpenAI;                      // OpenAIClient

   Program.cs

   builder.Services.AddScoped<CaseTools>();
   
   builder.Services.AddMentorAgent(options =>
   {
       options.AppName = "Case management"; // the agent card's name
       options.AppDescription =
           "Support case management: case status, notes and closure";
       options.ChatClient = new OpenAIClient(
               builder.Configuration["OpenAI:Key"]
               ?? throw new InvalidOperationException(
                   "Set OpenAI:Key with dotnet user-secrets."))
           .GetChatClient("gpt-4o-mini")
           .AsIChatClient();
       options.ScanAssemblies = [typeof(Program).Assembly];
       options.A2AServerEnabled = true;
   });
   
   // Novior.MentorAgent.Server: registers the A2A agent
   // (AddMentorAgentServer() calls it too)
   builder.Services.AddMentorAgentA2A();
   // after var app = builder.Build();
   app.MapMentorAgentA2A();   // POST /a2a and GET /.well-known/agent-card.json

   AddMentorAgentA2A() registers the A2A agent when A2AServerEnabled is on. Call it after AddMentorAgent(). AddMentorAgentServer() calls it for you. MentorAgent reads A2AServerEnabled when AddMentorAgent runs, so set it in that callback.

Run the app and open /.well-known/agent-card.json. The card lists A2A skills: entries that tell callers what your agent can do. An A2A skill is not a MentorAgent skill. The card has:

• your AppName and AppDescription;
• one A2A skill for each tool name, here get_case_status. The skills come from the actions of classes registered in dependency injection that have no role and do not ask for confirmation. If another action with the same name has a role or asks for confirmation, the name is left out;
• the task endpoint, which uses JSON-RPC;
• text as input and output, and the streaming capability.

The card says that streaming is supported, but a reply still arrives as one message when the turn ends.

A caller that cancels a task, with tasks/cancel, stops its turn as Stop does: no action starts after it, and the task ends Canceled.

The card still shows only the path /a2a. An agent on another host needs the full URL: the complete configuration sets it.

Set the public URL of the task endpoint in the configuration of each environment:

{
  "A2A": {
    "PublicUrl": "https://cases.example.com/a2a"
  }
}

Then describe the card, require authentication and limit each calling agent:

builder.Services.AddScoped<CaseTools>();

builder.Services.AddMentorAgent(options =>
{
    options.AppName = "Case management";
    options.AppDescription =
        "Support case management: case status, notes and closure";
    options.ChatClient = new OpenAIClient(
            builder.Configuration["OpenAI:Key"]
            ?? throw new InvalidOperationException(
                "Set OpenAI:Key with dotnet user-secrets."))
        .GetChatClient("gpt-4o-mini")
        .AsIChatClient();
    options.ScanAssemblies = [typeof(Program).Assembly];

    options.A2AServerEnabled = true;
    // The public URL of the task endpoint, path included:
    // the card publishes it as it is
    options.A2AServerUrl = builder.Configuration["A2A:PublicUrl"];
    options.AgentCard = new AgentCardInfo
    {
        Version = "1.2.0",
        Provider = "Support operations",
        DocumentationUrl = "https://cases.example.com/docs/agent",
    };

    // Every task is a full turn with the model: a limit per calling agent
    options.RateLimitPerUser = 30;
});

// Registers the agent, and passes the authenticated caller
// of each task to MentorAgent,
// for RequiredRoles and RateLimitPerUser
builder.Services.AddMentorAgentA2A();

// Plus your authentication scheme for the calling agents:
// builder.Services.AddAuthentication()...
// after var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
// The task endpoint and the card
app.MapMentorAgentA2A(configure: e => e.RequireAuthorization());

• A2AServerUrl is the full public URL of the task endpoint, path included, and the card publishes it as it is. If you map the endpoint elsewhere, with MapMentorAgentA2A("/agent") or A2AServerPath, the URL must end with that path.
• AgentCard fills the card's version, provider, icon and documentation URL. Tags is not published: the A2A card has no field for it.
• The configure parameter of MapMentorAgentA2A applies to both endpoints: the task handler and the card. A MentorAgent caller sends its credentials in the Headers of its RemoteAgents entry, with the card request and with every task.
• AddMentorAgentA2A() registers the agent, and passes the authenticated caller of /a2a to MentorAgent, in any host: a backend or a Blazor Server app. RequiredRoles and RateLimitPerUser then work for the calling agent. AddMentorAgentServer() calls it for you.

Every option is in Configuration options, and the A2A ones under A2A.

A task comes from a program: nobody on the other side can answer a confirmation. The card and the task follow the same rules:

• Writes ask by default. Which declarations ask, and so stay off the card, is in Every declaration, on every channel. A write that declares RequiresConfirmation = false, or a method with only [Description], is on the card and runs for every caller. Mark a method that changes data with [MentorAction].
• How MentorAgent knows the caller.
  • The MCP server asks your McpCallerPrincipal.
  • The A2A server reads the user of the request, in every host. A Blazor Server app is included. MentorAgent reads that user before it asks Blazor's own AuthenticationStateProvider, which works only inside a circuit.
  • To add claims or roles for a task, see Secure the endpoints.
  • A task whose caller is not authenticated is anonymous, and its role-gated actions are refused.
• The endpoints are open until you protect them. /a2a runs a paid turn for whoever reaches it, and the card describes your application to anyone. Secure the endpoints protects them together with the others.
• Access is decided here, not by the caller. A MentorAgent host that lists your agent in its RemoteAgents does not check roles before it sends you a request: any of its users can reach you. What a task may do depends on the authentication on /a2a and on the roles of your actions.
• Each task starts with no history. A task runs in its own dependency injection scope, a set of services created for that task only. It has a new coordinator and a new conversation: nothing carries over from earlier tasks. It has no browser, no current page and no UI actions.
• Per-record checks are your code, in your methods or in an action policy, as on every channel: see What stays in your code.

How the other channels handle confirmations is in Where nobody can answer.

• The app stops at startup with "Cannot map A2A endpoint: A2AServerEnabled is false". Set options.A2AServerEnabled = true in AddMentorAgent, or remove the call.
• The app stops at startup with "Cannot map the A2A endpoint: the A2A server is not registered". Nothing registered the agent. Call AddMentorAgentA2A() after AddMentorAgent(), or call AddMentorAgentServer().
• The app stops at startup with "A2AServerEnabled is true, but AddMentorAgentA2A() ran before AddMentorAgent()". Call AddMentorAgentA2A() after AddMentorAgent().
• The app stops at startup with "A2AServerEnabled is true, but it was false when AddMentorAgent() read it". Set A2AServerEnabled in the AddMentorAgent callback. A later Configure<MentorOptions> or a configuration binding comes too late. See Troubleshooting.
• The build does not find AddMentorAgentA2A or MapMentorAgentA2A. Both methods are in the Novior.MentorAgent.Server package. Add it to the project.
• A calling agent fails before it sends anything, or sends tasks to the wrong address. A2AServerUrl is not set, or it does not include the path of the endpoint. The card then carries only the path. A MentorAgent caller resolves the path against your host, but other clients, such as the A2A SDK, cannot. On Windows they fail with UriFormatException. On Linux and macOS they read the path as a file: URI, which an HTTP client refuses.
• The card lists no A2A skills. There are four possible causes:
  • Every action has roles or asks for confirmation. A [MentorAction] that declares nothing asks by default: see Every declaration, on every channel.
  • The class has [MentorAgent], or it is the toolbox of a team member.
  • The assembly of the class is not in ScanAssemblies.
  • The class is not registered in dependency injection.
• The caller receives "NOT GROUNDED: …". Two attempts ended without a tool that returns data, and the reply stated something about your records. Give the agent an action that returns that data.
• The task fails with "this agent could not produce a reply to the request". The turn produced no text. The cause is in your log, just before the warning about the task.
• A role-gated action is refused for a caller that holds the role. MentorAgent sees an anonymous caller. Require authentication on the endpoint with configure: e => e.RequireAuthorization(), call UseAuthentication() and UseAuthorization() before the map call, and check that the roles are in the claim that the identity names as its RoleClaimType.
• The caller gets 401 on the card. configure protects the card as well as the task endpoint: the caller must send its credentials for both.