CH 01 · What Is an Agent Harness? · 09/12
Read as one pageReal code: pi plugs a coding harness into a generic loop
mini-swe-agent keeps the model, the environment, and the agent in one program. pi splits them. @earendil-works/pi-agent-core streams a reply and runs tools, and it does not know about a git repo. @earendil-works/pi-coding-agent is the coding harness: createAgentSession hands that generic Agent a session and a way to call the model. thinkingLevel is how much reasoning to request. Two fields go in empty.
const agent = new Agent({ // [1]
initialState: {
systemPrompt: "",
model,
thinkingLevel,
tools: [], // [2]
messages: existingSession.messages, // [3]
},
convertToLlm: convertToLlmWithBlockImages,
streamFn: async (model, context, options) => {
const requestOptions = buildRequestOptions(model, options);
// ... (8 lines: warm this session's prompt cache)
return modelRuntime.streamSimple(model, context, requestOptions); // [4]
},
// ... (3 lines: extension hooks on the raw provider request and response)
sessionId: sessionManager.getSessionId(),
transformContext: async (messages) => {
const runner = extensionRunnerRef.current;
if (!runner) return messages;
return runner.emitContext(messages);
},
steeringMode: settingsManager.getSteeringMode(),
followUpMode: settingsManager.getFollowUpMode(),
// ... (3 lines: transport, thinking budgets, retry delay)
});
Source: earendil-works/pi, packages/coding-agent/src/core/sdk.ts (MIT)
What to notice
- [1]
Agentcomes from@earendil-works/pi-agent-core. It does not import the coding tools (read,bash,edit,write). The coding harness creates those and attaches them later. - [2]
toolsandsystemPromptare empty, socreateInitialSystemMessagereturns nothing and this constructor adds no system message. Settings and thetoolsoption are already reduced toinitialActiveToolNames, which is not on the agent yet._applyToolLoadoutassignsagent.state.toolslater.prepareLoadoutcan adjust those declarations first. If a prompt section changed,_preparePromptAndToolLoadoutreturns a system message with emptycontentand, insections, only the sections whose text changed. TheHarnessclass createsself.toolsonce. - [3]
messagesis a projection of an append-only session file.hasExistingSessionis true when that list is non-empty, so an empty projection is a new session. - [4] This
streamFnfills timeout andmaxRetriesfrom settings, then callsmodelRuntime.streamSimple, which loads the API key. The generic agent already hasgetApiKeyandmaxRetryDelayMs. This session leaves the key to the runtime and passes the retry delay on its own. The eight hidden lines start a cache warmer whenoptions.sessionIdequals this session's id.
transformContext runs before the model call. emitContext clones the list: context handlers see no system messages, and context_with_system handlers then see the full list. steeringMode waits until the current assistant message has finished its tool calls, and those calls still run.
Read it yourself: Read createInitialSystemMessage in packages/ai/src/utils/transcript.ts. Then find initialActiveToolNames in sdk.ts, and this.agent.state.tools = declared at agent-session.ts line 1623.
Finished this idea?
Your learning progress stays in this browser.