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

Date: 2026-05-17

Audience: IT developers working with .NET + actor models + LLM integration

Sister page (Korean): Akka.NET에 LLM Agent 객체 만들기 — Akka.io Agent SDK를 액터 모델로 이식하기

Related memorizer notes (new window):

- Akka.NET Distributed Actor Model (Korean)

- Akka Agents Platform Overview (Korean)

- Akka Sample Projects (9 agents) (Korean)

- Akka Hello World Agent Tutorial (Korean)

- Akka Multi-Agent Planner (Korean)

- Actor-Agent RAG (Memorizer-v1, Akka.NET production case) (Korean)

TL;DR

Background — Why isn't there an Agent in Akka.NET?

1. Akka.io Agent in one line

@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 mapping table — what becomes what

3. AkkaAgent abstraction design

3-1. Message protocol

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. Abstract actor — lifecycle as Behavior transitions

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

    private readonly ILlmClient _llm;
    private readonly IActorRef _memory;          // SessionMemoryActor (child)
    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 "waiting for request") ----
    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 call) ----
    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 (tool dispatch) ----
    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));
            }

            // re-inject tool results into the prompt → fall back to Reasoning
            var nextPrompt = AppendToolResults(BuildPromptFromCompletion(raw), invocations);
            Become(() => Reasoning(req, caller, nextPrompt));
            Self.Tell(nextPrompt);
        });

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

Key: Akka.io's four-stage lifecycle (Context Gathering → Reasoning → Action → Progress Evaluation) becomes four Behaviors transitioned via Become(...) in .NET. The state machine is now visible in the code, instead of being hidden inside SDK lifecycle annotations — so you can debug transitions with your eyes.

3-3. Tool abstraction

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

// Usage — reflection auto-generates IAgentTool
public sealed class WeatherTool
{
    [AgentFunction(Description = "Get current weather for a city")]
    public Task<WeatherResult> GetWeather(string city) => /* HTTP call */;
}

3-4. Session memory (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. Runnable sample — HelloAgent (Q&A)

4-1. Concrete actor

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. Invocation — session-keyed routing

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

// Wire it up
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. Second call — memory applied automatically

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. Runnable sample — WeatherAgent (tool calls)

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) => /* same as above */;
}

6. End-to-end sequence

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 recs?"
    R->>A: Forward (session-keyed)
    Note over A: Behavior=Idle
    A->>M: LoadSessionMessages
    M-->>A: SessionMessages history
    Note over A: Behavior=GatheringContext to Reasoning
    A->>LLM: complete prompt + tools
    LLM-->>A: tool_call GetWeather Madrid
    Note over A: Behavior=Acting
    A->>T: GetWeather Madrid
    T-->>A: rain 18C
    Note over A: Behavior=Reasoning (reentry)
    A->>LLM: complete prompt + tool_result
    LLM-->>A: "Rainy. Try Prado Museum."
    A->>M: AppendMessages
    A-->>R: AgentResponse
    R-->>U: AgentResponse
    Note over A: Behavior=Idle

7. Operational considerations

8. Anti-patterns

9. Porting matrix — Akka.io official samples → Akka.NET

9-1. Multi-Agent Planner (workflow orchestration)

@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();
    }
}

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

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 omitted
    }

    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 };
                _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's @StepName method = Akka.NET's Become(Step) function

• componentClient.forAgent().method(...).invoke(...) = agentActorRef.Tell(...) (async, result via Receive<AgentResponse>)

• transitionTo(NextStep) = Become(NextStep)

• Automatic checkpointing = PersistentActor.Persist(evt, handler)

• thenPause() = Become(WaitingForExternalInput) (e.g. wait for user approval)

9-2. RAG Chat Agent (streaming + vector search)

@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;       // vector-search actor
    private readonly IStreamingLlmClient _llmStream;

    protected override AgentPrompt BuildPrompt(
        AgentRequest req, IReadOnlyList<ChatMessage> history)
    {
        // 1) Embed the question and fetch top-5 similar docs (Ask pattern)
        var docs = _ragHelper.Ask<TopKDocs>(
            new SimilaritySearch(req.UserMessage, K: 5),
            TimeSpan.FromSeconds(3)).Result;

        // 2) Prepend retrieved docs as system context
        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);
    }

    // Streaming-only entry point (Reasoning Behavior splits off)
    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 tools + Timer + EventSourced)

public sealed class CustomerServiceAgentActor : LlmAgentActor
{
    public CustomerServiceAgentActor(
        ILlmClient llm,
        IActorRef emailGateway,        // Tool 1: send email
        IActorRef customerEntity)      // Tool 2 + Entity: persist customer info
        : base("cs-agent", llm, new IAgentTool[] {
            AgentToolFactory.Wrap(new SendEmailTool(emailGateway)),
            AgentToolFactory.Wrap(new SaveCustomerTool(customerEntity)),
        }) { }

    protected override AgentPrompt BuildPrompt(...) =>
        /* "If customer info is incomplete, call SendEmail to follow up; if complete, call SaveCustomer." */;
}

// Timer: send a reminder 24h later if no follow-up arrives
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. Common porting rules

TL;DR: Akka.io's annotation-driven lifecycle maps 1:1 to .NET's explicit Become transitions + PersistentActor checkpoints. You lose a touch of automation, but the state machine becomes visible in code — which pays off massively during debugging and operations.

10. Next steps

1. Fork a sample repo: refactor memorizer-v1's ChatBotActor into the 4-Behavior pattern from this article

2. Multi-Agent synergy: replicate the Activity/Weather/Summarizer 3-agent collaboration from the Akka Multi-Agent Planner using an Akka.NET router + child agents

3. Akka.Cluster.Sharding integration: route sessionId → ShardId to scale across multiple nodes

4. Wire in MCP tools: wrap an MCP server call inside an IAgentTool implementation and expose it to the LLM

11. References

• Akka.io official Agent guide: https://doc.akka.io/java/agents.html

• Akka.NET official: https://getakka.net/

• Akka Hello World Agent Tutorial (Memorizer, KO)

• Akka Sample Projects — 9 agents (Memorizer, KO)

• Actor-Agent RAG: Memorizer-v1 (Memorizer, KO)

• Akka.NET vs other concurrency models (Memorizer, KO)

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

Tags