Introduction

QitOS is a research-first agent framework for building reproducible LLM agents with a clean AgentModule + Engine kernel.

QitOS gives you a stable AgentModule + Engine kernel for building reproducible LLM agents. Whether you’re prototyping ReAct loops, running GAIA benchmarks, or shipping a production coding agent, QitOS keeps your runs traceable, your patterns composable, and your results reproducible.

A long-running QitOS coding run stays readable instead of turning into opaque glue code.

Two ways to author agents in QitOS

QitOS keeps two authoring paths on purpose.

Research-first

This is the default path for researchers who want the most control.

You handwrite:

• the system prompt
• the parser
• the model protocol
• the model transport
• the tool surface

This is the most torch-like path in the framework: direct, explicit, and easy to mutate for experiments.

Preset-first

This is the fastest path when you want a stable baseline or fast model-family switching.

You start from:

• family presets
• harness policies
• preset tool builders

This path is especially useful when one agent should switch across Qwen, Kimi, MiniMax, gpt-oss, and Gemma 4 without rewriting the agent.

Who QitOS is for

QitOS is built for three kinds of practitioners:

• Researchers — prototype ReAct, PlanAct, Tree-of-Thought, Reflexion, and new agent methods with reproducible runs you can diff, replay, and publish.
• Agent builders — build tool-using agents on a stable execution loop instead of piling framework glue code on top of raw LLM calls.
• Evaluators — run GAIA, Tau-Bench, and CyBench-style workflows on the same kernel you use in product agents, so benchmark results actually transfer.

Key capabilities

Reproducible runs

Every QitOS run writes a manifest.json, events.jsonl, and steps.jsonl to a local run directory. The manifest captures the model ID, prompt hash, config hash, seed, and tool manifest — everything you need to reproduce or compare runs exactly.

Built-in observability with qita

qita is QitOS’s built-in trace viewer. After any run, launch the board to inspect step-by-step execution, replay the trajectory, and export traces to standalone HTML.

qita board --logdir runs

The board runs at http://127.0.0.1:8765 and auto-refreshes as new runs appear.

Canonical agent patterns

QitOS ships with canonical implementations of four established reasoning patterns, each runnable from examples/patterns/:

Pattern	Description
ReAct	Text protocol with one action per step
PlanAct	Explicit plan first, then step-by-step execution
Tree-of-Thought	Branch and score before acting
Reflexion	Actor-critic loop with grounded retry behavior

Benchmark adapters

QitOS includes adapters for GAIA, Tau-Bench, and CyBench that run on the same AgentModule + Engine kernel you use for your own agents. You don’t need a separate evaluation harness.

Featured designs

These are the design decisions that make QitOS feel different from a pile of agent utilities.

Single-kernel architecture

QitOS is opinionated about one thing above all: there is one runtime kernel per run.

• AgentModule defines policy
• Engine owns execution
• tools, parsers, critics, memory, and tracing attach to that kernel instead of creating side orchestrators

This is what keeps examples, benchmarks, and production-style agents comparable.

Protocol-aware prompting and parsing

QitOS treats prompt format and parser choice as a first-class contract.

• ReAct prompts pair with ReActTextParser
• JSON prompts pair with JsonDecisionParser
• XML prompts pair with XmlDecisionParser
• more structured variants such as Terminus and MiniMax tool-call parsers stay in the same model-response -> parser -> Decision path

This is one of the main reasons traces stay understandable instead of collapsing into provider-specific glue.

Preset-first agent authoring

QitOS gives you reusable authoring blocks instead of forcing every agent to rebuild the same wiring.

• preset tool bundles such as coding_tools(...), advanced_coding_tools(...), web_tools(), task_tools(...), and security_audit_tools(...)
• reusable memory adapters such as WindowMemory, SummaryMemory, VectorMemory, and MarkdownFileMemory
• reusable history strategies such as WindowHistory, TokenBudgetSummaryHistory, and CompactHistory
• reusable planners such as NumberedPlanBuilder and DynamicTreeSearch

The framework is designed so researchers can change the policy without rebuilding the whole stack.

Long-running context control

Long-running agents are a first-class concern in QitOS.

You can control context growth through:

• HistoryPolicy for message selection
• token-budget-aware summarization with TokenBudgetSummaryHistory
• multi-stage compaction with CompactHistory
• memory adapters for semantic or persistent recall

This is the practical side of the research story: the framework helps you study and shape long runs instead of pretending context is free.

Trace-first observability with qita

QitOS assumes that if a run matters, it should be inspectable.

Every traced run produces structured artifacts, and qita turns them into:

• a board for comparing runs
• replay for step-by-step inspection
• export for shareable standalone HTML

This trace-first design is why the same kernel works well for experiments, benchmarks, and debugging.

Domain specialization without a new runtime

One of the strongest design features in QitOS is that domain agents are still ordinary QitOS agents.

The Claude Code-style agent, benchmark runners, and the code security audit agent all reuse the same runtime. Domain behavior lives in:

• state design
• prompt policy
• tool composition
• reduce() semantics

That makes specialization easier to reason about and easier to reproduce.

Status

QitOS is currently Alpha. The stable foundation is the AgentModule + Engine kernel, the qita trace/observability flow, canonical examples, and benchmark adapters. Higher-level convenience APIs, some kit modules, and experimental toolsets are likely to evolve. If you are evaluating adoption, start from the kernel and examples rather than assuming frozen surface area.

Where to go next

Quick start

Run your first agent in under 2 minutes

Tutorials

Follow the four-lesson research track for designing agents in the QitOS mindmap

Installation

Install QitOS and its optional extras

Core concepts

Understand AgentModule, Engine, State, and Tools

Agent patterns

ReAct, PlanAct, Tree-of-Thought, and Reflexion examples

Kit reference

Explore pre-built tools, memory, parsers, planners, and history strategies

Tracing & qita

Learn how QitOS makes every run inspectable, replayable, and exportable