Agent Harness Worker Model
What it is
The Worker Model is an alternative architecture for agent harnesses that decomposes the monolithic framework into independent, composable workers communicating over a shared bus. Each worker handles a single concern (state machine, provider routing, credential vault, policy engine, approval gate, budget tracking, hook dispatch, context compression, session tree, telemetry). Replacing one worker does not require changes to others.
The iii engine implements this through one primitive: a worker that connects over WebSocket and registers functions and triggers on a shared engine bus. The harness becomes a stack of installable workers, and "build your own" stops meaning "fork a framework" and starts meaning "swap a few workers."
Why it matters
Current mainstream agent frameworks (LangChain, LangGraph, OpenAI Agents SDK, Anthropic SDK, CrewAI, AutoGen) bundle fifteen distinct concerns into a single import. Long-running agent teams eventually outgrow these bundled choices and rewrite their harness from scratch. The Worker Model keeps the choice in the builder's hands.
Mike Piccolo's core argument: a harness is not a thing you install. It is a set of jobs your system has to do for an agent to run durably, safely, and observably. The framework era bundled those jobs together because nothing underneath gave you a way to compose them. The Worker Model gives you that substrate.
The 15 jobs an agent harness has to do
| # | Job | iii Worker | What it does |
|---|---|---|---|
| 1 | Accept turn request | harness::trigger | Receives client POST, persists request, seeds OTel trace |
| 2 | Resolve credentials | auth-credentials | Pulls provider API keys via auth::get_token |
| 3 | Model capability lookup | models-catalog | Registers models::list, models::get, models::supports |
| 4 | Drive per-turn state machine | turn-orchestrator | Provisions, streams assistant, runs tools, steers, tears down |
| 5 | Load skill bodies | iii-directory | directory::skills::download / directory::skills::get |
| 6 | Assemble system prompt | turn-orchestrator | Mode paragraph + identity preamble + default skills appendix |
| 7 | Stream tokens to client | assistant-streaming | provider:: |
| 8 | Policy check before tool call | policy engine | consultBefore calls policy::check_permissions (allow/deny/needs_approval) |
| 9 | Pause for human approval | approval-gate | Parks calls in awaiting_approval; wakes via turn::on_approval trigger |
| 10 | Track LLM spend | llm-budget | budget::record per call; enforces per-workspace/per-agent caps |
| 11 | Run hooks before/after tool calls | hook-fanout | publish_collect; short-circuits when no subscriber registered |
| 12 | Persist session as branching tree | session | External state storage for forks and resumes |
| 13 | Compact session history | context-compaction | Subscribes to agent::turn_end; compacts per-turn instead of per-event |
| 14 | Emit event stream for UI | harness meta-worker | agent::events fanout for UI subscription |
| 15 | OpenTelemetry trace across steps | automatic instrumentation | src/runtime/worker.ts wraps every registerFunction in Proxy |
How the loop runs
Client POST → harness::trigger → run::start → turn-orchestrator
↓
provisioning → boot sandbox + download skills + assemble prompt
↓
assistant_streaming → provider::<name>::stream
↓
tool calls → function_execute → dispatchWithHook
↓
consultBefore → policy::check_permissions
↓
allow / deny / needs_approval
↓
batch completes → steering_check → continue / stop / max_turns
↓
finishSession() → teardown inline
Fail-closed by construction: if policy worker is unreachable or 5-second timeout fires, consultBefore denies with gate_unavailable. If iii::durable::publish errors, hook fanout returns publish_failed: true and orchestrator treats as deny.
Approval wake is reactive and shared: one turn::on_approval state trigger on scope approvals covers every session. No per-call resume functions. No startup re-scan.
Key design properties
Thin vs thick is a slider, not a fork
- Thin harness: turn-orchestrator + provider + auth + minimal meta-worker. No approvals, no budgets, no policy. Run anything. Trust the model.
- Thick harness: all 13+ workers + custom policy + custom approval + Slack integration + budget caps.
- The distance between them is a config change, not a rewrite.
Composition gives you local rewrite freedom
The turn-orchestrator recently refactored its FSM from 11 states to 7, deleted per-call approval_resume mechanisms, and inlined tearing_down into finishSession(). Every other worker stayed unchanged. The approval::resolve wire shape didn't move. This is the property composition gives you: a major internal rewrite of one worker is self-contained because every neighbor talks through bus-level function ids.
Replacing a layer is writing a worker
Five concrete examples from iii:
-
Replace model catalog with live API: write a worker registering models::list/get/supports, fetch from provider endpoint, cache. iii worker add your-org/dynamic-models-catalog. Stop static worker. Orchestrator never knows.
-
Add a new provider: one folder, one iii.worker.yaml, one register.ts. Publish or keep local. Turn-orchestrator picks provider by run's provider field.
-
Serve skills from private artifact store: write directory::skills::get/list backed by internal docs or S3. Disconnect default iii-directory. Orchestrator's bootstrap keeps working.
-
Override system prompt entirely: pass system_prompt on run::start. Orchestrator uses verbatim string, skips assembly. Skill download still runs.
-
Replace approval UI surface: default approval-gate registers approval::resolve. Want Slack approvals? Write a Slack worker listening for /approve and /deny slash commands, calling approval::resolve. Orchestrator never knows. Existing approval-gate stays untouched.
Evidence across sources
| Source | Key Claim | Relevance |
|---|---|---|
| Mike Piccolo — How to Build Your Own Agent Harness | Full 15-job decomposition with production stack from iii-hq/workers | Primary source; detailed architecture and replacement examples |
| AI Briefing 2026-05-29 Morning | Worker model replaces monolithic harness with composable workers on shared bus | Initial architectural framing |
| Nick Nisi — Case Harness | Gate design, SHA-256 verification, evidence-driven review | Shows same concerns (policy, verification, approval) implemented at application layer |
| Cole Medin — Harness Engineering | Skills + hooks + mindset shift from context to control | Methodology layer that runs on top of any harness architecture |
Counterpoints & Gaps
- Performance overhead: bus communication via WebSocket vs direct function calls. Not benchmarked in source.
- Operational complexity: running 10-15 independent workers vs one monolithic process. DevOps surface increases.
- Adoption friction: iii is new (2026-05). No large production deployments publicly documented yet.
- LangChain/LangGraph response: both frameworks are actively adding modularity (LangSmith Engine, SmithDB, Context Hub). The gap may narrow.
Open questions
- Has any production system outside iii implemented the full fifteen-worker decomposition?
- What is the latency overhead of bus communication vs in-process calls under high throughput?
- How does cross-cutting auth/logging work when every worker is independent?
- Can the Worker Model apply to personal/small-team harnesses, or is it only for platform-scale infra?
Related
- harness-engineering/overview — MOC for harness concepts
- harness-engineering/what-is-agent-harness — Definition of harness as model-external shell
- harness-engineering/lightweight-vs-orchestration-harness — Thin vs thick harness tradeoffs
- harness-engineering/multi-agent-coordination-patterns — Multi-agent orchestration patterns
- harness-engineering/zero-trust-ai-agents — Security and verification in agent systems
- product-trends/agent-native-architecture — Agent-native product architecture trends
2026-09-14 evening: the harness carries four durable jobs
来源:AI Briefing 2026-09-14 Evening
Greg Isenberg 将 Agent Harness 压缩为四类职责:让模型循环工作,给它调用文件、工具和代码的手,跨长任务管理记忆,以及限制它能触碰什么并在必要时请求人类。这个四项模型与本页已有的十五个 worker 对应:循环属于 turn orchestrator,工具属于执行和 provider 层,记忆属于 session 与 context worker,限制和停顿属于 policy 与 approval worker。
可复用之处不是四项数量,而是把模型能力和工作系统分开。模型可以替换,工作流中的状态、权限、反馈和完成定义仍需稳定。Harness 的边界也应允许从薄配置逐步加厚,而不是把所有控制面一次性打包进一个不可替换的框架。
Counterpoints & Gaps
- 四项职责是商业化解释,不是独立的架构标准;实际 worker 拆分会受延迟、部署和团队规模影响。
- “完成工作”计价和模型可替换性需要真实任务数据,不能从概念描述直接推出商业结果。
Sources (addendum)
Pending Jean review
- harness-engineering/agent-harness-worker-model —
ai_draft; map one current workflow to loop, tools, memory, permissions, and completion evidence before deciding whether to split workers.
2026-09-17:协调器、判断器和执行 worker 可拆开
本次晚间 briefing 里的多层 Model Routing、Jev 判断器和跨额度 handoff,分别对应 provider、judge、orchestrator 和 worker 的不同职责。把它们拆开可以提高替换性和观测性,但也会增加状态同步与调试成本。Worker Model 的边界应由任务证据决定,而不是由组件数量决定。
Counterpoints & Gaps
- 来源主要是社区经验,没有在同一任务上比较单体 harness 与拆分 worker 的成本。
- 过度拆分会让恢复链路和责任边界更难理解。
Sources (addendum)
Pending Jean review
- harness-engineering/agent-harness-worker-model —
ai_draft; compare one coordinator-only task with a split judge, router, and worker task using recovery and trace evidence.
2026-10-24:OpenAI FDE 案例——客户定制到可复用能力
来源:AI Briefing 2026-10-24 Afternoon
OpenAI FDE 案例:半导体客户用 eval + harness + skills 把定制流程产品化,验证环节省 48% 时间,第二个团队部署从 2 个月缩到 1 天;模型变强后定制胶水代码被退役。这是「客户定制 → 可复用能力」演进路径的量化证据。