https://jiajia.fun/qa/8c12b9f8-%E7%94%A8-python-%E4%BB%8E%E9%9B%B6%E5%86%99%E4%B8%80%E4%B8%AA%E5%8D%95%E6%9C%BA-agent-runtime-%E5%BA%94%E8%AF%A5%E6%80%8E%E4%B9%88%E5%BC%80%E5%A7%8B

# 用 Python 从零写一个单机 Agent Runtime，应该怎么开始

从零写单机 Agent Runtime，最忌讳一上来就引一堆重型框架或者先搭 RAG、多 Agent 调度。单机 Runtime 的本质其实很薄，先把最小闭环跑通，再往外长护栏。 建议按这个顺序动手，两天就能写出一个能干活的原型： 第一步，直接用原生 SDK（openai 或 anthropic）写死核心的 while 循环。不要套 LangChain 这类重封装，自己控循环才能看清 KV Cache 前缀、streaming 和协议细节。循环的逻辑就四步：把当前 messages 和 tools 发给模型；拿到回复后如果有 tool\_calls，就依次执行；把 tool result 拼回 messages；没 tool\_calls 或者达到 max\_turns 就退出。 第二步，先实现最小工具集，别急着接 MCP。单机干活最核心的就四个工具：bash、read\_file、write\_file、edit\_file。用 Python 的 inspect 配合 Pydantic 就能从函数签名和 docstring 自动生成 JSON Schema 喂给模型。这里有两个工程坑必须第一天就堵住：一是 bash 必须设超时（比如 30 秒）和工作目录限制，防止模型跑个死循环或者把环境搞乱；二是工具返回必须做截断，比如超过几千字符就只留头尾并把完整输出写进临时文件，不然一次 ls 或 grep 就能把上下文撑爆。 第三步，把状态持久化做成纯文件。单机环境没必要一上来就上数据库，直接用 JSONL 按追加写的方式把每次的 user 消息、assistant 回复、tool call 和 tool result 存到本地文件里。这样天然支持断点续传（--resume），出问题了也能直接翻文件 debug。 第四步，补上基本的 Harness 护栏。在工具执行前后留出 Hook 切面：执行前做高危动作拦截（比如删库、改环境变量前挂起等人工确认）和步数/Token 熔断；执行后做确定性检查（比如改完代码自动跑一下 lint 或单测，把报错直接塞回 tool result 逼着模型修）。 至于上下文管理，初期别搞复杂的记忆框架。先把系统提示词和当前工作目录的文件树索引放进初始上下文，剩下的让模型自己用工具按需读文件。等这套单机闭环跑顺了、攒出真实 badcase 了，再去考虑子进程隔离（如 git worktree）和上下文压缩。
