控制面与执行面分离harness-sdk 架构里藏着智能体工程化的答案【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk2026 年的智能体框架赛道几乎被同一个词占据Harness。OpenAI 开源 Codex Harness微软发布 Agent Framework Harness 与 Hosted AgentsDeepSeek Harness 开源即爆火——各家不约而同地把给 Agent 装上缰绳当成下一代框架的核心命题。在这股浪潮里harness-sdk 给出的是一个更彻底的架构答案控制面与执行面分离。它不是把几个工具函数拼进一个循环里而是先把让模型干活这件事拆成两个正交的系统——一个负责决策与执行模型推理、工具调用一个负责约束、预算、状态与干预契约、规则、生命周期、持久化再通过一条明确的边界把它们缝合起来。本文基于仓库源码拆解这条边界是怎么设计、怎么落地的以及它相比单体 Agent 到底多赚了哪些工程能力。为什么要把控制从执行里拆出来先看仓库根目录的 README.md 对项目的一句定位Choose Strands when you would otherwise write your own agent loop: it runs in your process with no hosted control plane, and it covers the jobs a hand-rolled loop grows into. 这句话信息量很大SDK 明确宣称没有托管的控制面——控制逻辑全部运行在你的进程内同时把手写循环长出来的一堆活全部内置。单体 Agent 的痛点正在于此提示词、工具注册、状态管理、超时处理、上下文裁剪、并发容错全部揉在一个循环里demo 能跑上生产就崩。而 harness-sdk 用两层结构把这个问题拆开执行面strands-py/下的底层 SDK提供 Agent 类、模型接入、工具注册和事件循环负责把任务干完控制面harness-py/下的装配层用一次create_harness()调用把模型、工具、记忆、会话、上下文管理、干预策略全部装配成一个开箱即用的生产级 Agent。关键的接缝在 harness-py/src/strands_harness/agent.py 的create_harness()工厂函数它接收约二十个关键字参数model、effort、tools、plugins、mcp_servers、builtin_tools、session、memory、skills、interventions等内部完成模型解析、内置工具装配、插件注册、名称冲突预检、子智能体配置注入最后返回一个普通的strands.Agent。调用侧极简from strands_harness import create_harness agent create_harness() agent(Find the slowest test in this repo and explain why its slow)一行调用拿到的不只是一个会聊天的模型而是一整套带默认值的控制面。执行面 SDK 把循环开放出来控制面 SDK 把循环的默认行为长满——这就是分离的第一个收益你既可以开箱即用也可以在控制面不够时下钻到执行面自己接管循环。四个部件如何分工调度循环、规则契约、技能注入、编排器社区对 harness 类框架的关注点通常落在四件事上调度循环、规则引擎、技能系统、编排器。在 harness-sdk 里这四件事分别对应四段职责清晰的代码彼此只通过标准接口通信。调度循环一个 cycle 管住推理—执行—继续执行面的心脏是 strands-py/src/strands/event_loop/event_loop.py 的event_loop_cycle()。它定义了一个标准 cycle检查执行上限 → 调用模型 → 若返回工具调用则执行工具 → 把结果回灌 → 递归进入下一 cycle。这个循环把执行本身做成了可中断、可续跑的状态机预算控制_check_limits()按turns、total_tokens、output_tokens三个维度在上限处优雅终止并返回stop_reason而不是抛异常容错重试_handle_model_execution()内置ModelRetryStrategy默认最多 6 次、初始延迟 4 秒、最大延迟 240 秒对节流类瞬时错误做指数退避取消与恢复cancel()线程安全、幂等循环在模型流式输出、工具执行前、MCP 调用中等安全点检查取消信号检查点checkpointingTrue时循环在after_model/after_tools边界暂停返回stop_reasoncheckpoint配合会话管理器可跨进程恢复。值得注意的是循环本身对模型是什么、工具有哪些一无所知——模型通过Model/ModelRouter抽象注入工具通过tool_registry注册。调度循环只负责节奏不负责内容。规则契约约束不写死在循环里而是作为干预注入规则引擎在 harness-sdk 里分两层。第一层是行为契约见 harness-py/src/strands_harness/prompt.py 的HARNESS_CONTRACT一份模型无关的行为准则明确要求有足够信息就行动、改东西前先探索、完成前必须验证、不可逆操作先确认。它不声明身份和领域领域内容由调用方的instructions追加——控制面与业务面也被这条线分开。第二层是真正的规则执行interventions。看 harness-py/src/strands_harness/interventions.py它把干预配置统一解析成 SDK 的InterventionHandler列表# 每个工具调用都需人工批准 agent create_harness(interventionsask) # LLM 风险分类器标记高危调用仅标记的需批准 agent create_harness(interventionssmart) # 自然语言策略把这段文字作为风险分类器的评判标准 agent create_harness(interventions不允许任何写操作访问 /etc 之外的路径) # Cedar 策略文件显式的授权策略 agent create_harness(interventionspolicy.cedar)解析逻辑是确定性的、不做内容嗅探ask/smart映射到HumanInTheLoop配置.cedar结尾加载CedarAuthorization策略其余字符串一律视为自然语言风险策略。干预 handler 在每个生命周期事件模型调用前、工具执行前按注册顺序求值deny 立即短路guide 则跨 handler 累积反馈——规则是挂在执行面上的开关和阀门而不是嵌进执行路径的 if-else。技能系统上下文注入而不是改写历史技能系统由三块拼成内置插件、skills 插件和上下文管理。内置插件见 harness-py/src/strands_harness/plugins/todos.py 与 harness-py/src/strands_harness/plugins/environment.pyTodos给 Agent 一个todo_write工具维护多步任务清单并通过ContextInjector在每次模型调用前everyTurn而非userTurn把当前清单重新注入为system-reminderEnvironmentContext每轮注入平台、当前日期、工作目录和项目AGENTS.md超过 16KB 截断并提示按需读取发现逻辑走 Agent 的 sandbox 接缝Docker/SSH 沙箱同样生效。这个设计的精妙之处在于注入的临时性todo 列表每次todo_write都在变如果走改写agent.messages的路子要么在持久历史里堆积过期提醒要么反复删了再插。而ContextInjector注入只增强一次模型调用、从不落盘天然适配频繁变化的状态。注释里还点出一个细节环境插件把日期做成逐轮注入而非烧进 system prompt正是因为日期每轮变化会击穿 system prompt 的缓存前缀注入落在缓存点之后、保持缓存温热。控制面的每次动作都在为执行面的成本与正确性负责——这就是分离带来的精细化。skills 插件AgentSkills则实现渐进披露默认加载./.agent/skills目录让模型按需读取SKILL.md避免把所有技能一次性塞进上下文。编排器子智能体委托权限只能收窄不能扩张多智能体编排在 harness-sdk 里收敛为一个subagent工具实现见 harness-py/src/strands_harness/tools/subagent.py。它的核心是一套轴权限模型每个维度指令、工具、MCP 服务器、模型、上下文都由四种模式之一决定——Fixed(value)开发者钉死模型看不到参数Inherit()继承父 Agent 的值Open(...)模型自由书写Choice(...)模型从开发者提供的枚举中挑选且选中集在调用时重新校验——子 Agent 永远不可能获得父 Agent 没有的能力。深度委托被max_depth默认 2硬性封顶剩余委托预算存在每个子 Agent 自己的agent.state上归零时工具直接拒绝并返回错误结果而不是继续递归。子 Agent 通过注入的create_harness工厂重建因此它是完整的 harness 成员继承父级的模型、内置工具、插件、干预策略记忆则以只读方式共享harness-py/src/strands_harness/memory.py 中的_ReadOnlyStore包裹可搜索可注入但删掉一切写路径防止一次性子任务把脏数据蒸馏进长期记忆。相比单体 Agent这套架构的工程收益收益一可观测性是内建的不是后补的harness-py/src/strands_harness/telemetry.py 只有六十行但它说明了一个关键事实SDK 层的 Agent 已经全链路埋点——模型循环、工具调用、子智能体委托都会发出 OpenTelemetry span单体 Agent 只是没有地方送出去。harness 的唯一职责是按标准OTEL_TRACES_EXPORTER环境变量接上导出器且默认不开启避免静默起一个指向localhost:4318的导出器拖慢进程退出。控制面只补最后一块拼图可观测性成本因此趋近于零。收益二状态与韧性被抽象成可插拔的子系统会话、记忆、上下文管理是三个独立的子系统各自有默认实现和替换接口会话默认SnapshotSessionManager 文件存储每次消息快照session{id: ...}可续接上次对话记忆默认FileMemoryStore把跨会话的事实蒸馏成./.agent/memory下的 markdown每次调用前检索并注入injectioneveryTurn提取跑在廉价小模型上与主模型解耦上下文管理auto模式在上下文 85% 利用率时主动摘要、把大型工具结果 offload 出上下文并保留检索入口Agent 靠retrieve_context按需读回。这些子系统全部通过构造参数注入session_manager、memory_manager、context_manager替换后端比如换成 Qdrant/Redis 记忆存储不改动执行路径——控制面的替换不影响执行面反之亦然。收益三模型可移植与配置即资产harness-py/src/strands_harness/models.py 用一张Provider表统一了 Bedrock、Anthropic、OpenAI、Gemini、Ollama、LiteLLM 的接入同样的effort语义被映射到各家的thinking/reasoning字段web_fetch摘要模型按主模型的 provider 自动选同家小模型共享凭证caching按 provider 能力自动开启或降级。业务代码面对的是anthropic/claude-...这样的字符串换模型不改逻辑。同时 harness-py/src/strands_harness/config.py 提供一套可序列化、跨语言共享的 harness 配置DEFAULT_HARNESS_AGENT_CONFIG工具、子智能体、插件、干预都可以用模块引用声明Python 与 TypeScript 共用同一份 schema。Agent 的组装从代码变成配置资产这本身就是工程化程度的分水岭。小结回看整个架构控制面与执行面分离的本质是把模型很聪明这个假设从系统很可靠这个要求里彻底摘出来执行面假设模型会犯错、会超时、会忘记上下文所以循环做预算、重试、取消和恢复控制面则把约束、状态、观测和编排做成注入式的旁路让每一次决策都可审计、可干预、可回滚。单体 Agent 把聪明和可靠混在一起赌运气而 harness-sdk 把它们拆开、各司其职——这正是智能体从 demo 走向生产所缺的那一层工程答案。【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考