配置

QitOS 的配置入口总览：AgentModule.run() 参数、Engine 构造参数、追踪控制与环境变量。

QitOS 的配置主要分三层：

1. AgentModule.run() 关键字参数：最常见、最推荐的每次运行配置入口
2. Engine 构造函数参数：更底层的运行时控制
3. 环境变量：供应商凭证与模型默认值

​

AgentModule.run() 参数

这些参数都可以直接传给 agent.run(task, ...)：

任务与执行

• task：str | Task
• max_steps
• return_state
• workspace
• env

解析与决策

• parser
• search
• critics（评估器，可批准、停止或重试当前步骤）
• stop_criteria
• history_policy

追踪与渲染

• trace
• trace_logdir
• trace_prefix
• render
• theme

钩子与 Engine 透传

• hooks
• render_hooks
• engine_kwargs
• **state_kwargs

一个典型例子：

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 构造参数

当你直接构造 Engine 时，最常用的参数包括：

• agent
• budget（预算）
• validation_gate
• recovery_handler
• recovery_policy
• trace_writer
• parser
• stop_criteria
• branch_selector
• search
• critics（评估器）
• env
• history_policy
• hooks（钩子）

RuntimeBudget 的常见字段：

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

​

环境变量

常见环境变量包括：

变量	用途
OPENAI_API_KEY	OpenAI / OpenAI 兼容 API 密钥
OPENAI_BASE_URL	OpenAI 兼容端点基础 URL
QITOS_API_KEY	ModelFactory.from_env() 可识别的备用密钥
QITOS_MODEL	默认模型 ID
AZURE_OPENAI_API_KEY	Azure OpenAI 密钥
AZURE_OPENAI_ENDPOINT	Azure OpenAI 端点
AZURE_OPENAI_DEPLOYMENT	Azure 部署名称
AZURE_OPENAI_API_VERSION	Azure API 版本

示例：

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.siliconflow.cn/v1/

​

追踪输出目录

默认情况下，AgentModule.run() 会把追踪记录写到 ./runs/：

<trace_logdir>/
└── <trace_prefix>_<YYYYMMDD_HHMMSS_ffffff>/
    ├── manifest.json
    ├── events.jsonl
    └── steps.jsonl

你可以通过 trace_prefix 覆盖自动生成的前缀：

agent.run(task="...", trace_prefix="experiment-01")

然后用：

qita board --logdir ./runs

来查看这些结果。