Ironbees.Ironhive 0.7.1

Ironbees

👁 CI
👁 NuGet - Core
👁 NuGet - AgentFramework
👁 NuGet - Ironhive

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?

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

Samples

Contributing

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

License

MIT License - See