D4S.Agent 1.1.5

D4S.Agent

Reusable Microsoft Agent Framework implementation for Microsoft 365 / Teams bots. Add one DI call, depend on IMafAgent, and the package owns the agent turn, guardrail, middlewares, tools, and prompt composition — your host keeps only auth, storage, and bot wiring.

Features

• Single-call setup — AddMafAgent(configuration) wires chat clients, middlewares, plugins, guardrail, and MCP tools.
• Agent turn — InvokeAgentAsync with session persistence; returns text or an Adaptive Card.
• Topic guardrail — off-topic messages get a polite redirect, no main-model call.
• Middlewares — thinking-UX labels, audit logging, loop cap, Teams keep-alive heartbeat.
• Citations — retrieval sources are captured from tool results and appended as a short source list.
• Tools — built-in Adaptive Card tool, host-contributed tools, and MCP server tools.
• Prompt composer — one folder per customer under Prompts/<customer> (base always-on generic + specific always-on customer prompts and on-demand tool/MCP instructions files), selected via Bot:PromptsFolder.

Install

dotnet add package D4S.Agent

Quick start

Register everything the agent needs in one call:

builder.Services.AddMafAgent(builder.Configuration);

Depend on IMafAgent from your bot and render its response:

var response = await _agent.InvokeAgentAsync(turnContext, turnState, cancellationToken);
// response.ContentType ∈ { Text, AdaptiveCard }; response.Content is the payload.

Your host must:

• provide the MicrosoftFoundry config — a valid Endpoint is required at startup;
• set Bot:PromptsFolder to a customer folder name under Prompts/ (e.g. Customer1);
• copy that customer's Prompts/<customer>/base/*.md and Prompts/<customer>/specific/*.md to its output directory — the composer reads them from AppContext.BaseDirectory (plus Skills/ when Bot:AgentSkillsEnabled is on).

Configuration

Citation tool contract

For each tool listed in Citations:ToolNames, the citation middleware reads a citations collection from the result root or from the MCP structuredContent object. Every item can contain title, sourceUrl, and score; at least title or sourceUrl must be present. A #page=N fragment in sourceUrl is displayed as the source page, and score controls source ordering.

Sources are deduplicated on sourceUrl, falling back to title when there is no URL, and the entry kept is always the highest-scoring one. Citations:CollapseByDocument decides how much the key covers:

• false (the default) — the whole URL, fragment included, so a retrieval that projects page anchors lists the same document once per cited page. On a long document that is the useful shape: the reader gets the sections that answered the question, not one link to the document.
• true — the URL without its fragment, so a document is listed once, at the page it ranked best.

Turning it on is also the way to shorten the list for ask, whose citations the retrieval side never collapses — one per [ref_id:N] reference by design.

The D4S Knowledge Retrieval MCP conforms to this contract for both search and ask. Its search response still contains passages for grounding and compatibility, but the Agent reads citations only from the common citations collection.

Architecture

MafAgent is a thin orchestrator. Each turn it delegates to three focused services, every one behind an interface and registered as a replaceable default:

The whole turn loop itself is IMafAgent (default MafAgent).

MafAgent is transient, so all three are built on every turn. That is why ITopicGuard resolves to NoOpTopicGuard while Bot:TopicGuardEnabled is false: registering the classifying implementation would construct its keyed chat client — and demand a guardrail deployment — for a bot that never classifies anything.

Extending

AddMafAgent returns a MafAgentBuilder, so overrides chain off it. Each WithCustomXxx replaces the matching default registration, so call order doesn't matter and your implementation always wins.

• Add a tool (code): AddMafAgent(config, o => o.AdditionalTools.Add(new AgentTool(sp => AIFunctionFactory.Create(...), InstructionsFile: "my-tool.md"))). The optional .md (shipped in the customer's Prompts/<customer>/specific folder) is appended to the instructions on demand.

• Add MCP servers (config): list them under Mcp:Servers (Http or Stdio). An optional Tools allow-list selects a subset; unreachable servers are logged and skipped (fail-soft).

• Replace a single concern: chain the matching builder method, passing your implementation of that seam's interface:

  builder.Services
      .AddMafAgent(builder.Configuration)
      .WithCustomAgentBuilder<MyAgentBuilder>()   // IAgentBuilder — instruction/tool/middleware composition
      .WithCustomMcpToolkit<MyMcpToolkit>()       // IMcpToolkit  — MCP discovery + disposal
      .WithCustomTopicGuard<MyTopicGuard>();      // ITopicGuard  — classification, redirect, history
  

• Replace the whole turn loop: .WithCustomAgent<MyAgent>() with your own IMafAgent — the heaviest seam; use only for a fundamentally different flow.

Requirements

• net10.0
• Key dependencies: Microsoft.Agents.AI, Microsoft.Extensions.AI(.OpenAI), Microsoft.Agents.Builder, Azure.AI.OpenAI, ModelContextProtocol.