构建第一个 Agent

从零开始构建一个可运行的 QitOS 最小 coding agent：state、model、tools、run 与 qita 检查。

每个 QitOS agent 都遵循同一条执行路径：AgentModule + Engine + Trace。你负责定义策略，Engine 负责执行循环。本页会用 examples/quickstart/minimal_agent.py 里的最小 coding agent，带你把这条主链路从头走一遍。

​

前置条件

• Python 3.10+
• 任意 OpenAI-compatible endpoint 的 API key

1. 安装 qitos 并设置模型配置

   pip install "qitos[models]"
   export OPENAI_API_KEY="sk-..."
   export OPENAI_BASE_URL="https://api.siliconflow.cn/v1/"
   export QITOS_MODEL="Qwen/Qwen3-8B"
   
2. 围绕 coding task 定义 state

   最小 QitOS coding agent 依然从一个强类型 StateSchema 开始：

   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"'
   

   核心心智模型是：task、scratchpad 和 verification contract 都显式放在 state 里，而不是藏在隐式胶水里。

3. 接入真实模型和 coding toolset

   这个最小示例故意保持模型驱动。它使用一个 OpenAI-compatible model，再配上 canonical coding preset：

   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()},
           )
   
4. 把 trajectory 归约回 state

   reduce() 是 QitOS 把 tool result 变成 agent 进度的地方：

       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。这一点在 coding agent 里也完全一样。

5. 种一个 workspace 并运行 agent

   最小示例会先创建一个带 bug 的小文件，再让 agent 去修它：

   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)
   
6. 用 qita 检查这次 run

   qita board --logdir ./runs
   

   board 默认启动在 http://127.0.0.1:8765。你可以用它检查 patch 轨迹、replay run，并把 trace 导出成 HTML。

​

完整示例

完整的最小 coding-agent 例子在这里：

• examples/quickstart/minimal_agent.py

你也可以直接运行打包好的版本：

qit demo minimal

​

常见错误

错误	症状	修复方式
忘记在 reduce 里 return state	StateValidationError 或 state 变成 None	reduce 最后总是返回 state
没有先配 provider config	run 还没开始就报 OPENAI_API_KEY / QITOS_API_KEY 错误	先导出 API key 和 base URL
从不做验证	agent 改了代码，但没有完成证明	把明确的 test_command 放进 state，并把它成功通过当成完成条件
prompt 和 parser 不匹配	每一步都出现 parse error	让 prompt 格式和 ReActTextParser 之类的显式 parser 对齐
toolset 给得过宽	run 在不必要的工具之间游走	先从最小 coding preset 开始，只有任务真的需要时再加工具

​

下一步建议

教程课程

沿着 ReAct、PlanAct、Claude Code 风格与安全审计路线继续学习

Agent 模式

在选模式之前，先比较不同 QitOS pattern family 的权衡

可观测性

用 qita board、replay 与 export 检查每次 run

Kit 参考

查看 lessons 里会用到的 parsers、toolsets 与 helpers