Build a general-task agent from scratch (Manus lineage): follow one task, assemble it piece by piece

What you write: the single entry chat

chat(messages, tools, *, system=None, tool_choice="auto") ->
  { content: str | None,                      # 模型说的话
    tool_calls: [{id, name, arguments: dict}]  # 模型想调用的工具（可能为空）
  }

• messages: the dialogue history so far (who said what).
• tools: this turn, tell the model “which tools you have in your hands” (the next step will use this; leave the slot now).
• tool_calls[].arguments: must already be a dictionary after json.loads. Do not pass the raw string downstream—this is one of the most common blow-ups.

Compare with real source

OpenManus’s entry at this layer is LLM.ask_tool (app/llm.py). Three details are worth copying its wisdom:

• Give timeout enough room: default 300 seconds (llm.py:648). Research tasks often wait a long time for the model to think; a timeout that is too short will kill it by mistake.
• Do not retry quota errors in a death loop: network jitter can retry, but an error such as “token exceeded” will not help no matter how many times you retry. OpenManus specifically comments Don’t retry TokenLimitExceeded (llm.py:641-642).
• Empty replies must error: the model occasionally returns empty choices; then you must throw explicitly (llm.py:737-740). You must not silently treat it as “nothing to say”—otherwise the loop will spin empty.

Acceptance (after this step, run these)

断言 1：不给任何工具，纯聊天，能拿到 content。
断言 2：给它一个「结束工具」的说明，然后 prompt「请直接结束」，它能返回一个 name=terminate 的 tool_call。
断言 3：故意填错 API key → 抛错或记下可读的错误，绝不静默空转。

How it most easily blows up

• Pass arguments to the tool as a raw string → execution downstream will explode. json.loads it at this client layer.
• Reach for “streaming” immediately, then execute a tool call whose arguments arrived only half-formed → for Gate 1, first use non-streaming, get a complete reply, then talk about the rest.

🧠 One sentence: the brain can only speak. It can give you a perfect suggestion, and it cannot change a single byte—so next, we have to give it a hand.

What a tool looks like: one mold for all

Every “hand” is a tool object that looks the same:

Tool:
  name: str                 # 模型按这个名字点单
  description: str          # 告诉模型「这只手能干嘛、什么时候用」
  parameters: JSONSchema    # 规定参数格式
  async execute(**kwargs) -> ToolResult   # 真正干活的函数

ToolCollection（工具箱）:
  to_params()               # 把所有工具的「说明书」打包给模型看
  execute(name, arguments)  # 按名字找到对应工具、跑它

Compare OpenManus: BaseTool.to_param (app/tool/base.py:124-137) turns a tool into a format the model can read; ToolCollection.execute (tool_collection.py:25-35) dispatches by name.

First build the two plainest hands; script α is enough

Hand one: fetch_url — read a URL

parameters: { url: string, max_chars?: number = 20000 }
行为:
  - 只允许 http / https
  - 超时 15 秒
  - 剥掉 <script>/<style>，正文转成干净文本
  - 太长就切断，并注明「已截断」
失败: 返回 ToolResult(error="...")，不要抛异常炸穿循环

Hand two: write_file — write the summary to disk

parameters: { path: string, content: string }
行为:
  - 算出真实路径后，必须仍在 workspace 目录内（防止 ../../ 穿越出去）
  - 自动创建父目录
  - 返回「已写入 N 字节到 ...」
失败: 路径穿越 / 磁盘错误 → 返回 error 字符串

One iron rule: tool failure must become an “observation”; it must not blow up the whole task

This is the core of why a research agent can survive dirty pages and bad links. When you execute any hand, walk this pipe:

flowchart TD
    CALL["模型点单：调用某个工具"] --> N{"这个工具存在吗？"}
    N -->|"不存在"| E1["返回一句 Error 文本"]
    N -->|"存在"| J{"参数能解析成 JSON 吗？"}
    J -->|"不能"| E2["返回一句 Error 文本"]
    J -->|"能"| X{"执行时抛异常了吗？"}
    X -->|"抛了"| E3["返回一句 Error 文本 + 记日志"]
    X -->|"没抛"| OK["返回执行结果"]
    E1 --> OBS["全都变成一条『观察』
写回对话历史"]
    E2 --> OBS
    E3 --> OBS
    OK --> OBS
    OBS --> NEXT["模型下一圈看到它，自己换招"]
    style OBS fill:#fff3df
    style NEXT fill:#e7f8f1

Principle: tool failure, by default, becomes an observation text fed back to the model, so it can change tactics next turn. Do not write it as “one failure blows up the whole task.” Compare OpenManus’s execute_tool (toolcall.py:166-208)—unknown tool, JSON parse failure, execution exception, all are collected into an Error: ... string and returned, not thrown out.

Acceptance

断言：调用一个不存在的工具 → 循环继续，历史末尾是一条 error 观察。
断言：给 write_file 传 path="../../etc/passwd" → 返回 error，且你电脑上那个文件没被动。
断言：工具箱的 to_params() 能被真实的 OpenAI SDK 接受（拿真 API 打一轮）。

How it most easily blows up

• write_file does not validate paths → one sentence from the model can write a file anywhere on your whole disk. After you compute the absolute path, you must confirm it is still inside workspace.
• The tool raises on first failure → one bad link can blow up the whole task. Soft-fail, always soft-fail.

🖐️ One sentence: the model orders, the harness plates. Tool failure is not an accident; it is “one observation”—let the model change tactics itself.

Skeleton of the loop

flowchart TD
    START(["进入循环：历史里已经有用户那句话"]) --> GATE{"还没超步数上限？
而且还没喊停？"}
    GATE -->|"否"| BUDGET["预算耗尽 → 收尾走人"]
    GATE -->|"是"| THINK["🧠 think：把历史发给模型
问它下一步干嘛"]
    THINK --> Q{"模型这一圈
调工具了吗？"}
    Q -->|"没调，只说了话"| MAYBE["它是不是想收尾了？
（见第 4 步）"]
    Q -->|"调了"| ACT["🖐️ act：真去执行工具
把结果写回历史"]
    ACT --> STOP{"刚才那个工具
是 terminate 吗？"}
    STOP -->|"是"| FIN["翻状态 = 完成 → 退出"]
    STOP -->|"否"| GATE
    MAYBE --> GATE
    style THINK fill:#eef2f7
    style ACT fill:#eaf1ff
    style FIN fill:#e7f8f1

Compare with real source: three thin layers stacked

OpenManus’s heart is not some 2000-line mega-function. It is three small files stacked:

step is short enough to understand at a glance:

# react.py:33-38
async def step(self) -> str:
    should_act = await self.think()          # 想：要不要动手？
    if not should_act:
        return "Thinking complete - no action needed"
    return await self.act()                  # 做：真去执行

The outer run is also a plain while (base.py:116-154; here we grab the skeleton):

if self.state != AgentState.IDLE:            # ① 门禁：非空闲不许跑
    raise RuntimeError(...)
if request:
    self.update_memory("user", request)      # ② 把用户那句话记进历史
while self.current_step < self.max_steps and self.state != AgentState.FINISHED:
    self.current_step += 1
    await self.step()                        # ③ 想一步、做一步
    if self.is_stuck():                      # ④ 卡住了？（第 9 步讲）
        self.handle_stuck_state()

Three disciplines you must copy

1. Gate: if the state is not “idle,” it may not start (base.py:128-129). Prevents the same agent from being triggered concurrently at random.
2. Tools execute serially: if the model ordered several tools in the same turn, one by one, do not concurrent (toolcall.py:141). Gate 1 wants stability, not speed.
3. Cleanup must always run: success, failure, or exception, browser and connections and those resources must be cleaned at the end (cleanup at toolcall.py:229-250).

On the “step budget”

Giving the loop a max_steps is the safety rope that stops it from burning money forever. In OpenManus, Manus defaults to 20 steps (manus.py:27-28).

• Running golden tasks: set 12–20 steps.
• Want to test the “budget exhausted” path: deliberately set it to 3 steps.

Compare other projects and you will see what magnitude 20 is: some agents default to 40, even 200 steps. OpenManus’s 20 steps reveal its position—one “homework shift.” Long tasks get another planning layer outside, rather than stretching one loop to hundreds of steps.

Acceptance

断言：max_steps=1，任务又确实需要用工具 → 结果是「预算耗尽」，行为稳定可复现。
断言：同一圈里模型点了两个工具 → 它们按顺序执行（看日志时间戳是递增的）。
断言：清理函数在「成功 / 失败 / 抛异常」三条路径下都会跑到（用一个计数器 mock 验证）。

How it most easily blows up

• The loop has no step budget → the model can wander into a dead end and burn your wallet empty.
• Week one you already want “several tools in parallel” → concurrency bugs will keep you debugging at the moment you most need to verify the main logic. Serial first.

🔁 One sentence: think one step, do one step, stuff the result back, think again—this circle turning, turn after turn, is the agent’s entire life.

What you write: the terminate contract

{
  "name": "terminate",
  "description": "任务完成、或你无法继续时，调用它来结束工作。",
  "parameters": {
    "type": "object",
    "properties": {
      "status": { "type": "string", "enum": ["success", "failure"] },
      "summary": { "type": "string", "description": "给用户的一段话，说清你干了什么" }
    },
    "required": ["status"]
  }
}

Compare OpenManus app/tool/terminate.py—it has only the one enum field status. We add a summary on top of that, so when the model closes it can hand the user one sentence of human speech.

A tool is not enough; you have to teach it in the “manual”

The model will not be born knowing “after you write the file, call terminate.” You have to say it in the system prompt (step 6 will expand this; remember this hard rule first):

When the thing to deliver already exists under workspace/, you must call terminate(success). Do not keep chatting.

Compare OpenManus’s prompt (prompt/manus.py:9): “If you want to stop the interaction at any point, use the terminate tool.”

Acceptance

断言：prompt「什么都别做，直接结束」→ 头一两步内就出现 terminate 调用。
断言：terminate 之后不再发起任何模型调用（看日志，步数停住了）。
断言：status=failure 时，进程的退出码 ≠ 0（或返回结果里 ok=false）。

How it most easily blows up

• Expect “the model went quiet = finished” → it will empty-spin until the budget is gone. You must have explicit terminate.
• Treat terminate’s “return value” as the stop signal → stopping depends on flipping state, not on that return text.

🔔 One sentence: clocking out requires punching the card. The model saying “I am done” does not count; it has to press the terminate bell with its own hand.

What you write: Message + Memory

Message（一条消息）:
  role: system | user | assistant | tool   # 谁说的
  content: str | None                       # 说了什么
  tool_calls?: [...]                         # assistant 发起的工具调用
  tool_call_id? / name?                      # tool 回执用
  base64_image?: str                         # 可选，调研看图时用

Memory（记忆本）:
  messages: list[Message]
  max_messages: int = 100                    # 上限
  add_message() / clear() / get_recent(n)

Compare OpenManus app/schema.py:54-62 (Message) and :159-187 (Memory).

What if memory will not fit? Gate 1: hard cut

The model’s context has a capacity limit. History rolls longer and longer; eventually it will not fit. The plainest method is keep only the last N messages:

# schema.py:167-168
if len(self.messages) > self.max_messages:
    self.messages = self.messages[-self.max_messages:]

Hard cut, no summary—OpenManus does exactly this at Gate 1, default keep the last 100 (schema.py:161). Do not rush to the advanced game of “use a large model to compact history.” Get it running first.

A discipline table for “what goes into memory”

This table is where beginners most easily dirty the context. Follow it:

How it most easily blows up (OpenManus itself stepped in this pit)

Every turn OpenManus appends a “this-turn reminder” (the next_step sticky note) into memory (toolcall.py:41-43). Run 20 turns and history may be stacked with nearly 20 almost identical sticky notes, eating the 100-message quota for nothing.

Your improvement, pick one:

1. Recommended: this-turn reminder is sent to the model only as a “temporary message,” not written permanently into memory.
2. Writing it in is also fine, but raise the cap to 200, and mark “truncation happened” in the log.

Two more pits:

• The same agent instance runs two tasks in a row, you forgot memory.clear() → the second task will “taste of the first,” reading the first task’s history (when OpenManus exhausts the budget it resets the step count, but does not clear memory, base.py:149-152).
• Large blobs such as browser screenshots stacked directly into memory → tokens explode fast.

Acceptance

断言：连续跑 30 步后，记忆条数 ≤ max_messages。
断言：同一个 Agent 实例第二次跑之前，必须先 memory.clear()——否则串味。
断言（若你选了「说明书不进记忆」策略）：导出记忆，里面不该有 role=system 的条目。

📓 One sentence: the model is amnesiac. That it can pick up each turn is entirely because we re-feed the whole history—that is context, and it is also why long conversations get slower and more expensive.

What you write: Gate 1’s system template (usable as-is)

你是 {name}，一个「调研并交付」的 Agent。
工作目录：{workspace 的绝对路径}
你只能在这个目录下面产出文件。

本次要交付的东西：
{deliverable_spec}   # 例：一份 summary.md，≥200 字，含原网址

规矩：
1. 优先用工具，别靠猜。缺数据就去抓、去搜。
2. 交付物在硬盘上出现后，立刻调 terminate(status="success", summary=...)。
3. 卡住了（断网/付费墙），调 terminate(status="failure", summary=...)。
4. 绝不要把 API key 写进任何文件或摘要里。

This template formally writes step 4’s hard rule—“after writing, you must terminate”—into the manual.

Why two layers?

Because some reminders are “identity that never changes” (who you are, which directory you may write) and some are “the temporary situation of this second” (which page the browser is on now). Mix them in one file and changing one disturbs the other. Split them and you can swap only one layer—when step 10 “clones a new specialist,” you will see that swapping only the system layer produces a brand-new specialist, without changing one line of loop code.

Acceptance

断言：同一套循环，只换 system prompt 文件，行为就从「写摘要」变成「订行程」。
断言：日志能打印出本轮实际用的 next_step 是哪一版，方便回放调试。

📜 One sentence: the manual decides the persona. Swap one manual and the same brain goes from “chat contestant” to “your specialist.”

Contracts of the three stages

Compare OpenManus: this closed loop hides in the action chain of the browser_use tool (browser_use_tool.py). One key detail is worth noticing—its web_search action searches and then jumps straight to the first result (browser_use_tool.py:251-268), gluing “search” and “open” together. And the “extract” step (extract_content, :375-444) calls the model once more inside the tool to distill the body—“a model nested inside a tool,” a common method for raising research quality, at the cost of slower and more tokens burned.

You can run the loop without a real browser first

Do not reach for Playwright on day one. First use the plainest four-piece set to prove the closed-loop semantics are connected:

web_search(query)         -> [{title, url}]     # 搜
fetch_url(url)            -> 干净正文            # 开（复用第 2 步）
extract_facts(goal, text) -> 要点清单           # 抽（内部再调一次模型）
write_file(...) + terminate                     # 交付 + 收尾

First prove “search → open → extract → deliver” strings together, then consider swapping in a real browser.

⚠️ When you go to a real browser, notice: OpenManus defaults disable_security=True (browser_use_tool.py:144)—it turned off the browser’s security restrictions to save trouble. This configuration must never be taken to a public deployment; before you go live you must turn it off and audit yourself.

Acceptance

断言：跑一个「查城市景点」的任务，日志里至少有 1 次 search、1 次 open、1 次 write_file、1 次 terminate。
断言：产出的文件里 ≥ 3 个真实链接。
断言：故意让搜索 API 失效 → 得到一条 error 观察，Agent 要么换引擎成功、要么最终 terminate(failure)，不许空转。

🔍 One sentence: search, open, extract; missing one is not research. This closed loop is where a “general-task agent” differs from a “chatbot.”

Acceptance

断言：输出的 HTML 里含那句固定的 footer 字符串。
断言：places ≥ 3，且每一项都带 url。

🧱 One sentence: you decide the shell; it fills the meat. Do not let the model waste effort writing CSS.

Besides terminate, three more clock-out bells

“Stuck” detection: the model started repeating

Sometimes the model will say the exact same thing for several turns in a row—it is stuck in one thought and cannot get out. OpenManus’s detection is plain (base.py:163-186): if this latest assistant message has appeared, character-for-character identical, ≥2 times among earlier ones, judge stuck.

The handling is also restrained—do not force-terminate; only add one sentence to the “this-turn reminder,” forcing it to change tactics:

“Noticed you are repeating. Change strategy; do not walk a dead road you already tried.”

Compare handle_stuck_state (base.py:163-168). You can strengthen: stuck 3 times in a row and still not changing, then terminate(failure).

Leave one log line per step

Debugging depends on it. Drop one JSON line per step (one line, one step):

{"step":3, "phase":"act", "tool":"fetch_url", "ok":true, "ms":812, "args":{"url":"https://..."}}

Never print a complete secret or a whole page of original text into the log (truncate to 500 characters). This log piece does not get a figure—it is line after line of text; a table and an example are clearer than a picture.

Acceptance

断言：断网跑剧本 α → 日志里出现 ok:false；进程不无限 while。
断言：max_steps=3 → 结局是「预算耗尽」，且 workspace 里可以有半成品。
断言：人为让模型复读同一句话 → 出现「卡住」日志，或本轮提醒里加进了那句换招提醒。

🛑 One sentence: network down, over budget, repeating—you need all three brakes, or the agent will crash or empty-spin and burn money.

Acceptance (this is Gate 1’s graduation exam)

断言：git diff 显示循环那个文件『零改动』，只新增了 specs/ 和 prompts/ 下的文件。
断言：两个专员都能独立跑通各自的黄金题。

Deliberately do not do yet

• A “planning flow” where several agents dispatch each other—OpenManus itself marked it unstable; Gate 1 does not touch it.
• Moving the whole MCP plugin ecosystem in—when you need it, then talk.

👥 One sentence: the loop is the generic chassis; a specialist is just a swapped manual. That is why adding a new specialist is almost zero cost.

Pain A · Two tasks overwrite each other’s files → workstation isolation

Where it hurts: two tasks run at once, both write workspace/summary.md—they overwrite each other, a mess.

Fix: when each task starts, issue a unique run_id, give it a dedicated workstation. One task, one directory; nobody steps on anybody.

flowchart TB
    RUN["新任务进来"] --> ID["发一个唯一 run_id
run_id = 'r_' + 随机串"]
    ID --> WS["专属工位
./workspaces/{run_id}/"]
    ID --> BR["（可选）专属 git 分支
agent/{run_id}"]
    WS --> W1["任务A 只在自己工位里写"]
    WS --> W2["任务B 只在自己工位里写"]
    W1 -. 井水不犯河水 .- W2
    style WS fill:#eaf1ff

Kortix pushes this idea to the extreme—it has an iron rule: session = sandbox = git branch, three in one, and once this identity is established it cannot be changed. Its source comment is hard (runtime-identity.ts): a sandbox holding user data is an “immutable identity boundary”—even if it crashes, you can only stop it, never swap in a new one to take its identity. Why so strict? Because once identity can be stolen and swapped, it means “task A’s artifact may be pinned on task B”—fatal for a multi-tenant platform.

Naming warning: in Kortix “conversation id” and “workstation id” are two different things; do not mix them. From day one, log these two fields separately.

验收：并行跑两个任务 → 它们的 workspace 路径不同；
     在 A 的工位里，找不到任何属于 B 的内容。

🚧 One sentence: one task, one workstation, one identity that cannot be stolen and swapped. That is the foundation of multi-task not fighting.

Pain B · Secrets leak into logs → secret gateway

Where it hurts: the task has to call a third-party service that needs an API key (send Slack, query Notion). If you let the agent itself hold the key and call, that key will eventually appear in some log, some deliverable—leak is only a matter of time.

Fix: build a wall in front of the key. The agent never gets the real key; it can only knock on a gateway carrying a request “I want to call X”; the gateway secretly fills in the key on its side, calls, and hands the result back (redacted).

flowchart LR
    subgraph SBX["Agent（跑在沙箱里）· 拿不到真钥匙"]
        REQ["「帮我调 slack.send，
参数是这些」"]
    end
    subgraph GW["网关（可信进程）· 保管钥匙"]
        SEC["从保险箱取出真钥匙"]
        CALL["拿钥匙调第三方"]
        RED["把结果脱敏后返回"]
    end
    REQ -->|"只带任务id + 请求，
不带钥匙"| SEC
    SEC --> CALL --> RED
    RED -->|"干净的结果"| REQ
    style SBX fill:#fdeded
    style GW fill:#eaf1ff

Compare Kortix’s Executor: the real credential is attached only on the side of the trusted API process; the sandbox running the agent holds only a restricted temporary token (executor/execute.ts, credentials.ts).

This wall also brings a side benefit—permission tiers. Since every third-party call must pass the gateway, the gateway can incidentally judge “should this operation be allowed.” Kortix’s policy engine (executor/policy.ts) splits actions into three bins, and the default is set cleverly:

This “read allowed, write needs approval” default (called default_mode = risk in source) is much safer than “allow everything,” and will not annoy you into confirming every read.

验收：在所有日志和交付物里搜 'sk-' / 'api_key' / 'Bearer' → 零命中。
     网关单测：不带任务凭证去请求 → 返回 401。

🔐 One sentence: the agent only hands over a request; the key is locked in the gateway. If it can act, it can cause trouble—so dangerous actions by default need a human nod.

Pain C · A broken prompt must be revertible → change discipline

Where it hurts: you (or the agent itself) changed the default manual, and the next day every task runs crooked. How do you go back?

Fix: you do not need to invent a complex system. Put all manuals, configs, policy files into git; if it is broken, git revert once and it is back.

• Manuals prompts/, configs specs/, policies policies/ — all into git.
• The agent by default may only write its own workstation; changing a manual must go through a human PR.
• Add a “config format check” in CI; wrong format is a red light; bad config cannot enter the trunk.

Compare Kortix: it puts artifacts and config into git; merge walks a change_requests review process. Your poor-person version—one GitHub PR is enough; you need not invent a review UI. This step is pure process discipline; there is no mechanism worth drawing.

验收：故意提交一个格式非法的配置 → CI 红灯。
     把一次改坏的说明书 revert 掉 → 剧本 α 恢复成功。

📋 One sentence: config goes into git; a bad change can roll back. Do not let “change one sentence of prompt” become an accident you cannot undo.

Pain D · Trigger from phone / Slack → channel delivery

Where it hurts: the Gate 1 agent can only be started by typing a command in your own terminal. A colleague wants to use it, or you want to send a task from your phone. Then what?

Fix: wrap an HTTP entry around the outside of the loop. Every channel (web, Slack, phone) eventually becomes a call to the same loop.run—the loop itself does not change at all.

flowchart LR
    C1["💻 网页"] --> API
    C2["💬 Slack"] --> API
    C3["📱 手机"] --> API
    API["POST /v1/runs
{message, spec_name}"] --> Q["建 run_id + 工位
丢进后台队列"]
    Q --> LOOP["还是那个 loop.run
（一行没改）"]
    LOOP --> POLL["GET /v1/runs/{id}
查状态 + 下载产物"]
    style API fill:#eaf1ff
    style LOOP fill:#e7f8f1

Do not invent a complex queue yet—one SQLite + a single background worker is enough to verify “a colleague can send a task from a phone.”

验收：用 curl 创建一个任务 → 轮询到「成功」→ 下载 summary.md → 通过剧本 α 的机检。

📡 One sentence: a thousand channels, one loop. Every entry finally converges on the same loop.run.