nanobot source learning roadmap

This library is not meant to make you memorize the classes in nanobot. It is designed to help you build three practical abilities:

1. Trace a message from an entry point and explain how it becomes the final response.
2. Observe sessions, context, tool calls, and runtime state well enough to diagnose common problems.
3. Decide whether a new capability belongs in a Tool, Skill, MCP integration, Provider, Channel, or an external service, then implement the smallest appropriate extension.

Source baseline

Every claim about nanobot’s implementation is based on the v0.2.2 snapshot at example/nanobot/code-EN. The public website does not copy that source tree; implementation references point to the fixed upstream v0.2.2 revision. The repository’s official documentation establishes public usage, while source code and tests establish actual behavior.

Translation authority

learning-CN is the authoritative edition. This English library mirrors its structure, facts, diagrams, and exercises instead of developing a separate curriculum.

Documentation-to-source convention

Except for prerequisites, pure navigation, and learning-method notes, every implementation-facing lesson identifies its “Corresponding source” near the beginning:

• nanobot implementation paths are relative to the current example/nanobot/code-EN source baseline; editable learning exercises under example/nanobot/learning-EN/examples/ are marked from the vault root;
• file.py::Class.method identifies the class or function to open directly;
• a directory means that the subject spans a family of implementations sharing one contract;
• source excerpts in the body are snapshots selected for explanation, so use the original file when studying every branch;
• “Corresponding tests” verify implementation facts but do not imply that those tests are the only coverage.

An excerpt is not a replacement implementation

Excerpts may omit branches, types, or logging unrelated to the concept being taught. Any omission is identified, and the excerpt must not replace the original file as the basis for a modification.

What this library is not

It does not repeat the complete installation guide, Provider configuration tables, Channel integration catalog, SDK/API reference, or deployment manual. When those subjects matter, a lesson explains only what is needed to understand the source and links to nanobot’s own documentation:

• nanobot documentation
• Quick Start
• Concepts
• Architecture
• Troubleshooting

Recommended learning path

flowchart TD
    A["Prerequisites: Python, asyncio, LLM messages, and tool calling"] --> B["Minimal runtime: connect DeepSeek and complete one request"]
    B --> C["Project overview: entry points, core modules, and source map"]
    C --> D["One turn: the AgentLoop state machine"]
    D --> E["Model-tool loop: AgentRunner"]
    E --> F["State and persistence: Session, Context, and Memory"]
    F --> G["Runtime surfaces: CLI, Gateway, API, SDK, and WebUI"]
    G --> H["Engineering and security: concurrency, cancellation, retries, Workspace, and SSRF"]
    H --> I["Extensions: Tool, Skill, MCP, Provider, and Channel"]
    I --> J["Progressive source exercises and review"]

Library navigation

Editable examples live under example/nanobot/learning-EN/examples/. They are kept separate from the reading path so that learning exercises never modify the code-EN source snapshot directly.

Bilingual boundary

Chinese is completed and confirmed first, then English mirrors it lesson by lesson. Website publishing verifies the one-to-one mapping and Chinese-source hash, and stops when an English page is missing or stale.

Stage 1: Run and observe first

Start with the prerequisite map, then continue to Runtime and Source Map. At this stage, you only need to:

• run Python commands;
• understand basic classes, functions, and async def;
• recognize messages, streaming, and tool calls in an LLM API;
• complete one real request using a DeepSeek key.

You do not need React, MCP, advanced concurrency, or production deployment yet.

Stage 2: Understand one turn end to end (the main Agent architecture)

The central question is:

After a user message enters nanobot, which states, objects, and asynchronous boundaries does it pass through?

This stage centers on the following source files:

Stage 3: Understand state and runtime surfaces

Once the core turn is clear, learn:

• why Session, Memory, and model context are different concepts;
• why MessageBus and RuntimeEventBus solve different problems;
• how CLI, API, SDK, Channel, and WebUI reuse the core runtime in different ways;
• where Cron, Goal, Continuation, and Subagent sit in the system.

Stage 4: Debug and extend

Finish with concurrency, cancellation, error recovery, security boundaries, and extension development. The recommended order is:

1. Tool;
2. Skill;
3. MCP;
4. Provider;
5. Channel;
6. API, SDK, or WebUI.

Three optional tracks

Track A: Agent development fundamentals

For readers who have not yet built an agent independently.

Recommended order:

1. Prerequisites;
2. Minimal runtime;
3. Project overview;
4. One turn;
5. Session and context;
6. Tool extension;
7. The first four practice tasks.

Track B: Source debugging

For readers who can already call an LLM API and want to diagnose nanobot problems.

Recommended order:

1. Entry points and source map;
2. AgentLoop state machine;
3. AgentRunner;
4. Runtime events;
5. Exceptions, timeouts, cancellation, and retries;
6. Session persistence;
7. Tests and troubleshooting.

Track C: Extension development

For readers who understand the core turn and want to add capabilities.

Recommended order:

1. The responsibility boundary between AgentLoop and AgentRunner;
2. The differences among Tool, Skill, and MCP;
3. Engineering and security boundaries;
4. The relevant extension lesson;
5. The matching practice task.

How to read each lesson

Each core lesson tries to answer the same set of questions:

• Learning objectives: What should you be able to explain or do afterward?
• Prerequisites: What do you need to know, and to what depth?
• Corresponding source: Which files, classes, and functions should remain open while reading?
• Initial intuition: What simple model makes the problem easier to grasp?
• Source facts: What does the current code actually do?
• Call chain and state changes: Which steps does the data pass through?
• Source and test locations: Where can you verify the claim?
• Observation or verification: How can you see the behavior yourself?
• Boundaries and pitfalls: Which conclusions should not be generalized?

Evidence rules

Statements in this library fall into five categories:

Do not infer behavior from names

A class name, configuration field, or document title is only a clue. Verify callers, state transitions, and tests before treating it as a fact.

Completion criteria

After completing the core path, you should be able to:

• draw a sequence diagram for both a normal turn and a tool-call turn;
• explain the responsibility split between AgentLoop and AgentRunner;
• distinguish message queues, runtime events, Session, Memory, and model context;
• trace a CLI, API, or SDK entry point to process_direct() or the message bus;
• locate model selection, Provider construction, and fallback logic;
• locate Tool schema validation, execution, and result reinsertion;
• explain why turns are serialized within one session but can run concurrently across sessions;
• verify your reasoning with a minimal test or breakpoint;
• decide whether an extension belongs in the core, a Tool, Skill, MCP integration, Provider, or Channel.

Next step

Open the prerequisite map and identify the foundations you still need.