Nedo.AspNet.AgentOrchestration 1.2.0

Nedo.AspNet.AgentOrchestration

A provider-agnostic .NET library for orchestrating AI agents in ASP.NET applications. Seamlessly switch between OpenAI, Claude, and Gemini — or run all three side-by-side — with a unified API, middleware pipeline, tool loop engine, and streaming support.

Features

• Multi-Provider — Built-in support for OpenAI, Anthropic Claude, and Google Gemini
• Middleware Pipeline — ASP.NET-style middleware chain (Logging, Retry, Timeout, Rate Limit, Tracing)
• Tool Loop Engine — Automatic iterate-execute-append cycle with safety controls
• Streaming — SSE streaming with IAsyncEnumerable<AgentStreamEvent>
• Agent Definitions — Named agents with provider, model, system prompt, and tool bindings
• Testable — In-memory provider for unit testing without HTTP calls
• OpenTelemetry — Built-in tracing middleware with activity spans

Installation

dotnet add package Nedo.AspNet.AgentOrchestration

Quick Start

using Nedo.AspNet.AgentOrchestration.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAgentOrchestration(options =>
{
    // Register providers
    options.UseOpenAI("your-openai-key");
    options.UseClaude("your-claude-key");
    options.UseGemini("your-gemini-key");
    options.DefaultProvider = "openai";

    // Define agents
    options.AddAgent("assistant", agent =>
    {
        agent.UseProvider("openai");
        agent.UseModel("gpt-4o-mini");
        agent.UseTemperature(0.7f);
        agent.UseMaxTokens(2048);
        agent.UseSystemPrompt("You are a helpful AI assistant.");
    });

    options.AddAgent("code-generator", agent =>
    {
        agent.UseProvider("claude");
        agent.UseModel("claude-sonnet-4-20250514");
        agent.UseTemperature(0.2f);
        agent.UseMaxTokens(4096);
        agent.UseSystemPrompt("You are an expert code generation assistant.");
    });

    // Middleware pipeline
    options.Pipeline(pipeline =>
    {
        pipeline.UseLogging();
        pipeline.UseRetry();
        pipeline.UseTimeout(TimeSpan.FromSeconds(30));
    });
});

Invoke an Agent

public class ChatController : ControllerBase
{
    private readonly IAgentOrchestrator _orchestrator;

    public ChatController(IAgentOrchestrator orchestrator)
        => _orchestrator = orchestrator;

    [HttpPost]
    public async Task<IActionResult> Chat([FromBody] ChatRequest request, CancellationToken ct)
    {
        var messages = new[] { ChatMessage.User(request.Message) };

        var response = await _orchestrator.InvokeAsync("assistant", messages, cancellationToken: ct);

        return Ok(new { response.Message.Content, response.Usage, response.FinishReason });
    }
}

Stream a Response

[HttpPost("stream")]
public async Task StreamChat([FromBody] ChatRequest request, CancellationToken ct)
{
    Response.ContentType = "text/event-stream";
    var messages = new[] { ChatMessage.User(request.Message) };

    await foreach (var evt in _orchestrator.InvokeStreamingAsync("assistant", messages, cancellationToken: ct))
    {
        if (evt is TextDeltaEvent delta)
        {
            await Response.WriteAsync($"data: {delta.Delta}\n\n", ct);
            await Response.Body.FlushAsync(ct);
        }
    }
}

Supported Providers

Built-in Middleware

Tool Loop Engine

Register tools and the engine automatically handles the iterate-execute-append cycle:

options.AddTool<WeatherTool>();
options.AddTool<DatabaseTool>();

options.AddAgent("tool-agent", agent =>
{
    agent.UseProvider("openai");
    agent.UseModel("gpt-4o");
    agent.UseTools("weather", "database");
});

// Safety controls
options.ToolLoop = new ToolLoopOptions
{
    MaxIterations = 10,
    EnableCycleDetection = true,
    OverflowBehavior = OverflowBehavior.ReturnPartial
};

Testing

Use the in-memory provider for unit tests without HTTP calls:

services.AddAgentOrchestration(options =>
{
    options.UseInMemory(provider =>
    {
        provider.OnInvoke(request => new AgentProviderResponse
        {
            Message = new ChatMessage("assistant", "Mock response"),
            Usage = new AgentUsage(10, 20)
        });
    });

    options.AddAgent("test-agent", agent =>
    {
        agent.UseProvider("in-memory");
        agent.UseModel("test");
    });
});

Project Structure

src/Nedo.AspNet.AgentOrchestration/
├── Abstractions/       # IAgentOrchestrator, IAgentProvider, IAgentTool, IAgentInvocationMiddleware
├── Agents/             # AgentDefinition, AgentBase, AgentAttribute, AgentRegistry
├── Configuration/      # AddAgentOrchestration(), AgentBuilder, PipelineBuilder
├── Middleware/          # Logging, Retry, Timeout, RateLimit, Tracing
├── Models/             # ChatMessage, AgentOptions, ToolCall, ToolResult, AgentResponse
├── Pipeline/           # AgentInvocationContext, InvocationPipeline
├── Providers/          # OpenAI, Claude, Gemini implementations
├── Streaming/          # AgentStreamEvent, TextDeltaEvent, CompletionEvent
├── Testing/            # InMemoryAgentProvider, InMemoryTool
├── ToolLoop/           # ToolLoopEngine, ToolLoopOptions, ToolLoopState
└── AgentOrchestrator.cs

test/Nedo.AspNet.AgentOrchestration.Tests/    # 24 unit tests
sample/Nedo.AspNet.AgentOrchestration.Sample/ # ASP.NET sample app
docs/                                          # Architecture & usage documentation

Documentation

Examples

License

MIT