Glossary

Shared language for runs, trajectories, actions, artifacts, replay, and benchmark outputs in QitOS.

Core runtime terms

Run

One invocation of AgentModule.run(...) or an equivalent benchmark execution path that produces a trace directory.

Trajectory

The temporal record of one run: prompts, decisions, tool calls, observations, reductions, and stop conditions across steps.

Observation

The structured data available to the agent after a step. In QitOS this usually includes action results and environment outputs.

Decision

The engine-level semantic output of the agent loop. A decision may contain actions or a final answer.

Action

A normalized tool invocation (normalized meaning the call is validated, typed, and expressed in a canonical format independent of the original model output) selected by the agent and executed by the runtime.

Reproducibility terms

Artifact

Any persisted output of a run, especially manifest.json, events.jsonl, steps.jsonl, exported HTML, and benchmark result JSONL.

Replay

Reconstructing and inspecting a previous run from its artifacts with qita replay or the benchmark replay path.

Official run

A run that carries the official QitOS contract: structured specs, standard artifacts, and qita-compatible replay/export behavior.

Benchmark result

A normalized BenchmarkRunResult row with fields such as task_id, benchmark, split, prediction, success, stop_reason, steps, latency_seconds, and run_spec_ref.

Runtime control terms

Tool manifest

The serialized description of the tool surface exposed to the run. It is part of the official-run contract because tool drift changes behavior.

Prompt protocol

The format contract between the model and the parser — it defines what structure the model output should have (e.g., ReAct text, JSON, XML, or a model-specific harness) so the parser can reliably extract a Decision.

Parser

The component that converts raw model output into a Decision. The parser must match the prompt protocol.

Context compaction

Any strategy used to shrink accumulated context while keeping a long-running run operational. QitOS records compaction telemetry (structured metrics about what was compacted, when, and how much context was recovered) in the trace.

Inspection terms

qita board

The run index and comparison surface for multiple traces.

qita replay

The single-run temporal playback view.

qita diff

The summary-level comparison view for two runs, focused on stop reason, result, step/event counts, parser diagnostics, config differences, and token/latency/cost summaries.

Quality control terms

Critic

A runtime quality controller that evaluates agent behavior after each step. A critic returns a CriticResult with an action (continue, stop, or retry), a reason, a score, and optional patches to the agent’s instructions or state.

CriticResult

The structured output of a critic evaluation. Contains action (continue/stop/retry), reason, score (0.0–1.0), and optional instruction_patch, state_patch, or modified_prompt for retry actions.

instruction_patch

Additional instruction text appended to the agent’s system prompt on the next iteration when a critic returns a retry action.

state_patch

Key-value pairs merged into the agent’s state before the next iteration when a critic returns a retry action.

Runtime extensibility terms

EngineHook

The base class for runtime extension points. Hooks observe the Engine loop at defined lifecycle points (step start/end, tool use, critic evaluation, etc.) without controlling execution flow.

HookContext

The dataclass passed to hook callbacks, containing the current step ID, phase, state, observation, decision, and action results.

ToolHookContext

An extended HookContext for tool-level events, adding tool_name, tool_args, tool_result, and permission_decision fields.

Tool system terms

@function_tool

A decorator that turns a Python function into a QitOS FunctionTool by automatically inferring the tool schema from type hints and docstrings.

ToolFilter

A filter applied when bridging MCP server tools into a QitOS tool registry, controlling which tools are exposed based on name patterns or custom predicates.

Persistence terms

CheckpointStore

The abstract interface for saving and loading agent run state. Implementations include InMemoryCheckpointStore and SqliteCheckpointStore.

Fork

Creating a new checkpoint branch from an existing checkpoint without overwriting the original. Supports time-travel (same thread) and true branching (new thread).

DurabilityMode

Controls how aggressively checkpoints are persisted. SYNC mode writes to disk before continuing the run.

StateVersionTracker

Tracks per-field version numbers in agent state, enabling fine-grained change detection between checkpoints.

Integration terms

MCP Bridge

A component that connects a Model Context Protocol (MCP) server to QitOS, converting MCP tool definitions into FunctionTool instances that can be registered in an agent’s ToolRegistry.

MCPServerStdio

An MCP server transport that communicates with a subprocess via stdin/stdout JSON-RPC.

Harness and preset terms

Preset override

Creating a customized copy of a built-in FamilyPreset using preset.override(**kwargs). The original preset is never mutated; override() returns a new instance with the specified fields replaced.

MaxTokensCriteria

A stop criterion that halts the Engine when cumulative token usage exceeds a budget. The Engine tracks total_tokens across all steps and passes it in runtime_info.

Advisory defaults

Optional fields on FamilyPreset (recommended_max_steps, recommended_max_tokens, recommended_retry_budget, recommended_temperature) that document tested baseline values. These are advisory only — the engine does not auto-apply them.

Tracing integration terms

WandbTraceProcessor

A TraceProcessor implementation that streams QitOS run metrics (token usage, step counts, critic scores, tool calls, stop reason) to a Weights & Biases project. Requires the wandb package (pip install qitos[wandb]).

MlflowTraceProcessor

A TraceProcessor implementation that streams QitOS run metrics to an MLflow tracking server. Supports custom tracking_uri for remote servers. Requires the mlflow package (pip install qitos[mlflow]).

Engine export terms

CriticTrace

A structured record of a single critic evaluation within a run, captured as EngineResult.critic_traces. Contains step_id, critic_name, action, reason, score, and optional instruction_patch/state_patch.

HandoffTrace

A structured record of an agent handoff within a run, captured as EngineResult.handoff_traces. Contains step_id, from_agent, to_agent, context_strategy, and messages_passed.

EngineConfig

A frozen, serializable snapshot of Engine configuration produced by Engine.export_config(). Contains agent name, model ID, budget settings, critic names, protocol, and capability flags.

ToolPermissionSpec

A frozen, serializable snapshot of a tool’s permission and capability profile produced by ToolRegistry.export_permissions(). Contains name, permissions, needs_approval, read_only, concurrency_safe, and required_ops.

Method template terms

Method template

A ready-made Agent + Critic pair that implements a well-known agentic reasoning pattern. QitOS ships with Self-Refine, Reflexion, LATS, MoA, and Magentic-One templates in qitos.recipes. Each template packages a specialized state, critic, and agent.

Self-Refine

An iterative refinement pattern (Madaan et al. 2023) where the agent generates a draft, receives critique, and refines until quality meets a threshold. The SelfRefineCritic drives the loop with heuristic scoring; the SelfRefineAgent enriches prompts with the current draft and critique history.

Reflexion

An iterative reflection pattern (Shinn et al. 2023) where the agent acts, evaluates results, and on failure generates a verbal reflection stored in state. The ReflexionCritic detects failures and produces reflections as instruction patches; the ReflexionAgent injects previous reflections into the system prompt so the LLM learns from past mistakes.

LATS

Language Agent Tree Search (Zhou et al. 2023) applies Monte Carlo Tree Search to language agents. The LATSAgent explores solution paths, the LATSCritic evaluates each path using UCB1-inspired scoring and generates reflections on failed trajectories, and the LATSState tracks tree statistics including best reward, failed paths, and reflections.

MoA (Mixture-of-Agents)

A layered pattern (Wang et al. 2024) where multiple proposers independently generate responses and an aggregator synthesizes the best insights. The MoAOrchestrator manages proposal collection and aggregation; the MoACritic drives the loop by checking proposal count and prompting for collection or synthesis.

Magentic-One

A dual-ledger orchestration pattern (Furtado et al. 2024) where an orchestrator maintains a Fact Bank and Task Ledger, delegates to specialist agents, and re-plans when stuck. The ProgressCritic detects stalls and triggers re-planning; the MagenticOneOrchestrator enriches prompts with facts and task progress.