Agent Coordination System

An event-driven orchestration platform built on the Microsoft Agent Framework that enables multiple agents to coordinate on tasks while maintaining strong isolation, security, and state management guarantees.

🚀 Quick Start

New to the project? Start here: Getting Started

This 5-minute guide will get you up and running with your first agent conversation.

Technology Stack

• .NET 8.0 - Primary runtime and framework
• C# - Implementation language
• Microsoft Agent Framework (.NET SDK) - Agent orchestration and workflows
• ASP.NET Core - Web API and hosting
• Blazor Server - Web chat UI component
• Entity Framework Core - ORM for data persistence
• xUnit - Unit testing framework
• FsCheck - Property-based testing
• Moq - Mocking framework

Project Structure

AgentCoordinationSystem/
├── AgentCoordinationSystem.Core/              # Core domain models and interfaces
│   ├── Agents/                                # Decision loop types
│   ├── Capabilities/                          # Capability and policy types
│   ├── Channels/                              # Channel adapter types
│   ├── Common/                                # Common types (Result, Unit, Errors)
│   ├── Events/                                # Event types (Raw, Normalized)
│   ├── Isolation/                             # Isolation environment types
│   ├── Logging/                               # Logbook types
│   ├── Routing/                               # Event routing types
│   ├── Sessions/                              # Session and identity types
│   ├── Workflows/                             # Workflow types
│   └── StronglyTypedIds.cs                    # Strongly-typed IDs
│
├── AgentCoordinationSystem.Infrastructure/    # Infrastructure implementations
│   └── (EF Core implementations, adapters)
│
├── AgentCoordinationSystem.WebApi/            # REST API
│   └── (ASP.NET Core Web API)
│
├── AgentCoordinationSystem.Blazor/            # Web chat UI
│   └── (Blazor Server application)
│
├── AgentCoordinationSystem.Console/           # Console application
│   └── (Console channel adapter)
│
├── AgentCoordinationSystem.Core.Tests/        # Core unit tests
│   └── (xUnit + FsCheck tests)
│
└── AgentCoordinationSystem.Infrastructure.Tests/  # Infrastructure tests
    └── (xUnit + FsCheck tests)

Core Concepts

Strongly-Typed IDs

• SessionId - Unique identifier for isolated sessions
• UserId - User identifier
• WorkflowId - Workflow identifier
• ExecutionId - Workflow execution identifier
• CapabilityId - Capability identifier

Event-Driven Architecture

• RawEvent - Unprocessed events from external sources
• NormalizedEvent - Standardized events for agent consumption
• EventRouter - Converts and routes events to sessions

Session Isolation

• Each conversation/task runs in an isolated session
• Sessions have bounded state and permissions
• Identity verification before any action
• Immutable scope after session creation

Decision Loop

Five-phase cycle: Collect → Interpret → Plan → Act → Reflect

• Collect: Gather events and facts
• Interpret: Analyze information
• Plan: Generate action plan
• Act: Execute actions through policies
• Reflect: Evaluate outcomes

Security Model

• Scope-First: Permissions defined before intelligence
• Policy Wrapper: Security layer for all capabilities
• Isolation Environment: Constrained execution for risky actions
• Zero-Trust: Identity verification for all operations

Memory Management

• Logbook: Append-only event log for audit trail
• Working Memory: Ephemeral storage for facts and tasks

Getting Started

Quick Configuration Check

Run the configuration check script to verify your setup:

# Windows (PowerShell)
.\scripts\check-config.ps1

# Linux/Mac
chmod +x scripts/check-config.sh
./scripts/check-config.sh

This will verify:

• ✅ .NET 8.0 SDK is installed
• ✅ AI provider is configured
• ✅ Database connection is set up
• ✅ Solution builds successfully
• ✅ Tests pass

1. Configure AI Provider (Required)

Before running the system, you must configure an AI model provider. See AI Setup Guide for detailed instructions.

Quick setup with OpenAI:

# Set your API key
export OPENAI_API_KEY=sk-your-key-here

# Or copy and edit the example config
cp appsettings.example.json AgentCoordinationSystem.Infrastructure/appsettings.json
# Edit the file and add your API key

2. Build the Solution

dotnet build

3. Run Tests

dotnet test

4. Run the Applications

Console Application (Recommended for testing):

dotnet run --project AgentCoordinationSystem.Console

Blazor Web Chat:

dotnet run --project AgentCoordinationSystem.Blazor
# Navigate to https://localhost:5001

Web API:

dotnet run --project AgentCoordinationSystem.WebApi

Documentation

• Getting Started - 5-minute quick start guide
• AI Setup Guide - Configure OpenAI, Azure OpenAI, Anthropic, or local models
• Model Strategy - Model selection strategy with GPT-5, o3, Claude 4.5
• Manual Testing Guide - Comprehensive testing procedures
• Integration Guide - Connecting all the pieces
• Logging Guide - Logging configuration and levels
• Quick Start - Minimal quick-start reference
• TODO Summary - Remaining integration tasks
• Configuration Templates:
  • appsettings.example.json - General purpose
  • appsettings.development.example.json - Development (cost-optimized)
  • appsettings.production.example.json - Production-ready
  • appsettings.code-heavy.example.json - Code generation/review
• scripts/check-config.ps1 / scripts/check-config.sh - Configuration verification scripts

Development Status

✅ Task 1: Project structure and core type definitions - COMPLETED

• Solution structure with 7 projects
• Core type definitions (IDs, events, sessions, workflows, capabilities)
• NuGet packages configured (Microsoft.Agents.Core, EF Core, xUnit, FsCheck, Moq)
• Solution builds successfully

Next Steps

• Task 2: Implement Event Router core functionality
• Task 3: Implement Session Store and session management
• Task 4: Checkpoint - Ensure all tests pass
• (See tasks.md for full implementation plan)

License

[License information to be added]