UtilityAi.Maf 1.6.5

🧠 UtilityAI Framework (.NET 8)

👁 NuGet
👁 .NET 8
👁 Coverage

A lightweight, modular .NET 8 framework for building AI agent orchestration systems using classic Utility AI decision-making patterns. The framework evaluates and scores candidate actions each tick, executing the highest-utility option based on current context — no hardcoded workflows required.

Don't script workflows — evaluate them.

Table of Contents

• The Concept: Utility AI
• Features
• Quick Start
• Architecture Overview
• Core Features
• Integration Examples
• Dashboard
• Testing
• Project Structure
• Documentation
• Use Cases
• Contributing
• License

🎓 The Concept: Utility AI

Utility AI is a decision-making architecture pioneered by Dave Mark, author of Behavioral Mathematics for Game AI (2009) and a leading voice in the game AI community. Through his influential GDC talks — most notably "Architecture Tricks: Managing Behaviors in Time, Space, and Depth" and the "Improving AI Decision Modeling Through Utility Theory" series — Mark demonstrated how mathematical response curves can replace brittle state machines and rigid behavior trees with fluid, context-sensitive reasoning.

The Core Idea

Traditional AI decision systems (finite state machines, behavior trees, rule engines) hardcode transitions between states. They become fragile as complexity grows — every new behavior requires hand-authored connections that are difficult to maintain and impossible to tune gracefully.

Utility AI takes a fundamentally different approach: every possible action is scored numerically, and the highest-scoring action wins.

For each candidate action:
 score = f(world state, action parameters)

Execute the action with the highest score.

This simple loop produces remarkably sophisticated behavior because:

1. Decisions are continuous, not discrete. Instead of binary "on/off" transitions, each action has a score on a spectrum (0.0 to 1.0), allowing smooth, proportional responses to changing conditions.
2. Multiple factors combine naturally. An action's final score is the product of several considerations — independent scoring functions that each evaluate one axis of the decision (urgency, cost, opportunity, risk, etc.). This multiplicative composition means a zero in any consideration vetoes the action entirely, while strong signals across all axes produce a high combined score.
3. Response curves shape behavior. Each consideration maps a raw input signal to a normalized score using a mathematical curve (linear, logistic, exponential, piecewise). By adjusting curve parameters, designers can fine-tune how aggressively or conservatively an agent reacts to a stimulus — without touching any logic code.
4. New actions are additive, not invasive. Adding a new behavior means adding a new candidate with its own considerations. There are no transitions to rewire and no state graphs to restructure.

The Infinite Axis Utility System

Mark's architecture — sometimes called the Infinite Axis Utility System (IAUS) — formalizes this pattern into a reusable framework:

The power of this approach is its composability: considerations are independent and reusable, curves are data-driven and tunable, and the set of candidate actions is open-ended.

From Game AI to Agent Orchestration

While Utility AI was originally developed for game NPCs, its principles apply directly to modern AI agent orchestration:

This framework brings Dave Mark's Utility AI architecture to the .NET ecosystem, extending it with event-sourced state management, LLM intent integration, and multi-agent coordination — while preserving the elegant simplicity of score everything, pick the best.

"The beauty of utility-based systems is that they allow you to ask the question 'what is the best thing to do right now?' rather than 'what state should I be in?'" — Dave Mark

✨ Features

🚀 Quick Start

Installation

# NuGet (recommended)
dotnet add package UtilityAi

Or clone the repository to explore the source and examples:

git clone https://github.com/mrrasmussendk/UtilityAi.git
cd UtilityAi
dotnet build
dotnet test

Minimal Example

using UtilityAi.Orchestration;
using UtilityAi.Utils;

// 1. Create the event bus (shared state / blackboard)
var bus = new EventBus();

// 2. Configure the orchestrator
var orchestrator = new UtilityAiOrchestrator(bus: bus)
 .AddSensor(new MyEnvironmentSensor())
 .AddModule(new MyCapabilityModule());

// 3. Run the sense → propose → score → act loop
await orchestrator.RunAsync(maxTicks: 10, CancellationToken.None);

Attribute-Based Registration

Reduce boilerplate with declarative attributes:

[Capability(Priority = 100, Domain = "validation")]
[RequiresFact<TaskQueue>]
[ActiveWhen("priority_mode", "urgent", "balanced")]
public class ValidationModule : ICapabilityModule
{
 public IEnumerable<Proposal> Propose(Runtime rt) { /* ... */ }
}

// Auto-discover all modules from the assembly
var orchestrator = new UtilityAiOrchestrator(bus: bus)
 .AddSensor(new MySensor())
 .DiscoverCapabilities(Assembly.GetExecutingAssembly());

See the for a complete demo comparing manual and attribute-based approaches.

🏗️ Architecture Overview

The framework follows a Sense → Propose → Score → Act loop:

┌─────────────────────────────────────────────────────┐
│ EventBus │
│ (Shared state with history & scoping) │
└──────────▲──────────────────────┬──────────────────┘
 │ │
 ┌──────┴──────┐ ┌─────▼──────┐
 │ Sensors │ │ Modules │
 │ (Observe) │ │ (Propose) │
 └─────────────┘ └─────┬──────┘
 │
 ┌──────▼──────┐
 │ Proposals │
 │ + Score │
 └──────┬──────┘
 │
 ┌──────▼──────┐
 │Orchestrator │
 │ Select Best │
 │ & Act │
 └─────────────┘

Key Components

Utility Formula

utility = prior × (geometric_mean_of_considerations) ^ temperature

• Prior — base tendency (0–1)
• Considerations — each returns a score in 0–1, combined via geometric mean
• Temperature — >1 sharpens differences, <1 flattens them

💡 Core Features in Detail

1️⃣ LLM Intent Interpretation

Proposals declare what parameters they need; the framework exposes this metadata so an LLM can provide structured responses that drive scoring automatically.

yield return ProposalHelper.For("ticket.create.priority")
 .WithDescription("Create high-priority support ticket")
 .ForIntent("ticket.create", IntentMatchType.Exact)
 .ScoreByIntentParameter("urgency", x => Math.Pow(x, 3), (0, 1),
 description: "How urgent the issue is (0=low, 1=critical)")
 .UsesIntentParameter("customer_tier", "string",
 allowedValues: new[] { "free", "premium", "enterprise" })
 .WithAction(async ct => await CreatePriorityTicket(rt, ct));

Flow: Proposals declare parameters → Framework exposes metadata via GetCapabilitiesInfo() → LLM prompt includes parameter specs → LLM returns structured intent → Proposals score automatically → Best action wins.

Automatic Validation: Proposals with UsesIntentParameter or ScoreByIntentParameter are automatically protected by HasIntentParametersEligible — they're only eligible when all declared parameters exist in the IntentAnalysis.Parameters dictionary. This prevents proposals from being selected when the LLM hasn't provided the required parameters.

2️⃣ Event History & Subscriptions

// Timestamped history — perfect for building LLM conversation context
var history = bus.GetHistory<UserMessage>(maxItems: 10);
foreach (var evt in history)
 Console.WriteLine($"{evt.Timestamp}: {evt.Value.Text}");

// Type-safe subscriptions — react to events as they happen
using var sub = bus.Subscribe<TaskCompleted>(task =>
 logger.LogInformation($"Task {task.Id} completed in {task.Duration}"));

3️⃣ Scoped Buses (Multi-Agent State)

Isolate per-agent state while sharing global facts:

var rootBus = new EventBus();
rootBus.Publish(new GlobalConfig("production"));

var agent1Bus = rootBus.CreateScope("agent-1");
var agent2Bus = rootBus.CreateScope("agent-2");

agent1Bus.Publish(new AgentStatus("busy"));
agent2Bus.TryGet<AgentStatus>(out var status); // ❌ Not found (isolated)
agent1Bus.TryGetWithFallback<GlobalConfig>(out var config); // ✅ Found in parent

4️⃣ Memory Management

Two-tier architecture: EventBus (fast, last 100 events per type) + IMemoryStore (long-term, unlimited). The MemorySensor archives old facts automatically.

var memoryStore = new InMemoryStore();
var orchestrator = new UtilityAiOrchestrator(bus: bus)
 .AddSensor(new MemorySensor(
 store: memoryStore,
 archiveThreshold: TimeSpan.FromMinutes(10),
 typeof(UserMessage), typeof(AssistantMessage)))
 .AddModule(new MyModule());

5️⃣ Microsoft Agent Framework (MAF) Integration

Orchestrate MAF agents with utility-based decision-making:

var orchestrator = new UtilityAiOrchestrator(bus: bus)
 .AddMafAgentSensor(
 new MafAgentRegistration("research", researchAgent),
 new MafAgentRegistration("writer", writerAgent))
 .AddMafAgent(researchAgent, "research",
 considerations: new IConsideration[] { new MafAgentAvailable("research") })
 .AddMafAgent(writerAgent, "writer",
 considerations: new IConsideration[] { new HasMafAgentResult("research") });

|

🔌 Integration Examples

OpenAI

public class OpenAIModule : ICapabilityModule
{
 private readonly ChatClient _client;

 public OpenAIModule(string apiKey)
 => _client = new ChatClient("gpt-4", apiKey);

 public IEnumerable<Proposal> Propose(Runtime rt)
 {
 var userMsg = rt.Bus.GetOrDefault<UserMessage>();
 if (userMsg == null) yield break;

 yield return new Proposal(
 id: "openai.respond",
 cons: new[] { new HasFact<UserMessage>() },
 act: async ct =>
 {
 var history = rt.Bus.GetHistory<UserMessage>(maxItems: 5);
 var messages = history.Select(e => new UserChatMessage(e.Value.Text)).ToList();
 var response = await _client.CompleteChatAsync(messages, ct);
 rt.Bus.Publish(new AssistantMessage(response.Value.Content[0].Text));
 });
 }
}

The framework also supports Azure OpenAI, Anthropic Claude, and any custom provider via the ILlmProvider abstraction. See the for complete examples.

📊 Dashboard

An optional web dashboard to visualize proposals, consideration scores, and tick history in real time:

var dashboardState = new DashboardState();
app.MapUtilityAiDashboard(dashboardState);
await orchestrator.RunAsync(maxTicks: 10, ct, sink: new DashboardSink(dashboardState));

Navigate to http://localhost:5000/utilityai/dashboard to inspect scores, override priors/temperatures, and step through ticks.

🧪 Testing

The framework is designed for testability. 203 tests cover all core functionality.

[Fact]
public async Task Orchestrator_ChoosesHighestUtility()
{
 var bus = new EventBus();
 bus.Publish(new UserMessage("test"));

 var sink = new TestingSink();
 var orch = new UtilityAiOrchestrator(bus: bus)
 .AddModule(new MyModule());

 await orch.RunAsync( maxTicks: 1, CancellationToken.None, sink);

 Assert.Single(sink.ExecutedProposals);
 Assert.Equal("my.action", sink.ExecutedProposals[0]);
}

dotnet test

📦 Project Structure

UtilityAi/
├── src/
│ └── UtilityAi/ # Core framework (NuGet: UtilityAi)
│ ├── Utils/ # EventBus, Runtime
│ ├── Orchestration/ # UtilityAiOrchestrator, Extensions
│ ├── Sensor/ # ISensor + built-in sensors
│ ├── Capabilities/ # ICapabilityModule, Attributes
│ ├── Consideration/ # IConsideration + built-in considerations
│ ├── Evaluators/ # Response curves (Logistic, Power, etc.)
│ └── Memory/ # IMemoryStore, InMemoryStore, MemorySensor
├── integrations/
│ ├── UtilityAi.Maf/ # Microsoft Agent Framework integration
│ ├── UtilityAi.LLM.Abstractions/ # LLM provider abstraction
│ └── UtilityAi.LLM.OpenAI/ # OpenAI provider implementation
├── examples/
│ ├── Example/ # Demo agents (AgentAssistant, SmartHome, ChatBot, Intent)
│ └── Example.Maf/ # MAF integration demo
├── tools/
│ └── UtilityAi.Dashboard/ # Real-time web dashboard
├── Tests/ # 203 xUnit tests
└── docs/ # Architecture, integration, and pattern guides

📚 Documentation

Getting Started

Examples

Deep Dives

• — Long-term storage, querying, and automatic archival
• — TimeSensor, ConversationHistorySensor, ResourceSensor, MemorySensor
• — HasFact, CurveSignal, Cooldown, TimeWindow, and more
• — IdleModule, CleanupModule, StopOnSignalModule
• — Real-time orchestration visualization

🎯 Use Cases

• AI Agent Systems — Coordinate multiple AI agents with shared and isolated state
• LLM-Based Applications — Build context from event history for prompts
• Dynamic Workflows — Let actions emerge from current state instead of hardcoding sequences
• Game AI — Classic utility AI for NPCs and decision-making
• Task Orchestration — Prioritize and execute tasks based on resources and constraints
• IoT / Smart Home — Balance competing objectives (comfort, energy, security)

🤝 Contributing

Contributions that improve extensibility, documentation, or add well-tested features are welcome!

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass (dotnet test)
5. Submit a pull request

For maintainers: see for the release process.

📄 License

MIT License — see for details.

🙏 Acknowledgments

Built with inspiration from:

• Dave Mark — whose work on Utility AI, the Infinite Axis Utility System, and Behavioral Mathematics for Game AI laid the theoretical foundation for this framework
• Blackboard pattern from classical AI
• Java Annotations (Spring Framework, Jakarta EE)
• Modern agent orchestration (Microsoft Agent Framework, Semantic Kernel, AutoGen, LangGraph)

📞 Support

• 📖
• 💬 Issues
• 📧 Discussions

<p align="center"> _{Built with ❤️ for the AI agent community} </p>