IronHive

IronHive는 기업용 AI 애플리케이션을 위한 .NET 10 파이프라인 프레임워크입니다. 이름 기반 레지스트리 패턴으로 멀티 Provider LLM 통합, 멀티에이전트 오케스트레이션, RAG 파이프라인, 파일 처리를 제공합니다.

주요 기능

• 멀티 Provider LLM — OpenAI, Anthropic, Google AI (Gemini/Vertex AI), OpenAI Compatible (Ollama, LM Studio, GPUStack 등)
• 멀티에이전트 오케스트레이션 — Sequential, Parallel, Handoff, GroupChat, HubSpoke, Graph (DAG)
• RAG 파이프라인 — 텍스트 추출, 청킹, 임베딩, 벡터 검색
• 다중 모달리티 — 이미지 생성, 음성 TTS/STT, 비디오 생성
• 플러그인 — MCP (HTTP/Stdio/OAuth), OpenAPI 자동 도구 생성
• M.E.AI 호환 — ChatClientAdapter / EmbeddingGeneratorAdapter
• 워크플로우 — 코드 기반 타입 안전 워크플로우 엔진
• 도메인 예외 — 컨텍스트 윈도우 초과 시 프로바이더별 오류를 ContextOverflowException(ContextWindow 포함)으로 정규화 — 문자열 파싱 없이 catch로 압축·복구 로직 작성 가능

설치

dotnet add package IronHive.Core
dotnet add package IronHive.Providers.OpenAI    # 또는 Anthropic, GoogleAI 등

빠른 시작

Standalone (콘솔)

using IronHive.Core;
using IronHive.Providers.OpenAI;
using IronHive.Abstractions.Messages.Content;

var hive = new HiveServiceBuilder()
    .AddOpenAIProviders("openai", new OpenAIConfig { ApiKey = "your-api-key" })
    .Build();

var agent = hive.CreateAgentFrom(cfg =>
{
    cfg.Provider = "openai";
    cfg.Model = "gpt-4o-mini";
    cfg.Instructions = "당신은 친절한 도우미입니다.";
});

// 단순 텍스트 호출
var response = await agent.InvokeAsync("안녕하세요");

// per-request 옵션 (에이전트 기본값 위에 이 호출에만 overlay)
var response2 = await agent.InvokeAsync("안녕하세요", new AgentInvokeOptions
{
    ThinkingEffort = MessageThinkingEffort.High,
    Suggestions = new SuggestionOptions(),  // 후속 질의 제안 활성화
    MaxTokens = 2048,
});

// 스트리밍
await foreach (var chunk in agent.InvokeStreamingAsync("안녕하세요"))
{
    // chunk 처리
}

ASP.NET Core DI 통합

// Program.cs
builder.Services.AddHiveService((hiveBuilder, sp) =>
    hiveBuilder
        .AddOpenAIProviders("openai", new OpenAIConfig
        {
            ApiKey = builder.Configuration["OpenAI:ApiKey"]!
        })
        .Build());

// 서비스에서 IHiveService 주입
public class ChatService(IHiveService hive)
{
    public async Task<string> ChatAsync(string text)
    {
        var agent = hive.CreateAgentFrom(cfg =>
        {
            cfg.Provider = "openai";
            cfg.Model = "gpt-4o-mini";
        });
        var response = await agent.InvokeAsync(text);
        return response.Message?.Content
            .OfType<TextMessageContent>()
            .FirstOrDefault()?.Value ?? string.Empty;
    }
}

패키지

패키지	설명
IronHive.Abstractions	인터페이스 및 계약 (외부 의존 없음)
IronHive.Core	핵심 구현 (에이전트, 오케스트레이터, 워크플로우)
IronHive.Providers.OpenAI	OpenAI / Azure OpenAI / xAI (Responses API, Embeddings, DALL-E, TTS/STT)
IronHive.Providers.Anthropic	Anthropic Claude
IronHive.Providers.GoogleAI	Google Gemini + Vertex AI (이미지, 비디오, 오디오 포함)
IronHive.Providers.OpenAI.Compatible	Ollama, LM Studio, vLLM, llama.cpp, GPUStack 등 — Chat Completions 표면

출력 길이 파라미터 선택 (0.16.0~) — OpenAI 가 max_tokens 를 max_completion_tokens 로 개명하면서 생태계가 갈렸다. 최신 OpenAI 모델은 구 이름을 거부하고, 다수의 self-hosted 서버는 새 이름을 모른 채 무시한다 — 모르는 필드는 오류가 아니라 침묵이므로, 상한이 조용히 사라지고 증상은 "응답이 예상보다 길다" 뿐이다. 어디서나 통하는 이름이 없어 선택지로 제공한다:

var config = new OpenAICompatibleConfig
{
    BaseUrl = "http://localhost:11434",
    TokenLimitParameter = TokenLimitParameter.MaxTokens   // 구 이름만 아는 서버
};

기본값은 MaxCompletionTokens — 종전 동작 그대로라 기존 설정은 영향받지 않는다. Both 는 둘 다 받아들이는 엔드포인트에서만 쓴다(구 이름을 거부하는 곳에서는 요청 전체가 실패한다). MaxTokens 를 지정하지 않으면 어느 설정에서도 두 필드 모두 전송되지 않는다. | IronHive.Storages.Qdrant | Qdrant 벡터 데이터베이스 | | IronHive.Storages.Amazon | Amazon S3 파일 저장소 | | IronHive.Storages.Azure | Azure Blob / File Share | | IronHive.Storages.RabbitMQ | RabbitMQ 큐 | | IronHive.Plugins.MCP | Model Context Protocol (HTTP/Stdio/OAuth) | | IronHive.Plugins.OpenAPI | OpenAPI 도구 자동 생성 |

문서

문서	설명
docs/ARCHITECTURE.md	시스템 아키텍처 및 설계 원칙
docs/SETUP.md	HiveServiceBuilder 구성 및 DI 통합
docs/AGENTS.md	에이전트 생성 및 호출
docs/MIDDLEWARE.md	미들웨어 시스템 (Retry, Timeout, CircuitBreaker 등)
docs/ORCHESTRATION.md	멀티에이전트 오케스트레이션 패턴
docs/TOOLS.md	FunctionTool 및 커스텀 도구
docs/MEMORY.md	RAG 파이프라인 및 MemoryWorker
docs/PROVIDERS.md	AI 프로바이더 설정
docs/STORAGES.md	스토리지 백엔드 설정
docs/PLUGINS.md	MCP / OpenAPI 플러그인
docs/SERVICES.md	IHiveService 서비스 상세

Skills (AI 코딩 에이전트용)

AI 코딩 에이전트(GitHub Copilot, Claude Code, Cursor 등)에서 IronHive Skills를 사용하려면:

npx skills add iyulab/ironhive

설치 후 에이전트가 IronHive API 패턴, 오케스트레이션, RAG 파이프라인, 툴 사용법을 자동으로 인식합니다.

요구 사항

• .NET 10.0+

라이선스

MIT — LICENSE 참조.