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.
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) -> effectswhere 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:
- Core. Low-level actor framework.
AgentRuntimeAgentMessageTopic. Async message exchange, event-driven. - AgentChat. Task-driven high-level API (replacement for v0.2's ConversableAgent).
AssistantAgentUserProxyAgentRoundRobinGroupChatSelectorGroupChat. - 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 withsenderrecipienttopicbody.Actorabstract withreceive(message, runtime).Runtimeevent loop with a shared queue, delivery, failure isolation.- A two-actor demo:
ReviewerAgentreviews code,ChecklistAgentruns a checklist; they exchange messages until consensus.
Run it:
python3 code/main.pyThe 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
- 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?
- Implement
SelectorGroupChat: a selector actor picks who processes the next message based on conversation state. - Add distributed transport: swap the in-process queue for a JSON-over-HTTP server so actors can run in separate processes.
- Wire an OTel span per message (or a no-op stand-in). Emit
gen_ai.agent.namegen_ai.operation.nameper Lesson 23. - Read AutoGen v0.4's architecture post. Port your toy to the real
autogen_coreAPI. What did you skip that matters in production?
Key Terms
| Term | What people say | What 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
- AutoGen v0.4, Microsoft Researchthe redesign post
- LangGraph overviewgraph-shaped alternative
- OpenTelemetry GenAI semantic conventionsspans AutoGen emits by default
Check what you learned
7 questions. Answer each one to see why.
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.
"""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()