Build Your Own Deep Research Agent + Technical Writer

A generated LinkedIn post can look finished while saying very little. The opening example piles up familiar problems: stock words such as “delve” and “intricacies,” unsupported generalizations about what most teams do, and formulaic contrasts between one idea and another. It also calls GPT-4 state of the art, even though Louis-François Bouchard says the post was generated the previous week. Removing conspicuous punctuation would not fix its stale information or shallow substance. Better writing needs both better evidence and a deliberate editorial process.

Towards AI encounters this problem while producing technical courses, articles, and videos. AI engineers supply expertise; writers and editors turn that expertise into an explanation; the group iterates on accuracy and storytelling. The proposed system starts with a topic such as “What is harness engineering?”, researches it, and passes the findings to a writing stage that can incorporate code and useful images. Human judgment still supplies the connections that make an explanation relatable.

The team used the system to help create the course that teaches it, bringing internal use and student feedback into development. This workshop implements a smaller version: a research agent followed by a workflow for short LinkedIn posts. The companion repository accompanies the architecture discussion and code demonstrations. Bouchard, Towards AI’s CTO and co-founder, covers the design decisions; Samridhi Vaid, an ML engineer and technical writer, implements research; Paul Iusztin, a software builder, educator, and author of the LLM Engineer’s Handbook, develops writing and evaluation.

Architecture starts with cost per task, latency, quality, and data privacy. Moving from a prompt to a workflow and then to an agent gives the model more freedom, but also makes execution less predictable and potentially more expensive. Retrieval, tools, and memory expand what a model can do; adding them does not by itself make the surrounding application an agent.

A workflow can still be sophisticated. It can chain prompts, route requests to different models, execute independent calls in parallel, combine answers through majority voting, or repeat an edit after a judge supplies feedback. The defining property is that the application determines the execution structure. Prompt chaining can simplify individual tasks, but the extra calls do not inherently reduce latency. In Anthropic’s workflow–agent distinction, the agent instead chooses actions in response to its environment: it plans, selects tools, interprets results, and decides when a tool is unnecessary.

Use the smallest mechanism that supplies the missing capability:

Bouchard suggests roughly 200,000 tokens as a working upper range for directly supplying known context, rather than as a universal model limit. Repeated questions about the same report can reuse cached context. Private information, recent developments, or domain-specific material may instead need retrieval after the user asks a question.

A support-ticket system illustrates why a workflow can be sufficient. Its sequence is fixed: receive the ticket, classify it, route it to the right team, draft a response, validate against that team’s policy, and send it. When those steps always occur in that order, asking an agent to rediscover the sequence introduces overhead without adding a useful decision.

Autonomy becomes useful when the next action depends on what the system discovers: choosing an API, deciding whether to write to a database, or branching after a tool response. A Canadian CRM client initially requested a multi-agent marketing assistant as part of an AI-grant proposal. Examining the actual work revealed a tightly connected sequence: plan the request, retrieve client-specific data, generate content, validate it, and repair it if necessary.

Each decision needed the same client and content context. Splitting planning, retrieval, generation, and repair among agents would create handoffs where information could disappear or tool calls could be misinterpreted. The team instead kept one decision maker and implemented specialists as tools. An SMS tool, email tool, or validation tool can have its own instructions, validation logic, and even internal LLM calls. A specialist capability does not require a separate autonomous planner.

Keeping one planner also concentrates context. System instructions, tool definitions, examples, retrieved documents, and conversation history all compete for its attention. Bouchard reports that degradation can become pronounced around 200,000 tokens, well before an advertised million-token window, while emphasizing that the threshold changes. Capacity and effective use are different questions: fitting an entire book into a request does not mean the model will integrate every relevant passage.

His explanation invokes the difference between retrieving an isolated fact and using a whole body of material. The related Lost in the Middle research concerns sensitivity to where relevant information appears; it does not establish the proposed training-data cause or a universal token threshold. The practical response is to keep active context lean through trimming, summarization, selective retrieval, and compaction, including the compaction approaches Bouchard points to in Claude Code discussions. Delegating a bounded task to a tool or sub-agent can also keep its detailed working context separate.

Bouchard offers more than about 20 tools as a heuristic for considering delegation, not a measured cutoff. Other reasons are architectural: independent decisions, substantially different tool sets, or a security boundary such as an agent that must operate inside a hospital. Real applications consequently mix fixed workflows, specialist tools, and autonomous components. The research-and-writing system uses that combination rather than forcing every stage into the same pattern.

A deep research agent receives an objective rather than an exact list of searches. It plans, accesses web pages or other sources, inspects results, identifies gaps, pivots, and synthesizes a cited answer. Feedback can come from its own assessment or from a person. For technical education, the desired result must support an article with runnable code and useful images, so research needs both recall and precision: enough relevant evidence to explain the subject, without burying the writer in noise.

The business case comes from the cost of senior engineering expertise and repeated editorial review. Existing deep research products were useful to the team, but often returned more material than its lessons needed. A custom system could constrain research to the intended explanation and writing to the desired tone and structure. The goal remained writer augmentation: selecting a relatable story or a context-appropriate joke still benefited from a human.

Research and writing need different freedoms. Research must search again when evidence is missing; writing must obey vocabulary, format, tone, and factual constraints. The team therefore separated an exploratory research agent from a more deterministic writer. Internal use then simplified the connection: people generally ran both stages, edited with the writer afterward, and restarted the process for a major change. They did not need continual negotiation between agents.

The handoff is research.md. A basic script runs the stages sequentially, and dedicated files in one project carry their shared artifacts. Those files also give humans a place to inspect or revise the work. Keeping the implementation together reduces maintenance friction and makes the relationship between the stages visible to an AI coding assistant.

The research guideline defines the topic, intended coverage, and useful seed links. These might include a newsletter, an earlier video, or material the team has already produced. Bouchard says tighter goals improved their results, while acknowledging that the system’s creators were also its early users. The intended sequence is to digest supplied sources, search for missing information, and revise the findings into the writer’s final research artifact.

The broader system assigns different sources to existing capabilities:

• Web pages: Firecrawl and agentic scraping handle supplied pages, including sites that are dynamic or difficult to scrape.
• Web questions: Gemini grounded search replaced Perplexity to return focused answers with sources; useful source pages can then be scraped in more depth.
• YouTube: URL-based video analysis replaces a separate download-and-transcribe pipeline for supported videos.
• Repositories: A GitHub-ingestion library turns repository material into prompt-friendly text and accepts a token for authorized private-repository access.

This division lets the agent concentrate on what information is missing instead of implementing every extraction method itself.

The implementation uses Python, uv, and FastMCP. MCP tools expose capabilities, while an MCP prompt provides a recipe for using them. The team alternates Gemini Pro and Gemini Flash according to task complexity; video support and a student-accessible free tier also influenced provider selection. Bouchard recommends comparing models for the actual task rather than treating that choice as permanent. Human checkpoints are encoded in the workflow instructions, with guidelines and output files carrying the interaction. The repository README also points readers to the architecture cheat sheet used alongside the workshop.

In Vaid’s implementation, Claude Code is both the agent harness and the MCP client. Its model decides whether the research has gaps and which capability to invoke next. The server supplies those capabilities; FastMCP handles the protocol plumbing. A different compatible harness can take the client role without moving the research logic into its conversational interface.

The workshop reduces research to three tools. Grounded research returns an answer with sources; video analysis returns material derived from a YouTube video; compilation combines their outputs. The first two persist results in .memory, making the intermediate evidence available for logging and inspection. The compiler reads those artifacts and writes research.md. Research and writing implementations occupy separate folders in the same repository.

The MCP server loads settings, establishes its name and version, registers tools, resources, and prompts, and configures logging. Opik provides observability around the calls. Each tool registration names the capability, declares its arguments, explains those arguments, and delegates to an implementation function. The grounded-research tool takes a working directory and a question. Precise descriptions matter because the harness uses them to choose and call the tool.

Its execution path is deliberately ordinary:

1. Validate the working-directory paths.
2. Ensure the .memory directory exists.
3. Run a grounded search for the supplied question.
4. Preserve the answer and source information.
5. Return status, the original query, the answer, and details useful for debugging.

The research prompt asks for a comprehensive response grounded in official, authoritative references, with clear citations. The wrapper then normalizes provider source data into the application’s URL, title, and snippet fields. This makes the stored evidence consistent for downstream consumers.

Video analysis follows the same wrapper pattern: accept a working directory and YouTube URL, validate paths, extract or sanitize a video identifier, and delegate to the provider call. A dedicated prompt controls the returned Markdown. The displayed prompt requests timestamps, descriptions of visual material, speaker labels, and section summaries, making the artifact more useful than an undifferentiated block of speech.

The demonstrated request contains two parts: the YouTube URL as a file URI and the transcription instructions. Vaid describes Gemini analyzing the video rather than fetching an existing caption file, and estimates two to three minutes for the demonstrated video-analysis operation. Returned text is cleaned and saved in .memory. For reproductions with current APIs, Gemini video understanding supports public YouTube inputs and sampled audio/visual processing, not guaranteed exhaustive frame-by-frame inspection; current grounding documentation also exposes structured citations. Those interfaces may differ from the recording’s request and response shapes, while the application-level normalization and persistence remain the same design concerns.

Compilation reads the research and video artifacts, writes research.md, and returns a success status or message. Resources expose server and model configuration, including the research and transcription models. The workflow prompt then connects these pieces by naming the tools, explaining how to use the working directory, and specifying where results belong.

Local setup uses an environment file for the Google API key and, optionally, an Opik key. A project-root .mcp.json tells Claude Code how to launch the research server. The configuration identifies the server, command, arguments, and environment-file handling. In this workshop, uv manages the Python environment and dependencies, and the launch command invokes FastMCP against the server file. Claude Code starts it as a subprocess that communicates through standard input and output. A remotely hosted MCP service instead uses a server URL; Notion and Snowflake are offered as examples of that connection model. The demonstrated deployment is local.

Vaid first uses /mcp to inspect the configured servers, their launch details, and their exposed tool descriptions and parameters. She then asks Claude Code to analyze an earlier talk about agents. The harness selects the video tool, the server executes it, and .memory appears as the output directory. After execution, Claude interprets the result and points to a Markdown artifact identifying an AI Engineer Code Summit video, with a detailed transcript and a short summary of its key ideas. This single-tool run establishes the full path from natural-language request to a stored result before introducing a combined task.

The first combined request asks for research alongside video analysis. Claude decomposes it into those capabilities and starts with the video. During the run, an audience member asks whether the whole implementation could live in a skill instead of MCP. Vaid explains that she temporarily removed the skill to demonstrate the MCP path and that their skill currently replaces the workflow-prompt portion. The run then returns the video analysis without fully answering the research question. She clears Claude’s conversation context and deletes .memory before retrying, identifying previous-request state as a possible source of interference.

Progressive disclosure is the useful distinction in the next demonstration. A skill’s name and description support discovery; its body supplies the detailed procedure when needed. Agent Skills can package instructions and executable components, but this implementation reuses the existing research-workflow prompt rather than copying it into a second place. Selective loading reduces up-front context; it should not be treated as a guarantee that loaded instructions disappear automatically when a request ends. The files can be versioned and shared with the team.

Using /clear and /skills, Vaid shows the project skill and its discovery metadata. She asks it to research AI agent skills and analyze the supplied video. Because the prompt and server code are local, the skill can read the existing workflow instructions. The harness then runs video analysis and grounded research, inspecting returned information to decide which additional questions would fill gaps. Vaid estimates two to three minutes for this combined research run.

The audience presses the architectural question: a skill could also invoke the executable code, so why retain the server? Vaid’s answer is implementation-specific. The project began with MCP, and the team wants to retain its existing components and server logic while changing how workflow instructions are delivered. At this point, keeping both is a maintenance choice; the broader distribution rationale arrives with the writing workflow.

The successful combined run produces an initial answer, a second distinct search, and another targeted query before compilation. This is the autonomous part of the design: the harness examines what it has learned and formulates the next question instead of executing a fixed list of searches.

A further audience question exposes a freshness problem: why are queries about the latest skills architecture targeting 2025? Vaid suggests that the supplied 2025 video may have influenced the searches, but says she would need to inspect the traces to determine the cause. The cause remains unresolved during the demonstration. The agent subsequently asks to create the Markdown output, and the completed research.md includes detailed comparisons and the video transcript at the bottom. A complete artifact is therefore available, but its research framing still deserves inspection.

The writing workflow consumes research.md and guideline.md, adds reusable profiles and examples, and builds the generation context. It then creates a first draft and runs an evaluator–optimizer loop that reviews and edits it. This sequence is predictable enough to implement as a workflow. The same pattern can support lessons, reports, or book chapters whose requirements include code, images, and references: even occasional omissions create a repeated manual repair burden.

Iusztin pastes one generated post into a slop detector, which returns “not slop.” He describes its position as below a human reference, while noting that outputs vary. This is an illustrative result for one post, without a validated detector comparison. The visible writing goals are more concrete: readable wording, a skimmable LinkedIn structure, and avoidance of the punctuation and expressions the profiles prohibit. The repository includes the full post example.

The guideline controls what to say. Instead of asking for a post on a topic, the author supplies an angle, key points, and a narrative flow. This is the changing human input from one post to the next. Profiles control how to say it:

The terminology profile maintains examples such as “delve,” “tapestry,” and “vibrant.” The character profile uses Iusztin’s biography and preferred style. These Markdown files are reusable and configurable, and they join the guideline in the writer’s system prompt.

The writer also receives three of Iusztin’s posts as few-shot examples. He chose that count pragmatically, not through an optimization study. The examples should be high quality and representative, while varying in topic, length, and structure. His suggested selection procedure is to begin with more examples, remove them while the output remains satisfactory, and restore an example when removing it hurts the result. Every retained example adds recurring tokens, latency, and context pressure.

The workshop dataset draws on roughly 20 real posts from Iusztin’s higher-traction writing. It supports example selection and later evaluation work. Fine-tuning could move some behavioral learning out of the prompt, but Iusztin considers the extra infrastructure and development friction excessive for this starting point.

The evaluator–optimizer loop uses separate writer and reviewer contexts. The intention is to reduce the tendency to favor text already produced in the same conversation. The reviewer receives the draft and checks its adherence to the guideline, research, and profiles. The writer then acts as editor, applying the feedback before another review. The workshop examples use a small fixed iteration budget rather than an open-ended search for a score threshold.

Preserve every draft. Writing is subjective, and a later revision can satisfy more rules while becoming less appealing to its author. Keeping earlier versions gives the person a choice. For the same reason, the team found score-based stopping noisy: a subjective threshold was difficult to define consistently. A fixed number of iterations bounds the work, and the user can request more if useful.

The reviewer returns structured Pydantic objects instead of unrestricted commentary. Each issue identifies the governing profile or requirement, the location, and the requested correction. Field descriptions tell the model what belongs in each attribute. A compact Python representation of the demonstrated feedback contract is:

from pydantic import BaseModel, Field


class Review(BaseModel):
    profile: str = Field(
        description="Guideline, research, or writing profile being violated."
    )
    location: str = Field(
        description="Paragraph or passage where the issue occurs."
    )
    comment: str = Field(
        description="Explain the violation and the correction to make."
    )


class ReviewBatch(BaseModel):
    reviews: list[Review]


feedback = ReviewBatch(
    reviews=[
        Review(
            profile="terminology",
            location="paragraph 2",
            comment="The word 'leverage' is banned; replace it with direct wording.",
        )
    ]
)

print(feedback.model_dump_json(indent=2))

The paragraph-two terminology violation is the example Iusztin uses. The object records a proposed correction; it does not itself edit the draft. He reports that structured feedback worked better in the team’s tests than unconstrained review text, without supplying a numerical comparison.

The editor receives those review objects, the current post, and the original writing context. When suggestions conflict, the demonstrated priority is guideline first, research second, and profiles third. This lets a specific user requirement override a generic style default. The before-and-after example compares version zero with the output after four review iterations: the opening is punchier, the wording changes, and the layout is more appropriate for LinkedIn. Versions zero through four remain available for inspection.

The writer has three entry points: a simple make command for an end-to-end local check, an MCP interface, and a write-post skill. Iusztin reports a three-to-four-minute writing run and shows precomputed output. The skill receives a relative directory path, locates its guideline and research, and writes the post versions there. The displayed directory contains the initial draft plus four revisions.

The guideline in that directory specifies the angle, audience, key points, tone, and character constraints. Its explicit requirements can override static profile defaults, including length. The human still has to decide what the post should contribute. A lightly developed extension invokes another tool to generate an image after writing. To adapt the workflow to other content, change the profiles and examples along with the output requirements.

Iusztin then answers the earlier MCP question directly: this local example could run entirely through skills. The reason to retain a server is distribution. A code-bearing skill may ask each recipient to install Python dependencies, configure CLI tools, and supply credentials. Centralizing business logic behind a server can reduce that per-user setup, while skills personalize how the capability is invoked. The appropriate boundary depends on who will operate the code, not on whether a skill is technically capable of running it.

Terminal logs become difficult to interpret once execution includes multiple model calls, tool calls, and revision loops. Monitoring should preserve inputs, outputs, metadata, token usage, latency, and cost, with enough structure to connect them. The same retained traces can later supply evaluation cases. Both the research agent and writing workflow are instrumented in Opik.

In the writing example, a thread represents the broader interaction that produces a post and image. The displayed thread contains 44 messages. Its traces let Iusztin descend into a generation operation, inspect whole-operation timing and usage, and then inspect the nested tool and LLM calls, including their model, cost, and latency. Inputs and outputs sit alongside those measurements, so a slow or incorrect result can be connected to the request that produced it.

Research uses the same hierarchy. Its thread contains successive searches and report compilation, while the shown individual research traces each contain one LLM call. This distinction helps explain the architecture: one grounded-search call is a capability; the harness’s sequence of searches is the larger reasoning process.

Reading one generated post is easy. Reading ten already invites spot checks; reviewing a hundred after every prompt change becomes a different job. Iusztin uses that progression to motivate automated evaluation across both outputs and versions. A small prompt edit can change behavior elsewhere, so a favorable impression of one result is insufficient evidence that the system still works.

Evaluation serves three distinct purposes:

• Optimization: Measure whether a proposed change improves the behavior being targeted.
• Regression testing: Check that new features preserve existing behavior.
• Operational monitoring: Evaluate live traces and surface problems after users begin using the system.

All three depend on a dataset that represents the work. The workshop starts with 20 real LinkedIn posts; Iusztin suggests expanding the overall dataset to at least roughly 100 for a fuller application.

The dataset construction procedure keeps the actual writer under test:

1. Derive a guideline from an existing post.
2. Run the research agent on that guideline.
3. Give the guideline and research to the writing workflow.
4. Label the generated post as pass or fail, with a short critique.
5. Split the labeled examples into training, development, and test sets.

Synthetic assistance can help create inputs, but the outputs must come from the system being evaluated. Otherwise the evaluation measures fabricated examples rather than the writer’s behavior. Iusztin’s labeling practice is to stop at the first failure, explain it in two or three sentences, and move to the next example. Only after those labels and splits exist does he build and evaluate the judge.

The LLM judge receives a generated post together with its guideline, research, and profiles. It returns a binary pass/fail label and a critique. Training examples include the writer’s inputs, the actual generated output, the human label, and the human explanation. Those examples teach the judge which deviations matter; a complicated system prompt is less useful than examples that capture the expert’s decisions.

The judge is a classifier that must itself be evaluated. Its purpose is to agree with a domain expert, not merely produce a confident critique. Iusztin measures that agreement with F1, which combines precision and recall:

Here, P is precision and R is recall for the class and averaging convention chosen by the evaluator. Calibration runs the judge on the development split, adjusts prompts or examples, and repeats. The test split is reserved for the final validation after those choices are made. Once calibrated, the judge can label new workflow outputs.

The order matters: build the dataset, construct the judge, calibrate it, and only then apply it to new data. Opik manages this process in the workshop, but the same sequence can live in another platform or an internal implementation. What matters is keeping the examples, predictions, experiments, and traces connected.

The calibration demonstration reruns an already calibrated judge. A small evaluation harness passes generated posts to the judge and compares its predicted labels with the dataset’s human labels. The dataset’s YAML index links each sample’s media, guideline, research, generated post, and annotations. Scope assignments distinguish generator examples, evaluator examples, and held-out evaluation cases, keeping the different uses of the same collection explicit.

The demonstrated judge achieves F1 = 1.0 against human labels on both the development and test splits, with only five samples in each split. These are judge-agreement scores, not measurements of the writer’s overall quality. Iusztin attributes the perfect results partly to the small splits and recommends expanding each evaluation split to at least 20–30 samples.

Asked which F1 would justify deploying a judge, he emphasizes the relationship between development and test performance and the requirements of the task. A large drop on held-out data is a warning to investigate generalization; a test score below one is not itself proof of overfitting. There is no universal near-perfect deployment threshold. In Opik’s experiment view, predicted and human labels can be compared directly, while the critique explains the decision for a person investigating failures. The F1 calculation uses the labels, not the prose critiques.

The next demonstration applies the judge to a simulated online workload. It generates real posts through the workflow and evaluates them, rather than substituting fabricated writer outputs. Iusztin shows precomputed results because he says the simulation takes about five minutes or more. The experiment view places generated posts beside binary judgments and critiques.

The judge passes every trace in the simulated online experiment, despite human labels showing failures. This result changes the interpretation of the preceding perfect scores: the small held-out sets did not cover enough of the behavior encountered in the simulation. Iusztin proposes taking these failure cases back into development, expanding the examples, and refining the judge again. The evaluation layer is useful here precisely because its own failure is visible.

The final entry point is /research-and-write. Give it a guideline file, and it runs research before continuing into the writing workflow. Opik threads and traces expose both stages. The practical next step is to run the companion project and read the code alongside those artifacts: the guideline captures intent, research.md carries evidence, saved drafts expose editorial changes, and evaluation results show where the system still needs work.

The workshop closes by distinguishing this small local system from the team’s broader course on production-ready agents. Iusztin advertises 34 lessons, three portfolio projects, a certificate, Discord access, and six free introductory lessons; he also reports a five-out-of-five rating from more than 300 students. The local implementation remains a starting point for inspection and iteration, with the simulated judge failure supplying a concrete reason to keep improving the data before relying on automated approval.