Skip to slide
009 / 170

CH 01 · What Is an Agent Harness? · 09/12

Read as one page

Real 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. [1] Agent comes 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. [2] tools and systemPrompt are empty, so createInitialSystemMessage returns nothing and this constructor adds no system message. Settings and the tools option are already reduced to initialActiveToolNames, which is not on the agent yet. _applyToolLoadout assigns agent.state.tools later. prepareLoadout can adjust those declarations first. If a prompt section changed, _preparePromptAndToolLoadout returns a system message with empty content and, in sections, only the sections whose text changed. The Harness class creates self.tools once.
  3. [3] messages is a projection of an append-only session file. hasExistingSession is true when that list is non-empty, so an empty projection is a new session.
  4. [4] This streamFn fills timeout and maxRetries from settings, then calls modelRuntime.streamSimple, which loads the API key. The generic agent already has getApiKey and maxRetryDelayMs. This session leaves the key to the runtime and passes the retry delay on its own. The eight hidden lines start a cache warmer when options.sessionId equals 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.