> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 构建第一个智能体
> 从零开始构建一个可运行的 QitOS 最小编码智能体：状态、模型、工具、运行与 qita 检查。
每个 QitOS 智能体都遵循同一条执行路径：`AgentModule + Engine + Trace`（追踪记录）。你负责定义策略，Engine 负责执行循环。本页会用 `examples/quickstart/minimal_agent.py` 里的最小编码智能体，带你把这条主链路从头走一遍。
## 前置条件
* Python 3.10+
* 任意 OpenAI-compatible 端点的 API key
```bash theme={null}
pip install "qitos[models]"
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.siliconflow.cn/v1/"
export QITOS_MODEL="Qwen/Qwen3-8B"
```
最小 QitOS 编码智能体依然从一个强类型 `StateSchema` 开始：
```python theme={null}
from dataclasses import dataclass, field
from qitos import StateSchema
@dataclass
class MinimalCodingState(StateSchema):
scratchpad: list[str] = field(default_factory=list)
target_file: str = "buggy_module.py"
test_command: str = 'python -c "import buggy_module; assert buggy_module.add(20, 22) == 42"'
```
核心心智模型：任务、草稿区和验证契约都显式放在状态里，而不是藏在隐式胶水里。
这个最小示例故意保持模型驱动，使用一个 OpenAI-compatible 模型，再配上规范编码预设（preset，预配置的模型家族默认值）：
```python theme={null}
from typing import Any
from qitos import Action, AgentModule, Decision
from qitos.kit import REACT_SYSTEM_PROMPT, ReActTextParser, format_action, render_prompt
from qitos.kit.toolset import coding_tools
from qitos.models import OpenAICompatibleModel
class MinimalCodingAgent(AgentModule[MinimalCodingState, dict[str, Any], Action]):
def __init__(self, llm: OpenAICompatibleModel, workspace_root: str) -> None:
super().__init__(
toolset=[coding_tools(workspace_root=workspace_root, shell_timeout=20, include_notebook=False)],
llm=llm,
model_parser=ReActTextParser(),
)
def init_state(self, task: str, **kwargs: Any) -> MinimalCodingState:
return MinimalCodingState(
task=task,
max_steps=int(kwargs.get("max_steps", 8)),
target_file=str(kwargs.get("target_file", "buggy_module.py")),
test_command=str(kwargs.get("test_command")),
)
def build_system_prompt(self, state: MinimalCodingState) -> str | None:
_ = state
return render_prompt(
REACT_SYSTEM_PROMPT,
{"tool_schema": self.tool_registry.get_tool_descriptions()},
)
```
`reduce()` 是归约（reduce，将观测结果和决策归约回状态的钩子），也是 QitOS 把工具执行结果变成智能体进度的地方：
```python theme={null}
def reduce(
self,
state: MinimalCodingState,
observation: dict[str, Any],
decision: Decision[Action],
) -> MinimalCodingState:
action_results = observation.get("action_results", [])
if decision.rationale:
state.scratchpad.append(f"Thought: {decision.rationale}")
if decision.actions:
state.scratchpad.append(f"Action: {format_action(decision.actions[0])}")
if action_results:
first = action_results[0]
state.scratchpad.append(f"Observation: {first}")
if isinstance(first, dict) and int(first.get("returncode", 1)) == 0:
state.final_result = "Patch applied and verification passed."
return state
```
`reduce` 必须返回 `state`。在编码智能体里也一样。
最小示例会先创建一个带 bug 的小文件，再让智能体去修它：
```python theme={null}
from pathlib import Path
WORKSPACE = Path("./playground/minimal_coding_agent")
TARGET_FILE = "buggy_module.py"
TASK = "Fix the bug in buggy_module.py and make the verification command pass."
def seed_workspace() -> None:
WORKSPACE.mkdir(parents=True, exist_ok=True)
target = WORKSPACE / TARGET_FILE
if not target.exists():
target.write_text("def add(a, b):\n return a - b\n", encoding="utf-8")
def main() -> None:
seed_workspace()
agent = MinimalCodingAgent(llm=build_model(), workspace_root=str(WORKSPACE))
result = agent.run(
task=TASK,
workspace=str(WORKSPACE),
max_steps=8,
target_file=TARGET_FILE,
return_state=True,
)
print("final_result:", result.state.final_result)
print("stop_reason:", result.state.stop_reason)
```
```bash theme={null}
qita board --logdir ./runs
```
看板默认启动在 `http://127.0.0.1:8765`。你可以用它检查补丁轨迹、回放运行，并把追踪记录导出成 HTML。
## 完整示例
完整的最小编码智能体例子在这里：
* [`examples/quickstart/minimal_agent.py`](https://github.com/Qitor/qitos/blob/main/examples/quickstart/minimal_agent.py)
你也可以直接运行打包好的版本：
```bash theme={null}
qit demo minimal
```
## 常见错误
| 错误 | 症状 | 修复方式 |
| ----------------------------- | ---------------------------------------------- | -------------------------------------- |
| 忘记在 `reduce` 里 `return state` | `StateValidationError` 或状态变成 `None` | `reduce` 最后务必返回 `state` |
| 没有先配置提供商 | 运行还没开始就报 `OPENAI_API_KEY` / `QITOS_API_KEY` 错误 | 先导出 API key 和 base URL |
| 从不做验证 | 智能体改了代码，但没有完成证明 | 把明确的 `test_command` 放进状态，并把它成功通过当成完成条件 |
| 提示词和解析器不匹配 | 每一步都出现解析错误 | 让提示词格式和 `ReActTextParser` 之类的显式解析器对齐 |
| 工具集给得过宽 | 运行在不必要的工具之间游走 | 先从最小编码预设开始，只有任务真的需要时再加工具 |
## 下一步建议
沿着 ReAct、PlanAct、Claude Code 风格与安全审计路线继续学习
在选模式之前，先比较不同 QitOS 模式家族的权衡
用 qita 看板、回放与导出检查每次运行
查看课程里会用到的解析器、工具集与辅助函数