Concepts

Read these once before diving into the API. They explain why the framework looks the way it does. What’s a primitive vs an implementation, what state lives where, and how the pieces compose.

The Agent class is a configured loop driver. Architectures iterate; layers gate; protocols decouple.What is an Agent One Run is one agent.run() call. A Session is a long-lived conversation across runs. RunContext is the contextvar that threads scope through tools.Run vs Session vs RunContext Episodes are raw conversations the agent had. Facts are structured (subject, predicate, object) claims extracted from episodes. Different lifecycles, different queries.Episode vs Fact A Tool is a callable. A ToolHost is a registry. A Skill is a playbook the model loads on demand. Three primitives, one composition surface.Tools vs Skills vs ToolHost How user_id partitions every primitive. Memory, budget, audit, permissions, without app-side namespace plumbing.Multi-tenancy

The shape in one diagram


                                Agent (the configured loop driver)
                                          │
                ┌─────────────────────────┼─────────────────────────┐
                │                         │                         │
            Architecture              Dependencies                Hooks
            (the strategy)            (the protocol bundle)       (lifecycle callbacks)
                │
        ┌───────┴────────┐
   ReAct  Plan-and-      Supervisor / Debate / Swarm / ...
          Execute        (multi-agent shapes)

   Dependencies = Model · Memory · Runtime · ToolHost · Budget · Permissions · Telemetry · AuditLog
                  ─────────────────────────────────────────────────────────────────
                  Each is a Protocol with multiple shipped implementations.
                  Each can be replaced without forking the framework.

The five guiding ideas

Protocols, not inheritance. Every cross-layer interface is a Protocol. To add a new model adapter, memory backend, or architecture, satisfy the protocol. No inheritance required.
user_id is a typed primitive. Pass it once at agent.run(user_id="alice"); the framework propagates it through memory recall, budget tracking, audit attribution, and tool RunContext automatically.
No-op defaults; pay only for what you wire. AllowAll permissions, NoTelemetry, no audit log, InProcRuntime. The loop detects each at construction and skips its integration point on the hot path.
The agent loop is a strategy. ReAct is the default; architectures are pluggable. Same Agent class, one kwarg flips the iteration pattern.
Recursive composition. Architectures wrap each other. Reflexion-of-Supervisor is a team that learns. Same Agent, different shape per layer.

Where to next

Build: Quickstart → walk through the shipped surface.
Pick a loop: Architectures → the twelve strategies behind one constructor.
Ship: Production → multi-tenant footguns, closed.

These concepts are stable. The framework’s API surface evolves; the mental model behind it has been deliberate since v0.1. If you read these five pages and the Architecture (internals) tour, you’ll have the complete picture in about an hour.