QitOS

QitOS is the torch-flavor framework for agent researchers.

Prototype methods, run benchmarks, and inspect long-horizon trajectories on one AgentModule + Engine kernel with built-in qita observability.

QitOS core is the small framework. Product-grade applications and showcase agents live in qitos-zoo, including planned apps such as qitos-coder and qitos-cyber-agent.

Quickstart · Tutorial Track · Benchmarks · CLI Reference · Changelog · Chinese README

What's New in v0.5.0

• 12 method templates: ReAct, PlanAct, SWE-Agent, Voyager, Debate, Manager-Worker, Planner-Executor, Self-Refine, Reflexion, LATS, MoA, and Magentic-One — each with paper.md, config.yaml, and recipe implementations.
• qit new CLI: Scaffold a new agent project from built-in templates with qit new --template <name>.
• Export APIs: EngineConfig, ToolPermissionSpec, CriticTrace, and HandoffTrace for programmatic access to engine configuration and trace data.
• Tracing integrations: W&B (WandbTraceProcessor) and MLflow (MlflowTraceProcessor) for experiment tracking.
• FamilyPreset extensibility: override(), recommended_* advisory fields, and MaxTokensCriteria stop criterion.
• qita cost panel: Token usage and cost metrics in the run overview.

See CHANGELOG.md for the full list.

Live Terminal of QitOS for Code Review

Who QitOS is For

• Method researchers who want to change prompts, parsers, critics, tools, and memory policies without rewriting the runtime.
• Benchmark users who want GAIA, Tau-Bench, and CyBench workflows on the same kernel they use for agent development.
• Long-running agent debuggers who care about trajectory review, replay, diff, and context-collapse diagnosis instead of app scaffolding alone.

Run QitOS in 2 Minutes

The minimal agent in QitOS is a minimal coding agent. It configures a real model, works inside a workspace, edits code, runs a verification command, and leaves behind a qita-ready trace.

pip install "qitos[models]"
export OPENAI_API_KEY="sk-..."
qit --version
qit demo minimal
qita board --logdir runs

Optional but common for OpenAI-compatible providers:

export OPENAI_BASE_URL="https://api.siliconflow.cn/v1/"
export QITOS_MODEL="Qwen/Qwen3-8B"

qit demo minimal seeds a tiny buggy workspace, asks a model-backed coding agent to fix it, verifies the patch, and writes the trajectory to ./runs.

Then go deeper:

• Want ReAct? See examples/patterns/react.py
• Want a coding agent? See examples/real/coding_agent.py
• Want benchmarks? Start with the benchmark guides
• Want method templates? See Method Templates Guide

Why QitOS

If you want...	QitOS gives you...
reproducible agent research	a stable AgentModule + Engine kernel
method = Agent + Critic	12 built-in method templates with paper mappings
observability	qita board, replay, export, and trace artifacts
benchmark workflows	GAIA, Tau-Bench, and CyBench adapters
less framework glue code	one canonical execution loop

Method Templates

QitOS ships 12 method templates — each is an Agent + Critic pair implementing a well-known agentic reasoning pattern:

Template	Pattern	Paper
ReAct	Reason + Act	Yao et al. 2023
PlanAct	Plan then Execute	—
SWE-Agent	Software Engineering	Princeton 2024
Voyager	Open-ended Exploration	Wang et al. 2023
Debate	Multi-agent Debate	—
Manager-Worker	Orchestration with Delegation	—
Planner-Executor	Plan Decomposition	—
Self-Refine	Generate → Critique → Refine	Madaan et al. 2023
Reflexion	Act → Reflect → Retry	Shinn et al. 2023
LATS	Monte Carlo Tree Search	Zhou et al. 2023
MoA	Parallel Proposals + Aggregation	Wang et al. 2024
Magentic-One	Orchestrator + Specialists	Furtado et al. 2024

Use them directly:

from qitos.recipes.reflexion import ReflexionAgent, ReflexionCritic

agent = ReflexionAgent(llm=my_llm)
result = agent.run(
    task="Debug the failing test",
    critics=[ReflexionCritic(max_reflections=3)],
    max_steps=15,
    return_state=True,
)

Or scaffold a new agent from any template:

pip install qitos[cookiecutter]
qit new --agent-name my_agent --agent-description "My custom agent"
qit list-templates

Tooling Layout

QiTOS separates tool imports into three layers:

• qitos.kit: the simplest curated entrypoint for common toolsets
• qitos.kit.toolset: scenario-oriented presets and registry builders
• qitos.kit.tool.<domain>: advanced atomic capability imports

Default composition is list-first:

from qitos import ToolRegistry
from qitos.kit.tool.file import ReadFile
from qitos.kit.toolset import coding_tools

registry = ToolRegistry().include_toolset(
    [
        ReadFile(workspace_root="."),
        coding_tools(workspace_root="."),
    ]
)

Security-sensitive tools are explicit opt-in imports and are not part of qitos, qitos.kit, qit demo, or the quickstart path.

Documentation Map

• Start here: Introduction
• First successful run: Quickstart
• Install options: Installation
• Build your own minimal coding agent: First Agent
• Method templates: Method Templates Guide
• Learn the runtime: AgentModule / Engine
• Inspect traces: Observability
• Follow the course: Tutorials
• Run benchmarks: Benchmarks Overview
• Check commands: CLI Reference
• Need API details: API Reference

Preview

QitOS CLI	qita Board	qita Trajectory View

Status

QitOS is currently Beta.

• Stable direction: AgentModule + Engine, trace/qita flow, canonical examples, benchmark adapters, and official reproducible-run contracts.
• Likely to evolve: higher-level convenience APIs, some kit modules, and experimental toolsets.
• If you are evaluating adoption, start from the kernel and examples, not assumptions about frozen surface area.
• For ongoing project evolution and upgrade notes, see CHANGELOG.md.

Installation and Versions

• Supported Python version: 3.10+
• User install: pip install "qitos[models]"
• Version check: qit --version
• Minimal coding agent: qit demo minimal
• Optional provider config: OPENAI_API_KEY, OPENAI_BASE_URL, QITOS_MODEL
• Core-only install: pip install qitos
• Repo source install: pip install -r requirements.txt
• Full contributor install: pip install -r requirements-dev.txt
• Optional extras: qitos[wandb], qitos[mlflow], qitos[cookiecutter], qitos[all]
• Installation guide: Installation

Contributing

Contributions are welcome, especially around method templates, benchmark adapters, memory/history workflows, qita UX, and framework contracts. Product-grade agents should target qitos-zoo. Start with CONTRIBUTING.md for the PR process, DEVELOPMENT.md for the local workflow, ARCHITECTURE.md for system design, SECURITY.md for disclosure guidance, and CODE_OF_CONDUCT.md for community expectations.

License

MIT. See LICENSE.