Design Decisions

This document explains the key architectural choices in Orbiter and why they differ from AWorld and other frameworks.

Key Simplifications from AWorld

Orbiter is a ground-up rewrite that simplifies AWorld’s patterns while preserving its capabilities. The table below summarizes the major changes:

Why a Single Agent Class

AWorld had five agent types: LLMAgent, TaskLLMAgent, LoopLLMAgent, ParallelLLMAgent, and SerialLLMAgent. Orbiter collapses these into one Agent class because:

1. The differences were in orchestration, not capability. A “parallel” agent is really two agents run in parallel — that is orchestration (Swarm), not an agent property.

2. Inheritance hierarchies resist composition. With five agent types, you could not combine “task” behavior with “parallel” behavior without a new subclass.

3. Configuration replaces subclasses. The Agent class takes max_steps, output_type, handoffs, etc. as constructor parameters. Workflow behavior comes from Swarm(mode=...).

# AWorld: choose the right subclass
from aworld.agents import LLMAgent, TaskLLMAgent, ParallelLLMAgent

# Orbiter: one class, compose behavior
from orbiter import Agent, Swarm

agent = Agent(name="a", ...)
pipeline = Swarm(agents=[a, b, c], flow="a >> b >> c")

Why Flow DSL Instead of Builder Pattern

AWorld used builder classes (SwarmBuilder, AgentBuilder, SandboxBuilder) totaling ~400 lines. Orbiter uses a string-based flow DSL:

# Builder pattern (AWorld)
builder = SwarmBuilder()
builder.add_agent(a)
builder.add_agent(b)
builder.add_edge(a, b)
swarm = builder.build()

# Flow DSL (Orbiter)
swarm = Swarm(agents=[a, b, c], flow="a >> b >> c")

The DSL is:

• Readable — "a >> b >> c" is immediately clear
• Supports parallel groups — "a >> (b | c) >> d" forks and joins
• Parsed into a graph — Under the hood, parse_flow_dsl() produces a Graph that gets topologically sorted, so cycles are detected at construction time
• Serializable — A string is trivially saved/loaded from config files

Why Async-First with Sync Bridge

All internal functions are async def. The single sync entry point run.sync() calls asyncio.run():

# The ONLY place we bridge sync -> async
def _sync(agent, input, **kwargs):
    return asyncio.run(run(agent, input, **kwargs))

run.sync = _sync

This choice:

• Eliminates sync/async duplication — AWorld had BaseTool and AsyncBaseTool, run() and sync_run(), etc. Orbiter has one of each.
• Enables parallel tool execution — asyncio.TaskGroup runs multiple tool calls concurrently with zero threading complexity.
• Wraps sync functions automatically — @tool detects sync functions and wraps them via asyncio.to_thread() so users do not need to think about it.

Why Typed Messages Instead of Generic Message

AWorld’s Message[DataType] had 15 fields and used string-based category/topic routing. This made it easy to route messages to the wrong handler. Orbiter uses a discriminated union:

Message = UserMessage | AssistantMessage | SystemMessage | ToolResult

Each type is a frozen Pydantic model with only the fields that type needs:

class UserMessage(BaseModel):
    model_config = {"frozen": True}
    role: Literal["user"] = "user"
    content: str

class ToolResult(BaseModel):
    model_config = {"frozen": True}
    role: Literal["tool"] = "tool"
    tool_call_id: str
    tool_name: str
    content: str = ""
    error: str | None = None

Benefits:

• Pattern matching — isinstance(msg, ToolResult) is type-safe and exhaustive
• No invalid states — A UserMessage cannot accidentally have tool_calls
• Immutable — Frozen models prevent accidental mutation of conversation history

Anti-Patterns Avoided

These are patterns Orbiter explicitly rejects:

Influences from Other Frameworks