IronHive.Abstractions 0.45.0

IronHive

<p align="center"> <img src="assets/ironhive.png" alt="IronHive Logo" width="200"/> </p>

<p align="center"> <a href="https://github.com/iyulab/ironhive/actions/workflows/ci.yml"> <img src="https://github.com/iyulab/ironhive/actions/workflows/ci.yml/badge.svg" alt="CI"> </a> <a href="https://www.nuget.org/packages/IronHive.Core"> <img src="https://img.shields.io/nuget/v/IronHive.Core?label=NuGet" alt="NuGet"> </a> <a href="https://github.com/iyulab/ironhive/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/iyulab/ironhive" alt="License"> </a> </p>

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

주요 기능

• 멀티 Provider LLM — OpenAI, Anthropic, Google AI (Gemini/Vertex AI), OpenAI Compatible (Ollama, LM Studio, GPUStack 등)
• 멀티에이전트 오케스트레이션 — SequentialOrchestrator · ParallelOrchestrator · HubSpokeOrchestrator(각자의 …OrchestratorOptions 로 생성), HandoffOrchestratorBuilder · GroupChatOrchestratorBuilder · GraphOrchestratorBuilder(DAG). 공통 옵션 — 타임아웃 · StopOnAgentFailure · 에이전트 미들웨어 · 승인 핸들러 · 컨텍스트 스코프 · 결과 distiller — 은 옵션 객체 또는 빌더의 Set… 으로 준다(docs/ORCHESTRATION.md)
• RAG 파이프라인 — 텍스트 추출, 청킹, 임베딩, 벡터 검색
• 다중 모달리티 — 이미지 생성, 음성 TTS/STT, 비디오 생성
• 플러그인 — MCP: McpClientManager.AddOrUpdate(new McpHttpClientConfig{…} / McpStdioClientConfig{…}) 로 서버를 붙이고 세션의 도구를 에이전트 도구에 더한다(HTTP/Stdio/OAuth). OpenAPI: new OpenApiClientManager(tools) 에 await AddOrUpdateAsync(client) 로 OpenApiClient 를 등록하면 스펙의 연산이 그 IToolCollection 에 도구로 들어간다(docs/PLUGINS.md)
• M.E.AI 호환 — 패키지 IronHive.Extensions.AI(의존: Abstractions 뿐 — Core 없이 provider 를 IChatClient 로): generator.AsChatClient(model, provider) · AsEmbeddingGenerator(…) · AIToolAdapter(임의의 AITool을 ITool로 래핑·실행 — MCP McpClientTool 등). using IronHive.Extensions.AI;
• 워크플로우 — 코드 기반 타입 안전 워크플로우 엔진
• 구조화 출력 — OutputFormat.For<T>()/For(schema) 는 스키마로 구속, OutputFormat.Json 은 스키마 없는 JSON 모드(provider 네이티브 JSON 모드로 번역 — OpenAI json_object, Gemini responseMimeType, Anthropic 은 시스템 지시). AgentInvokeOptions.OutputFormat 또는 IChatClient 의 ChatOptions.ResponseFormat 으로 켠다
• 도구 결과 합계 예산 — ToolResultBudgetMiddleware가 한 호출의 도구 루프 전체에서 모델에 보내는 결과 텍스트 합계를 제한(작은 문맥 창 대응, docs/TOOLS.md)
• 공급자 고유 필드 — MessageRequest.ExtraBody(임베딩은 EmbeddingRequestOptions.ExtraBody, EmbedBatchAsync(model, inputs, options)) 가 요청 본문에 합쳐지고, 매핑되지 않은 응답 필드(예: llama.cpp timings)가 MessageResponse.ExtraBody 로 돌아온다(OpenAI Compatible, docs/PROVIDERS.md)
• 토큰 로그 확률 — MessageRequest.LogProbabilities(상위 대안 0~20)로 출력 토큰별 로그 확률을 받는다(MessageResponse.LogProbabilities, 스트리밍 done 프레임에도; OpenAI Compatible · Google AI, docs/PROVIDERS.md)
• 도메인 예외 — 컨텍스트 윈도우 초과 시 프로바이더별 오류를 ContextOverflowException(ContextWindow·RequestTokens 포함)으로 정규화 — 문자열 파싱 없이 catch로 압축·복구 로직 작성 가능. 프로바이더 대신 자기 OpenAI SDK 클라이언트(또는 Microsoft.Extensions.AI.OpenAI)를 쓰는 경우 OpenAIErrors.TryMapContextOverflow(ex)/TryMapRateLimit(ex)(IronHive.Providers.OpenAI)로 같은 매핑을 받는다

왜 IronHive인가

2026년 4월 Microsoft Agent Framework 1.0이 AutoGen과 Semantic Kernel을 통합해 GA로 출시되며 .NET LLM 오케스트레이션의 유력한 기본 선택지로 떠올랐습니다. IronHive는 이와 다른 설계 축을 선택합니다 — 로컬 우선, 클라우드 무의존입니다.

• 완전한 로컬 추론 루프 — lm-supply로 LLM 생성·임베딩·리랭킹·OCR까지 GGUF/ONNX 백엔드로 순수 .NET에서 실행합니다. 클라우드 계정이나 네트워크 연결 없이도 에이전트 루프 전체가 동작합니다.
• 네이티브 .NET, 브리지 불필요 — Microsoft Agent Framework의 로컬 실행 경로(Foundry Local)는 2026년 기준 Python 전용이며, .NET에서 쓰려면 커뮤니티 어댑터를 거쳐야 합니다. IronHive는 로컬 추론이 처음부터 .NET 1급 시민입니다.
• RAG 파이프라인 내장 — 문서 처리(FileFlux/WebFlux)부터 하이브리드 검색(FluxIndex)까지 별도 통합 없이 바로 사용합니다.

Azure 생태계에 이미 투자한 팀이라면 Microsoft Agent Framework가 자연스러운 선택입니다. 오프라인/에어갭 환경, 데이터 상주 요구사항, 또는 클라우드 종속을 피하려는 .NET 애플리케이션이라면 IronHive가 그 자리를 채웁니다.

설치

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,
    ThinkingOutput = MessageThinkingOutput.Summary,  // 추론 요약을 응답에 싣기 (None 이면 숨김)
    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;
    }
}

패키지

출력 길이 파라미터 선택 (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 를 지정하지 않으면 어느 설정에서도 두 필드 모두 전송되지 않는다.

localhost 와 연결 타임아웃 (0.41.0~) — 각 provider 가 직접 만드는 전송은 호스트의 주소들을 경주시킨다 (RFC 8305): localhost 가 ::1 부터 풀려도 IPv4 전용 로컬 서버(llama-server · Ollama 기본값)에 곧바로 붙는다. 그 전에는 Windows 에서 거부된 IPv6 연결이 약 2 초 걸려 OpenAI-compatible 의 2 초 ConnectTimeout 이 먼저 끝났다. HttpClient 를 직접 주입하는 경우 같은 동작은 IronHive.Abstractions.Http.ProviderConnect.CreateHandler(timeout) 로 얻는다.

문서

Skills (AI 코딩 에이전트용)

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

npx skills add iyulab/ironhive

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

요구 사항

• .NET 10.0+

라이선스

MIT — LICENSE 참조.