Method Templates

QitOS provides method templates — ready-made Agent + Critic pairs that implement well-known agentic reasoning patterns. Each template packages a specialized state, critic, and agent so you can apply the pattern without rewriting the control loop.

What is a method template?

A method template combines:

Component	Role
State	A `StateSchema` subclass with pattern-specific fields (reflections, drafts, refinement counts)
Critic	A `Critic` subclass that drives the pattern’s loop by returning `retry`, `continue`, or `stop` at the right times
Agent	An `AgentModule` subclass with pattern-aware `build_system_prompt()`, `prepare()`, and `reduce()`

The critic is the key: it evaluates each step and decides whether to retry (with an instruction patch), continue, or stop. The agent enriches prompts with pattern context (previous reflections, draft versions, critiques).

Self-Refine

The Self-Refine pattern (Madaan et al. 2023) iterates: generate → critique → refine until quality meets a threshold or max refinements are reached.

When to use it

Text generation tasks where quality matters more than speed
Summarization, translation, code generation with self-evaluation
Any task where iterative improvement reliably produces better output

Quick start

from qitos.recipes.self_refine import SelfRefineAgent, SelfRefineCritic

agent = SelfRefineAgent(llm=my_llm)
result = agent.run(
    task="Write a concise summary of the research paper on ...",
    critics=[SelfRefineCritic(max_refinements=3, quality_threshold=0.7)],
    max_steps=10,
    return_state=True,
)
print(result.state.draft)       # the refined output
print(result.state.final_result) # FINAL ANSWER if extracted

How it works

Generate: The agent produces an initial draft.
Critique: SelfRefineCritic evaluates the draft quality using heuristic scoring (longer drafts after more refinements score higher; very short drafts are penalized). In production, replace heuristics with an LLM-based scorer.
Refine: If the score is below quality_threshold and refinements remain, the critic returns retry with an instruction_patch asking the agent to improve. The agent sees its previous draft and the critique in the next prompt.
Accept: When the score meets the threshold or max_refinements is reached, the critic returns continue or stop.

SelfRefineCritic parameters

Parameter	Default	Description
`max_refinements`	3	Maximum refinement iterations
`quality_threshold`	0.7	Minimum score (0.0–1.0) to accept the draft

SelfRefineState fields

Field	Type	Description
`draft`	`str`	Current draft text
`refinement_count`	`int`	Number of refinements so far
`max_refinements`	`int`	Refinement budget
`critique_history`	`List[str]`	Accumulated critiques

Customizing the quality scorer

The built-in critic uses heuristics. For production use, subclass and override evaluate():

from qitos.recipes.self_refine import SelfRefineCritic, SelfRefineState
from qitos.engine.critic_result import CriticResult

class LLMScorerCritic(SelfRefineCritic):
    def evaluate(self, state, decision, results):
        refine_state = state if isinstance(state, SelfRefineState) else None
        if refine_state is None:
            return CriticResult(action="continue")

        # Call an LLM to score the draft
        score = self._llm_score(refine_state.draft, refine_state.task)

        if score < self.quality_threshold and refine_state.refinement_count < self.max_refinements:
            return CriticResult(
                action="retry",
                score=score,
                instruction_patch="Critique and improve the draft.",
                state_patch={"refinement_count": refine_state.refinement_count + 1},
            )
        return CriticResult(action="stop", score=score)

Reflexion

The Reflexion pattern (Shinn et al. 2023) iterates: act → evaluate → reflect → retry with memory. On failure, the critic generates a verbal reflection stored in state and injected into future prompts.

When to use it

Debugging and error-correction tasks where the agent must learn from failures
Tasks where different strategies should be tried after failure
Multi-attempt problems (coding, reasoning) where reflections improve subsequent attempts

Quick start

from qitos.recipes.reflexion import ReflexionAgent, ReflexionCritic

agent = ReflexionAgent(llm=my_llm)
result = agent.run(
    task="Debug the failing test in tests/test_module.py",
    critics=[ReflexionCritic(max_reflections=3)],
    max_steps=15,
    return_state=True,
)
print(result.state.reflections)    # list of verbal reflections
print(result.state.final_result)  # FINAL ANSWER if extracted

How it works

Act: The agent takes an action toward the task.
Evaluate: ReflexionCritic checks for failures (errors, non-zero return codes, empty results).
Reflect: On failure, the critic generates a verbal reflection from the error context and returns retry with the reflection as an instruction_patch. The reflection is stored in state.reflections.
Retry with memory: The agent’s build_system_prompt() includes all previous reflections, so the LLM can avoid repeating the same mistakes.

ReflexionCritic parameters

Parameter	Default	Description
`max_reflections`	3	Maximum reflection iterations before forced stop
`success_threshold`	0.6	Minimum score to consider the trajectory successful

ReflexionState fields

Field	Type	Description
`reflections`	`List[str]`	Accumulated verbal reflections
`reflection_count`	`int`	Number of reflections generated
`max_reflections`	`int`	Reflection budget
`last_action_success`	`bool`	Whether the last step succeeded
`attempt`	`int`	Current attempt number

LATS

The LATS pattern (Zhou et al. 2023) applies Monte Carlo Tree Search to language agents: select → expand → evaluate → backpropagate. Failed trajectories generate reflections that guide future exploration away from similar mistakes.

When to use it

Tasks requiring systematic exploration of multiple solution paths
Logic puzzles, coding challenges, and multi-step reasoning
Problems where trying different strategies improves success

Quick start

from qitos.recipes.lats import LATSAgent, LATSCritic

agent = LATSAgent(llm=my_llm)
result = agent.run(
    task="Solve the logic puzzle ...",
    critics=[LATSCritic(max_simulations=5, exploration_weight=1.41)],
    max_steps=20,
    return_state=True,
)
print(result.state.best_answer)    # best answer found
print(result.state.best_reward)    # best reward score

How it works

Simulate: The agent takes an action, producing a result.
Evaluate: LATSCritic computes a reward from the result (errors → low reward, FINAL ANSWER → high reward).
Reflect: Failed paths (reward < 0.3) generate reflections stored in state.reflections.
Guide: On retry, the critic provides an instruction_patch that includes reflections and UCB1-style exploration guidance.
Stop: When a path succeeds (reward ≥ success_threshold) or max_simulations is reached.

LATSCritic parameters

Parameter	Default	Description
`max_simulations`	5	Maximum simulation iterations
`exploration_weight`	1.41	UCB1 exploration constant (c)
`success_threshold`	0.8	Reward value for early stopping

LATSState fields

Field	Type	Description
`simulations_done`	`int`	Number of simulations completed
`max_simulations`	`int`	Simulation budget
`exploration_weight`	`float`	UCB1 c parameter
`best_reward`	`float`	Best reward found so far
`best_answer`	`str`	Answer from the best trajectory
`failed_paths`	`List[str]`	Descriptions of failed paths
`reflections`	`List[str]`	Reflections from failures

MoA (Mixture-of-Agents)

The MoA pattern (Wang et al. 2024) runs multiple proposers independently and synthesizes their outputs: propose → aggregate. Diversity of proposals improves quality, even when individual proposers are weaker models.

When to use it

Tasks benefiting from diverse perspectives or creative responses
Analysis, evaluation, and synthesis problems
Quality improvement through ensemble reasoning

Quick start

from qitos.recipes.moa import MoAOrchestrator, MoACritic

agent = MoAOrchestrator(llm=my_llm)
result = agent.run(
    task="Evaluate the system architecture design for ...",
    critics=[MoACritic(proposer_count=3, max_rounds=1)],
    max_steps=15,
    return_state=True,
)
print(result.state.synthesis)  # the aggregated answer

How it works

Collect: MoACritic checks if enough proposals have been gathered. If not, it returns retry with an instruction to gather more proposals.
Aggregate: When all proposals are collected, the critic prompts for synthesis.
Output: When synthesis is complete and meets the quality threshold, the critic returns stop.

For parallel proposer execution with actual multi-agent delegation, use qitos.kit.patterns.moa.build_moa_system().

MoACritic parameters

Parameter	Default	Description
`proposer_count`	3	Expected number of proposals
`max_rounds`	1	Maximum proposal-aggregation rounds
`quality_threshold`	0.6	Minimum score to accept synthesis

MoARecipeState fields

Field	Type	Description
`proposals`	`List[Dict]`	Collected proposals with proposer and content
`synthesis`	`str`	Final synthesized answer
`round_count`	`int`	Current round number
`max_rounds`	`int`	Round budget
`proposer_count`	`int`	Expected proposal count

Magentic-One

The Magentic-One pattern (Furtado et al. 2024) uses an orchestrator with a dual-ledger architecture: plan → delegate → track progress → re-plan when stuck. The orchestrator maintains a Fact Bank and Task Ledger, delegates to specialist agents, and re-plans when progress stalls.

When to use it

Complex, multi-step tasks requiring coordination of different capabilities
Tasks where an orchestrator needs to adapt its plan based on intermediate results
Open-ended problems with research, coding, and analysis subtasks

Quick start

from qitos.recipes.magentic_one import (
    MagenticOneOrchestrator,
    ProgressCritic,
    MagenticOneState,
)

agent = MagenticOneOrchestrator(llm=my_llm)
result = agent.run(
    task="Research and summarize the latest findings on ...",
    critics=[ProgressCritic(max_stalls=3)],
    max_steps=30,
    return_state=True,
)
print(result.state.fact_bank)        # accumulated facts
print(result.state.completed_tasks)  # finished subtasks

How it works

Plan: The orchestrator creates a task ledger and gathers initial facts.
Delegate: At each step, a subtask is assigned to a specialist.
Track: ProgressCritic evaluates whether new facts have been gathered or tasks completed.
Re-plan: If no progress is detected for max_stalls consecutive steps, the critic returns retry with re-planning guidance.
Stop: When a FINAL ANSWER is provided, or when stall budget is exhausted.

ProgressCritic parameters

Parameter	Default	Description
`max_stalls`	3	Maximum consecutive no-progress steps
`progress_threshold`	0.5	Minimum score to consider progress

MagenticOneState fields

Field	Type	Description
`fact_bank`	`List[str]`	Accumulated facts and educated guesses
`task_ledger`	`List[str]`	Current plan of subtasks
`completed_tasks`	`List[str]`	Finished subtasks
`stall_count`	`int`	Consecutive no-progress steps
`max_stalls`	`int`	Stall budget before forced stop
`specialist_calls`	`int`	Number of specialist delegations
`current_subtask`	`str`	Currently active subtask

Scaffolding a new agent

Use the qit new CLI command to scaffold a new agent project from the built-in cookiecutter template:

# Create a new agent with default settings
pip install qitos[cookiecutter]
qit new --agent-name my_agent --agent-description "My custom agent"

# List available templates
qit list-templates

# Create with full customization
qit new \
  --agent-name code_reviewer \
  --agent-description "Reviews code for security issues" \
  --author "My Team" \
  --default-model qwen-plus \
  --max-steps 20

The scaffolded project includes:

src/agent.py — Agent class with State, init_state, build_system_prompt, reduce
configs/default.yaml — Default model and step configuration
tests/test_agent.py — Basic smoke tests
snowl_compat.py — Snowl evaluation compatibility adapter
eval_config.yaml — Evaluation configuration

Building your own method template

To create a custom method template, follow the same Agent + Critic pattern:

Define a state that extends StateSchema with your pattern’s tracking fields
Implement a critic that returns retry with instruction_patch and state_patch when the pattern requires iteration
Implement an agent whose build_system_prompt() injects pattern context from state

from dataclasses import dataclass, field
from typing import Any, Dict, List
from qitos import AgentModule, Decision, StateSchema
from qitos.engine.critic import Critic
from qitos.engine.critic_result import CriticResult
from qitos.kit.parser import ReActTextParser

@dataclass
class MyMethodState(StateSchema):
    iteration: int = 0
    max_iterations: int = 5
    history: List[str] = field(default_factory=list)

class MyMethodCritic(Critic):
    def evaluate(self, state, decision, results):
        if not isinstance(state, MyMethodState):
            return CriticResult(action="continue")
        if state.iteration < state.max_iterations:
            return CriticResult(
                action="retry",
                score=0.5,
                instruction_patch="Try again with a different approach.",
                state_patch={"iteration": state.iteration + 1},
            )
        return CriticResult(action="stop", reason="Max iterations reached.")

class MyMethodAgent(AgentModule[MyMethodState, Dict[str, Any], Any]):
    def __init__(self, llm=None, **kwargs):
        super().__init__(llm=llm, model_parser=ReActTextParser(), **kwargs)

    def init_state(self, task, **kwargs):
        return MyMethodState(task=task, max_steps=kwargs.get("max_steps", 10))

    def build_system_prompt(self, state):
        prompt = "You are a method agent. Iterate until done."
        if state.history:
            prompt += "\n\nPrevious attempts:\n" + "\n".join(state.history)
        return prompt

    def prepare(self, state, observation):
        return f"Task: {state.task}\nIteration: {state.iteration}"

    def reduce(self, state, observation, decision, action_results):
        return state

​What is a method template?

​Self-Refine

​When to use it

​Quick start

​How it works

​SelfRefineCritic parameters

​SelfRefineState fields

​Customizing the quality scorer

​Reflexion

​When to use it

​Quick start

​How it works

​ReflexionCritic parameters

​ReflexionState fields

​LATS

​When to use it

​Quick start

​How it works

​LATSCritic parameters

​LATSState fields

​MoA (Mixture-of-Agents)

​When to use it

​Quick start

​How it works

​MoACritic parameters

​MoARecipeState fields

​Magentic-One

​When to use it

​Quick start

​How it works

​ProgressCritic parameters

​MagenticOneState fields

​Scaffolding a new agent

​Building your own method template

What is a method template?

Self-Refine

When to use it

Quick start

How it works

SelfRefineCritic parameters

SelfRefineState fields

Customizing the quality scorer

Reflexion

When to use it

Quick start

How it works

ReflexionCritic parameters

ReflexionState fields

LATS

When to use it

Quick start

How it works

LATSCritic parameters

LATSState fields

MoA (Mixture-of-Agents)

When to use it

Quick start

How it works

MoACritic parameters

MoARecipeState fields

Magentic-One

When to use it

Quick start

How it works

ProgressCritic parameters

MagenticOneState fields

Scaffolding a new agent

Building your own method template