Transcription
So, Clo introduced this sub-agent feature a few weeks ago. It was a super exciting concept. However, for people who tried it, they often had quite a negative experience where the sub-agent felt slow, consumed much more tokens, and most importantly, it didn't feel like it was contributing to a better result.
And I was among one of those people, but only recently I started learning the best practices of using sub-agents, and that has totally changed the game and made my cloud code perform much better consistently. That's why today I want to share how I think about and design sub-agent systems.
So, firstly, we've got to understand why Cloud Code introduced the sub-agent concept initially. And if you don't know how exactly the Cloud Code agent works behind the scenes, it's basically a tool called an agent that is equipped with a list of different tools for reading files, listing all the files, editing files, stuff like that. And some of the tools can consume a lot more tokens, like the read tool, because you're going to include the whole content of the file into the conversation history. And before Cloud Code had the sub-agent feature, everything would be done by the Cloud Code agent itself. Which means, before it starts implementing, it might already use 80% of the context window, 'cause those files will contain a large amount of context, which will likely trigger this "compact conversation" command that will summarize the whole conversation before it can proceed. And as we know, every time when you compact a conversation, the performance just drops dramatically because it starts losing context about what it has done before.
That's why later they introduced this "task" tool for the Cloud Code agent. It allows Cloud Code to assign a task to another agent, and this agent will have the exact same set of tools, including a read file, search file. So you can trigger this agent to actually scan the whole codebase, understand what are all the relevant files to change, and then based on that information, do the actual implementation. And the way this saves tokens is because, from the parent agent's perspective, all the steps that the sub-agent takes in the middle won't be part of the conversation history for the parent agent. It can only see that it assigned a task to the sub-agent, and then the sub-agent comes back with a summary of the research report, which can be used to guide the next best action. By doing that, you fatally turn those massive token consumptions from the read file, search file actions to something like just a few hundred tokens for a summary, but still containing the most important information to guide the next action.
So, the whole purpose of sub-agents has been around context engineering and context optimization. But where things fail is when people start trying to get a sub-agent not only doing the research work but also directly doing the implementation. For example, the first thought I had was, what if we can have a front-end dev agent to do just the front-end implementation with special rules and workflows, as well as a back-end dev agent who is specialized at back-end implementation? Then, for the parent agent, it really just orchestrates the whole conversation and delegates tasks to others. This sounds really good at the beginning, but the moment if whatever the sub-agent implemented is not 100% correct and you want the agent to fix it, that's where the problem begins. Because for each agent, it only has very limited information about what is going on. For the front-end dev agent, it only knows the action it took as well as the final message it generated in that specific task. Same for the back-end dev agent. And if you prompt the Cloud Code agent that there's a front-end bug, even though it's assigned to the front-end agent, this will just trigger a new conversation because the front-end dev agent wouldn't know what happened before in the last front-end session and also won't have any context about what the back-end dev has done before. So, each task is a very contained session.
Meanwhile, for the parent Cloud Code agent, it also has very limited information because, again, it won't see all the actions that have been taken by the sub-agent. Which means it won't know what specific files have been created and what did they actually put in those files. All the parent agent sees is that I assigned a task to the front-end dev, and the front-end dev came back saying "I completed the task," and same thing for the back-end. So, if you want to get the Cloud Code agent to fix the bug itself, it will have very limited information about what is causing the issue. This probably will be resolved later in the future. We will figure out a good way to share context across those different agents so that each one of them is always on the same page about what has been done. But for now, the best practice would be to consider each sub-agent almost as a researcher and think about what kind of planning and research steps can actually dramatically improve your current AI coding workflow.
I also received similar feedback from Adam Wolf, who is one of the key engineers on the Cloud Code team, where he says sub-agents work best when they are just looking for information and provide a small amount of summary back to the main conversation thread. So, with this one, I got this idea. What if each service provider, like Vercel AI SDK, Supabase, Tailwind, they can just have one agent that is equipped with all the latest knowledge about their documentations, best practices, and design? And then this agent can start looking through my existing codebase to figure out an implementation plan. And this is exactly what I tried. I started creating different expert sub-agents for each service, from Chassis, where it has access to a special MCP tool that can retrieve relevant components and same design to do a really good front-end job, or a Vercel AI SDK expert that is loaded with the latest Vercel SDK v5 docs because they just released this new version a couple of weeks ago, or a Stripe expert that is loaded with the latest Stripe docs as well as tools like Context 7, so you can do complex setups like usage-based pricing very easily out of the box.
Meanwhile, I also did some optimization about the context sharing across different agents. This is something I learned from Manu's team's blog on context engineering, where they talk about all the tricks and tips of how they make Manu's execute long-running tasks. There's a lot of good stuff in there, but the part that inspires me most is how they use the file system as the ultimate context management system. So, instead of storing all the tool results in the conversation history directly, they receive a result to a local file which can be retrieved later. In their case, when the agent runs a web scraping tool, instead of including the whole content script inside the conversation history directly, which might take more than 10,000 tokens, they will just save the script content into a local MD file, which can be retrieved later at any point in the conversation. And this is exactly what I designed here. Inside the `doccloud` folder, there will be a `task` folder that contains the context of each feature that you want a team to implement. Meanwhile, each sub-agent can start creating those MD files about the specific research report and implementation plan, so that the process will be: the parent agent will always create a context file that includes all the information about the specific project we're trying to execute. And for every sub-agent, before they start doing the work, they will read this context file first to understand the overall project plan and where things are at now. And after they finish, they will also update the context file to indicate what are the core steps they did and save the research report into an MD file in the `doc`. So, the parent agent or all the other agents can just read this `doc` later for getting more context. And this setup has dramatically improved the success rate and results for my Cloud Code. And this is what I want to quickly show you today.
So, hopefully, you get an idea about what type of sub-agent you can create that is going to be actually useful. But before we dive into that, I know many of you are first-time founders. Building a product is just one part of the puzzle. You also need to learn how to acquire users, how to price it, and how to prove value to customers. That's why I want to introduce you to this free material called "Money-Making AI Agents." It is done by Dimitri Shapira, founder and CEO of M Studio, which is one of the fastest-growing AI startups. He shared his whole journey and experience from spotting the real problem that they're solving all the way to pricing and closing deals, covering all the practical and essential workflows, tools, and processes. It even includes specific scripts about how he does demos to his customers, as well as many real-world case studies of how people are building and launching AI products that got six to seven figures annual recurring revenue. And my favorite part is how to think about pricing of your AI product and service. Different frameworks for working with enterprise versus SMB, and how to estimate the value from your client's point of view. It has more than one hour of practical guide plus guides that you can start using for free. You can click on the link in the description below to get this resource, and thanks HubSpot for bringing us this awesome material.
Now, let's start building some Cloud Code sub-agents. So, to build those sub-agents, the general rules I have is that I will include a lot of important docs directly inside the system prompt so I can have confidence that it will follow the latest practices. And meanwhile, I will also give them random tools to retrieve important context. In this Chassis and expert example, as I mentioned before, there are MCP tools that are specifically designed for those information retrievals from that specific package. One is this "Chassis Component MCP." They allow you to retrieve components, the example code for each component, and relevant blocks. So, it will have the full context. As well as another MCP tool to retrieve and design for Chassis. This MCP is from Twikins, which is a website that is specialized in those scene designs, and this MCP will just retrieve some well-designed scenes so that it can be used as reference.
Normally, I will open the terminal to `code.cloud.json`. This will open your global settings, and here's one key called `mcp_server` where I pass in this "Chassis Component" and "Chassis Scene" tool. So, sub-agents will have access to. And we can choose which tool the agent should have access to. The model, the color, and then you will see this new agent created. You can add agents if you want, but what I normally do is that I will open the terminal and then do `code .cloud`. So, this will open your personal settings for Cloud Code, which will be applied across all purchases. So, we'll create a new agent, and we can either create a project-specific agent or a personal-level agent that will be used across all purchases. For our example, I will use a personal level, and we can generate `claw`. It will try to generate a title, description, and the system prompt for this sub-agent based on your quick explanation. So, here the description I give is that it's a "Chassis front-end expert who can help design robust front-end UI relevant Chassis MCPS." As mentioned before, there are special MCP tools that I used here. So, here you can see an example it created here.
Normally, what I do at this point is either pasting docs into their system prompt or attaching special MCP tools and rules about how to use this MCP tool. In the final version I designed, before it has all those rules about the process it should follow. So, the overall plan here is that you will be listing all the components, choosing the right component, and get example code to know how exactly to use that, and also get some reference about how to composite different UI patterns together using the blocks, get the relevant scenes, as well as some rules about where to put which component files. And normally, what I will also do is I will firstly add a goal here for each sub-agent, where I will mention that the goal is to design and propose a detailed implementation plan and never do the actual implementation. And once they finish, just save the design file to `doccloud/doc` file. And in the end, I will also include this output format to instruct that the final message output should look something like this: "I've created plan as this file. Please read that first before you proceed." And this message will be sent back to the Cloud Code parent agent so that everyone knows that I need to look up this file, as well as a list of different rules to keep instructing that "don't actually do the implementation." And before you do any work, it should look at the context file first to get full context. And after finishing your work, it should update this context file.
And this is also one kind of weird behavior I observe sometimes: sub-agents will try to run this `cloud_mcp_client` to call itself. I'm suspicious because sub-agents actually inherit the `cloud.md` file we have, so I just add this rule here to making sure it is not getting confused. And this output format and rules, as well as the goals, are almost identical across all the sub-agents I created. For example, for this "Vercel AI SDK Expert," I also have just the same structure for the output format and the rules. The only difference here is I will throw more detailed documentation about the latest Vercel AI SDK doc, which is something I directly grabbed from their website. I just copy over some kind of fundamental important pages about Vercel AI SDK v5 into the system prompt, as well as a migration guide to clearly spell out the difference between 4.0 and 5.0, that is also something I get from their own docs. So, this is an example of how we can set up those specialized sub-agents for each service that you're going to use.
So now, let's give it a try. Our first is to set up a Next.js project with Chassis, and then I will do `cd my-app` and `claw`. So, this will set up the initial project. I do `init` to start initializing the codebase and create a base Cloud Code rule. And now I will create this `cloud.md` file. But to make it work better in the `cloud.md`, I also want to add some special rules about the sub-agents. So, firstly, I want this parent agent to always keep the project plan in the `doc/task/context.md` sessions so that we can use this file as a source of truth to maintain its context. And after it finishes the work, it must update this MD file. And meanwhile, I also want to give some rules about the sub-agents so that it has these two sub-agents that should delegate, and also when we pass tasks to sub-agents, making sure we do pass this MD file name. And after each sub-agent finishes the work, they need to read the documentation they created before it executes tasks.
So, with this setup, let's give it a try. So, our given prompt: "Help me build a replica of ChatGPT using Chassis as front-end and Vercel as SDKs AI service. Let's firstly build the UI, making sure we consult sub-agents." And firstly, it will try to create this `context_session_1.md` file to document the context about this project that we're executing. Then it triggers this Chassis agent. If I do `Ctrl+R` to open the detail, you can see that it gives a very specific task to this "Chassis Expert Agent," including the context file to read as well as specific tasks. Then the first thing this sub-agent does is that it tries to read this context file. Then it starts running the MCP tool called "Chassis Components." So, this special MCP tool that we connected. So, if I go back to the agent, it will continuously using those relevant tools to retrieve information that can help it design the UI with the right components. And for each component, it can also get some example code of how to use it. So, in the end, this Chassis agent will finish the work and create a `doc` file about this UI design, overall layout, and the plan components to use with a very detailed structure. And based on that, the parent agent will read this plan and start breaking down the actual implementation. And after a while, it finishes the whole thing in just one go and also updates this `context_session` file to indicate what kind of things have been done and what are the overall architecture. And I can run this application. By the way, Cloud Code just introduced background sessions that it can keep running and monitoring the result, which is really useful. If I open this UI, you can see it is extremely high fidelity with all those detailed interactions considered, which looks almost identical to the first version of ChatGPT. And there are some errors, which we can paste in and start fixing those errors. And this is why the new sub-agent structure is so good because all the execution will be done by this parent agent. So, it will have full context. What's the best way to fix the issue? Great. So, now there are no errors, and if I type in a message, it will also have nice interaction and animation has been handled.
Next, we can ask it to connect to the Vercel SDK. So, I ask it to "Let's do the Vercel SDK integration and make sure to consult the sub-agent." So, this will trigger the Vercel AI SDK implementation planner inside this agent. Again, it will firstly try to read this context file. Then it will look through the whole codebase to see what are the best ways to implement this. And after finishing, it will create this `doc` about the implementation plan for the Vercel AI SDK and also update this `context_session.md` file to document what has been done. And then this parent agent reads the whole implementation plan and comes up with specific implementation steps. And cool, again, after finishing, the remarks are completed, and it continuously updates this context file. So, now we get this application running. If I just type in "Hi, I'm Jason," it has this agent actually connect to the large language model and return me the result in just one shot, which is the amazing part.
So, here's a quick example of what I learned as best practice for using sub-agents. If you want to learn more, in the Bit Club, I'm pasting all the prompted processes of creating those sub-agents that I just showed you. Meanwhile, we have this Cloud Code template that we are curating, which includes a list of hooks, commands, and agents that we have actually tested and are really useful in production environments. So, if you're interested, you can click on the link below to join AI Builder Club. We also have a weekly session to talk through the best practices we learn every week. I hope you enjoy this video. Thank you, and I'll see you next time.