Agent Harness Mastery
Course map
Level 1LLM Protocol and Agent LoopFree

Message schema: system/user/assistant/tool

Build the smallest reliable loop around messages, tool calls, streaming, retries, and state.

Read

Message schema: system/user/assistant/tool

"Message schema: system/user/assistant/tool" means turning the protocol state machine across message schema, tool calls, streaming, retry, abort, and completion into an executable, observable, recoverable, and acceptable Harness unit. The direct output is not a prompt. It is replayable turn trace and minimal Agent Loop. The goal is to turn the concept into boundary, architecture map, engineering objects, code comparison, and acceptance evidence.

DefinitionWhat it is

"Message schema: system/user/assistant/tool" means turning the protocol state machine across message schema, tool calls, streaming, retry, abort, and completion into an executable, observable, recoverable, and acceptable Harness unit. The direct output is not a prompt. It is replayable turn trace and minimal Agent Loop.

BoundaryProtocol state

It does not make the model "think harder" and it does not hide every behavior inside a chat wrapper. It defines Protocol state so message -> model -> tool -> state -> done, multi-step loop and event stream, and tool result, retry reason, abort reason, and done proof can be traced.

CounterexampleTreating the last assistant text as completion

If the implementation causes "Treating the last assistant text as completion", the boundary is not established. Go back to input contract, policy, or runtime and split it again.

Acceptancereplayable turn trace and minimal Agent Loop

Done means delivering replayable turn trace and minimal Agent Loop, preserving tool result, retry reason, abort reason, and done proof, and reviewing it through Every step has an event, state, and recovery strategy.

Think of it this wayIt does not make the model "think harder" and it does not hide every behavior inside a chat wrapper. It defines Protocol state so message -> model -> tool -> state -> done, multi-step loop and event stream, and tool result, retry reason, abort reason, and done proof can be traced. The programmer shift in this lesson is from "I can call a model or tool" to "I can design multi-step loop and event stream and judge completion through Every step has an event, state, and recovery strategy."
Agent Loop architecture map
Rendering Mermaid...
Mermaid source
flowchart LR
  input["Input Contract"] --> boundary["Protocol state"]
  boundary --> route["message -> model -> tool -> state -> done"]
  route --> runtime["multi-step loop and event stream"]
  runtime --> policy{"Policy"}
  policy -->|allow| tool["Model and Tools"]
  policy -->|block| blocked["Treating the last assistant text as completion"]
  tool --> state["State and Events"]
  runtime --> state
  state --> evidence["tool result, retry reason, abort reason, and done proof"]
  evidence --> artifact["replayable turn trace and minimal Agent Loop"]
  artifact --> eval["Acceptance"]

  classDef inputNode fill:#eef4ff,stroke:#4664ff,color:#0b1220;
  classDef runtimeNode fill:#ecfdf5,stroke:#10b981,color:#0b1220;
  classDef gate fill:#fff7ed,stroke:#f59e0b,color:#0b1220;
  classDef stop fill:#fee2e2,stroke:#ef4444,color:#0b1220;

  class input,boundary,route inputNode;
  class runtime,tool,state,evidence,artifact,eval runtimeNode;
  class policy gate;
  class blocked stop;
Hermes / Pi / Fiitx relation
FrameworkUseful designHow this lesson uses it
HermesEntry points, AIAgent, tool dispatch, Session Storage, Gateway/CronJudge whether message -> model -> tool -> state -> done has long-running and delivery boundaries
Pi Agent CoreAgentSession, event stream, resource loader, compaction, save pointImplement multi-step loop and event stream and a recoverable turn lifecycle
FiitxWorkbench, progress stream, approval UI, model routing, history replayExpose tool result, retry reason, abort reason, and done proof as a visible control plane
EvalDone criteria, trace, failure case, regressionProve replayable turn trace and minimal Agent Loop meets acceptance criteria
Code comparisonFrom LLM call to Harness run

A plain LLM call returns an answer. A Harness run carries goal, boundary, tools, policy, and acceptance as parameters.

// Plain LLM call: returns text without boundary, state, or acceptance
const answer = await model.generate({
  prompt: "Implement: Message schema: system/user/assistant/tool"
});

// Agent Harness 写法:把目标、工具、策略、状态和验收写进运行合同
const result = await harness.runLlmAgentLoop1AgentLoop({
  lesson: "1.1 Message schema: system/user/assistant/tool",
  goal: "Implement: Message schema: system/user/assistant/tool",
  boundary: "Protocol state",
  runtime: "multi-step loop and event stream",
  route: "message -> model -> tool -> state -> done",
  tools: runtime.tools.forBoundary("Protocol state"),
  policy: {
    watch: "Treating the last assistant text as completion",
    requireEvidence: true
  },
  eval: [
    "trace_complete",
    "artifact_exists",
    "policy_checked",
    "llm_agent_loop_1_Agent_Loop_accepted"
  ]
});

assert(result.artifact === "replayable turn trace and minimal Agent Loop");
assert(result.evidence.includes("tool result, retry reason, abort reason, and done proof"));

Key points

  1. 1

    Definition: "Message schema: system/user/assistant/tool" means turning the protocol state machine across message schema, tool calls, streaming, retry, abort, and completion into an executable, observable, recoverable, and acceptable Harness unit. The direct output is not a prompt. It is replayable turn trace and minimal Agent Loop.

  2. 2

    Boundary: It does not make the model "think harder" and it does not hide every behavior inside a chat wrapper. It defines Protocol state so message -> model -> tool -> state -> done, multi-step loop and event stream, and tool result, retry reason, abort reason, and done proof can be traced.

  3. 3

    Code: a plain call gets answer; a Harness call must return artifact, evidence, and trace.

  4. 4

    Acceptance: deliver replayable turn trace and minimal Agent Loop, preserve tool result, retry reason, abort reason, and done proof, and guard against "Treating the last assistant text as completion".