Ironbees

GitOps-style declarative AI agent management for .NET

Ironbees brings filesystem conventions and declarative agent definitions to .NET AI development. Define agents as YAML files, let Ironbees handle loading, routing, and orchestration - then plug in any LLM backend.

Why Ironbees?

Feature	What it means
GitOps-Ready	Agent definitions are YAML files under version control - review, diff, rollback
Zero-Code Agent Setup	agent.yaml + system-prompt.md = fully configured agent
Observable	All state lives in the filesystem - debug with ls, grep, cat
Portable	Swap between IronHive and Microsoft Agent Framework without changing agent definitions
Intelligent Routing	Keyword, embedding, and hybrid agent selection out of the box
Cost Tracking	Accurate token counting and cost estimation via TokenMeter

Architecture

                    Ironbees.Core
         (Agent loading, routing, guardrails,
          token tracking, cost estimation)
                    |
              Ironbees.AgentMode
           (YAML workflows, definitions)
                  /            \
Ironbees.AgentFramework    Ironbees.Ironhive
  (Azure OpenAI + MAF)      (IronHive multi-provider,
                             Multi-agent orchestration)

              Ironbees.Autonomous
        (Iterative execution, oracle verification)

Ironbees Core is backend-agnostic. Pick the adapter that fits your stack:

• Ironbees.Ironhive - Multi-provider (OpenAI, Anthropic, Google, Ollama) + Multi-agent orchestration via IronHive
• Ironbees.AgentFramework - Azure OpenAI + Microsoft Agent Framework

Installation

Option A: IronHive backend (multi-provider)

dotnet add package Ironbees.Ironhive

Option B: Azure OpenAI backend

dotnet add package Ironbees.AgentFramework

Define an Agent

agents/
└── coding-agent/
    ├── agent.yaml          # Agent metadata and model config
    └── system-prompt.md    # System prompt

agents/coding-agent/agent.yaml:

name: coding-agent
description: Expert software developer
capabilities: [code-generation, code-review]
model:
  provider: openai
  deployment: gpt-4o
  temperature: 0.7

agents/coding-agent/system-prompt.md:

You are an expert software developer specializing in C# and .NET...

Quick Start

With IronHive

services.AddIronbeesIronhive(options =>
{
    options.AgentsDirectory = "./agents";
    options.ConfigureHive = hive =>
    {
        hive.AddOpenAIProviders("openai", new OpenAIConfig { ApiKey = apiKey });
    };
});

With Azure OpenAI

services.AddIronbees(options =>
{
    options.AzureOpenAIEndpoint = "https://your-resource.openai.azure.com";
    options.AzureOpenAIKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
    options.AgentsDirectory = "./agents";
});

Use the Agent

var orchestrator = serviceProvider.GetRequiredService<IAgentOrchestrator>();
await orchestrator.LoadAgentsAsync();

// Explicit agent selection
var response = await orchestrator.ProcessAsync(
    "Write a C# fibonacci function",
    agentName: "coding-agent");

// Automatic routing
var response = await orchestrator.ProcessAsync(
    "fibonacci in C#"); // Routes based on keywords/embeddings

// Streaming
await foreach (var chunk in orchestrator.StreamAsync("Write a blog post"))
{
    Console.Write(chunk);
}

// Per-request system prompt override (RAG context, per-workspace instructions)
var ragContext = await ragService.SearchAsync(query, workspaceId);
await foreach (var chunk in orchestrator.StreamAsync(query, new ProcessOptions
{
    AgentName = "rag-agent",
    ConversationId = sessionId,
    SystemPromptOverride = $"Context:\n{ragContext}\n\nInstructions: {workspace.Instructions}",
}))
{
    Console.Write(chunk);
}

ASP.NET Core Integration

Required packages — Ironbees.Core is abstraction-only. An LLM backend package must also be added:

dotnet add package Ironbees.Ironhive
dotnet add package IronHive.Providers.OpenAI

ConfigureHive is a property assignment, not a method call:

services.AddIronbeesIronhive(opts =>
{
    opts.AgentsDirectory = "agents";
    opts.ConfigureHive = hive =>       // ← property assignment (not a method call)
    {
        hive.AddOpenAIProviders("openai", new OpenAIConfig { ApiKey = "..." });
    };
});

LoadAgentsAsync() must be called after DI build, before app.Run():

var app = builder.Build();

var orchestrator = app.Services.GetRequiredService<IAgentOrchestrator>();
await orchestrator.LoadAgentsAsync();

app.Run();

Multi-Agent Orchestration

Ironbees.Ironhive provides declarative multi-agent orchestration via YAML:

# orchestration.yaml
orchestrator:
  type: Handoff          # Sequential, Parallel, HubSpoke, Handoff, GroupChat, Graph
  initialAgent: triage
  maxTransitions: 10
  middleware:
    retry:
      maxRetries: 3
    circuitBreaker:
      failureThreshold: 5
      breakDuration: 30s

Graph-based workflows for complex pipelines:

orchestrator:
  type: Graph
  graph:
    nodes:
      - id: analyze
        agent: code-analyzer
      - id: review
        agent: reviewer
    edges:
      - from: analyze
        to: review
        condition: "needs_review"
    startNode: analyze
    outputNode: review

Available Orchestrator Types:

Type	Use Case
Sequential	Pipeline processing, output chains
Parallel	Concurrent analysis, fan-out tasks
HubSpoke	Central coordinator with specialists
Handoff	Context-aware agent switching
GroupChat	Multi-agent discussion with speaker selection
Graph	DAG workflows with conditional routing

Token Tracking & Cost Estimation

Ironbees integrates TokenMeter for accurate tiktoken-based token counting and cost estimation across 40+ models (OpenAI, Anthropic, Google, xAI, Azure).

// Middleware pipeline with cost tracking
var builder = new ChatClientBuilder(innerClient)
    .UseTokenTracking(
        store,
        new TokenTrackingOptions { EnableCostTracking = true },
        CostCalculator.Default());

// Query cost statistics
var stats = await store.GetStatisticsAsync();
Console.WriteLine($"Total cost: ${stats.TotalEstimatedCost:F4}");
Console.WriteLine($"By model: {string.Join(", ",
    stats.ByModel.Select(m => $"{m.Key}: ${m.Value.EstimatedCost:F4}"))}");

Autonomous SDK

For iterative autonomous execution with oracle verification:

var orchestrator = AutonomousOrchestrator.Create<Request, Result>()
    .WithSettings(settings)
    .WithExecutor(executor)
    .WithOracle(oracle)
    .Build();

await foreach (var evt in orchestrator.StartAsync(request))
{
    Console.WriteLine($"[{evt.Type}] {evt.Message}");
}

Design Principles

• Thin Wrapper - Complement LLM frameworks, don't replace them
• Convention over Configuration - Filesystem structure defines behavior
• Declaration vs Execution - Ironbees declares patterns; backends execute them
• Filesystem = Single Source of Truth - All state observable via standard tools

Documentation

Document	Description
Architecture	System design and interfaces
Philosophy	Design principles and scope
Autonomous SDK	Autonomous execution guide
Agentic Patterns	HITL, sampling, confidence
Providers	LLM provider configuration

Samples

Sample	Description
OpenAISample	Basic OpenAI usage
GpuStackSample	Local GPU infrastructure
EmbeddingSample	ONNX embedding and semantic routing
TwentyQuestionsSample	Autonomous SDK demo

Contributing

Issues and PRs welcome. Please maintain the thin wrapper philosophy.

License

MIT License - See LICENSE