Blog
Working notes and hard-won lessons from building agent systems.
Agent Harness Notes
Hi there — welcome to 🐿️ JollySammy’s Agent Harness world.
I like to think of myself as a squirrel. I don’t spend my days soaring over the AI realm like an eagle, surveying my territory from on high — I scurry around all day just to crack open a few more pinecones. My best foraging tricks include, but are not limited to:
- Begging from humans — teaching myself from the projects the big labs generously open-sourced;
- Stuffing shoddy bark into hollow pinecones — wiring an agent up to whichever sketchy third-party API was cheapest that week, then pretending what I gnawed out was nutritious;
- Raiding another squirrel’s stash — with heartfelt thanks to a certain company whose harness code “accidentally” fell off the truck.
A squirrel’s real gift is hoarding — so that six months later, when the model’s context window has frozen over, I can still dig it back out.
What follows is my stash: a running set of notes and answers on the problems I found interesting while building agents and their harnesses. Some pinecones are plump; some are mostly bark. Help yourself. 🌰
大家好——欢迎来到 🐿️ JollySammy 的 Agent Harness 世界。
我常把自己想象成一只松鼠。我不会成天像雄鹰一般巡视 AI 的领地。我整天窜来窜去，只为多找几颗松果啃。我的觅食绝活包括但不限于：
- 向人类乞讨——靠大厂慷慨开源出来的项目努力自学；
- 往空心松果里塞劣质树皮——随手抓个当周最便宜的第三方 API 把 agent 接起来，再假装啃出来的东西很有营养；
- 偷别的松鼠的存货——特别鸣谢某司那份“不小心”从车上掉下来的 harness code。
松鼠的天赋在于囤，例如半年后当模型的 context window 结了冰，我还能把它刨出来。
下面是我的存货：一份持续更新的笔记与解答，记录我在搭 agent、造 harness 时觉得有意思的问题。有的松果肥美，有的基本是树皮。欢迎大家来啃！🌰
-
Bury Once, Nibble Cheap: Prompt Caching in an Agent Harness埋一次，吃一冬：agent harness 里的 prompt cache
An agent resends its entire history every turn. Prompt caching turns that resend into a deeply discounted re-read; all it takes is a request prefix that stays byte-for-byte identical. Where the breakpoints go, how to read the usage bill honestly, and why a fan-out of subagents can pay for the same cache many times over.agent 每一轮都要重发全部历史。prompt cache 能把这次重发变成大幅折扣的重读，只需请求前缀逐字节不变。断点打在哪里、usage 账怎么读、以及一批并发 subagent 为什么可能为同一份缓存付多次钱。
-
System-Prompt Layers: Assembly, Cache Boundaries, and Runtime OverridesSystem Prompt 分层：组装、缓存边界与运行时覆盖
A model may receive one long system prompt, but its components change at different rates. This post develops a structured assembly pipeline, explains where cache boundaries belong, and separates runtime context injection from role authority and mechanical enforcement in Claude Code and Codex.模型收到的可能是一整段 system prompt，但各组成部分的变化频率并不相同。本文讨论如何用结构化流水线完成组装、如何划定缓存边界，以及在 Claude Code 和 Codex 中，怎样区分运行时上下文注入、消息角色权限与机制层强制。
-
Ten Nuts, One Mouth: Multiple Tool Calls in a Single Turn十颗松果，一张嘴：一次回复里的多个工具调用与并行执行
The model asks for three tools in one breath. Do you queue them or run them at once? If you run them at once, the results come back in a random order. How do you keep each result matched to its own call?模型一口气要三个工具，你是排队做还是同时做？同时做的话，结果回来的先后是随机的。你怎么保证每个结果都对上它自己的调用？
-
Streaming Reconstruction: From a Delta Stream to Structured Messages流式重建：从 delta 流到结构化消息
A streamed response doesn't hand you a finished assistant message — it dribbles out fragments. Turning those deltas back into a saveable, replayable, tool-executable structured message is one of the least glamorous and most bug-prone jobs in an agent harness.流式 API 不会一次性给你一条完整的 assistant 消息，而是一小片一小片吐出来。把这些碎片重建成可保存、可回放、可执行工具的结构化消息，是 agent harness 里最不起眼、也最容易出 bug 的工作之一。