D4S.Agent 1.1.0

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

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

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.