Serialization for agents: tokens, schemas and cache-stable prompts
Models read text and you pay per token, which rewrites the rules: binary saves nothing the model sees, schemas become tool contracts, and byte-identical serialization decides your cache hit rate.
Everything earlier in this module optimised bytes on a wire. A model does not see bytes; it sees tokens, and you pay per token in and out. Encoding a tool result as Protobuf saves nothing the model reads, because the harness must turn it back into text. What matters is how many tokens the text costs and how stable it is from request to request.
Fewer tokens, same meaning
- Drop fields the model does not need. A 40-field API response trimmed to 6 fields often cuts tokens by 80%.
- Prefer short, clear keys over long ones, but never cryptic: the model must still understand them.
- Avoid repeating structure: a table-like list of records can be rendered as compact lines rather than verbose objects.
- Do not pretty-print large JSON in tool results; indentation is tokens.
JSON Schema as the contract
Tools are described to the model with a name, a description and a JSON Schema for their input. The model generates arguments that should match it, and structured-output modes can force them to (Module 13). The schema is now an API contract read by a model: descriptions, enums and examples improve call accuracy, and the evolution rules from the previous lesson apply to it too.
{
"name": "search_issues",
"description": "Search the issue tracker. Returns at most 20 issues, newest first.",
"input_schema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Full-text query, e.g. \"login timeout\"" },
"state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
"limit": { "type": "integer", "minimum": 1, "maximum": 20 }
},
"required": ["query"],
"additionalProperties": false
}
}Determinism and prompt caching
Providers cache the model's work for a prompt prefix and reuse it when a new request starts with exactly the same tokens (Module 13). Cached input is typically billed at a fraction of the normal rate and processed faster. The match is exact: one different token early in the prompt invalidates everything after it.
Same tools, different bytes, no cache
{"system":"You are a coding agent. Follow the repository conventions.","tools":[{"name":"bash","description":"Run a shell command","input_schema":{"type":"object","properties":{"command":{"type":"string"}}}},{"name":"edit","description":"Replace text in a file","input_schema":{"type":"object","properties":{"path":{"type":"string"},"old":{"type":"string"},"new":{"type":"string"}}}},{"name":"read","description":"Read a file","input_schema":{"type":"object","properties":{"path":{"type":"string"}}}}]}{"system":"You are a coding agent. Follow the repository conventions.","tools":[{"name":"read","description":"Read a file","input_schema":{"type":"object","properties":{"path":{"type":"string"}}}},{"name":"bash","description":"Run a shell command","input_schema":{"type":"object","properties":{"command":{"type":"string"}}}},{"input_schema":{"type":"object","properties":{"path":{"type":"string"},"old":{"type":"string"},"new":{"type":"string"}}},"name":"edit","description":"Replace text in a file"}]}- Prefix matching turn 1
- 18%
- Tokens read from cache
- ≈ 22
- Tokens processed fresh
- ≈ 8,103
Turn 2 built its tools from a map in a different order. The bytes diverge early, so everything after the first difference, including the 8,000-token conversation, is reprocessed.
/** Serialise with sorted keys so equal values always produce equal bytes. */
export function stableStringify(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
if (value && typeof value === "object") {
const entries = Object.entries(value as Record<string, unknown>)
.filter(([, v]) => v !== undefined)
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
}
return JSON.stringify(value);
}
// And sort the tool list itself by name before building the request.
const tools = [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));JavaScript objects keep insertion order, so two code paths that build “the same” object in different orders produce different JSON. Sorting removes the accident.
Go deeperCanonical serialization beyond caching
Signatures, content-addressed storage and deduplication all need one byte representation per value. JSON's freedom (key order, whitespace, number forms like 1.0 versus 1, Unicode escapes) defeats that. Canonical forms such as RFC 8785's JSON Canonicalization Scheme fix every choice.
Protobuf is not canonical either: field order on the wire and unknown-field handling can vary between libraries. Never hash serialised Protobuf and expect another implementation to match.
Where you will meet it
Harnesses put stable content first (system prompt, tools sorted by name), then the conversation, and track cache-hit rate as a metric.
Agents wrap verbose APIs in tools that return trimmed, consistently ordered fields, often cutting tokens by more than half.
Servers validate tool inputs against the same JSON Schema the model saw, and return precise error messages the model can act on.
Words to know
- Token
- The unit a model reads and is billed by: a piece of text from its vocabulary.
- Prompt cache
- Reuse of computed work for an exactly repeated prompt prefix.
- JSON Schema
- A vocabulary for describing the shape of JSON data.
- Canonical form
- A single agreed byte representation for each value.
Check yourself
Answer out loud before you open each one.
Why might two identical requests miss the same prompt cache?
Non-deterministic serialization: different key or tool order changes the token prefix.
Why does binary encoding not reduce a model's cost?
The model reads text tokens. Binary data must be converted back to text before the model sees it.
What does additionalProperties: false do in a tool schema?
Rejects arguments with fields the schema does not define.
Try it
Log the exact request body your harness sends for two consecutive turns, then diff the first few kilobytes. Any difference before the conversation starts is a cache miss you are paying for.