nanobot and Agent development glossary

Core execution

Term	Meaning in this library	Current source anchor
Agent	A software runtime that accepts a goal and combines a model, context, and Tools to advance the task; it is not a single LLM request	nanobot/agent/loop.py, nanobot/agent/runner.py
Turn	One top-level processing lifecycle triggered by an inbound message; it may contain multiple model requests and Tool Calls	AgentLoop._process_message()
AgentLoop	Manages outer Turn state, Session, commands, persistence, response delivery, and concurrency boundaries	nanobot/agent/loop.py::AgentLoop
AgentRunner	Repeatedly calls a Provider, parses Tool Calls, executes Tools, and feeds results back to the model within one run	nanobot/agent/runner.py::AgentRunner
ContextBuilder	Assembles the system prompt, workspace files, Skills, history, and current input into model context	nanobot/agent/context.py::ContextBuilder
Provider	Adapts nanobot’s unified model request and response contract to a particular model backend	nanobot/providers/base.py::LLMProvider
LLMResponse	The unified response object returned by a Provider to the Runner; includes text, reasoning, Tool Calls, usage, and related data	nanobot/providers/base.py::LLMResponse
Tool Call	A structured request from the model for its host to execute a Tool; the model is not itself running Python or shell	nanobot/providers/base.py::ToolCallRequest
stop reason	Why the Runner ended this run, not merely its final text	nanobot/agent/runner.py, AgentRunResult.stop_reason

Messages, events, and Sessions

Term	Meaning	Current source anchor
InboundMessage	A business message sent from an entry point into core, including channel, sender, chat, content, media, and metadata	nanobot/bus/events.py
OutboundMessage	User-visible output handed by core to a Channel or direct caller	nanobot/bus/events.py
MessageBus	Asynchronous queues for inbound and outbound business messages	nanobot/bus/queue.py::MessageBus
RuntimeEventBus	In-process publish/subscribe bus for runtime state; it does not carry ordinary chat content	nanobot/bus/runtime_events.py::RuntimeEventBus
Session	Persistable conversation history and metadata used for recovery across Turns	nanobot/session/manager.py::Session
Session key	A Session’s logical identifier; by default it is based on channel:chat_id, but callers can override it	nanobot/session/keys.py, InboundMessage.session_key
model context	The messages, system prompt, and Tool schemas actually sent in one Provider call	nanobot/agent/context.py, nanobot/agent/runner.py
checkpoint	A temporary recovery point during Tool execution that protects context after cancellation or failure	nanobot/agent/runner.py::_emit_checkpoint, nanobot/agent/loop.py::_restore_runtime_checkpoint
compaction	Compressing Session history at token or idle boundaries to reduce later context load	nanobot/agent/memory.py::Consolidator, nanobot/agent/autocompact.py
Memory	Long-term knowledge material the Agent reads and writes in the workspace; it is not raw Session history	nanobot/agent/memory.py
Dream	A mechanism that periodically starts an isolated Session and invokes the Agent to organize long-term memory	Dream helpers in nanobot/agent/memory.py, system tasks in nanobot/cli/commands.py

Capabilities and extensions

Term	Meaning	Best suited to
Tool	An action with an explicit JSON schema that the host executes and returns as structured data or text	“Let the Agent perform a specific action”
ToolRegistry	Runtime container that registers, lists, validates, and executes Tools	Enforcing a unified Tool contract
Tool loader	Discovers built-in Tools, package modules, and nanobot.tools entry points	Plugin-based Tool integration
Skill	Instructions, procedures, and resources injected for the model to guide a class of tasks	“Teach the Agent how to do something”
MCP	Connects to an external MCP server and wraps remote capabilities as nanobot Tools	Reusing an independent Tool service
Provider	Model-backend protocol adapter	Replacing or adding an LLM backend
Channel	Adapter between an external chat platform and InboundMessage/OutboundMessage	Adding a messaging platform
Gateway	Composes long-running services such as AgentLoop, Channels, Cron, Heartbeat, and WebUI	Persistent operation with several entry points
SDK	Public interface for invoking the nanobot runtime within a Python process	Embedding nanobot in a Python application
HTTP API	OpenAI-compatible network interface	Letting external programs invoke nanobot over HTTP

Long-running work

Term	Meaning	Do not confuse with
Goal	Persistent goal state stored in Session metadata	An ordinary one-shot prompt
Continuation	A control boundary that starts another Agent run within the same top-level Turn	A new user message
Subagent	A child-task runtime spawned by the main Agent with its own execution context	An ordinary parallel Tool
Cron	Persistent scheduling of actions by at, every, or cron expression	Heartbeat itself
Heartbeat	A periodic check or wake-up mechanism currently backed by Cron	An operating-system health check

Security and reliability

Term	Meaning	Boundary
workspace restriction	Application-level path policy that attempts to constrain file Tools to the workspace	It is not automatically OS isolation
sandbox	A stronger execution boundary for commands, files, or network; the current bwrap path depends on Linux/container conditions	A Windows configuration name does not prove enforcement
SSRF	Manipulating a server into accessing localhost, private networks, reserved addresses, or unsafe redirects	Requires checks across URL, DNS, and redirect layers
fallback	Trying candidate models or Providers after the primary Provider fails	Not every failure should switch
retry	Repeating a retryable failure against the same Provider or action	Not the same as fallback
atomic write	Writing a temporary file and replacing the target to avoid leaving half-written state	Does not provide a multi-file transaction

Commonly confused relationships

flowchart LR
    A["Turn<br/>one top-level lifecycle"] --> B["Multiple Provider calls"]
    B --> C["Zero or more Tool Calls"]

    D["Session<br/>persistent history"] --> E["ContextBuilder selects and transforms"]
    E --> F["Model context<br/>actual input for this call"]

    G["MessageBus<br/>business messages"] -.different.-> H["RuntimeEventBus<br/>runtime state"]
    I["Skill<br/>teaches the model how"] -.different.-> J["Tool<br/>host executes an action"]
    J -.one remote source.-> K["MCP server"]

Return to Quick reference.