google-gemini
Support SubAgent architecture
What would you like to be added?
This FR requests the implementation of a new SubAgent class: A re-usable component that manages LLM driven tool orchestration.
This is applicable in the following contexts:
- Allowing a Tool to iteratively solve a problem it encounters. For example, the EditTool using the SubAgent to find a better match string in the case of stale data; or a future "update docstrings" tool, which may call multiple existing tools to find files, edit them and test them.
- Agentic Scopes - Allowing a Tool to be run in an isolated mode - If a tool doesn't manage its' own self healing, and instead expects to do that on the main thread, a SubAgent can be created, which clones the MonoAgent history, executes the tool, and only returns the successful response back to the main thread ()
This FR suggests the most direct path towards implementation would be:
- Create a wrapper around GeminiChat which can drive the GeminiChat::sendMessage*(..) functions either in a nonInteractive, or Interactive function
- Allow a list of filtered tools to be passed to the GeminiChat ContentGenerator::generateContentStream(..) function, so that only a subset of tools may be considered during execution
- Allow a custom system prompt to be provided for GeminiChat to use.
- Allow variable output via a set of private tools that the Agent can use to calculate response data to be accessed via the Caller of the SubAgent.
Why is this needed?
Currently, GC uses a mono-agent architecture; One SWE Agent which is responsible for all work across the application. While this approach is powerful in its' own right, there's some challenges that it presents:
- Higher Memory Rot - Given that all self healing operations occur in a single History object, there's a higher chance of hallucinations over time as the context history becomes more complex and full of conflicting / stale information. Consider the situation where a file-read occurs, then 2-3 edit attempts that fail, followed by a success. There now may be 5 examples of the same block of code in history memory, which can lead to confusion.
- Lack of SmartTools - The GC Codebase currently has a single agent implementation (GeminiClient + GeminiChat), which means that tools themselves cannot currently support agentic loops in their processing (e.g. recovering from a failure, or orchestrating private tools to execute a task). Further, no other part of the application can engage in Agentic patterns, since there's no primitive to leverage to do so.
Additional context
Areas of open discussion:
- Tool permissions - There's some open discussion that needs to be had about how tool-based permissions work inside subagents. (For example, if you've given ToolX permission to write-always, does that permission also follow forward to when that tool is used inside of a subagent?)
- System prompt re-use - The SubAgent can accept a custom system prompt to drive work, but it may be viable to leverage existing portions of the existing MonoAgent prompt. This is a challenge because the current Mono-Agent system prompt is powerful but also static: It currently does not provide a mechanism to be re-used by sub agents, or be broken up in the case of available tools changing. In this case, an ideal solution for SubAgents orchestrating the existing tools may require breaking up prompts.ts to provide a sub-agent the ability to grab examples & multi-shot snippets for a specific tool it is using (which is currently hard-coded into the main prompt).
Important Notes:
- This FR only discusses the addition of the SubAgent primitive, and is not intended to be a solution to larger discussions around mass orchestration of Agents, or their coordinated efforts towards task resolution (e.g. "why not use existing agent-orchestration library X?"). Those are significant architecture conversations that need to happen across the team, as orchestration is a higher level discussion to the SubAgent primitive proposed here.
- This SubAgent suggestion is intended to be blocking, in that the calling thread blocks until SubAgent execution is finished - Discussions regarding async subagent execution & scheduling (and the impact that has on ChatHistory ) is left for a future discussion.
It would be a great help in major codebase refactors. For example once a refactor is decided, context can be added to sub-agent and each sub-agent can complete the refactor in a provided set of directories. Would make refactors a lot lot faster.
Essentially, tasks that are about applying the same change to a lot of files would benefit extremely from this.
surprised gemini cli doesn't already have this! subagents are a big part of cc's success
To add to the discussion, besides the Task tool, Claude Code now has a very interesting implementation for subagents with different roles and prompt definitions/personas and tools that could help this discussion: Claude Code: Sub agents
I think I will raise another issue for it explicitly since this issue is the first one that needs to be addressed, so once it supports sub-agentic tasks, it could later enhance and have a /agents slash command as well.
Is there any ETA on this? We've been working something similar but couldn't find a way to bring it inside terminal and managed independently. It is a use-case which is ready-to-use. Have a browse through:
https://github.com/devkindhq/gemini-cli-assistants
Hey @rome2o! We'll start making updates on this thread soon! Def working on it!
It's early days but I've found Claude Code subagents quite problematic so far. If you search on the Anthropic GitHub issue tracker for "subagent" you'll see a lot of issues.
I think currently opencode's agents feature is slicker, e.g.:
- you can define both custom primary agents and custom subagents
- when a subagent is running, you can switch to a view which "zooms in" and shows you exactly what it's doing
If Gemini CLI implements subagents, it would be well worth examining how other rival CLIs like opencode do it.
It's early days but I've found Claude Code subagents quite problematic so far
They've been working well so far for me. The only problem is that I manually have to guide Claude toward spawning multiple agents - I have a lot of **IMPORTANT**: Use subagents keywords in CLAUDE.md, but it tends to ignore them.
If anyone from Google reads this comment, please do something about this in Gemini and implement a system prompt/command/mode that guarantees the task will be implemented using subagents.
Zooming in and seeing exactly what it's doing would be helpful but since the work delegated to a subagent tends to be isolated and small (otherwise, why would you spawn it in the first place), you can debug it quite easily.
since the work delegated to a subagent tends to be isolated and small (otherwise, why would you spawn it in the first place)
Is this "tends to be isolated and small" assertion is backed by empirical evidence from a decent cross-section of Claude's user base?
But regardless, you already acknowledge here that subagent work isn't always isolated / small, so we need to cater for scenarios where they're doing a lot of work. Even if that only happens (say) 10% of the time across all users, there are people like me who regularly use subagents to do a lot of work. Currently in Claude they're currently impossible to debug. Even when they're doing a small amount of work, I don't see how that generally makes a black box easy to debug.
See also https://github.com/anthropics/claude-code/issues/5974#issuecomment-3253275900 which makes the good point that it's not just about debugging, it's about being able to trust whether the subagent came up with the right answer or did the right work.
Fair points, @aspiers.
I think what I wanted to say is I wouldn't mind if Gemini adds support for subagents without any ability to debug them, at first - simply having the feature would be helpful.
It's early days but I've found Claude Code subagents quite problematic so far
They've been working well so far for me. The only problem is that I manually have to guide Claude toward spawning multiple agents - I have a lot of
**IMPORTANT**: Use subagentskeywords inCLAUDE.md, but it tends to ignore them.If anyone from Google reads this comment, please do something about this in Gemini and implement a system prompt/command/mode that guarantees the task will be implemented using subagents.
Zooming in and seeing exactly what it's doing would be helpful but since the work delegated to a subagent tends to be isolated and small (otherwise, why would you spawn it in the first place), you can debug it quite easily.
Try to add into CLAUDE.md somethings like this: "Never implement task directly, never edit files directly. Work as an orchestrator." The main idea - the main agent should be in read only mode. This idea implemented natively in Kilo Code and working well.
since the work delegated to a subagent tends to be isolated and small (otherwise, why would you spawn it in the first place)
Is this "tends to be isolated and small" assertion is backed by empirical evidence from a decent cross-section of Claude's user base?
But regardless, you already acknowledge here that subagent work isn't always isolated / small, so we need to cater for scenarios where they're doing a lot of work. Even if that only happens (say) 10% of the time across all users, there are people like me who regularly use subagents to do a lot of work. Currently in Claude they're currently impossible to debug. Even when they're doing a small amount of work, I don't see how that generally makes a black box easy to debug.
In CC is able to press Ctrl+R and see internal state of an subagent - initial prompt, progress and the result.
@NaikSoftware wrote:
In CC is able to press Ctrl+R and see internal state of an subagent - initial prompt, progress and the result.
While this is true, in practice it doesn't work well at all because after pressing Ctrl+R the internal state doesn't update as the subagent works (e.g. if another user prompt is required, it won't display it until you exit that view mode).
opencode's UI for subagents is much better.
Sub-agents would go a long way to not have to cram the context with ton of useless tokens. Having sub-agents with their own context performing the right tasks and code generation, would also make it a simpler to crafty better context files. Right now I feel like I am repeating things which again is wasteful.
For example when I am coding an Angular Web app, I don't need any context for generating Component (UI) when the task is for generating a Service. Having a "smart agent" delegate the duties to the correct sub-agent would solve a lot of problem of jank code generation with useless context confusing the LLM.
hi, any updates?
I believe what must have happened is that they were working on it and then gemini did a hard git reset so they lost the progress irreversibly. and they have to start over from scratch
Hi folks, we had to put this aside for awhile while we were working on some other things, but Abhi and I have kicked off the work here in earnest this week. Keep an eye on the sub-issues to track our progress. I'm really excited about getting this set of features in.
surprised gemini cli doesn't already have this! subagents are a big part of cc's success
gemini-cli is ReAct like mode, I think...
Just came here to send you my force (since it is obviously so much complicated I can't help more). This is a major feature for Gemini CLI to come closer to OpenCode and Claude Code. All my support on this massive task <3
hi @jacob314 @abhipatel12
I would like to kindly suggest the addition of a built-in CodeSafe agent. From what I have observed, some other products implement a similar mechanism, where every code execution or bash command is processed through this CodeSafe agent. This helps in preventing high-risk operations, such as executing rm -rf, and enhances overall security.
@lifefloating see https://github.com/google-gemini/gemini-cli/pull/13193 which is related to #11976
Isn't subagents already implemented?
I was digging through the codebase and found that Users can define their own agents in:
~/.gemini/agents/(user-level).gemini/agents/(project-level)
That the main agent can call using delegate_to_agent Tool
I can't seem to get it to run custom agents though? I get the following error:
From an AI search on the Gemini CLI codebase, the problem seems to be:
The error "The delegate_to_agent tool is restricted to codebase_investigator" is a specific restriction within the gemini-cli codebase.
Explanation: The delegate_to_agent tool, which is used to pass control to sub-agents, has a built-in check that restricts its usage. currently, only the built-in codebase_investigator agent is allowed to effectively use this tool to delegate tasks. This is likely a safety/stability guardrail in the experimental "Agents" feature to prevent uncontrolled recursion or unexpected behavior in the main loop.
So we can't add custom agent yet?
