Skip to content

Podcast

305 - Subagents Explained - What They Are, When (Not) to Spawn Them

Fragmented - AI Developer Podcast

Source ↗ ← All highlights
  • Agent As A Reactive Loop
    • An agent runs a reactive loop: reason, act, verify, and repeat until a task is done.
    • This framing distinguishes agents from mere prompt files or SDKs and clarifies their purpose. Transcript: Kaushik Gopal Right. Before we go into sub-agents, let’s briefly touch on what an agent itself is. So in a previous episode, Yuri, you gave a really good definition pointing to the whole reactive loop. So not that React that developers usually are comfortable with, but this is any system that’s able to reason through a problem, then has the tools to execute or act based on that reasoning. So the act part, and finally the verify part. So they have the set of tools to be able to verify and make sure that the task that they set out to do was complete. So if you take those three components, the reasoning part, the acting part, and the verifying part, and you put that into a loop so that this system is able to repeat the whole process To come to the conclusion of a task. (Time 0:01:30)
  • Agents.md vs Agent SDKs
    • ‘Agents.md’ is just a system instructions file, not an agent process.
    • Agent SDKs (LangChain, OpenAI Agent SDK, etc.) are tools to build reactive-loop agents programmatically. Transcript: Kaushik Gopal So people point towards agents.md. Very different thing. That’s your systems instructions. Any agent or any tool has a set of systems instruction that it basically builds into the context and feeds into the agent. That’s like the markdown file that the early days of AI hype was like, hey, you got to really put these 10 tips into your agents.md and you will get unlimited productivity. You know, so that’s literally just an instructions file that has nothing to do with agents or sub-agents as a process. So that’s the first context that it’s used in. The second is an interesting one. You’ll find a lot of these big AI labs talk about agent SDKs. And, you know, the common ones that people hear this term with is LangChain or LangGraph. Then, you know, the big companies like OpenAI actually has an SDK called OpenAI Agent SDK. Anthropic has another one called Anthropic Agent SDK. Google has this one called ADK, which I think is Agent Development Kit. They’re very similar in that they are SDKs that allow you to build agents. You know, the whole reactive loop thing that we talked about? (Time 0:02:49)
  • Modes Swap System Instructions
    • Modes (plan/build) swap system instructions and change agent behavior and permissions.
    • Mode switching is deeper than UI; it alters the system prompt the model receives. Transcript: Kaushik Gopal That’s right. And when you say mode, what do you mean by this is the whole planning mode, build mode, thinking mode, all of those modes, right? Iury Souza Yeah, so especially like build mode and plan mode, I think for everyone who’s used cursor, I think there is a toggle exactly for that. There’s a drop-down option and you can select build or plan, for example. So the mode is just this behavior and permission profile for the main agent. I think a good way to think about this is like threads in doing planning work. So the mode is your main thread, your main agent. So you’re in this build mode. That means that your main agent that you’re talking directly to, this is going to be in that mode, which allows you to basically go about building code, you know, like writing code directly. But if you would be, for example, in plan mode, then your main thread, your main agent that you’re talking to, it would be in this exploratory mode that we will try to plan and think about The solution before. (Time 0:05:20)
  • Scout Analogy For Sub-Agents
    • Iury compares sub-agents to scouts in RTS games that reveal the fog of war across a map.
    • The main agent sends many Explorer sub-agents to gather intel and return concise findings. Transcript: Iury Souza There’s also an interesting analogy, like if you ever played RTS games. Kaushik Gopal What’s your poison? Iury Souza Yeah, so I mean, I think I’ve played a lot of Age of Empires. I also played Starcraft, but I think I never played StarCraft like really serious because I was too young. But like Age of Empires, I got more serious. Nothing, nothing good. Anyway. Kaushik Gopal Fun note, I don’t know if I’ve told you this, but my brother was actually a pro gamer. What the hell? And he was really good. He played Warcraft 3 pretty seriously and competitively. He was so good that even if he didn’t try, he would destroy me in these games. So I basically stopped playing myself. But I used to watch him. So when you talked about this analogy, it all clicked really well for me because I could relate very easily. You know, there’s these concepts called fog of war, scouting. So let’s build that analogy a little. Iury Souza Yeah, so this is going to be fast. This is going to be easy. Even if you haven’t played much of these, I think it’s relatable. So like Age of Empires, we start a game, right? So the map is completely dark. So you kind of have to explore the map. So you start off with a scout. So the idea here is that, for example, just think of a code base. Your agent also starts fresh. Like it doesn’t know anything about the code base. So for example, when you create like you’re in the plan mode and you ask something to the agent about the code base, then what it will do is it will spawn multiple Explorer agents now. Now this is, for example, Cloud Code or I think Open Code also does that. Kaushik Gopal So it’s like my little orc or human peons that we send when they come out. When the game starts, you send those little peons to go search the map. Iury Souza And you literally send them across the map in multiple directions. So the idea is that each agent, the Explorer agent, would be doing exactly that. So it would just be exploring the map and gathering intel for you. The idea is that you don’t need to do it manually. You don’t need to go and control each step and across everything. It’s just send these guys and they will reveal the important locations in the map, right? So they will go, wow, there’s gold. Here’s where your enemy is or here’s this resource, right? (Time 0:09:30)
  • Sub-Agents Reduce Context Bloat
    • Sub-agents prevent context bloat by returning succinct summaries instead of raw logs.
    • Main agent receives focused intel rather than verbose exploration traces. Transcript: Kaushik Gopal And I feel another interesting point here, and this goes back to the concept we’ve been trying to really beat in, right, which is context bloat. I think it plays pretty well into that too, right? Because when the peon comes and tells you, well, I say peon, by the way, it’s basically like, you know, the term used in the game for like some of these initial workers. But yeah, if the scout comes back and gives that information, you don’t want the scout to tell you, hey, I went north 10 steps. I then took 20 steps to the east. In my vision, I saw this enemy. So I didn’t go too close because I would be destroyed. I went to the other side and I found there’s a gold mine there. You literally just want to know, okay, just tell me where the gold mine was You know? Yeah, yeah. Now, bridging that into a programming concept, you don’t want your main agent to actually have the context of all the logs you pulled or like the different class names that you went. You just want a succinct summary of like the important points so that the main agent can then use that and make decisions. (Time 0:12:42)
  • Configure Sub-Agents Explicitly
    • Define sub-agents via an agent directory and metadata so the main agent can choose them.
    • Specify model, persona, and tool set per sub-agent to control cost and behavior. Transcript: Kaushik Gopal We talked about this in the last episode. You have agent skills. You can specify an agent skill. And then when you use that agent skill, we talked about context forking. So it executes it in an isolated way. Just like that, you can also have an agent’s directory. Anything you put in that agent is spawned as a sub-agent in CloudCode. So you can basically create a configuration file. It’s a markdown file, but then it has the YAML front matter, very similar to agent skills. For example, you can specify a cheaper model. You probably don’t want to use Opus 4.6 fast mode for your researching or your exploring. Bankrupt. Exactly. If you’ve seen those costs, it’s pretty expensive, man. So you probably want to use a cheaper model, like say the Haiku model, and you can actually explicitly specify that in that markdown file that you put in the agent’s subdirectory. That’s one way how it does it internally. But Cloud Code also comes with three built-in sub-agents. This is something actually that you pointed me towards in the docs. There’s like the Explorer sub-agent, there’s the Plan sub-agent, and of course there’s the General Purpose. And they internally use different tools. (Time 0:14:05)
  • Sub-Agents Are Tool Calls With Context
    • A sub-agent is essentially a tool call with its own metadata and system prompt.
    • If unspecified, a sub-agent inherits the main session’s model by default. Transcript: Iury Souza This is interesting. If there is going to be some overlap on your prompt, then the model will need to decide. So it’s very important how you define the description of the subagent because the main agent, the one that you’re talking to, that’s it’s going to have to make eventually a decision. And very beneath, like under the hood, a sub-agent is literally a tool call. No way. Yeah. So there is this tool called task and the main agent uses that to invoke the tools. But in any case, back to your point, the metadata in the agent definition is the thing that’s going to be used for the agent to make the decision. Kaushik Gopal The question I always had, Yuri, is say by default, we know that a sub-agent needs to be created, but the model cannot use one of the built-in agents and it doesn’t use one of the sub-agents That I’ve created, what does it use? Like, it’s going to create a sub-agent. What model does it use by default? Iury Souza It’s going to inherit. The default option is to inherit the model that’s used by the main session, the main agent. (Time 0:16:06)
  • Isolate Scope And Parallelize Research
    • Limit sub-agent scope and tools to the narrow task you want to isolate.
    • Run parallel constrained workers for broad research and aggregate their summaries at the top level. Transcript: Iury Souza So the whole idea of like context isolation and isolating or minimizing the number of tools that the sub-agent will have. So for example, this research agent that you can build for searching the web, you could put all your MCPs, like, I don’t know, maybe if you want to use perplexity MCP or browser use or all These tools related to research, you give this sub-agent that set of tools. Also, like, limit what it can do. So, for example, it’s not going to write any code. When you spawn that agent, you can be certain that that’s what it’s going to do. And also like the idea that you can parallelize work, so you can launch multiple research agents. And then the main agent is going to be the orchestrator prompting those sub-agents. So if you want to do like a very broad research, you could launch multiple of these research agents with different prompts and with this constrained set of tools. So then it kind of starts making sense like when you put it in that way, like in this kind of context. (Time 0:18:08)
  • Spawn Sub-Agents For Token-Heavy Tasks
    • Use sub-agents for token-heavy operations like log analysis, test runs, or long outputs.
    • Spawn them to avoid polluting the main session and to keep conversation context small. Transcript: Kaushik Gopal Can you tell me what are some good opportunities to start using subagents? When should I be using subagents? Iury Souza I think I would typically use a subagent for anything that is very, you know, token hungry or something like that. You know, high output operations. I don’t know, like if you want, for example, to do test runs or some debugging lot of reading a lot of logs. Kaushik Gopal Oh, I see. I see. Because the test runs would, you keep having to dump the output, read the output to see if it passed, failed. So that can flood your context window. Same with logs. I see. That makes sense. Yeah. Iury Souza So you just spawn a sub-agent. It just doesn’t pollute your main session. And trying to keep the sub-agent role very narrow, so it’s like one thing that this sub-agent will do, so you don’t confuse it with other agents that you keep swapping all the time. Yeah. It also prevents overlapping of tools, right? (Time 0:21:39)
  • When Not To Use Sub-Agents
    • Avoid sub-agents for tiny edits or tightly coupled workflows that need full traceability.
    • Keep ambiguous, interactive problem-solving in the main agent to preserve conversational context. Transcript: Kaushik Gopal Oh, I see. When we should not use subagents. When you have tiny edits, sometimes the overhead to literally spawn the sub-agent, because remember, you know, there’s a separate context window, you’re spinning up a separate model Potentially, that is also costly. You don’t always want to just keep spinning sub-agents left, right, and center. Like say you have a simple task where you know the main agent can do it within like a single call and it’s not going to like dump too much output. Those are times where you should think twice and say, hey, maybe, you know what, I don’t want to… Iury Souza Like you don’t want the sub-agent to create commits for you. Kaushik Gopal Exactly. Which brings us to the next point, when you have tightly coupled tasks. Because sometimes the main agent might need all of the information, right? You know, the scout analogy is great when you just need to know where the gold mine is. But that’s not always the case. Sometimes you need to know how you traced your path. There are a few situations where it’s important for the main agent to know the final details. In those cases, you kind of want to keep it in the main agent. Don’t actually spin it off into separate sub-agents. And the last point where you probably don’t want to use a sub-agent is say you have an ambiguous problem and you yourself don’t know exactly how to get to the end result because that happens Quite often, right? Where you’re like, hey, I want to use, you know, an agent to get to my results. I’m going to have a lot of back and forth in my conversation. I’m going to ask follow-up questions based on some of the results that I get from the response of the agent. In those cases, it actually makes more sense for you to keep it within the main agent because that context needs to be coupled again, right? You need to have that back and forth with the model. (Time 0:23:38)