Taking Ownership of Prompts
Introduction: Taking Control of What the Model Sees
In the previous lesson, you built a stateless reducer agent, but there is a critical issue: the system prompt is hardcoded inside the TypeScript code, and the raw ContextItem[] array is passed directly to the model without any formatting.
This means you cannot easily review or version your prompts, and the model sees technical noise like "type", "call_id", and "arguments" instead of clean, structured information. Now, we are going to implement Factor 2 (Own your prompts) and Factor 3 (Own your context window) by extracting your system prompt into a versioned markdown file and building a context serializer that transforms the raw ContextItem[] array into clean, focused text that the model can process efficiently.
In the updated agent.ts, the Agent constructor loads base_system.md from disk using readFileSync, anchored to the module's own location via fileURLToPath(import.meta.url). Meanwhile, the private callLlm method calls serializeContextToText(context) before forwarding the result as the input field of this.client.responses.create(...). This means the model never sees raw ContextItem objects — it only receives the serialized markdown.
Planning the New File Structure
Before we dive into creating the prompt files and serializer, let's understand how we need to reorganize our project structure. We're going to add two new directories to separate concerns and make our codebase more maintainable.
We're going to extend the existing structure to include dedicated directories for prompts and utilities:
Here's what each new component adds to our architecture:
prompts/directory — Houses all prompt-related files as versioned markdown documents, treating them as first-class artifacts alongside your codebase_system.md— Defines the agent's role and behavioral requirements in a structured, reviewable formatcontext_format.md— Provides the template for how context should be presented to the model
utils/directory — Contains helper modules that don't fit into the core agent logiccontextSerializer.ts— Transforms rawContextItem[]arrays into the clean markdown format defined by our template
This structure separates three concerns: agent logic (the reducer loop and control flow), prompt definitions (what the agent should do and how it should see information), and utilities (supporting functions that transform data). By organizing files this way, you can modify prompts without touching TypeScript code, review prompt changes in version control, and test different prompt versions independently. Now let's create these files and implement the externalization.
Extracting the System Prompt to a Markdown File
Following the structure we just planned, let's create the first prompt file at src/core/prompts/base_system.md. This file will define the agent's role and core requirements in a structured, readable format.
The # ROLE section defines the model's identity, while the # REQUIREMENTS section provides specific rules that guide behavior, including the critical instruction to call the final_answer tool when complete. The # EXTRA INSTRUCTIONS placeholder allows you to append custom instructions without modifying the base file.
This is significant because your prompt is now a versionable artifact — you can track changes over time, review prompt modifications in pull requests just as you review code, and deploy new prompt versions independently of code changes. Now, we need to update the Agent to load this prompt from the file.
Loading the System Prompt in the Agent Constructor
We need to update the Agent class constructor to load the system prompt from the file instead of using an inline string. In Node.js with ES modules, there is no __dirname available by default, so we derive the current file's directory at runtime using fileURLToPath(import.meta.url).
dirname(fileURLToPath(import.meta.url)) resolves to the directory containing agent.ts — that is, src/core/ — so join(baseDir, "prompts", "base_system.md") correctly locates the prompt file without any hardcoded absolute paths. readFileSync loads the entire markdown file as a UTF-8 string at construction time. We then concatenate options.extraInstructions ?? "" at the end to fill the # EXTRA INSTRUCTIONS section.
All constructor parameters are optional and come from the AgentOptions interface, with sensible defaults applied via the nullish coalescing operator (??). Your prompt is now externalized, versioned, and maintainable without touching TypeScript code. Next, we need to control how the context is formatted before it reaches the model.
Designing the Context Format Template
The raw ContextItem[] array contains objects with technical keys that add noise for the model. We need to transform this into a clean, structured format that highlights what matters: the user's request and what actions have already been completed. This is the essence of context engineering — deliberately structuring information to guide model behavior. Let's create the second file in our planned structure: src/core/prompts/context_format.md.
This template has three sections: the user's original question using the {user_message} placeholder, a list of completed actions using the {execution_history} placeholder with an explicit warning not to repeat them, and a clear directive regarding what to do next.
The {key} placeholders match the convention used in our serializer's .replace() calls, making it straightforward to inject dynamic content. By structuring information this way, we remove noise and focus the model's attention on the relevant state — this is what Factor 3 means by owning your context window. Now, let's build the serializer that performs this transformation.
Setting Up the Context Serializer Module
The context serializer is a module that exports a single function: serializeContextToText. It takes a typed ContextItem[] array and transforms it into the formatted markdown text our template defines. Following our planned structure, we create this in src/core/utils/contextSerializer.ts.
The templatePath uses dirname(fileURLToPath(import.meta.url)) to anchor itself to the utils/ directory, then navigates up one level ("..") to reach core/, and finally into prompts/ — exactly as we planned in our file structure. The template is loaded once at module import time and stored in the module-level constant template, so the file is only read from disk once regardless of how many times the agent is called.
serializeContextToText accepts the same typed ContextItem[] that the agent accumulates during its reducer loop and delegates to two private helpers: buildCompletedActionLines, which produces the execution history lines, and the formatting utilities formatArgs and formatValue that it calls internally. We will implement each of these in the following sections.
Extracting the User Message
The first piece of information we need is the user's original request. We use Array.prototype.find with a type-narrowing predicate to locate the first ContextItem that carries a "role" field, then extract its content with optional chaining.
The predicate "role" in item && item.role === "user" narrows the union type: "role" in item confirms the item is the message-style variant of ContextItem, and item.role === "user" selects the user's turn specifically. The ?.content optional chain returns undefined if no match is found, and the ?? "" nullish coalescing operator falls back to an empty string. This is more idiomatic TypeScript than a manual for loop and makes the intent immediately clear. Next, we need to format the execution history to show what tools were called and what results they produced.
Building the Function Call Map
To format the execution history, we build a Map<string, string> that indexes formatted function call signatures by their call_id. This map is built inside the private buildCompletedActionLines function so all execution-history logic stays in one place.
We iterate through the context looking for items with item.type === "function_call". For each one we call formatArgs(item.arguments) to turn the raw JSON arguments string into a human-readable key=value list, then store the result in callsById.
formatArgs handles the conversion from JSON string to readable text:
It parses the JSON arguments string, then maps each key-value pair through formatValue to produce a readable representation. If parsing fails for any reason, it falls back to the raw string.
formatValue handles the per-value rendering:
Strings are wrapped in single quotes with proper escaping, null renders as "null", booleans render as "true" or "false", and numbers fall through to String(value). The result is that a call like {"base": -5, "exponent": 2} becomes the readable text base=-5, exponent=2. With the map ready, we can now pair each call with its output.
Formatting Completed Actions
With callsById populated, we make a second pass through the context to find "function_call_output" items and pair each one with its originating call signature.
For each function_call_output item we look up its call_id in callsById. If the id is present we get back the human-readable call signature; if it is missing for any reason, we fall back to unknown_call(<call_id>) so the output remains informative rather than crashing. Each matched pair is formatted as a ✓ COMPLETED: <call signature> → Result: <output> line and collected into a string[] array. The completed buildCompletedActionLines function returns this array to serializeContextToText.
Completing the Serializer Function
With userMessage extracted and execution-history lines collected, we replace the two template tokens in one pass. A user message containing text such as {execution_history} is inserted as data and is not processed as another placeholder.
The replacement callback chooses the user message or the formatted history for each token in the original template. The history is joined with newlines, or falls back to (No actions completed yet) when no tool outputs have been recorded. Inserted values are never scanned again. The result is a clean markdown document that presents the relevant information in a structured, readable way without any technical noise from the raw ContextItem objects.
Template note: One-pass replacement also protects against placeholder-like text in tool output. A larger system may additionally validate that the template contains each required placeholder.
Integrating the Serializer into the Agent
With the serializer built, we update the Agent's private callLlm method to use it. Instead of passing the raw context array to the model, we serialize it first and pass the formatted text as the input field.
The key addition is serializeContextToText(context), whose result is passed as input. The system prompt — loaded at construction time from base_system.md — is passed separately as instructions. The reasoning field is conditionally included only when this.model === "gpt-5", because other models do not support that option. The method returns response.output, a typed ResponseOutputItem[] array that the agent's reducer loop then inspects for function calls.
Now, the model receives clean, structured markdown that highlights the user request and completed actions, implementing Factor 3 by explicitly controlling what goes into the context window.
Visualizing the Serialized Input
To understand the impact of Factor 3, imagine the agent is one step into the task. Instead of the LLM receiving an internal array of ContextItem objects, serializeContextToText provides a structured prompt. For example, after the agent has calculated the square of the discriminant term, the model sees this:
By presenting the state as a markdown document, we guide the model's attention toward the logic of the solution rather than the technical plumbing of the tool-calling loop.
Launching the Agent
Now let's look at main.ts, which wires everything together. We initialize the typed context array and run the agent until it produces a final answer.
agent.run(context) returns a RunResult object with three fields: status, finalAnswer, and the updated context array. By iterating over result.context and logging each item, we get a full audit trail of every ContextItem the agent accumulated internally — even though the model only ever saw the clean serialized versions during each step.
Running the Complete Agent
When we run main.ts, the Node.js runtime prints the result of the agent's reducer loop. The raw context is useful for auditing, but here is a shortened excerpt:
This illustrative run uses math tools to calculate the discriminant and divide both numerators by two before reporting the roots. The model may choose a different valid call order or grouping. The raw ContextItem objects logged above are what we maintain internally for full auditability — every call_id, argument string, and tool output is preserved. Note that call_id values will differ between runs since they are assigned by the API.
Viewing the Serialized Context
Even though we print the raw context for our own records, it is important to remember what the model actually saw during its final step. The serializeContextToText function produces exactly this:
This format removes technical noise like call_id and type, showing only the user's request, completed actions with results, and a clear next-step directive. The argument text — base=-5, exponent=2, a=4, b=6, and so on — comes directly from formatArgs and formatValue, which parse each tool's JSON argument string and convert it into a human-readable key=value representation.
Notice that final_answer does not appear in the serialized history. The serializer only includes items that have a corresponding function_call_output entry, and final_answer terminates the loop before any output is generated. This separation gives us complete records for debugging while providing focused information to the model.
Summary and What's Next
You have now implemented Factor 2 and Factor 3 by extracting your system prompt to a versioned markdown file and building a context serializer that controls exactly what the model sees through context engineering.
Your prompts are now first-class artifacts that can be reviewed, tested, and deployed independently of TypeScript code, while your context is explicitly curated to remove noise and present information in a structured format. The Node.js module system — readFileSync, fileURLToPath(import.meta.url), dirname, and join — gives you portable, reliable file resolution without any hardcoded absolute paths. This context engineering approach gives you precise control over model behavior by shaping the information it receives. In the upcoming practice exercises, you will extend these concepts by modifying the templates to experiment with different formatting styles and exploring how changes to the serialized input affect model behavior.
