Configuration

All configuration options available in QitOS: AgentModule.run() arguments, Engine constructor arguments, tracing controls, and environment variables.

QitOS is configured through three overlapping layers:

1. AgentModule.run() keyword arguments — the normal per-run entrypoint
2. Engine constructor keyword arguments — lower-level runtime control
3. Environment variables — provider credentials and model defaults

---

AgentModule.run() arguments

All of the following can be passed to agent.run(task, ...). This is the canonical user-facing configuration surface for QitOS runs.

Task and execution

Argument	Type	Default	Description
task	str | Task	required	Task objective string or structured Task object
max_steps	int | None	None	Override TaskBudget.max_steps; also sets state.max_steps via state_kwargs
return_state	bool	False	Return the full EngineResult instead of just state.final_result
workspace	str | None	None	Path to workspace root; automatically constructs a HostEnv and sets env_spec on the task
env	Any	None	Explicit Env instance; takes precedence over workspace

Parsing and decisions

Argument	Type	Default	Description
parser	Any	None	Parser (a component that converts raw model output into a typed Decision) instance (e.g. ReActTextParser, JsonDecisionParser) forwarded to the Engine
search	Any	None	Search strategy instance for branch decisions (e.g. DynamicTreeSearch)
critics	List[Any] | None	None	List of Critic (a module that evaluates each step and can trigger retries or stops) instances evaluated after each step
stop_criteria	List[Any] | None	None	Custom stop criteria list; replaces the default FinalResultCriteria
history_policy	Any	None	HistoryPolicy instance controlling message history window

Tracing and rendering

Argument	Type	Default	Description
trace	Any	None	True to enable default TraceWriter; pass a TraceWriter instance for full control; False/None disables tracing only if trace_writer is not already set in engine_kwargs
trace_logdir	str	"./runs"	Directory where trace run subdirectories are created
trace_prefix	str | None	None	Prefix for the auto-generated run ID; defaults to agent.name
render	Any	None	True to enable the default ClaudeStyleHook render hook; pass a hook instance for custom rendering
theme	str	"research"	Theme name passed to the render hook

Hooks and engine passthrough

Argument	Type	Default	Description
hooks	List[Any] | None	None	Additional EngineHook instances appended to the Engine’s hook list
render_hooks	List[Any] | None	None	Additional render hook instances merged into hooks
engine_kwargs	Dict[str, Any] | None	None	Any Engine constructor keyword argument; lower-priority than the explicit arguments above
**state_kwargs	Any		Extra keyword arguments forwarded to agent.init_state()

Minimal example

result = agent.run(
    task="Analyse the repository and list all public API functions.",
    workspace="/path/to/repo",
    max_steps=20,
    trace_logdir="./experiment-runs",
    trace_prefix="api-analysis",
)

---

Engine constructor arguments

When you construct an Engine directly (or via engine_kwargs), these parameters are available:

Parameter	Type	Default	Description
agent	AgentModule	required	The agent whose hooks the Engine calls
budget	RuntimeBudget | None	RuntimeBudget(max_steps=10)	Step, time, and token budgets for the run
validation_gate	StateValidationGate | None	default gate	Validates state before and after each phase
recovery_handler	RecoveryHandler | None	None	Callable (state, phase, exc) -> None invoked on recoverable errors
recovery_policy	RecoveryPolicy | None	RecoveryPolicy()	Controls retry behaviour and backoff
trace_writer	TraceWriter | None	None	Writes trace (a structured log of all run events and steps) artifacts; set via AgentModule.run(trace=True)
parser	Parser[ActionT] | None	None	Parser (a component that converts raw model output into a typed Decision); converts raw LLM output to Decision
stop_criteria	List[StopCriteria] | None	[FinalResultCriteria()]	Ordered stop criteria evaluated after each step
branch_selector	BranchSelector | None	FirstCandidateSelector()	Selects among branch candidates
search	Search | None	None	Search strategy for expanding and scoring branch candidates
critics	List[Critic] | None	[]	Critics (modules that evaluate each step and can trigger retries or stops) evaluated after each step
env	Env | None	None	Environment for observe/step/is_terminal lifecycle
history_policy	HistoryPolicy | None	HistoryPolicy()	Controls how history messages are assembled for model calls
hooks	List[EngineHook] | None	[]	Engine lifecycle hooks
render_hooks	List[Any] | None	None	Render hooks merged into hooks

RuntimeBudget fields

@dataclass
class RuntimeBudget:
    max_steps: int = 10
    max_runtime_seconds: Optional[float] = None
    max_tokens: Optional[int] = None

When a Task object is passed to Engine.run(), the Task.budget values override the Engine’s RuntimeBudget for that run.

---

Environment variables

Variable	Required	Description
OPENAI_API_KEY	Yes (for OpenAI / compatible APIs)	API key sent in the Authorization header. Used by OpenAIModel and OpenAICompatibleModel
OPENAI_BASE_URL	Yes (for compatible APIs)	Base URL of the API endpoint. Required by OpenAICompatibleModel; optional for OpenAIModel (defaults to https://api.openai.com/v1)
QITOS_API_KEY	No	Alternative API key variable. Recognized by ModelFactory.from_env() as a fallback when OPENAI_API_KEY is not set
QITOS_MODEL	No	Default model identifier. Read by ModelFactory.from_env() to select the model when none is specified in code
AZURE_OPENAI_API_KEY	Only for Azure	API key for Azure OpenAI. Used by AzureOpenAIModel
AZURE_OPENAI_ENDPOINT	Only for Azure	Endpoint URL for Azure OpenAI
AZURE_OPENAI_DEPLOYMENT	No	Deployment name for Azure OpenAI
AZURE_OPENAI_API_VERSION	No	API version; defaults to 2024-02-15-preview

Example .env file

# OpenAI-compatible endpoint (e.g. SiliconFlow, Ollama proxy)
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.siliconflow.cn/v1/

---

Trace output directory structure

By default, AgentModule.run() writes traces to ./runs/. Each run creates one subdirectory:

<trace_logdir>/
└── <trace_prefix>_<YYYYMMDD_HHMMSS_ffffff>/
    ├── manifest.json    # Run metadata and final summary
    ├── events.jsonl     # All runtime events (one JSON object per line)
    └── steps.jsonl      # All step records (one JSON object per line)

Auto-generated run ID format

<agent.name>_<YYYYMMDD_HHMMSS_ffffff>

Override the prefix with trace_prefix:

agent.run(task="...", trace_prefix="experiment-01")
# → runs/experiment-01_20260407_120000_123456/

Pointing qita board at your trace directory

qita board --logdir ./runs

Tracing is enabled by default in AgentModule.run(). Set trace=False only for quick interactive experiments — disabling tracing means runs cannot be replayed or inspected with qita.