【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载Unreal AgentUnreal Labs 出品的 Async-first agent harness通过在每次请求的系统提示system prompt最前面注入一段固定的preambleharness/contextbuilder/prompts/preamble.md向模型传递回合turn制、异步工具调用、心跳保活、无保姆式等待这套运行约定。本文以该 preamble 为骨架结合 contextbuilder 的组装逻辑、coordinator 的事件循环与相关测试讲解这段提示词每一句话对应的真实机制以及它如何让模型在本 harness 下走得更宽、睡得安心、任务达成后才收工。读完你可以理解为什么同一模型在 Unreal Agent 中的行为会与在普通单轮对话框架中不同以及这套约定背后的实现证据。一、Preamble 是什么系统提示的第一段出厂说明书在 Unreal Agent 中模型的每一条请求都从一个 system message 开始它的文本由三部分顺序拼接而成preamble固定内嵌 \n\n system prompt运行时可配置拼装发生在 contextbuilder/builder.go 与 SetSystemPrompt//go:embed prompts/preamble.md var preambleFile string var preamble strings.TrimSpace(preambleFile) ... current.committedPrefix[0] llm.Item{Type: llm.ItemMessage, Data: llm.Message{ Role: llm.RoleSystem, Text: strings.TrimSpace(current.preamble \n\n current.systemPrompt), }}也就是说无论运行方传入什么样的 system promptpreamble 永远位于最前面。测试 TestBuilderLeadsSystemPromptWithPreamble 明确断言最终 system message 文本等于preamble \n\nBe concise.。运行方cmd/internal/agentrunner/run.go默认提供的 system prompt 是 You are an AI agent running inside an isolated sandbox container... 一类的行为准则也可以由调用方通过 JSON 请求中的system_prompt字段覆盖但 preamble 始终打头。另外如果注册了 skillsformatSkillsForPrompt 会把 skill-preamble.md 与available_skillsXML 清单追加到 preamble 之后对应测试 TestBuilderAppendsSkillsToPreamble。因此最终的 system 文本顺序是preamble固定skills 引导语 可用技能清单可选运行方 system prompt可选二、回合Turn模型一次读对话、一次回复Preamble 的第一条约定是You work in turns. A turn is one reading of the conversation and one reply: text, tool calls, or both. Each turn re-sends the whole conversation, so prefer to go wider with tool calls — they are cheap — rather than chaining them across a longer sequence of turns.它在 harness 里的实体是session.Turn每次向模型发起请求前coordinator 都会创建一个带唯一 ID 的新 turnloop.go并把这一轮的所有输入、模型回复、工具调用与结果作为会话历史持久化下一轮请求会重新发送整个对话committed prefix staged suffix这正是 preamble 所说 Each turn re-sends the whole conversation 的机制来源。由此产生一条直接可用的行为准则当多个操作互不依赖时把它们放进同一个回合并发执行而不是串行地一步一回合。preamble 给出的理由很直白——工具调用很便宜cheap而整段对话重发是有成本的把调用摊到更多回合里等于重复付费。典型场景需要同时查看多个文件、同时跑构建和测试、同时验证两个假设时就在同一回合发出多个独立的工具调用。三、异步工具调用发起即后台运行Tool calls are asynchronous: each starts the moment you issue it and runs in the background, so issuing one never blocks you and many run at once.这是整个 harness 的架构核心项目自述即为 Async-first agent harness见 README.md。在 Unreal Agent 中工具调用不会阻塞模型模型在回合里发出的 tool call 会被 coordinator 解析为operation可序列化的工作描述见 README 术语表交由 operation manager 异步执行模型这一回合立即结束去等待结果。因此 preamble 才敢告诉模型发出调用不会阻塞你多个调用可以同时运行。同时运行的机制coordinator 的Run事件循环把 inbox 输入、operation 更新、心跳、模型响应都接入一个select多路复用loop.go任意操作完成都会唤醒新回合而不是排队等待。结果到达的编排每个完成的操作更新被累积到 tool call 状态当某个 tool call 关联的全部 operation 都进入终态completed/failed/canceled见 operationIsTerminal后翻译器把结果组装成模型可见的 tool resultaddToolResultToLocalState。四、运行中结果的占位符让模型知道还在跑As each finishes, its result is appended and wakes a new turn; results that land together arrive in the same turn, and a call still running shows a placeholder until its own result comes.still running 显示占位符在代码中是字面实现的。contextbuilder 定义了常量const ToolCallRunningPayload Tool call is still running. Its result arrives in a later turn: continue with independent work, or end your turn to wait for it.见 builder.go。当 coordinator 发现某次工具调用仍有非终态 operation 时会调用AddToolResult(..., runningtrue)此时 builder 会把ToolCallRunningPayload作为该调用的暂定结果注入 staged suffixbuilder.go。后续真实结果到达时builder 会先删除旧的 running 占位条目再追加最终结果测试 TestBuilderRemovesOnlyStagedRunningResultsForUpdatedCall 验证了只替换对应调用、不影响其他调用的行为。因此模型在本回合看到的对话形如调用 A 的结果是仍在运行于是它可以选择继续做独立工作或者结束回合睡觉等结果——这正对应 preamble 说的 continue with independent work, or end your turn to wait for it.。五、心跳Heartbeat不用盯梢十分钟没动静就唤醒你You never have to babysit a running call: harness does it for you. As a backup, if calls are active and nothing has happened for ten minutes, a heartbeat wakes you, and this is an opportunity to check that all is well.这是 preamble 中最容易被误解的一句十分钟是配置示例不是硬编码。真正的机制在 coordinator 中当模型没有在等待模型响应、没有待处理输入、但仍有工具调用在跑时isWaitingForOnlyToolCalls事件循环会启动一个time.After(ToolHeartbeatInterval)定时器loop.go。定时器到点后postHeartbeat 把当前仍在运行的工具调用列表序列化构造一条Mode: inbox.Heartbeat的控制消息其 Reason 形如Heartbeat: waited 60 seconds for tool calls. Running: [{CallID:call-0,Name:ViewImage,Arguments:{}},...]这条消息经 inbox 回到事件循环被转成一条 user 消息注入下一回合AddControlMessage 中的inbox.Heartbeat分支。模型读到它就是一次检查一切是否安好的机会。间隔由运行方通过-tool-heartbeat-interval命令行参数配置最终写入Dependencies.ToolHeartbeatIntervalrun.go负值会被拒绝TestCoordinatorRejectsNegativeHeartbeatInterval。coordinator 层面的默认值零值为 0表示完全禁用——例如在 cmd/internal/agentrunner/heartbeat_test.go 的集成测试中就以10ms触发心跳来验证 Bash 结果的释放。因此 ten minutes 只是说明这是一个保底唤醒机制实际节奏完全可控。值得注意的细节心跳只在仅有工具调用在跑时启动且一旦有新的外部输入或模型响应到来旧的心跳 deadline 会被丢弃TestHeartbeatDiscardsPreviousDeadline心跳不会打断正在进行的模型请求TestQueuedHeartbeatPreservesActiveModelResponse。六、回合结束规则睡觉 vs 收工Ending a turn with no tool calls while calls are running means you sleep until one finishes; ending a turn with nothing running ends the session, so do that only when the task is complete.这条睡眠/收工语义对应 coordinator 的状态判定有工具调用仍在运行、没有模型响应在途、没有待处理输入时模型处于等待工具结果状态此时结束回合不会终止会话而是睡眠直到某个操作完成唤醒loop.go 的 select 持续监听operationUpdates。没有任何在运行的东西时事件循环就进入了 idle 状态isIdle。此时如果收到了StopWhenIdle控制消息Run会返回结束会话loop.go如果没有任何 stop 控制harness 会一直待命等待新的外部输入。所以 preamble 的告诫只有任务完成时才结束回合是有工程含义的模型结束回合且无运行中调用等价于把会话交给 harness 的停止判定逻辑。测试 TestCoordinatorHeartbeatsWhileWaitingForTools 完整演示了这一节奏工具调用运行期间模型可以结束回合睡觉模型响应Still waiting. 之后操作完成才把结果送达全部完成后停掉不再有心跳。这验证了 preamble 描述的睡觉—唤醒—检查—收工闭环。七、最后一句把 prompt 当作目标Treat the prompt as a goal and keep working until it is met. I believe in you!这是对模型的行为指令也是 harness 设计目标的人格化表达会话不会因为一次无工具调用的回合就结束除非明确收到停止控制或上下文取消。结合上一节的停止机制StopHard强制取消、StopWhenIdle空闲停止见 handleStop可以这样理解任务何时算完成由停止控制消息决定而不是由模型想休息决定。因此 preamble 鼓励模型持续工作到目标满足。结语preamble 是 async-first 行为契约的浓缩Unreal Agent 的 preamble 表面上是写给模型的一段行为建议实际上逐句对应着 harness 的硬机制回合制上下文重发turn session store、异步 operation 执行、运行中占位符ToolCallRunningPayload、可配置心跳ToolHeartbeatInterval与睡觉 vs 收工的停止判定。如果你要为 Unreal Agent 编写或调试 agent 行为这段提示词就是最值得先读的运行约定说明书相关代码从 contextbuilder/builder.go 到 coordinator/loop.go 一脉相承测试文件如 builder_test.go、heartbeat_test.go则为每条约定提供了可复现的验证证据。赞分享【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载相关推荐制作者MakerAgent Prompt 完全拆解learn-harness-engineering 中实现型 Agent 的角色设计、五步工作流与实战模板制作者MakerAgent Prompt 完全拆解learn harness engineering 中实现型 Agent 的角色设计、五步工作流与实战模learn-harness-engineering 仓库设计文档规范如何用 DESIGN.md 沉淀 agent-first 的持久化设计决策learn harness engineering 仓库设计文档规范如何用 DESIGN.md 沉淀 agent first 的持久化设计决策 导读 本指南以Agent-first 仓库中的设计文档入口模式解析 learn-harness-engineering 的 DESIGN.md 模板Agent first 仓库中的设计文档入口模式解析 learn harness engineering 的 DESIGN.md 模板 本篇文章围绕 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考