Full Workshop: Build Your Own Deep Research Agents - Louis-François Bouchard, Paul Iusztin, Samridhi

Hello, everyone. Not too loud? I hope—yeah, I hope it's fine. Perfect. So, yeah, we will start—uh—kick off the workshop, and we will introduce ourselves shortly. But first, we just wanted to present the slide because that's basically LinkedIn this year.

It's the type of content that, when you ask ChatGPT, that's basically what you get: a very generic response. And there are a few things wrong with this actual response, or that we don't really like seeing. The obvious ones are the slop words, the AI slop, so all the Dell intricacies that we all know about.

But there are more—and fortunately there aren't even some em dashes in there—but there are some other problems, like the—

Ow, ow, I was sitting there.

Allright, the lines are a bit off. But the most that is more general, like most companies miss, or most people miss, it does that often. These are some examples from LinkedIn posts, where they all say "most teams," "most people," or here "most AI projects," and I'm actually guilty of that one.

So, uh, we learn as we do. And there are some other problems with hallucinations, or here "outdated information." Obviously, this was generated, like, last week, and GPT-4 is not state-of-the-art. And likewise, there are some AI phrases slop with that we see a lot.

The obvious "rapidly evolving" one, but also the classic "it's not about something but something else" that it generates a lot. And the worst of all is that, typically, this is really meaningless and shallow. It doesn't provide any value or anything useful.

And so what we need here is proper research and proper writing around these language models. And to give more context of this workshop, we basically, at Towards AI, create courses and tons of videos, training, and technical content. And to do that, we need to create technical content around AI engineering.

So we need technical writers, which means we need AI engineers, writers, editors that iterate together, and a lot of time to create a good storytelling, a good—just a good article, good lesson, or good video in general, which in the end costs a lot of money.

So what we tried to do is to automate this process, which we did, or at least a part of it, because another part is really a human thing to make a good story relate to the others. And so that's what we did.

We built a system for replacing this whole process of doing a very thorough research and then technical writing. So what it does is we give a topic, like "what is harness engineering," and we have our own deep research agent that will search various websites and tools, use tools to do lots of things, and then another system to write an actual technical article with code, images, and ideally non-slop writing in there.

And actually, the system, since we build courses, we used it to build a course to teach it to build this system. So it was a really fun project to do in general, and it allowed us to iterate and test a lot and to have user feedback directly with our students.

So it was—it's really nice. And that's what we try to share here in this 2-hour workshop, or at least a much more compact version with a deep research—a smaller, simpler deep research system and a writing agent strictly for shorter content for LinkedIn type of posts.

And also we try to share what we learned building it. And you can open the—or get the GitHub repository. It's public. In the first 30 minutes, I will just talk with slides, so you won't be needing it. But after that, my colleagues will jump in with the code, so it might be worth to have it.

And we will show this QR code again later on, so you can get that on time. But basically, I will cover what we learned and some terminologies, because we are an educational company, and that's what we like to do.

And so I will cover, like, some basics to bring everyone to the same level, or at least to our definitions of things, and share what we learned by building it. And then Samridhi will take over to talk about the actual deep research agent, and Paul with the rest.

So who are we? On my end, I'm the CTO and co-founder of Towards AI. My name is Louis-François, and I was a PhD student in AI until ChatGPT came out, where I basically switched to being an educator full-time and creating Towards AI to focus around that.

I've been doing videos to explain research papers for 7 years now, and obviouslyright now I'm more around AI engineering. And I've been developing in the space since 2020. At first startup, I was hired at. And so I will leave Samridhi to introduce herself.

Hi everyone. I'm Samridhi. I am a machine learning engineer. I'm also a technical writer and consultant helping Towards AI grow. So nice to meet you all.

Hello everyone. I'm Paul Iusztin, and I'm building software for 8 years, and I've been into the teaching AI space for 4 plus years. And I'm also the author of the LLM Engineers Handbook bestseller, and I'm excited to show this workshop to you guys today.

Perfect. So I'll start with introducing. We always start with a problem. And here it's pretty general. I start introducing the AI engineering problem space, where basically it's just that all our decisions as AI engineers are governed by constraints that typically are applied less to software engineers, which is like the cost per task, which can swing a lot based on the model you use, the architecture you use.

We have latency requirements with reasoning models and other things that we can control. We obviously have some quality to respect and data privacy in this case that we need to be careful of. Fortunately, we have a stack to help us, whether it is from prompt engineering, context engineering, to using tools orchestration, or building our own evaluation systems.

And we like to see that as some sort of autonomy slider that goes from very simple just prompting a model to building agentic systems, where the more you add complexity from prompting to more advanced workflows to agentic systems, the more autonomy you add, but also the less control you have over your whole system.

And obviously, the higher the cost. And to us, that's very important to choose when we build for—we also build for clients, so that's why we try to teach what we build and all this loop. But to us, it's really important to build theright system where we don't need

too much autonomy, where it can add problems and uncertainty. And obviously, most people are interested in building agents, but most of these agents that our clients want are actually somewhat super simple workflows, or at least workflows that we can come up with pretty easily.

And so I want to try to start by defining workflows up to multi-agent systems, finishing with this deep research example that we have made. So what is a workflow? A workflow is very simple. It's just a language model but augmented, mostly because language models just take in tokens and text and generate tokens and text.

So you cannot do much with text other than reading and writing emails, which a lot of us—some of us—do more than that. So ideally, you want to add stuff to it, like adding data that it may not have access to, whether it's at your company or some other data that needs to best answer the user.

You can add—you can give it access to tools to do other things than just generating tokens. And you can add memory so that it can remember the interaction and be much more useful. But still, this is not an agent.

It's just a thing we can build easily that can be reliable. And a workflow can be even more complex than that. You can chain prompts together to reduce the latency and complexity, to do many more things based on strict conditions.

You can even do that with a router to decide automatically based on conditions, on what you want to do, whether it is to use a smaller model or just do a different task and then come back. You can do that in parallel to be more efficient or to improve the results with majority voting and other techniques.

And you can even add loops to automatically improve the results based on a judge feedback. But all this is still not agentic. It's just a workflow that we can build and add all these things. We can even combine them.

We can build really advanced workflows. So when does that thing become an agent? And here again, I'm using an illustration from Anthropic. It's a definition we really like. It's just when it needs to take actions, and more importantly, when it can react to what happens in the environment.

So very simply, it should be able to take autonomous action and react to what happens, as I said, and be able ideally to plan, to decide which tool to use, and more importantly, which tool not to use, how to respond, and everything.

So when should we use this thing, an agentic system, compared to a workflow? Well, typically, we always want to use the simplest solution. If just a prompt works, that's ideal. And when we build things, we always try to start with questions and use our sort of autonomy slider.

So just a list of simple questions we can answer would be if the model already knows enough about the task to be done, whether it is the user asking a question or some other task. Obviously, you can just prompt it and do it, and ideally add some examples, so few-shot examples, just because it really helps the model to adapt, somewhat adapt on the fly, which would be just simple prompting.

Then if you need external context, if it's not too big and you can paste it in the prompt under somewhat around 200,000 tokens, you can just paste itright away and ideally have it beforehand before your user asks it, and use context caching so that it's more efficient to just, for example, answer several questions about the same report or your privacy documents or whatever internal documents you may have.

Now, if the context is not known until the user asks a question to your model, this is where you may try to inject knowledge on the fly based on the question, whether it is because your data is private and you need to retrieve it to answer the question, or if it's something recent that the models haven't been trained on or domain-specific, you might want to inject knowledge.

And if you want to do all this in different ways or depending on conditions, this is where you use a more advanced, quote-unquote, "workflow" with predetermined steps and sequences. And so in practice, an example of a workflow we built for a client was support ticket handling, where basically you have always the same steps in the same order.

The system receives a ticket, it classifies it, routes it to theright team, it drafts a response, it can validate it against the policy of the team, and then send it. And here the key point is that these steps are always the same.

The order never changes. It always needs to do

these six steps in the same order. And so building this as an agent would just add overhead without adding anything extra. You don't need to dynamically react on anything here. You just need to execute these steps. So a workflow definitely makes sense in this case.

So for an agent, what you want to ask yourself is if your system needs to take actions or to be able to branch dynamically. So whether it is to call different APIs depending on what the user needs, or write to the database or not, do reasoning, and other things.

This is where an agent can be useful. And an example we had was a CRM platform in Canada that wanted to create a chatbot for their CRM platform for their users, their clients, to be able to generate marketing content automatically.

And initially, they reached out to us because they were applying to an AI grant, and they wanted a multi-agent system to do a lot of different things with agents for everything, which did sound really well for the grant because it was like AI-focused.

But it seemed really overkill to make many agents to do something quite simple as a marketing chatbot. So in the end, what we always do is to try to really understand what the client needs and wants, which is oftentimes very different.

And so by talking with them, we figured that the actual workflow was always somewhat the same, always simple. The agent needed to make a plan to decide what it should do, then retrieve the data specific to the client, generate the content, validate it, and fix it if needed.

And so the tasks were always sequential, the same few tasks that we wanted to do. They were super coupled, always the same thing about generating marketing content, but just for different clients and for different formats. And the whole sequence is context-dependent.

So whether it is the plan, the retrieval, or generation, or fix, it all needs to have the content in mind to be able to generate the best content as possible. So splitting decisions across different agents as the client wanted would have caused a lot of issues, whether it is information or just handoff errors with tool calls and other things that would

reduce reliability. So instead, we just built one agent but used tools as our capabilities. And this is really great because with tools,

they can have their own system prompts, they can have their own validation logic, even their own LLM or own LLM calls. So we can do tons of things with tools. And from our example, we had like a validation tool, one tool specific to all formats, the SMS tool or email tool.

And the result is that we use tools as specialists, but the global context stays within our only agent, the decision maker, and the planner. But if we do that, it means that everything stays within our agent. So we have a constraint, which is the context window of our agent, of the model that we are using, which is made of many things: the system prompt, obviously, the instructions that we give it, the tool definitions, the different schemas, and how to use these tools, few-shot examples of the task to be done.

It's really great, obviously, to teach by examples. As we've seen with models, they learn very quickly that way for most tasks. You can have retrieved data depending on what you want to do, and even entire conversation history if it's a chatbot or whatever type of agent that evolves over time.

So all this can take up a lot of space, which causes a problem because as we go through each of these steps, the context grows and the performance degrades, which we call context rot. And the problem is that this happens much before the actual context window limit of like 1 million tokens, for example.

It worsens quite fast after like 200,000, or it keeps changing, but around 200,000 now. And this is mostly because the lost-in-the-middle problem, where we basically teach these long-context models to be able to handle long context by feeding them a large corpus, inserting a random fact in them, and retrieving that fact.

So it's basically more retrieval of one specific thing, but it doesn't teach those models to leverage the whole book, the whole context, to answer the question. So it's definitely not ideal, but it would be too expensive to build this kind of large dataset.

So this way of training them caused the problem of

us having to manage this context budget, which means to always keep the context as lean and relevant as possible, both to reduce cost in terms of token amount, but also to improve the metrics that we are using. And we can use many techniques for that.

We can trim the content, we can summarize it, we can retrieve based on criteria. Or there are also many interesting techniques in the Cloud Code Leak compaction methods that I recommend looking into, really powerful ones. But the one I'm most interested in for this talk is the delegation that we can do to either tools or sub-agents with their own context, which is what most

harnesses that we use are doing. And so this leads us to the multi-agent systems, where we basically want to use them when we have too much of this context, mostly, like over 20 tools, or just the context becomes way too large.

We can delegate to tools or to agents. And there can be other reasons, like if you need to make autonomous decision-making, or you need tool variability, or just security compliance, if you need to have one agent locally inside one hospital, for example, because I was in the healthcare field before, and we used to have everything local.

So that can be a reason for multi-agents. And why am I talking about all this? Because what we've seen is that AI products are never just you build an agent or you build a multi-agent crew AI thing. They basically combine all of that.

They combine tools, workflows. Some parts are more specific and predefined, some parts have more flexibility. And we believe that AI engineers need to understand all these to build complex systems. And Deep Research actually implemented that. It's a very good example of a complete system since they integrate all of these techniques.

And before we show how we built our own and allow you to use it as well, let me just cover quickly what a Deep Research system is, just in case. It's a reasoning system that will plan what it needs to research about.

It has some autonomy to decide what to research about. It has tools, internet or web access. It's reliable. It will cite its sources. It has feedback loops with itself, but also with the human for human feedback. So this is much more agentic, as we see.

It evolves in an environment, which is typically the web or user-provided sources or just API access. And it's goal-driven. It has one objective. We don't tell it how to do it exactly. We just tell it, "Do a research about something."

So it's typically much more than just a chatbot. It basically replaces someone that would do a very thorough research about a specific topic. It plans, it searches, it inspects, it pivots, it synthesizes information, and can iterate. So Deep Research Systems are really, to us, one of the best projects to learn how to build such a complex end-to-end system.

So we decided to build our own. And in this case, our own is basically an end-to-end technical article production from a topic because we create lessons, course lessons in our case. So it came out of real utility, which is the most important part.

So the goal here is to take a topic, research deeply about it, and write a very good technical article with code integration that is actually runable, with images that are useful, not just randomly generated images throughout. And there are a few challenges when doing this.

First, you need a really high precision and recall when doing the research because you need as much relevant sources as possible, but you don't need too much of them because of the limited context problem. You need to reduce hallucinations and AI slop, obviously, and incorporate a lot of human feedback, especially in the writing aspect.

And as we always do with projects, and I think you all should do as well, we started this with asking ourselves questions to better understand how we should do it and if we should do it at all. So the first question is, is this worthwhile?

Is there a solution outside of what we could build that already exists? So our analysis is that high-quality technical content is expensive to produce. We do that every day, and we need a lot of people, and it needs a lot of time and review.

And it's just really time-consuming, really expensive, especially because these people need to be somewhat senior AI engineers to be able to explain anything in AI engineering. So they need expertise, but to teach someone not to build a successful product.

So it's expensive and not that lucrative. So yeah, it would be ideal to automate most of this process. As I said, the research needs strong recall and precision. And on the other side, the writing needs to be more constrained.

It needs to avoid hallucinations, be of high quality, follow your tone or the writing tone that you want, the structure that you want. And in terms of Deep Research tools, we use all of them pretty much daily. And they are way too exhaustive.

They gather way too much content, and they have a lot of noise. It's not ideal for us in our case. We do use them, but we decided to build our own just to

be able to do exactly what we wanted. So the decision is, yes, that this was worthwhile, but especially as a writer augmentation, not to replace them. Because as we've seen, even if you

do as if you build the best system possible these days, it's really hard to create a piece of content, whether it is a video or a written lesson, that connects with the reader or the viewer. You really need a human touch so that it's relatable to someone.

You need to make jokes, good jokes, not the same ones all the time, and the ones that are appropriate to the context. So it's really difficult to automate all this, and we want to keep a human in the loop there.

Now, the first actual question we ask ourselves is, what should be the architecture? If it should be an agent, multiple agents, a workflow. And the analysis here is that first, we have the research part that is really exploratory.

It needs to

find lots of sources. It needs to explore the web to understand what it needs to find if it misses information. So it needs to be able to iterate, to pivot, to search again. It needs a lot of flexibility.

And on the other side, the writing agent is much more deterministic. It needs to follow a specific tone, to follow a structure,

yeah, it needs to be much more constrained than it needs flexibility. You don't want this AI slop. You don't want specific words, specific sentences. You want specific sentences and specific formats. So it's much more constrained. So we have a conflict here where the research needs flexibility, but the writing needs constraint.

And so the decision is to split into two systems: the research agent that is more exploratory, dynamic, more agentic, and the writer agent, the writer system that is more deterministic and consistent. And we have tons of these questions, and we show in our course exactly how to build these two systems.

But here it's just two hours, so we focus on the research agent a bit more, especially for the next few questions. So here, how should it be created? Well, how should the research agent communicate with the writer workflow, the writer step?

Well, we pivoted a few times after testing it, and that's the most important part, is to actually use your product, or a potential user should use your product to give you feedback as early on as possible. And on our end, we used it to build a course to use it.

So it was really easy to iterate and to teach what we learned and what we did. And what we saw is that our users, which were myself and the team, saw that we always used either both agents or we didn't use a system.

So we weren't just alternating between the research and then the writer. If we were to alternate, it was just with the writer at the end to add new suggestions, new topics, new information to add to the article or to remove it.

But the research was already quite perfect and done beforehand, as you will see with Samridhi. And if a big change was needed, we just would rerun the process again. So we didn't need to have proper orchestration in place.

And the two agents work on the same artifacts. The research agent produced a research.md file with all its research summarized and sent it to the writer. So they need to have ways to communicate together. So the decision that we made is to separate the two agents and run them sequentially without orchestration, so just a script, just a very basic script.

And our two agents are in the same project so that it's easier to maintain, but also they share dedicated files. So it's easy to have them communicate with each other, but also have them communicate with us through these files.

And having them together in the same project is useful for AI-assisted coding with Cloud Code or whatever system you are using. The next question for the research agent is, how should it behave? So we really wanted to understand what would be the process that we would want out of this research assistant before building it.

And again, we refined this after testing. And in the end, we really needed a good human-written guideline, which would basically be just what is the topic about anything I'm interested in covering in this lesson, and useful links that we think are relevant.

Sometimes I send the AI newsletter on some specific topics. Sometimes it's my own videos or other topics that we covered. And we saw that, obviously, there's creator bias here, but we saw that the more we define the agent's goal in the guideline, so the less freedom it had, the better the results were.

Then if we give links in that guideline we send to the agent, the agent needs to scrape web pages. It needs to be able to digest YouTube videos, GitHub repositories, even if they are private to the user, to myself, to gather all the necessary context.

And then after that, it needs to do its actual deep research thing, so search the web for anything that is missing and needs understanding, and then revise all this context and write that into a very nice final artifact that will be sent to the writer agent.

So how did we do all that? How did we scrape web content that we give the links to and do web searches? Well, we, as always, simplify the problem and don't reinvent the wheel. We use existing things, existing systems and APIs, and divide the problem into simpler problems.

So first, scraping solution, we use Firecrawl and agentic scraping. And this is for many reasons that, well, Samridhi will talk a bit more about the research agent, so I won't cover it too much. But it's really useful to have this kind of scraping for more dynamic websites and other types of websites that can block scraping.

And for web searches, we used to use Perplexity, now Gemini with Grounding, to get precise answers with sources directly, which we can then scrape if we need to. But otherwise, we can already prompt it well enough to get the information we want from these grounding queries.

Now, for YouTube videos, because there are a lot of great information on YouTube, we want to ideally pass just the text to the agent because the video is quite heavy. And we tried a lot of things, but typically, a lot of things, but typically, you need to download the video and extract the transcript.

But fortunately, Gemini now handles this directly with a YouTube URL. You just give the YouTube URL and ask questions about it, or even ask to provide the transcript. So it's very useful. We decided to use that, obviously. And now for the GitHub content, we just used the GitHub ingest library to get GitHub-specific content into Markdown, and we can provide it with a token to access our private repositories.

So it's really simple, and you will see that in the repository. For framework, we used MCP with FastMCP so that we can have tools for the different processes. And we can have an MCP prompt to basically give a recipe on what to do and how to use the tools to the agent, which is very useful.

We will talk in depth about that in the next hour and a half. Then for the setup, we basically just used Python, UV for managing the dependencies, and GitHub, obviously. And for the models, we recently changed for everything to be Gemini, mostly because of the YouTube thing that I mentioned, but also we saw that first, it works really well, and we can alternate between Pro and Flash, the cheaper one and more expensive, depending on the complexity of the task.

So we use them alternatively in the code. And the one thing that we really like is also that it has a free tier for our students, so it's really convenient for us. But obviously, we also compared to the other models.

We were using Opus before and other cloud models and even OpenAI's. But we've seen that Gemini is much more interesting, especially from OpenAI these days. So we are using Gemini, but you need to compare with different models to be sure that you are using theright ones.

And finally, for the more theory part, how does the research agent communicate with the user? It's inside the MCP prompt. We have specific steps to stop and interact with the users. And all these interactions are handled through files, whether it is the guideline or the research file or other files that Paul will talk about in the writer part.

And by the way, everything I mentioned and much more is in some sort of cheat sheet that we also linked in the README of the repository. So you can definitely access it for free, obviously. It's on GitHub. And now is the part where we talk about the deep research.

And so you can scan the code if you haven't to get the repository. And Samridhi will take over. You want to come down? Okay.

Sorry, everyone. Just give me one minute.

Okay.

Awesome. So I'll be talking about the deep research agent. And so what is a deep research agent? As Louis already explained, that it can search any topic by searching the web. It can analyze YouTube videos. And finally, it'll give you a cited report.

How we've built it, we've used MCP for this, which is an open standard for giving agents access to tools and data. The key idea, like the design choice here, is that the agent is the brain that is doing all of the reasoning.

As Louis highlighted, that any gaps that are there in the research part are being done by the agent. It thinks if there's anything missing in the research, if it needs to run multiple researches, or it has to search something else, that is the part that is being done by the agent, whereas the server, the MCP, is handling all of the capabilities.

So it's going to be exposing all of the tools. It's going to be exposing the resources and the prompts that are there. We've used something called FastMCP, which is a library that really makes creation of agents very easy.

So it hides all of the complexities, and you do not have to write any sort of protocols or any sort of communications between agents. All of that is handled by FastMCP. And we're using Claude Code as our agent harness.

But this code is independent of that. If you're more inclined towards using Cursor or GitHub Copilot, you can swap Claude Code with any of the agent harness that you like. So I'll be repetitively talking about these three things.

So an MCP server exposes tools, prompts, and resources. So what are tools? Tools are basically all of the actions an agent can take. So like deep research, or like going and doing Google search, or like analyzing a video and giving us a transcript, or compiling a report.

So all of these action-oriented things are done by tools. Whereas the second thing that the MCP exposes is prompt, which is basically instruction. When you're talking to ChatGPT, you give it instructions. So this in case is prompts that the agent can follow.

And in our case, we have a detailed prompt that I'll show you in a minute with the code. And finally, the third thing is resources, which is the data the agent can read. So this is like static data, which is the model names we're using, the sort of versions that we have.

If we have any sort of feature flags, those are all part of the resources. So these are something that the agent can read. There is no action being done here. In terms of tools, we have three tools. So first is the deep research tool.

The deep research tool basically does Google search and gives us sources for everything that we have. So it provides us with answers for any sort of query we have. And also, it provides us all of the sources of that.

So we're using Gemini API for this. The second tool that we have is the Analyze YouTube video tool. For this as well, we're using the Gemini API. So you can take any YouTube URL and paste it, and it's going to give you a transcript here.

And finally, we have the compile research tool. So it basically compiles the output of the previous two tools. So we're going to be talking more about the .memory file and the details of that when I show you the code.

So I just talked about the parts of the agent that we have, but this is the overall architecture. So we are using Claude Code as MCP client. Just to highlight here, Claude Code for us is both MCP client and an LLM.

So it is like the brain, which is being used. Also, it is MCP client, which is talking to the MCP server that we have. The FastMCP server that we have has tools, resources, and prompts. These are the details about each of the tools that we have.

So all of these tools, the first two tools write to a folder called .memory. And basically, we wanted something. We wanted to preserve all of this because it is easier for logging. It is easier for us to verify all of the results that we're getting.

So we are writing down all of our results to a folder. And the third tool reads from this folder and creates a file for us, so a research, a Markdown file called research.md. The first two tools do API calls to Gemini 3.

And finally, everything is like read and written to this particular folder.

So now I'm going to show you the code.

Okay, so this is how the let me just zoom a bit. Sorry. Okay, perfect. So this is how we have structured our code. You don't have to get intimidated by this. So we're going to simplify it a lot.

So these are the main two folders, the research folder and the writing folder. Paul is going to be talking about the writing part. I'll just go and talk about the research part. So if you remember, when I started my presentation, the first thing I talked about was the MCP server.

So this is the MCP server file that I have. And then this is how you set up the MCP server. So we have some settings that we are loading up here. So these are basically the name of the models that we have.

I can show that to you in a minute. And this is how you set up the server. So you give it a name and the version. And then you register three things. So this is something that you should remember.

We're registering tools, resources, and prompts. And then we're just setting up basic logging here. And we're using something called Opik for observability. And Paul is going to be talking more in detail about that. And then we're finally creating the MCP server.

And now let's see how we have registered the tools. So if we go to this file called tools, the Python tools file, this is how we have registered the tools. So for registering the tools with FastMCP sorry, for registering tools, you need three things.

The first thing is, of course, the name of the tool. So here, the name of the tool is deep research. The second thing is arguments. So we're passing it to arguments. The first one is the working directory, and the second is the question or the query that we're going to be asking it.

Then you need a definition for what your tool is going to be doing. So you have to be as precise as possible when you're writing this definition. And finally, we also have the definition for the arguments that we have.

So this is the way you write the tool. Then we just have the code for the observability. And then finally, we have the implementation. We're returning the implementation for the tool. So this is it. So this is how you define your tool.

And there's no complications here. But let's go into a little bit more detail about the tool itself. So how this tool is working. So for the deep research tool, basically, in the first step, we're just validating all of our parts.

So we're checking if we are in the current directory or not. And secondly, we are ensuring that the memory file that we're writing to, basically, it's a folder where we're writing all our results to, if it exists or not.

And we do all of this validation here. And then we run this grounded search on the query that we have. Once we get the result of this query, we return the status, if it's successful or not. What was the query that we sent?

What is the answer that we get? So we get like a detailed response. And this has been very helpful for our team to debug and go through all of the data that we get so that we can refine the research results we have.

Going into more detail about how we are running the research. So if you see this, the run grounded search function that we have, we have a prompt that we've already written. So if you go here, you can see the research prompt that we have.

So we're basically saying that if you have any questions, you have to provide a detailed, comprehensive answer to the question that is there. Focus on only official, authoritative references, and make sure you're including all the relevant details as possible.

And make sure to cite your sources clearly. So this is the prompt that we're using for the deep research tool that we have. And then we're just calling the Gemini API here. And we're getting the answer text and the sources.

Then in this part of the code, we're just so I mean, every time you get sources from Gemini API, it's not in a structured form. So here, we're just trying to structure it in a better way. I'll show that to you when I run it.

You'll see that we get the output in this structure, where we get the URL, we get the title, and we get the snippets. And finally, we are returning the research results. So this is all the details about our first tool.

But going on to our second tool, which is the YouTube video analysis. So this has also got the same structure as the deep research tool that I showed you. So three things. The first is the name of the tool.

The second is the arguments that it is using. So even in this case, it is using the working directory and the YouTube URL. And then the details about the tool, what it is doing, and the details about the arguments that we have.

And then we're just returning the execution of the tool. So going into more details about what the Analyze YouTube video tool looks like. So here is the implementation for that. Similar to what we did for the deep research tool, we're validating all of the parts here.

And then we're taking out the YouTube video ID using this get video ID function. If we do not get the video ID for the YouTube URL that we have provided, we try to sanitize the result and get the video ID.

And then we're calling this is the line where we're calling the Gemini API. And similar to the deep research tool, we're returning all of these different details so that we can keep track of the things. We can see what is the output that we have got.

And let's go into the Analyze YouTube video implementation. So similar to the deep research tool, we have a prompt for the YouTube transcription. And here is the prompt that we have written.

So we're just saying that you have to this is basically guiding the Gemini API to give us the transcript in a certain format and give us all of the instructions and the details that we want in our output.

So for this part, so here we are dividing our requests into two parts. The request that we're sending the Gemini API. In the first part, we are sending the file sorry, in the first part, we are sending the YouTube URL that we have as a file URI.

And in the second part, we are sending the prompt that I showed you. And this is like a very cool thing.

So Gemini is a multimodal model. And actually, when you send a YouTube URL as a file URI, it actually sees the video. So it goes through part by part. It doesn't access any sort of transcript. And that's why when we'll be running the

YouTube video analyzer tool, you'll see that it takes like two to three minutes because it is actually going through your entire video. So it is like really multimodal. I mean, in here, we are sending the request to Gemini.

And once we get the output, we try to clean the output that we are getting in a certain format and then outputting it and saving it in the .memory folder that we get. Finally, coming back to the final tool that we have, which is the compile research tool.

So what it basically does here is it returns and compiles all of the results that we get from the previous two tools. If you go here and see the implementation for the compile research tool, you'll see that what it is trying to do is it is trying to write to the output research.md file.

And then it gives us a success status or a return message. So we have seen how we have registered the tool in the MCP server. Similarly, we've got the code for registering the resources. So here are all the things that we are sharing with the agent as resources.

So basically, what is the name of the server that we have, the version that we are using, what sort of Gemini model are we using, what is our YouTube transcription model? And all of these different details are being provided to the agent using resources.

And then the MCP prompt. So this is how we have registered the MCP prompt. So basically, we're returning something called workflow instructions. And this is the detailed prompt that we have written. So basically, in this prompt, we are telling the agent that these are the tools that are available to you.

And you can use this workflow to use these tools. And some additional details about the working directory and where all of the results should be stored. So this is our detailed prompt that we're giving to the agent. Awesome.

So going back, this is like the sorry, one more thing I wanted to highlight here is that this is our env file. So this is all being accessed as resources. But this is where you'd have to add your Google API key.

You can add the Opik API key if you want any sort of observability. But this is the env file that we have. Additionally, apart from that, we have the scripts here, which are helping us with the code throughout.

And these are scripts we have written additionally to manage some of the utils. So sorry. Yeah, going back. So now we have the entire architecture there. And so how do we exactly connect it with our agent harness? In our case, this is Claude Code.

So this is a very straightforward way. For Claude, you just need to create an MCP.json file in the project root and give it a command like this. And then for our case, we are running the MCP locally. We're not hosting it anywhere.

It's being run locally. And it's using standard in, standard out for communication. So this works. But in case your MCP is hosted elsewhere, you would need an URL. Notion is a very popular example. Notion has its own hosted MCP.

You can have access to it by getting the URL. So this part of the code would be changed slightly. Instead of putting the UV command, you would be instead of putting the UV command, you would have that URL here.

And you can connect with any MCP that is available, Snowflake, Notion, anything that you want. One more thing that I would like to highlight here is that, as I said at the beginning of my talk, we're using Claude Code as an agent harness.

You can use anything that you want. If you like Copilot, you can use it for this. Any sort of agent harness you want to use, you can use it with that. But this is for Claude Code. OK, so let's see where that file is.

So you have to create that MCP.json file in the root directory. And I can explain it to you. It's a very simple thing. So here we have the name of the MCP server we have. So it's deep research.

And this is the command that we have. So we are using UV because it simplifies everything. So any sort of virtual environment that you're creating, any sort of packages that you're downloading, it's all being handled by UV. So you don't have to do anything.

And then we have this command, which is basically running the server file that I showed you a couple of minutes ago. So it is just doing that. So Claude runs the server file as a subprocess locally. So our server is running locally.

And this entire code is sorry, this entire command is only doing that. It says run fast MCP, run, and the part to the server file that we have. And this is the environment file that I told you that you're supposed to create.

OK, so now it's time to see how the code works.

OK, cool.

So I would go to Claude.

Sorry.

OK, so if you go to Claude and you do MCP, you can see that I have two servers here. So because of the MCP.json file that I have, it was automatically able to detect both the agents. So we'll just be seeing the deep research agentright now.

And this is all the details. You can see the command. You can see the arguments that we have. You can see all of the capabilities that the server is exposing. So you can just do view tools. And you can see all of the details about the tool.

So the tool name, the description that I showed you, all of the arguments, the parameters that we have. Similarly, for all of the other tools, you can see all of the details here. Now I'm going to try to

sorry.

I'm going to try to run one of the tools and see how Claude does it. So I've already written out this question. This was from a previous AI talk about AI agents. So I'm going to just tell it to analyze this video for me.

And it should automatically be able to detect the tool that we have that is being exposed by the MCP server. So you can see here that it has automatically picked up the tool that we are exposing. And

it is trying to use that. And on the side, you can see that there's a .memory folder that I told you where we are tracking all of our results. It is being created. And it's going to write the transcript sorry, write the transcript to this file.

So as I told you, Gemini is watching or analyzing this video in real time. That's why it's going to take a couple of minutes for it to produce the transcript. So yeah,

so basically, every time you get this question, Claude Code tries to see what it can do, what tools are being available. And then it sends a request to the MCP server that, can you please execute this tool? And once the MCP executes the tool, it sends the results back to Claude Code.

And then it further analyzes that result.

So we can wait a minute for that.

Sorry. Yeah, so it has created this Markdown file. So it says that this video is from

the AI engineer called Summit. It has provided me all of the details. And it is like pretty good, detailed transcript that we can see here. And it also

gives its input at the end. Plus, I also really like this thing that we are storing all of the transcript. But it gives you a really neat summary at the bottom where it says what were the key ideas that were shared in the video.

And it says that, OK, the transcript is here. So this is like a short example of how we could run and see one of the tool if Claude is able to run that or not. And now I will try to run the entire pipeline again.

So sorry.

OK, so I've already written a question for that. So I'm telling it to do an end-to-end research. And

so now I'm trying to use the deep research tool that I have and the YouTube video tool that I have and trying to see how it runs both of them together. So it says that

it is trying to do the analyze YouTube video part first.

So when you have a big question like this, the entire workflow, how it works is Claude breaks down the question into different parts and then sees which tool it needs. So it has an entire reasoning going on that, OK, if these are the sort of tools that I have available, I need the YouTube analyze YouTube video tool for analyzing the YouTube video.

I need the deep research tool for the first part of the question. So it's going to divide it into two parts and then try to call both the tools.

OK, let's see.

Yeah, sorry. It usually takes some time for it to.

Can I ask a question while filling the gap?

Sure.

I'm very clever because I know all the MCPs. Have you guys think about the difference between MCP and SKU and whether this whole thing can actually.

Yeah, I'm actually going to talk. That's the next part. I was trying to remove the skill initially when I moved it to the temporary folder so that it doesn't pick up the skill because it tends to do that as well.

OK, my question was more like in the whole MCP, the deep research, have you thought about actually building the whole deep research as the skill rather than MCP?

Not about that. Just the prompt part, though.

OK, you haven't thought about actually whether the skill can actually do all of these things?

So I mean, for us, we're using the skill and replacing the prompt part. So trying to use that entire thing. I'll show it to you just in a minute. I think that might clarify your question. So I mean, here it gives me it has analyzed the YouTube video again.

It didn't give me the entire answer for the first part. But yeah, I mean, I think it just

just give me one second.

I have to clear the context of Claude because it tends to

use whatever I asked it previously. And I also had to delete the memory folder.

So till the time this is running and generating research for us sorry, till the time it's running and generating research, I could talk about the next slide that we have, which is the agent skills. So I'm sure all of you must have heard a lot about agent skill.

It is very popularright now. So this is basically a compact, concise way of telling agent about capabilities and workflows. And so basically, tools do the work. And skills provide you the way to do it. So we talked about the entire prompt that I showed you, the workflow prompt that we have.

In that, we were telling sorry, we were telling our agent that, OK, these are the tools that are available. And this is how you should execute them. But instead of writing it in the prompt, we can instead create a skill out of that.

And what is the benefit of doing that? When one thing is already solving the problem, why should we create another one? The reason for that is that skill has something called progressive disclosure. So when you like I did when I showed you I'm going to show it to you in a minute.

When you load the skill, so when Claude just shows you the skill, it doesn't load the entire information. It has only load the name and the description of the skill. Once you run a query, it's going to load the entire thing.

And once that query is executed, it is going to wipe off everything. So it is not going to be there in the context. Whereas when you're using prompt, everything is going to be there in the context. It's going to pollute the context.

And so you'd want to avoid that. So skills are a very clean way of doing that. And it is also very shareable because we internally write a lot of skills for our team and share it with each other.

So it's a very it's a concise, shareable way. And it's more maintainable because you can check it into GitHub. It's like your go-to place. And you can do the entire thing there. So

OK, so we have the results for this. But before that, I would just like to show you how we have written the skills.

OK, so I mean, we've written the research skills. So this is replacing the prompt that we have. So here we have to write the name of the skill that you want. You need to write the description. So why this description is necessary?

Because when your agent is trying to match a query to a skill, it is going to look at this part of this part of the skill. So you need to have a good description here. And then this is called the front matter, which is loaded.

And then this is the rest of the part of the skill. So in our case, we are reusing the research workflow prompt that we had instead of writing all of the details in here. You can do that. But it's a design choice for us.

And this is the rest of the body for this skill. OK, so now how could you see all of those skills? And what do I mean that it only loads the front matter? So if you go to Claude again and if you do sorry, clear.

If you do skills, you'll be able to see so these are some of the skills that I've already downloaded. And these are the project skills that we have created, so particularly the research skill that I was talking about.

And

so every time you do this and you see this, only the front matter is loaded, not the entire description,right? And you can actually if you want to use this, you can just do something like this. Or Claude can automatically pick up the skill when you ask it a question.

Now I'm going to try to ask it the same question I was trying to ask the MCP with

OK, so I'm going to ask it that it researches what an AI agent's skills are and then also analyzes the YouTube video for me.

Yeah, so it is loading the research workflow prompt. And it is able to do that because our server is running locally. And that's why it's able to read the prompt because they're all in the same folder. And now it has started to do a deep research.

You can see here. Oh, sorry.

OK,

so it has created so it is running the deep research here. And then it has run firstly, it ran the analyze YouTube video tool. Then it is running the deep research tool. And I think one amazing thing here that I would like to highlight is that the initial query that I had was, can you give me details about what our agent skills?

And every time our agent harness identifies the gap in the output that it gets, so in my initial question, it is going to identify all of the gap that exists. And then it's going to ask a different question every time to fill that gap.

So it is doing all of the reasoning behind the scene and making sure all of those gaps are filled in the research that we're trying to do.

So yeah, I mean, it usually takes around two to three minutes for me to run this entire output.

Let's see.

Maybe a follow-up question.

Sure.

Why both skills and MCP? Because you could wrap all of this into skills.

Yeah, so I mean, we built it originally with the MCP portion of it. And now we are transitioning. But we want to keep our original code. And.

So your view is it can be replaced, I guess?

I mean, not the server part. But the prompt essentially that we have, we can replace it with skills.

But why not? I think the whole MCP kind of workflow can be embedded in skills so that the whole code itself, with the harness, can literally just run it as you're instructing it.

Yeah, but I mean, we have a lot of detailing and different components within the servers. That's the reason we wanted to maintain that.

So it's more like complexity?

Yeah, yeah, it's more of the complexity in that case. That's why we want to maintain that. So here we can see we've got the output of the video. And now we're just going to wait for it to produce the output for the MCP file.

Perfect. So here you can see we've got this was my initial question that I asked it. And it has given me the answer for that. And this is the first run that we've had. And now it's doing more research on that because it gave us an answer.

But it identifies some of the gaps in that. So this is the second query it ran. And this is a different question you can see here,right? So it ran two queries. And it is like, OK, this is good enough.

And then it says all three research tasks are completed. Let me run one more targeted query and then complete everything. So that's why we wanted all of the reasoning to be done by agents because this is something a human would do.

Because if you're reading an article or if you're doing any sort of research, you try to identify the gaps and try to fill it with that. So that's what it is trying to do. And that's why we needed all of the brain and are trying to utilize that.

So this is the third query that it is running for me. And then finally, we expect it to create a compiled report, which is going to be any minute.

Can I ask another question?

Sure.

It seems like the idea of the MCP approach for 2025, do you have an idea of why the pipeline I mean, Claude could know today. So why is it asking queries about data skills architecture in 2025?

I think I mean, that is internal. I mean, we would have to see the observability for that and check and identify why it is not seeing the latest code. But we also have given it a video from 2025.

So I think maybe it's because of that. So the video that I asked it to transcribe, it is regarding that.

But I think to probably answer that better, I would go into all of the observability part of the code that we have and see what is going on there.

So finally, it's asking me if it could create a Markdown file for me. And so here is the research MD file that our final tool creates. And it is really detailed. It has got all of the comparison tables.

And it has got all of the details. So I think this is a really nice way to compile everything that we have gotten so far. And it also compiles and adds the YouTube video link that we have sorry, video transcript that we have at the bottom.

So yeah, thank you so much, everyone. Now I'll hand it over to Paul.

Awesome. Thank you, Luis and Samridhi, for those

great slides. And just give me a second to set up everything over here.

OK, so now we are moving to part three of this whole system, which is the LinkedIn writing workflow, which basically transforms this research from deep research agent to polished post that passes slop detectors so we can transform all of you into LinkedIn influencers.

OK, so just like a high-level overview, this is our full system architecture,right? So we did we already implemented the research agent, which outputs this research MD file, which will be as input to the writing workflow, which on top of that has as input the guideline.md file, which basically is a fancy way to put

it's a fancy way of the user input. And this is how we will model the user input to guide the generation process. And the final output will be, well, the LinkedIn post,right?

OK, now let's actually zoom in into the architecture, which is split into three big pieces. So the first one is where we build up the context. And ultimately, we end up with the big system prompt. Because remember, ultimately, this is not an agent.

This is just a workflow. Because in reality, to write a piece of content, regardless of what it is, a LinkedIn post, a video, or an article, you don't really need agents,right? Because as Luis said in the beginning, this process can be it's very static.

You always kind of go through always the same steps. So an agent will just make everything a lot complicated. Of course, you can put agents in some parts of it. But we won't show that

into this workshop. So the first part is to load the context, which is, as I said, the guideline.md file, which is the user input, the research. And then we have some static files, the profiles, and a few short examples, which I will dig into more detail a bit later.

So we take all of these, build the system prompt, and then pass everything to the LLM. So this is phase two. So so far, nothing fancy. We just basically create this huge system prompt and call the LLM to create the first draft of the post.

And then the last phase is to apply the evaluator-optimizer loop, which is probably the most interesting part of this, where we let the LLM create in a loop, reviews, and edit the post a couple of times,right? So this is super important because in reality, you can apply this not only to LinkedIn posts but to any type of content, starting from video transcripts to reports, financial reports, medical reports, even articles or book chapters or very detailed article lessons, as we did in our course where we needed to follow text snippets, images, code snippets, references, and all these little details that the LLMs usually sometimes getright but most often don't getright.

And even if they getright 80% of the time, it's annoying to manually go and fix that,right? That's the whole point. So all of this is automated end to end. So we'll dig again into this process in more depth later on.

So this is just one of our examples. So this is the beginning of a LinkedIn post that we asked to generate. And

just for fun, I would just want to copy this post. So it's the exact same post and put it into this pretty popular slop score detector. So

you can trust me that this actually works. And hit analyze. And yay, not slop. And this is actually lower and less sloppy than a human, as you can see is over there on the bottom. Of course, not all the posts are this not sloppish.

But most of them are really good and that they sound human. But remember, this is LinkedIn language. So we need to sound a bit like LinkedIn,right? But ultimately, as you can see, it doesn't have any em dashes, any weird

adverbs, verbs, and things like this. It can be read very, very nicely. The structure is schemable as we would like for LinkedIn and things like that. You can check the full post at this link in the GitHub repository.

And also try the slop test yourself if you aren't using that link. OK, so now let's start to dig deeper into the first phase of this workflow, where our core focus is understanding how we can actually control the generation,right?

Because as Luis said in the beginning, we don't want just to write, hey, I want a LinkedIn post on topic X. We actually want to dump our ideas, values, and thoughts into that post so it actually sounds like us.

So the first trick is actually to structure this guideline, which is the user input, and structure it more than just write me a post on X,right? So this actually guides what we want to write. So usually what we did, we created a template for this where we need to fill in such as what topic we want to address, what angle we want to address, some key points we want to address, the narrative flow, and things like this.

And this is the only piece that changes from post to post. So basically, from the whole system, this is what we need to write ourselves as a human as input to write a different post. And yeah, as I said, this is dynamic and changes.

Next, the and again, you can see an example here into this example from the repo along many others. But I will show them a bit later. So the second trick is to add these writing profiles, which basically tell the LLM how to write this post,right?

Because in reality, you don't really want the LLM to just do its own thing. You want to guide it. And these are static because, as I said, with the guideline, you define what you want to write. And this is how you define how you want to write it.

It's basically the styling layer on top of it. And we mainly created three profiles, which by themselves are Markdown files, which are the structure profile, where basically we define things such as how many characters on average a LinkedIn post has, like the core structure of a LinkedIn post.

We want a hook, like the body, the call to action. Also, for the terminology, we define things such as the active voice and the AI slop words and expressions that we want to ban. And unfortunately, this is all you can do.

You just need to keep track of a huge list of delve, tapestry, vibrant, and all those verbs that we love and just kindly ask the LLM to not use them until you start using them as a human as well.

And the last one is the character profile, which is kind of static. But you can also configure it. For example, in our writing workflow, we actually configure it under my Paul Iusztin biography,right? So it knows a bit about me, like how I want to write, how I like to write, my style, and things like this.

So this is how you can add a bit of personality to it. So again, we put all of this into the system prompt plus the guideline that we defined before. And you can see these are static. So as I said, we define them just once.

And you can access them under writing profiles and look around. There are, I know, Markdown files of a few hundreds of lines of words,right? So the last trick is actually to add few-shot examples. So this is nothing fancy.

But in reality, the hard part is actually to get them,right? Basically, this is under the data collection part of your system. And in our particular use case, we added kind of three LinkedIn posts from my writing. And the key idea is to use high-quality and representative few-shot examples and make them as varied as possible in things such as topic, length, structure, and so on and so forth.

And one question I think many people are curious about is why three LinkedIn posts. I know three is a magic number. But in reality, I just guessed it. And the thing is that with few-shot examples, because you always pass them in your system prompt, you want the lower number possible that gets the job done.

So usually, people tell like 3, 5, 10, 20 few-shot examples. But usually, you want to start with a bigger number and trim down that as much as possible until it works. And when it stops working, you put that back in.

And because you want to keep the idea is that you want to keep your system prompt with the few-shot examples as small as possible because, well, you always pass that to LLM, which translates to more cost, more latency, and even degradance in performance because the content grows.

OK, so

for that, I made available a data set in the GitHub repository where I extracted like 20 random LinkedIn posts from my profile that got more traction. So I used that as a data set for this writing workflow and further down the line to configure other things.

And one thing to highlight is that probably the only way to reduce this load on the system prompt with few-shot examples is through fine-tuning. But that often overkill and adds a lot of friction into your tech stack. So the last part of the system is the evaluator-optimizer pattern, which probably is the most

fancy one from all of this. And basically, it contains two LLM calls. And this is really important. It contains two different context windows,right? We have the writer and the reviewer, where basically the writer first writes the draft. And the reviewer, with a completely different context window, takes the draft and reviews it.

And this is super important to avoid bias because LLMs usually tend to be biased in liking what they already written. So by just putting that into a completely new context window can remove that bias. So basically, how this works, the reviewer checks adherence of the draft against to the guideline, which is the user input, against the research, basically to remove hallucinations, and against the profiles, those structure, terminology, and character profiles.

So we ensure that it adheres to it. And then the editor, which is often the writer itself, applies the reviews. And then we run this loop in our examples three, four times to basically write the post, review it, edit it, optimize it, and so on and so forth, similar to a fine-tuning optimization loop.

And a few tricks here that we absorbed over time is that just by keeping in our working directory all those versions, it helps because writing is subjective. And often, if you apply this reviewer too aggressively, it might make it you might just not like it.

So you want to look around the last versions and pick the one that you like the most. And again, because writing is subjective, usually the evaluator-optimizer pattern works with a score. So basically, the reviewer gives a score to the input.

And you loop until you reach upon a specific threshold. But because creative work is subjective, that threshold is very hard to quantify,right? And this loop becomes very noisy and not reliable. And we realized that it's just easier to just put a fixed number of iterations and let the user run these iterations again manually if he just wants to.

And now let's dig a bit deeper into how the reviewer works. So basically, as input, it has the current state of the post. Next, as context, it gets the guideline, the research, and the profiles, which basically it's what the writer needs to look around.

And they are basically the rules the writer needs to follow. And the outputs is actually a set of pedantic objects,right? And I think this is the most interesting part here is that you actually constrain the LLM to output a list of structured objects.

And this is powerful because if you give a pedantic object to an LLM, pedantic objects have this property where you can put a field under each attribute and actually explain what that field means. So basically, this is a prompt engineering technique which guides the LLM a lot better into actually understanding what each attribute of the return object actually needs to contain.

So for example, our review model has these profile, location, and comment attributes. And an example

output is, for example,

we violated the terminology profile on paragraph 2 where the LLM used the leverage band term. And like this, the editor, when it gets these reviews, will understand exactly what it violated. And from our tests, we realized that it's a lot easier to use this structured actually, it's a lot more performant to use these structured outputs than just letting the LLM, I don't know, spit out whatever it wants.

Again, you can check this code within this Python file. The code itself is pretty simple. So unfortunately, I won't have time to dig too deep into it. And now on the editor part, basically, it gets this list of pedantic objects and the current state of the post.

And also, it gets all the context that the writer initially has because the editor is actually the writer itself,right? This is similar to how a team of writers and editors will work. I write something. I give it to a team of editors.

I get the reviews. And I apply them. And another important thing is that reviews are not created equals,right? Especially, people like to give reviews on everything usually. And this also is true for the LLMs. And because we loop for a couple of times, we realized that it's super important to put a priority on them.

So usually, we always want to prioritize the guideline first, which is the user input, then the research, and then the profile. And this is super powerful when those reviews clash on the same paragraphs or on the same sentences and things like this.

Then we know what to pick up and what to apply.

OK, again, you can check the system, the prompt within this Python file within the repo. And here are concrete examples where we can see the post v0, which is basically what the LLM spits out before the evaluator-optimizer loop.

And this is how it looks like after four reviewing iterations. So we can see that the text is nicely formatted for LinkedIn. Also, the first sentence, which is the most important, is punchier and things like this. This is valid also for the first part of the post and also for the second part of the post.

Again, it modified the structure, the wording, everything to look more

about something that you would expect on LinkedIn. And again, you can check the whole post and all the versions from 0 to 4 within the examples directory.

And ultimately, let me actually show you how this directory looks like. So to test this code, you actually have three levels. So I created a simple main command just to check that everything works. So no, nothing crazy here.

If this works end to end, it means your code works locally. You can pass that to Claude Code to make your code work. So we serve similar to how the research agent works, everything to an MCP server prompt.

And then we connected this MCP with a write post skill. And the thing is that this takes like three, four minutes to run. So

I already ran it to

avoid wasting your time. But here is how you can run it. So basically, you take this write post skill

and just ask the LLM.

We take, for example, the same example that we took. We copy the relative path. And we ask it to use the guideline from this dear. And then basically, it will know to pick up the guideline and the research associated with it and write a post.

And the output is here. As you can see, we have the

four versions of the post, actually five versions of the post, and also the guideline, which I think is the most interesting one. So basically, as you can see, instead of just kindly asking an LLM to write about something, you need to be very explicit about what you want from it.

So you need to put an angle, the target audience that you want, key points that you actually want to cover, the tone, and things like this, and actually a constraint of characters that overrides the other profiles that are static.

So encoding in the system prompt that within this guideline, you actually can override the default profiles if you want something different. And basically, here you can go wild and input anything you want. But I just wanted to highlight you actually need to put in some effort to think it through.

You cannot just fully automate everything if you don't want to sound like true AI slop.

OK, and on top of this, we actually have a small image generator. We haven't put a lot of effort into this. But this prompt actually generates the post using this writing workflow and then asks another tool to automatically generate an image for that post.

OK, so now to move on. So just to wrap up on what we'll build on the writing workflow, we build this writing workflow pipeline that generates reviews and edits the post, which again, you can apply to any type of content.

We tested it with almost every type of content. And it works really well. You just need to adapt basically the profiles, the examples, and things like this.

And then we learn how to control the generation, the guideline, the profiles, and the few-shot examples. Again, for different content types, you will need to adapt these. And then how to serve everything as an MCP server and skills.

And yes, for this local example, you could do everything through skills. You don't really need MCP servers to make it work. But from my experience, MCP servers help you distribute logic

a lot easier because skills are like your local setup, your local hacked setup that works great for you. But if you want to distribute business logic, you don't really want to ask someone, hey, download those skills, install these UV dependencies over there, plug in those CLI tools.

Oh, no, you also need those credentials. And it quickly becomes a mess to distribute this at scale. And MCP servers solve that problem. And skills can help you personalize how you use that. Or basically, if you want a skill to be more than a prompt and actually run that code, it works.

But it can become a quick mess to set it up if it's too complicated,right?

So now let's move on to part four of this system, which is observability, more exactly monitoring and evals. So we will use the writing workflow as an example for evals. And we did monitoring for both.

So for monitoring, we will go really quick over this because theory-wise, there's not much to say. So the idea is that the core problem behind monitoring, which in my opinion exploded when we started to use agents and workflow, is that debugging workflows and agents purely through the logs is hard.

I personally can't really understand what's going on inside the terminal, especially when you see those thinking of the agent, which hides a lot of stuff. So it quickly becomes painful to debug what's going on just using the logs.

So basically, you need some tool to monitor this nicely that captures all your traces, such as all the LLM and tool calls, your input, output, your metadata. It captures everything about your run and also latency and cost tracking,right?

And as a bonus, it also stores your traces to build an AI eval layer on top of everything, which

I will dig more into it a bit later. So now let's actually look into our monitoring logs. So we used OPIK to monitor both our agents, the research, and the writing workflow. And yeah, just let's look into it because it's a lot easier to understand like this.

So for monitoring, usually, you have three big concepts. You have those threads, which is basically, in our use case, is like the whole workflow of writing an end-to-end post, starting with the post itself plus the image. For example, as you can see, this workflow has 44 messages, which basically captures all the bouncing around between the user and the LLM.

You can more intuitively see it as a conversation thread, which that's why it's called a thread. And then you have the traces. And here, you can actually dig deeper into what's going on. So a thread contains multiple traces,right?

And within a thread, within a trace, you can actually dig into what's going on. So for example, for a generate post

trace, here we have the high-level overview generate post call where we can see how long it took to run, how many tokens it consumed, how much it cost to run. And here, we can see all the tool calls and LLM calls that happen under the hood,right?

So we can see the models used, the cost per model, the latency per model, and all of that. And on theright, we can also see

the high-level input and output of the system, some metadata, the token usage, and basically everything that happened within that run, which helps you a lot to quickly understand what's happening,right? And we have something similar for the research agent as well.

Here, the thread is a lot easier to understand because, for example, we have this latest thread, which captures all those tool calls, basically all the deep research tool calls, the tool call that creates the final report, and all the bouncing around.

And then the

traces, which have just single tool calls, that they capture just a single tool call. Whereas you can see, we have just one LLM call per deep research tool call. OK,

so now let's move on to

AI evals. So I want to start with why evals matter because it's not necessarily a cool topic, but it can do a lot on your system. So basically, let's take our writing workflow.

At some point in time, look into doing that. That's going to be a professional.

With vibe checking. And when we generate just one post, we read it. We say that, hey, it's cool, awesome, it works. Well, then we have 10 posts. We read them, maybe, maybe not. Maybe we read two. Maybe we read three and call it a day and say it works for the others as well.

And then when we want to check how well it works in 100 posts, it quickly becomes impossible. And just imagine that you do this at the beginning. But as you evolve your system, you start to plug in more features,right?

And every feature can just break everything. And yeah, this is standard practice in software engineering. But here, you work with prompts. And just one word somewhere randomly can just break all your features if you're not careful. And you need this layer on top of it.

So basically, evals fit in three big layers. So we have optimization, which is very similar to training a model. So basically, we have this AI evals layer, which lets us quantify how well our writing workflow writes LinkedIn posts,right?

Then when we want to improve it, we have a score which tells us that, hey, do we move in theright directions or we don't move? So on every change, we run this AI evals layer. And we know if we did better or worse.

The next layer is regression testing, which is basically similar to test in classic software engineering, where whenever we start working on a new feature, we just ensure that we don't break current functionality. And the layer three will be to actually run this in production on live traces to actually get warnings and errors and alarms and all of that when users actually use your system.

And in reality, how this is different from normal unit integration and regression tests is that everything starts from the eval data set,right? So this is a data problem. We actually build a model here. So here is how we build it for our LinkedIn posts, where we were lucky enough to actually already have the data.

So I extracted 20 real posts from my LinkedIn. Why 20? I said that is a big enough number for a workshop. But in reality, we'll probably need to go at least to 100. Then I reverse engineered the guideline and the research.

Basically, I took the guideline from the post. And then I ran the deep research agent on top of the guideline to find whatever I need to support that post. And then I generated the output. So basically, I put the guideline and the research as inputs and generated new posts.

And this is super important because you actually want to see results from your real system. And when you want to generate synthetic data of some sort, never ask the LLM to directly generate the output. Always ask it to help you generate the input, but never the output.

You want the output from your real system because that's what you're testing ultimately. And then I looked around and labeled each output with binary pass and fail labels and two, three sentences critique on why exactly I gave it a pass or fail label to it.

And usually, I stop when I find the first error. It's just easier for me while labeling and also for the LLM to understand that whenever I see the first fail, I stop at it. I write why it failed into three sentences and move on.

And ultimately, I split all of this into a train dev test split because ultimately, remember that here we're building a machine learning AI model. So we need to treat it as such. So we need a classic split.

And only when we have this data set and these splits, we can actually build the evaluator and evaluate the evaluator, which most often, for some reason, when they build LLM judges, they think they can just skip this last step, which is probably the most important one.

And again, what's the most important and interesting here is the data set that we created because actually creating an LLM judge out of this, if you have the data set, is just very easy.

OK, so now let's see how this LLM judge would work for our current scenario. So as input, it will take the generated post that it needs to label, but also the profiles, research, and guideline. And this is super important because the LLM judge actually needs to understand the context used to generate this post.

And ultimately, it outputs the pass/fail label plus the critique, basically exactly the same labels as our data set. And then we pass, as few-shot examples, our train split from the data set. And this is the most important one because the system prompt of the LLM judge can be extremely simple if it has theright few-shot examples in place that tells the LLM judge what decisions to take,right?

So the few-shot examples look like this.

They have the writer input, which is the guideline and research,right? So the input to our writing workflow system. Then the writer output, which is basically the generated post of the workflow and the labels,right? So in the few-shot examples, we also have the labels, the pass and fail label, and the two, three sentences critique about the label.

And you can check out our system prompt within this file. But there's nothing fancy. The most important part from this is building the data set.

And our last step is to actually measure the judge reliability because ultimately, what we did here, the LLM judge is just a binary classifier,right? We output pass and fail labels. So yeah, we used an LLM judge because the reality is that it's easy.

But we could have just used any other model that gets the job done and can output these pass and fail labels.

And ultimately, when we measure judge reliability, our final goal is to align the LLM judge with the domain expert. And how we will do that, we will do that by testing it against the dev test data set splits.

So this is a process very similar to training any other binary classifier. There's nothing new here. Just the word LLM judge is fancier. So what we do basically is test the LLM judge against the dev test data set splits and then use F1 score, which is a combination of precision and recall, to actually measure how well the LLM judge performs against these splits.

And the process looks like this. So we first run the LLM judge on the dev split, compute the F1 score, and adjust the LLM judge and prompt examples to maximize this F1 score because most probably, when we first start this process, the F1 score will be low.

And we basically want to get a score as high as possible. And we repeat until we convert. Usually, you need to do this a couple of times. And when you think you're done and the LLM judge is ready to go, you run it on the test split as the final validation step,right?

Basically training a machine learning model.

And now it's ready to run on new data. So after we go through these steps, we have the LLM judge, which is ready to run on new samples of data, which will just output the binary pass or fail and the critique.

Now, to wire everything together that we had in this section is that we first build a data set. Then based on that, we build the LLM judge. Then we calibrate the judge. And only after that, we can run it on real data.

And usually, all these steps are managed by some observability platform. We used here Opik. But you can use any other platform or just build something in-house. It doesn't really matter. But the idea is everything should be managed by a cohesive platform.

OK, so now as a quick demo, let's emulate as much as possible this calibration step because the LLM judge is already calibrated. So I will just show you

how the LLM judge performs on the eval split.

So under the hood with Opik, we've built a very simple evaluation harness where it allows us to run these calibration steps and then run it on production traces.

So in reality, the code for our use case is pretty straightforward. So just to show you around a bit until it runs,

OK, so actually what it does now, it takes all the generated posts,right? It passes the LLM judge on top of all those generated posts. And then what I wanted to show you is this F1 score

where basically we compute an F1 score based on the outputs from the LLM judge against our labels from the data set, which I think is more interesting to see how our data set looks like really quickly to get a sense of it.

So

basically, here we have a single sample within our data set where what's more interesting is we have a link to the media of the post, to the guideline, to the generated post, basically links to everything that we need as input and output, both for the deep research agent and the writing workflow.

And then just putting this scope, we plug them in as few-shot examples either for the post generator or for the evaluator or, for example, for the dev split and things like this. So this is how we are careful that we do the splits theright way between the LLM judge and also the generator.

And for simplicity, we have all those files linked together in this YAML file here locally within GitHub. So you can check everything and plate

and run everything very easily with minimal configuration. OK, so if we go back into the terminal, we saw that it had a perfect score. Yay. So now let's actually run this on the

test split. And the goal here is to see that our LLM judge did not overfit it,right? So we ran it on the dev split. We get the perfect score. Usually, this is a high signal that it overfitted. So unless the F1 score on the test split is not 1 or around 1, it means that our LLM judge is overfitted.

So again, similar to the process before, it's basically the exact same steps, but now we ran on the test split.

So let's see the final F1 score, which is again 1, which is good. And the scores are so good because we do this just on five samples per split. But if you expand your split, which you should have at least like 20, 30 samples, the score probably will not be perfect.

OK, and let me actually show how these experiments look inside Opik.

Can I just quickly ask a question?

Yeah, sure.

In terms of your decision of deploying the judge, what sort of the range of F1 score you would say is good practice between overfitting versus reality? What would you say?

Yeah, I think that the most important is the dynamics between the F1 score on your dev split and the dynamics on your test split because the overfit, when the model is overfitted, is actually

like how it's compared between the two. For example, as I said, if it has a very big score on the dev split and a low score on the test split, it means it overfitted. But the score itself usually is very correlated with your own data.

So for example, you're pleased with the.

Would you say what you're looking for is more like the relativity of the both score, like if they are more in the same branch?

Yeah, yeah, exactly.

It has less to do with the absolute value.

Yeah, exactly. Yeah, exactly. The absolute value usually is very correlated with your data. Usually, on the test split, you say, OK, this F1 score is good enough for me. And then you run on the test split to see that you have the same F1 score on the test split as well.

OK, so again, usually with these observability platforms, you have this experiments tab where you can actually run

experiments similar to fine-tuning experiment trackers from the old school. And for example, here we have the dev and test experiments. So let's open the test experiment that we just ran. And here we can actually see the output from the binary LLM judge and our label.

And we can see that there's a perfect match between the two. And if we hover over this, we can also see the critique of the judge. But in reality, here we compute the score only between the labels. And this critique is more useful for us because ultimately, our goal is us as humans to look over these results and understand what's going wrong with the system.

And then as a final step, I also prepared an online simulation where I simulated some online traces

where the LLM judge actually runs on top of them. And you get the binary labels and the critique. But the thing is that this takes like five minutes or even more to run because it actually needs to, for real, it needs to generate all the posts and run the LLM judge on top of it.

So I'll just show you a result over here, which I bundled it together as an experiment. So is this online test evaluation suite

where again, for example, just let us dig into what further. You can see, for example, the generated post here on theright and then the results from the binary from the judge where we will find the score and the critique itself.

And of course, this system is not yet perfect. I probably need to refine it more because here on live traces, as you can see, it kind of failed, to be honest. It just passed an F1 score. It just gave us a pass on all the traces.

While in reality, I also have the labels for these simulated scenarios. We can see that it failed. So probably I need to go back to the dev split, expand the dev split with new samples. For example, I could just take these samples and put them in the dev split and start refining it again and again and again until it actually works.

And I'm kind of running out of time. But

you also have the skill to actually run a demo end-to-end,right? Research and writing. You can, for example, write a guideline about something that you want to write a post about and give that as input to the skill, which is just a file.

And it will know to pick up, to do the research, and then continue to writing the post. And you can also observe that in Opik with all the threads, traces, and all of that. And yeah, I guess that the final step, if you haven't done so yet, is to actually open up the GitHub repository, run everything yourself, and read the code because without reading the code, most probably we won't really understand what's going inside.

So you can do that by accessing this link or scanning the QR code. And

whenever you're ready and you want to go deeper into building this type of multi-agent systems, we have this agentic engineering course, which basically was the inspiration for this workshop. But instead, our goal was actually to design and build production-ready AI agents and not just some small local systems.

And within 34 lessons, three end-to-end portfolio projects, a certificate, and a Discord community with access to us. And so far, it's rated 5 by 5 by 300-plus students. And if you don't believe us, the first six lessons are free to try out.

And you can access it using this link or scanning the QR code. Yeah, and that's it for the workshop today.