Get Started

The Actor Model for Agents, Async Messages and Typed Runtimes

Agents as actors: async message exchange, event-driven handlers, fault isolation, natural concurrency. AutoGen v0.4 (Microsoft Research, Jan 2025) redesigned agent orchestration around this model; the framework is now in maintenance mode, with Microsoft Agent Framework (public preview Oct 2025) as its production successor.

75 minutesLearn + BuildPython (stdlib)Free lesson

Learning Objectives

  • Describe the actor model: agents as actors, messages as the only IPC, failure isolation per actor.
  • Name AutoGen v0.4's three API layers, Core, AgentChat, Extensions, and what each is for.
  • Explain why decoupling message delivery from handling gives fault isolation and natural concurrency.
  • Implement a stdlib actor runtime in Python and port a two-agent code-review flow onto it.

The Problem

Most agent frameworks are synchronous: one agent produces, one agent consumes, in a call stack. Failures crash the stack. Concurrency is bolted on. Distribution requires rewriting.

AutoGen v0.4's answer: the actor model. Each agent is an actor with a private inbox. Messages are the only interaction. The runtime decouples delivery from handling. Failures isolate to one actor. Concurrency is native. Distribution is just different transport.

The Concept

Actors

An actor has:

  • A private state (never directly touched from outside).
  • An inbox (message queue).
  • A handler: receive(message) -> effects where effects can be "reply," "send to other actor," "spawn new actor," "update state," "stop self."

Two actors cannot share memory. They can only send messages.

Three API layers

AutoGen v0.4 splits its surface into three:

  1. Core. Low-level actor framework. AgentRuntimeAgentMessageTopic. Async message exchange, event-driven.
  2. AgentChat. Task-driven high-level API (replacement for v0.2's ConversableAgent). AssistantAgentUserProxyAgentRoundRobinGroupChatSelectorGroupChat.
  3. Extensions. Integrations, OpenAI, Anthropic, Azure, tools, memory.

Why decoupling matters

In the v0.2 model, calling agent_a.chat(agent_b) synchronously blocks agent_a until agent_b returns. In v0.4, send(agent_b, msg) puts the message in agent_b's inbox and returns. The runtime delivers later. Three consequences:

  • Fault isolation. Agent B crashing does not crash Agent A, the runtime catches the failure in B's handler and decides what to do (log, retry, dead-letter).
  • Natural concurrency. Many messages in flight at once; actors process their inbox concurrently.
  • Distribution-ready. Inbox + transport is the same abstraction whether the actor is in-process or on another host.

Topologies

  • RoundRobinGroupChat. Agents take turns in a fixed rotation.
  • SelectorGroupChat. A selector agent picks who goes next based on conversation context.
  • Magentic-One. Reference multi-agent team for web browsing, code execution, file handling. Built on AgentChat.

Observability

OpenTelemetry support is built in. Every message emits a span; tool calls carry gen_ai.* attributes per the 2026 OTel GenAI semantic conventions (Lesson 23).

Status: maintenance mode

Early 2026: AutoGen v0.7.x is stable for research and prototyping. Microsoft has shifted active development to the Microsoft Agent Framework, the production successor (public preview Oct 1 2025; 1.0 GA was targeted for end of Q1 2026). AutoGen patterns port forward cleanly, the actor model is the durable idea.

Build It

code/main.py implements a stdlib actor runtime:

  • Messagetyped payload with senderrecipienttopicbody.
  • Actorabstract with receive(message, runtime).
  • Runtimeevent loop with a shared queue, delivery, failure isolation.
  • A two-actor demo: ReviewerAgent reviews code, ChecklistAgent runs a checklist; they exchange messages until consensus.

Run it:

Code
python3 code/main.py

The trace shows message delivery, a simulated failure in one actor that does not crash the other, and convergence on a shared verdict.

Use It

  • AutoGen v0.4/v0.7 (maintenance), stable for research, prototyping, multi-agent patterns.
  • Microsoft Agent Frameworkthe production successor (public preview Oct 2025); same actor-model ideas in a refreshed API.
  • LangGraph swarm topology (Lesson 13), similar pattern via shared-tool handoffs.
  • Custom actor runtimewhen you need specific transport (NATS, RabbitMQ, gRPC).

Ship It

outputs/skill-actor-runtime.md generates a minimal actor runtime plus a team template (RoundRobin or Selector) for a given multi-agent task.

Exercises

  1. Add a dead-letter queue: when a handler raises, park the failing message for human inspection. How often does DLQ get hit in your toy?
  2. Implement SelectorGroupChat: a selector actor picks who processes the next message based on conversation state.
  3. Add distributed transport: swap the in-process queue for a JSON-over-HTTP server so actors can run in separate processes.
  4. Wire an OTel span per message (or a no-op stand-in). Emit gen_ai.agent.namegen_ai.operation.name per Lesson 23.
  5. Read AutoGen v0.4's architecture post. Port your toy to the real autogen_core API. What did you skip that matters in production?

Key Terms

TermWhat people sayWhat it actually means
Actor"Agent"Private state + inbox + handler; no shared memory
Message"Event"Typed payload; the only way actors interact
Inbox"Mailbox"Per-actor queue of pending messages
Runtime"Agent host"Event loop that routes messages and isolates failures
Topic"Channel"Named publish-subscribe route between actors
Fault isolation"Let it crash"One actor failing does not crash others
RoundRobinGroupChat"Fixed-rotation team"Agents take turns in order
SelectorGroupChat"Context-routed team"Selector picks who goes next
Magentic-One"Reference team"Multi-agent squad for web + code + files

Further Reading

Check what you learned

7 questions. Answer each one to see why.

Question 1 of 70 correct

What is the only legal way actors interact in AutoGen v0.4?

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""A stdlib actor runtime modeled on AutoGen v0.4 Core.

Actors have private state and an inbox. Messages are the only interaction.
Failures in one actor are caught by the runtime and routed to a dead-letter
queue; other actors keep running.
"""

from __future__ import annotations

from collections import deque
from dataclasses import dataclass, field
from typing import Any, Callable


@dataclass
class Message:
    sender: str
    recipient: str
    topic: str
    body: Any
    mid: int = 0


class Actor:
    def __init__(self, name: str) -> None:
        self.name = name

    def receive(self, message: Message, runtime: "Runtime") -> None:
        raise NotImplementedError


@dataclass
class Runtime:
    actors: dict[str, Actor] = field(default_factory=dict)
    queue: deque[Message] = field(default_factory=deque)
    dead_letters: list[tuple[Message, str]] = field(default_factory=list)
    counter: int = 0
    trace: list[str] = field(default_factory=list)
    max_messages: int = 100

    def register(self, actor: Actor) -> None:
        self.actors[actor.name] = actor

    def send(self, sender: str, recipient: str, topic: str, body: Any) -> None:
        self.counter += 1
        msg = Message(sender=sender, recipient=recipient,
                      topic=topic, body=body, mid=self.counter)
        self.queue.append(msg)
        self.trace.append(
            f"[send m{msg.mid:03d}] {sender} -> {recipient} topic={topic} body={body}"
        )

    def run_until_idle(self) -> None:
        processed = 0
        while self.queue and processed < self.max_messages:
            msg = self.queue.popleft()
            actor = self.actors.get(msg.recipient)
            if actor is None:
                self.dead_letters.append((msg, f"no actor {msg.recipient!r}"))
                self.trace.append(f"[DLQ m{msg.mid:03d}] no actor {msg.recipient!r}")
                continue
            try:
                actor.receive(msg, self)
                self.trace.append(
                    f"[recv m{msg.mid:03d}] {actor.name} handled topic={msg.topic}"
                )
            except Exception as e:
                self.dead_letters.append((msg, f"{type(e).__name__}: {e}"))
                self.trace.append(
                    f"[FAIL m{msg.mid:03d}] {actor.name} raised "
                    f"{type(e).__name__}: {e}  (others keep running)"
                )
            processed += 1


class ReviewerAgent(Actor):
    def __init__(self, name: str) -> None:
        super().__init__(name)
        self.verdicts: list[tuple[str, bool]] = []

    def receive(self, message: Message, runtime: Runtime) -> None:
        if message.topic == "review":
            code = str(message.body)
            issues = []
            if "eval(" in code:
                issues.append("uses eval")
            if "except:" in code:
                issues.append("bare except")
            ok = len(issues) == 0
            self.verdicts.append((code, ok))
            runtime.send(
                sender=self.name,
                recipient=message.sender,
                topic="review_result",
                body={"ok": ok, "issues": issues},
            )
        elif message.topic == "crash_me":
            raise RuntimeError("simulated handler failure")


class ChecklistAgent(Actor):
    def __init__(self, name: str, partner: str) -> None:
        super().__init__(name)
        self.partner = partner
        self.results: list[dict[str, Any]] = []
        self.consensus: bool | None = None

    def receive(self, message: Message, runtime: Runtime) -> None:
        if message.topic == "start":
            for snippet in message.body:
                runtime.send(
                    sender=self.name, recipient=self.partner,
                    topic="review", body=snippet,
                )
        elif message.topic == "review_result":
            self.results.append(dict(message.body))
            if all(r["ok"] for r in self.results):
                self.consensus = True
            if len(self.results) == 3:
                self.consensus = all(r["ok"] for r in self.results)


def main() -> None:
    print("=" * 70)
    print("AUTOGEN V0.4 ACTOR RUNTIME (STDLIB) — Phase 14, Lesson 14")
    print("=" * 70)

    runtime = Runtime()
    reviewer = ReviewerAgent("reviewer")
    checklist = ChecklistAgent("checklist", partner="reviewer")
    runtime.register(reviewer)
    runtime.register(checklist)

    runtime.send(
        sender="__user__",
        recipient="checklist",
        topic="start",
        body=[
            "def add(a, b): return a + b",
            "def hazard(): eval('1+1')",
            "def silent(): \n    try:\n        f()\n    except:\n        pass",
        ],
    )

    runtime.send(
        sender="__user__",
        recipient="reviewer",
        topic="crash_me",
        body={},
    )

    runtime.run_until_idle()

    print("\nmessage trace")
    for line in runtime.trace:
        print(f"  {line}")

    print(f"\nchecklist consensus: {checklist.consensus}")
    print(f"dead-letter queue:   {len(runtime.dead_letters)} message(s)")
    for msg, reason in runtime.dead_letters:
        print(f"  DLQ m{msg.mid:03d} ({reason}) "
              f"{msg.sender} -> {msg.recipient} topic={msg.topic}")

    print()
    print("property: reviewer's crash on 'crash_me' did not stop")
    print("the 'review' messages from being processed. fault isolation.")


if __name__ == "__main__":
    main()