Tutorials

A self-contained course for researchers designing agents in the QitOS mindmap.

This track is meant to be completed in order.

It is not a gallery of examples. It is a course about how to design agents in the QitOS mindmap without guessing where prompt policy, parser choice, tool composition, memory, and traceability belong.

Every lesson keeps the same kernel:

task -> state -> prompt/protocol -> decision -> tool execution -> reduce -> trace

What changes is the policy layer you build on top of that kernel.

Two authoring paths

The course now explicitly teaches QitOS through two authoring paths:

• Research-first: handwrite prompt, parser, protocol, transport, and tool surface.
• Preset-first: keep the agent implementation stable and switch model families through family presets.

The research-first path is still the default mental model for understanding the kernel. The preset-first path is the acceleration layer you adopt once you want stronger reuse or cleaner multi-family comparisons.

What makes this track different

Each lesson is written to be self-contained. That means every lesson explicitly covers:

• the exact agent shape you are building
• the state fields you introduce and why they matter
• the system prompt or prompt pair you use
• the parser or protocol contract that matches that prompt
• the tool surface or preset toolset you expose
• the model harness you use to talk to the LLM
• the memory and history choice for that stage of complexity
• the qita trace checkpoints you should inspect after the run

If a concept is not introduced yet, that is deliberate. The course is progressive.

The QitOS design worksheet

When you design an agent in QitOS, you are always answering the same questions:

Design question	QitOS surface	What you decide
What problem is the agent solving?	task, prepare()	The exact objective and the context you surface per step
What must persist across steps?	StateSchema	Plans, scratchpads, findings, mode flags, ranked summaries
How does the model know how to respond?	build_system_prompt(), model_parser, model_protocol	Text, JSON, XML, Terminus, MiniMax, or provider-specific harnessing
What can the agent do?	ToolRegistry, preset toolsets	Minimal tools, coding presets, audit tools, web tools, task boards
How does the loop learn from execution?	reduce()	What becomes state, what stays only in the trace, what counts as success
How do long runs stay under control?	HistoryPolicy, History, Memory	Message trimming, compaction, retrieval, durable memory
How do you inspect behavior?	TraceWriter, qita	Board, replay, export, prompt hash, parser diagnostics, context telemetry

That worksheet stays constant across all four lessons.

The progression

Lesson	What you build	New design idea	Prompt and parser	Tools	Context strategy
1. ReAct	The smallest useful coding agent	Learn the default LLM -> parser -> Decision path	REACT_SYSTEM_PROMPT + ReActTextParser	Manual ToolRegistry + compact CodingToolSet	No memory, no compaction, tiny scratchpad in state
2. PlanAct	A planning-first repair agent	Add explicit planning without adding a second runtime	PLAN_DRAFT_PROMPT for planning, PLAN_EXEC_SYSTEM_PROMPT + ReActTextParser for execution	Same compact coding tools	Plan in state, still no separate memory/compaction
3. Claude Code-style	A long-running coding agent	Move from hand wiring to preset toolsets and workflow prompts	Custom workflow system prompt + ReActTextParser	coding_tools(...) preset	HistoryPolicy first, then when to add CompactHistory and memory
4. Code security audit	A domain-specialized review agent	Specialize the kernel by domain rather than inventing a new runtime	SECURITY_AUDIT_SYSTEM_PROMPT + ReActTextParser, with protocol upgrade notes	SecurityAuditToolSet + codebase/task tools	Ranked finding memory, bounded history, audit-oriented traces

How model harnesses fit into the course

The first three lessons start from the same simple mental model on purpose:

• one transport
• one parser contract
• prompt-injected tool schema
• a visible LLM -> parser -> Decision path

That is the shortest path for learning the kernel.

In v0.4, the flagship coding example grows one level deeper:

• you still get an OpenAICompatibleModel transport underneath
• but you now resolve it through a family preset and a harness policy first

That keeps one example portable across Qwen, Kimi, MiniMax, gpt-oss, and Gemma 4.

Later in the course you will also learn how to reason about protocol upgrades:

• stay with ReAct text when you want maximal portability
• move to JSON or XML when you want stricter output contracts
• use Terminus protocols when the agent controls a live terminal stream
• use MiniMaxToolCallParser or another model-specific harness when the model emits native structured tool calls

QitOS supports those variants, but the course starts with the most transferable path.

Recommended order

Lesson 1: ReAct

Start with the smallest agent that still uses real tools, a real prompt, a real parser, and qita.

Lesson 2: PlanAct

Add explicit planning while keeping execution on the same default Engine path.

Lesson 3: Claude Code-style agent

Learn preset toolsets, workflow prompts, history control, and when compaction becomes necessary.

Lesson 4: Code security audit agent

Learn domain specialization, ranked findings, and how to use qita as a review artifact.

Research-first example

See the bare handwritten harness path in one real coding agent.

Preset-first switching

Learn how one coding agent switches across multiple model families.

v0.3 reproducibility workshops

Reproducible benchmark runs

Learn the official qit bench path, normalized result rows, and official-run metadata.

Replay failed runs

Learn how qita board, replay, export, and diff turn traces into review-grade artifacts.

Switch model families

Use the same Claude Code-style example across Qwen, Kimi, MiniMax, gpt-oss, and Gemma 4.

Before you begin

• You have already run Quickstart or First Agent.
• You understand the AgentModule + Engine split from Agent module and Engine.
• You can provide an OpenAI-compatible model endpoint, either directly or through a QitOS family preset.

What you should know after lesson 4

You should be able to:

• design a system prompt as a protocol contract rather than as vague instructions
• choose a parser that matches the prompt instead of treating parsing as cleanup
• decide when to hand-build a registry and when to switch to a preset toolset
• choose between state-only memory, HistoryPolicy, CompactHistory, and explicit memory adapters
• understand when a model-specific harness is worth the extra coupling
• use qita to debug prompt failures, parser failures, bad tool choices, and context collapse

Related reading

Build your first agent

Review the base AgentModule contract before or alongside the course.

Agent patterns

See the broader map of ReAct, PlanAct, Tree-of-Thought, and Reflexion.

Kit reference

Look up parsers, planners, toolsets, memory, and history helpers used by the lessons.

Observability

Learn how qita board, replay, and export turn traces into research artifacts.