Akka.NET에 LLM Agent 객체 만들기 — Akka.io Agent SDK를 액터 모델로 이식하기

Akka.NET에 LLM Agent 객체 만들기 — Akka.io Agent SDK를 액터 모델로 이식하기

🌐 English version: Building LLM Agents in Akka.NET — Porting Akka.io's Agent SDK to the Actor Model

수집일: 2026-05-16

대상 독자: .NET + 액터 모델 + LLM 통합에 관심 있는 IT 개발자

발행 매체: Notion AI-DOC 하위 (Type B*)

연관 메모리 (새창 열기):

- Akka.NET 분산 Actor 모델

- Akka Agents 구조화된 플랫폼

- Akka 샘플 프로젝트 (Agent 9종)

- Akka Hello World Agent 튜토리얼

- Akka Multi-Agent Planner

- Actor-Agent RAG (Memorizer-v1, Akka.NET 실전 케이스)

한 줄 요약

배경 — 왜 Akka.NET에는 Agent가 없는가

1. Akka.io Agent 한 줄 분석

@Component(id = "hello-world-agent")
public class HelloWorldAgent extends Agent {
    private static final String SYSTEM_MESSAGE = "You are a cheerful AI...";
    public Effect<String> greet(String userGreeting) {
        return effects()
            .systemMessage(SYSTEM_MESSAGE)
            .userMessage(userGreeting)
            .thenReply();
    }
}

2. .NET 매핑 표 — 각 Akka.io 자산의 등가물

3. AkkaAgent 추상화 설계

3-1. 메시지 프로토콜

public abstract record AgentMessage;

public sealed record AgentRequest(
    string SessionId,
    string UserMessage,
    Dictionary<string, object>? Context = null
) : AgentMessage;

public sealed record AgentResponse(
    string SessionId,
    string Reply,
    IReadOnlyList<ToolInvocation> ToolCalls,
    int PromptTokens,
    int CompletionTokens
) : AgentMessage;

public sealed record AgentError(
    string SessionId,
    string Reason,
    Exception? Cause = null
) : AgentMessage;

public sealed record ToolInvocation(string Name, string ArgsJson, string ResultJson);

3-2. 추상 액터 — 라이프사이클 4단계를 Behavior 전이로

public abstract class LlmAgentActor : ReceiveActor, IWithUnboundedStash
{
    public IStash Stash { get; set; } = null!;

    private readonly ILlmClient _llm;
    private readonly IActorRef _memory;          // SessionMemoryActor (자식)
    private readonly IReadOnlyList<IAgentTool> _tools;
    private readonly string _agentId;

    protected LlmAgentActor(
        string agentId,
        ILlmClient llm,
        IReadOnlyList<IAgentTool> tools)
    {
        _agentId = agentId;
        _llm = llm;
        _tools = tools;
        _memory = Context.ActorOf(SessionMemoryActor.Props(), "memory");

        Become(Idle);
    }

    // ---- Behavior 1: Idle (= Akka.io "수신 대기") ----
    private void Idle()
    {
        Receive<AgentRequest>(req =>
        {
            Stash.Stash();
            _memory.Tell(new LoadSessionMessages(req.SessionId), Self);
            Become(() => GatheringContext(req, Sender));
        });
    }

    // ---- Behavior 2: GatheringContext (= Context Gathering) ----
    private void GatheringContext(AgentRequest req, IActorRef caller) => Receive<SessionMessages>(loaded =>
    {
        Stash.UnstashAll();
        var prompt = BuildPrompt(req, loaded.Messages);
        Become(() => Reasoning(req, caller, prompt));
        Self.Tell(prompt);
    });

    // ---- Behavior 3: Reasoning (= LLM 호출) ----
    private void Reasoning(AgentRequest req, IActorRef caller, AgentPrompt prompt) =>
        Receive<AgentPrompt>(async _ =>
        {
            try
            {
                var raw = await _llm.CompleteAsync(prompt, _tools.Select(t => t.Schema));
                Become(() => Acting(req, caller, raw));
                Self.Tell(raw);
            }
            catch (Exception ex)
            {
                caller.Tell(new AgentError(req.SessionId, ex.Message, ex));
                Become(Idle);
            }
        });

    // ---- Behavior 4: Acting (= 도구 호출) ----
    private void Acting(AgentRequest req, IActorRef caller, LlmCompletion raw) =>
        Receive<LlmCompletion>(async _ =>
        {
            if (raw.ToolCalls.Count == 0)
            {
                _memory.Tell(new AppendMessages(req.SessionId, raw.AssistantMessage));
                caller.Tell(new AgentResponse(req.SessionId, raw.Content,
                    Array.Empty<ToolInvocation>(), raw.PromptTokens, raw.CompletionTokens));
                Become(Idle);
                return;
            }

            var invocations = new List<ToolInvocation>();
            foreach (var call in raw.ToolCalls)
            {
                var tool = _tools.First(t => t.Name == call.Name);
                var result = await tool.InvokeAsync(call.ArgsJson);
                invocations.Add(new ToolInvocation(call.Name, call.ArgsJson, result));
            }

            // tool 결과를 prompt 에 다시 주입 → Reasoning 으로 복귀
            var nextPrompt = AppendToolResults(BuildPromptFromCompletion(raw), invocations);
            Become(() => Reasoning(req, caller, nextPrompt));
            Self.Tell(nextPrompt);
        });

    protected abstract AgentPrompt BuildPrompt(AgentRequest req, IReadOnlyList<ChatMessage> history);
}

핵심: Akka.io의 4단계 라이프사이클(Context Gathering → Reasoning → Action → Progress Evaluation)이 .NET 측에서는 Become(...)으로 전이하는 4개의 Behavior가 된다. 한 액터 안에서 명시적 상태 머신으로 표현하니, Akka.io의 자동 라이프사이클을 눈으로 디버깅 가능하다.

3-3. 도구 추상화

public interface IAgentTool
{
    string Name { get; }
    string Description { get; }
    JsonSchema Schema { get; }
    Task<string> InvokeAsync(string argsJson);
}

[AttributeUsage(AttributeTargets.Method)]
public sealed class AgentFunctionAttribute : Attribute
{
    public string? Description { get; init; }
}

// 사용 예 — 리플렉션으로 자동 IAgentTool 생성
public sealed class WeatherTool
{
    [AgentFunction(Description = "Get current weather for a city")]
    public Task<WeatherResult> GetWeather(string city) => /* HTTP 호출 */;
}

3-4. 세션 메모리 (PersistentActor)

public sealed class SessionMemoryActor : ReceivePersistentActor
{
    public override string PersistenceId => $"session-memory-{_sessionId}";
    private readonly string _sessionId;
    private readonly LinkedList<ChatMessage> _history = new();
    private const int MaxHistory = 20;

    public SessionMemoryActor(string sessionId)
    {
        _sessionId = sessionId;

        Recover<MessageAppended>(evt => Apply(evt));
        Recover<SnapshotOffer>(offer =>
        {
            if (offer.Snapshot is List<ChatMessage> snap)
                foreach (var m in snap) _history.AddLast(m);
        });

        Command<LoadSessionMessages>(_ => Sender.Tell(new SessionMessages(_history.ToList())));
        Command<AppendMessages>(cmd => Persist(new MessageAppended(cmd.Message), evt =>
        {
            Apply(evt);
            if (_history.Count % 50 == 0) SaveSnapshot(_history.ToList());
        }));
    }

    private void Apply(MessageAppended evt)
    {
        _history.AddLast(evt.Message);
        while (_history.Count > MaxHistory) _history.RemoveFirst();
    }
}

4. 동작 샘플 — HelloAgent (Q&A)

4-1. 구체 액터

public sealed class HelloAgentActor : LlmAgentActor
{
    private const string SystemPrompt =
        "You are a cheerful AI assistant. Greet users in a new language each turn.";

    public HelloAgentActor(ILlmClient llm)
        : base("hello-agent", llm, Array.Empty<IAgentTool>()) { }

    protected override AgentPrompt BuildPrompt(
        AgentRequest req, IReadOnlyList<ChatMessage> history)
    {
        var msgs = new List<ChatMessage> { ChatMessage.System(SystemPrompt) };
        msgs.AddRange(history);
        msgs.Add(ChatMessage.User(req.UserMessage));
        return new AgentPrompt(msgs);
    }

    public static Props Props(ILlmClient llm) =>
        Akka.Actor.Props.Create(() => new HelloAgentActor(llm));
}

4-2. 호출 — 세션 단위 라우팅

public sealed class AgentRouter : ReceiveActor
{
    private readonly Func<string, Props> _propsFactory;
    private readonly Dictionary<string, IActorRef> _bySession = new();

    public AgentRouter(Func<string, Props> propsFactory)
    {
        _propsFactory = propsFactory;
        Receive<AgentRequest>(req =>
        {
            if (!_bySession.TryGetValue(req.SessionId, out var agent))
            {
                agent = Context.ActorOf(_propsFactory(req.SessionId), $"agent-{req.SessionId}");
                _bySession[req.SessionId] = agent;
            }
            agent.Forward(req);
        });
    }
}

// 실행
var system = ActorSystem.Create("agent-host");
var llm = new OpenAiClient(apiKey: ...);
var router = system.ActorOf(
    Props.Create(() => new AgentRouter(_ => HelloAgentActor.Props(llm))),
    "agents");

var reply = await router.Ask<AgentResponse>(
    new AgentRequest("alice", "Hi, I'm Alice"),
    TimeSpan.FromSeconds(30));
// reply.Reply: "Hello, Alice! (English)"

4-3. 두 번째 호출 — 메모리 자동 적용

reply = await router.Ask<AgentResponse>(
    new AgentRequest("alice", "I live in New York"),
    TimeSpan.FromSeconds(30));
// reply.Reply: "Bonjour, New York! Ah, la ville qui ne dort jamais. (French)"

5. 동작 샘플 — WeatherAgent (도구 호출)

public sealed class WeatherAgentActor : LlmAgentActor
{
    private const string SystemPrompt =
        "You are an activity planner. Use the weather tool before recommending outdoor activities.";

    public WeatherAgentActor(ILlmClient llm, WeatherTool weather)
        : base("weather-agent", llm,
            new IAgentTool[] { AgentToolFactory.Wrap(weather) }) { }

    protected override AgentPrompt BuildPrompt(
        AgentRequest req, IReadOnlyList<ChatMessage> history) => /* 동일 */;
}

6. 전체 흐름 다이어그램

sequenceDiagram
    autonumber
    participant U as User
    participant R as AgentRouter
    participant A as LlmAgentActor<br/>(WeatherAgent)
    participant M as SessionMemoryActor
    participant LLM as ILlmClient
    participant T as WeatherTool

    U->>R: AgentRequest("alice", "Madrid 추천?")
    R->>A: Forward (세션별 라우팅)
    Note over A: Behavior=Idle
    A->>M: LoadSessionMessages
    M-->>A: SessionMessages(history)
    Note over A: Behavior=GatheringContext → Reasoning
    A->>LLM: complete(prompt, tools)
    LLM-->>A: tool_call: GetWeather("Madrid")
    Note over A: Behavior=Acting
    A->>T: GetWeather("Madrid")
    T-->>A: "비, 18°C"
    Note over A: Behavior=Reasoning (재진입)
    A->>LLM: complete(prompt + tool_result)
    LLM-->>A: "비가 와요. Prado 미술관 추천."
    A->>M: AppendMessages
    A-->>R: AgentResponse
    R-->>U: AgentResponse
    Note over A: Behavior=Idle

7. 운영 고려사항

8. 안티패턴

9. Akka.io 공식 샘플 → Akka.NET 포팅 매트릭스

9-1. Multi-Agent Planner (Workflow 조율)

@ComponentId("plan-trip")
public class PlanTripWorkflow extends Workflow<State> {
    @StepName("get-weather")
    private StepEffect getWeatherStep() {
        var weather = componentClient
            .forAgent().method(WeatherAgent::query)
            .invoke(currentState().query());
        return stepEffects()
            .updateState(currentState().withWeather(weather))
            .thenTransitionTo(PlanTripWorkflow::suggestActivityStep);
    }
    @StepName("suggest-activity")
    private StepEffect suggestActivityStep() {
        var context = "Weather: " + currentState().weather() +
                     "\nPreferences: " + componentClient
                        .forEntity(currentState().userId())
                        .method(PreferencesEntity::getPreferences)
                        .invoke();
        var suggestion = componentClient
            .forAgent().method(ActivityAgent::query).invoke(context);
        return stepEffects()
            .updateState(currentState().withSuggestion(suggestion))
            .thenPause();
    }
}

// 1) 메시지·상태
public sealed record PlanTripStart(string UserId, string Query);
public sealed record PlanTripState(
    string UserId, string Query, string Weather = "", string Suggestion = "");

public sealed record WeatherReady(string Weather);
public sealed record SuggestionReady(string Suggestion);

// 2) Workflow 액터 — Become으로 Step 전이 + PersistentActor로 체크포인트
public sealed class TripPlannerWorkflowActor : ReceivePersistentActor
{
    public override string PersistenceId => $"trip-planner-{_userId}";
    private readonly string _userId;
    private readonly IActorRef _weatherAgent;
    private readonly IActorRef _activityAgent;
    private readonly IActorRef _prefsEntity;
    private PlanTripState _state = null!;

    public TripPlannerWorkflowActor(
        string userId, IActorRef weather, IActorRef activity, IActorRef prefs)
    {
        _userId = userId;
        _weatherAgent = weather;
        _activityAgent = activity;
        _prefsEntity = prefs;
        Become(Idle);
        // Persistence recovery (생략)
    }

    private void Idle()
    {
        Command<PlanTripStart>(cmd =>
        {
            _state = new PlanTripState(cmd.UserId, cmd.Query);
            // Step 1: Get Weather
            _weatherAgent.Tell(new AgentRequest(cmd.UserId, cmd.Query));
            Become(GettingWeather);
        });
    }

    private void GettingWeather() =>
        Command<AgentResponse>(resp =>
        {
            Persist(new WeatherReady(resp.Reply), evt =>
            {
                _state = _state with { Weather = evt.Weather };
                // Step 2: Get Preferences from Entity
                _prefsEntity.Tell(new GetPreferences(_userId), Self);
                Become(GettingPreferences);
            });
        });

    private string _preferences = "";
    private void GettingPreferences() =>
        Command<PreferencesResponse>(resp =>
        {
            _preferences = resp.Value;
            var ctx = $"Weather: {_state.Weather}\nPreferences: {_preferences}";
            _activityAgent.Tell(new AgentRequest(_userId, ctx));
            Become(GettingSuggestion);
        });

    private void GettingSuggestion() =>
        Command<AgentResponse>(resp =>
        {
            Persist(new SuggestionReady(resp.Reply), evt =>
            {
                _state = _state with { Suggestion = evt.Suggestion };
                Context.Parent.Tell(_state);
                Become(Idle);
            });
        });
}

• Akka.io의 @StepName 메서드 = Akka.NET의 Become(Step) 함수

• componentClient.forAgent().method(...).invoke(...) = agentActorRef.Tell(...) (비동기, Receive<AgentResponse> 로 결과 받음)

• transitionTo(NextStep) = Become(NextStep)

• 자동 체크포인트 = PersistentActor.Persist(evt, handler)

• thenPause() = Become(WaitingForExternalInput) (예: 사용자 승인 대기)

9-2. RAG Chat Agent (스트리밍 + 벡터 검색)

@Component(id = "ask-akka-agent")
public class AskAkkaAgent extends Agent {
    public Effect<StreamingResponse<String>> chat(String question) {
        return effects()
            .systemMessage("You are a helpful Akka assistant.")
            .userMessage(question)
            .thenReplyStreaming();
    }
}

public sealed record RagQueryRequest(string SessionId, string Question);
public sealed record RagChunk(string SessionId, string Token);
public sealed record RagDone(string SessionId, int TokenCount);

public sealed class RagChatAgentActor : LlmAgentActor
{
    private readonly IActorRef _ragHelper;       // 벡터 검색 액터
    private readonly IStreamingLlmClient _llmStream;

    protected override AgentPrompt BuildPrompt(
        AgentRequest req, IReadOnlyList<ChatMessage> history)
    {
        // 1) 질문 임베딩 + 유사 문서 5건 검색 (Ask 패턴)
        var docs = _ragHelper.Ask<TopKDocs>(
            new SimilaritySearch(req.UserMessage, K: 5),
            TimeSpan.FromSeconds(3)).Result;

        // 2) 검색된 문서를 컨텍스트로 추가
        var ctx = string.Join("\n\n",
            docs.Items.Select(d => $"[doc:{d.Id}] {d.Text}"));

        var msgs = new List<ChatMessage> {
            ChatMessage.System("Answer based on the docs below.\n\n" + ctx)
        };
        msgs.AddRange(history);
        msgs.Add(ChatMessage.User(req.UserMessage));
        return new AgentPrompt(msgs);
    }

    // 스트리밍 전용 메서드 (Reasoning Behavior 분기)
    public IAsyncEnumerable<RagChunk> ChatStreaming(RagQueryRequest req) =>
        Source.From(_llmStream.StreamComplete(BuildPrompt(
            new AgentRequest(req.SessionId, req.Question),
            Array.Empty<ChatMessage>())))
            .Select(token => new RagChunk(req.SessionId, token))
            .RunAsAsyncEnumerable(materializer);
}

9-3. Real Estate CS Agent (도구 2개 + Timer + EventSourced)

public sealed class CustomerServiceAgentActor : LlmAgentActor
{
    public CustomerServiceAgentActor(
        ILlmClient llm,
        IActorRef emailGateway,        // Tool 1: 이메일 발송
        IActorRef customerEntity)      // Tool 2 + Entity: 고객 정보 저장
        : base("cs-agent", llm, new IAgentTool[] {
            AgentToolFactory.Wrap(new SendEmailTool(emailGateway)),
            AgentToolFactory.Wrap(new SaveCustomerTool(customerEntity)),
        }) { }

    protected override AgentPrompt BuildPrompt(...) =>
        /* "고객 정보가 부족하면 SendEmail로 후속 질문, 충분하면 SaveCustomer 호출" */;
}

// Timer: 후속 응답 없으면 24시간 후 reminder
public sealed class CustomerInquiryWorkflowActor : ReceivePersistentActor
{
    public CustomerInquiryWorkflowActor(IActorRef agent, ITimerScheduler timers)
    {
        Command<EmailReceived>(email =>
        {
            agent.Tell(new AgentRequest(email.Sender, email.Body));
            Become(WaitingForFollowUp);
            timers.StartSingleTimer(
                "reminder", new SendReminder(email.Sender),
                TimeSpan.FromHours(24));
        });
    }
}

9-4. 포팅 시 공통 규칙

요약: Akka.io의 어노테이션 기반 라이프사이클은 .NET에서 명시적 Become 전이 + PersistentActor 체크포인트로 1:1 매핑된다. 자동성이 약간 줄지만, 상태 머신이 코드에 직접 드러나는 장점이 있다 — 디버깅·운영 시점에 큰 이점.

10. 다음 단계

1. 샘플 GitHub 레포 분기: memorizer-v1의 ChatBotActor → 본 글의 4-Behavior 패턴으로 리팩토링 시도

2. Multi-Agent 시너지: Akka Multi-Agent Planner 의 Activity/Weather/Summarizer 3-Agent 협업 패턴을 .NET 라우터 + 자식 액터로 재현

3. Akka.Cluster.Sharding 통합: 세션 ID → ShardId 매핑으로 다중 노드 확장

4. MCP 도구 연결: IAgentTool 구현체에 MCP 서버 호출을 감싸 LLM에 외부 도구 노출

11. 참고 자료

• Akka.io 공식 Agent 가이드: https://doc.akka.io/java/agents.html

• Akka.NET 공식: https://getakka.net/

• Akka Hello World Agent 튜토리얼 (Memorizer)

• Akka 샘플 프로젝트 목록 — Agent 9종 (Memorizer)

• Actor-Agent RAG 시스템: Memorizer-v1 (Memorizer)

• Akka.NET vs 다른 동시성 모델 (Memorizer)

• Memorizer-v1 GitHub: https://github.com/psmon/memorizer-v1

태그