Ironbees.Core 0.4.2

Ironbees

Filesystem convention-based LLM agent management wrapper for .NET

Ironbees is a lightweight wrapper that simplifies repetitive patterns in LLM agent development. It doesn't replace frameworks like Microsoft Agent Framework or Semantic Kernel—it complements them by providing filesystem conventions for agent management.

Key Features

• Filesystem Convention: Define agents via agents/{name}/agent.yaml + system-prompt.md
• Intelligent Routing: Keyword, embedding, and hybrid agent selection
• Multi-Framework Support: Microsoft Agent Framework, OpenAI, and custom providers
• YAML Workflows: Declarative workflow definitions with MAF integration
• Guardrails: Content validation with Azure AI and OpenAI Moderation support
• Autonomous SDK: Iterative autonomous execution with oracle verification

Installation

dotnet add package Ironbees.Core
dotnet add package Ironbees.AgentFramework  # For Azure OpenAI + MAF

Quick Start

1. Define an Agent

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

agents/coding-agent/agent.yaml:

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

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

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

2. Configure Services

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

3. 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

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

Autonomous SDK

For iterative autonomous execution with oracle verification:

settings.yaml:

orchestration:
  max_iterations: 10
  oracle:
    enabled: true
  confidence:
    min_threshold: 0.8

var settings = await OrchestratorSettings.LoadFromFileAsync("settings.yaml");

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}");
}

Architecture

┌─────────────────────────────────────────────┐
│   Ironbees (Thin Wrapper)                   │
│   - FileSystemAgentLoader                   │
│   - Agent Routing (Keyword/Embedding)       │
│   - Guardrails Pipeline                     │
├─────────────────────────────────────────────┤
│   Microsoft Agent Framework / LLM Providers │
│   - Agent execution                         │
│   - Tool integration                        │
│   - Conversation management                 │
└─────────────────────────────────────────────┘

Documentation

Samples

Design Principles

• Thin Wrapper: Complement LLM frameworks, don't replace them
• Convention over Configuration: Filesystem structure defines behavior
• Filesystem = Single Source of Truth: All state observable via ls, grep, cat

Contributing

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

License

MIT License - See LICENSE

Ironbees - Filesystem convention-based LLM agent wrapper for .NET