dtp/gadget
1
0
Fork 0
Code Actions Packages Projects Releases Activity

created

Browse Source
This commit is contained in:
Rob Colbert 2026-05-11 11:08:29 -04:00
parent 45609599ad
commit 09445cb565
1 changed files with 68 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/subagents.md Normal file
View File

@ -0,0 +1,68 @@
# Gadget Code Subagents
In Gadget Code, the User eventually enters a Chat Session to send prompts to a Large Language Model operating as the Master Agent. The Master Agent, among everything else it does, wants to efficiently manage it's context window. The Master Agent's context window _is_ the conversation the model is having with the User.
To help preserve the relevance of the information in that context, and waste less space in it, the Master Agent spawns Subagents.
Initially, there will be an Explore Subagent and a General Subagent.
## Master Agent
When a Work Order arrives within a `gadget-drone` process via the `processWorkOrder` socket message, `onProcessWorkOrder` is called to process the work order. That method _is_ the Master Agent. It sets up the process environment and API call, configures everything for the call's context, and submits the call to perform the work requested in that Chat Turn.
A tool available to it is the `subagent` tool, which it can use to span a Subagent.
When all processing is complete, the `onProcessWorkOrder` routine performs any cleanup, results submission and reporting, then terminates.
One Chat Turn is one 'run' of the Master Agent.
## What Is A Subagent?
A subagent is a specialized AI assistant designed to handle specific, isolated tasks, acting as a delegated worker within a larger, more complex AI workflow. They operate in their own context window with specific instructions and tools, returning only necessary summaries to the main "parent" agent to prevent context pollution and improve efficiency.
A Subagent is not a `chat` call. It's a `generate` call that gets spawned by the Master Agent to perform a specific task and respond with a specific result.
## What Isn't A Subagent?
Subagents are not whole drones. They are not a standalone process. Subagents run within `gadget-drone` itself in the same process space as the Master Agent. They aren't even a thread.
### Key Concepts of AI Subagents
- **Isolation**: Each subagent runs in its own session, meaning it does not share the parent agent’s immediate memory or conversation history, preventing "context rot".
- **Specialization**: They are configured for specific tasks, such as code reviews, documentation generation, or research, making them highly reusable, according to Augment.
- **Hierarchical Structure**: A central "parent" agent delegates tasks, routes input, and consolidates the results.
- **Usage**: They are ideal for complex workflows where parallel, specialized, or multi-step processes are needed without cluttering the main conversation window.
### Reference
- https://developers.openai.com/codex/subagents
- https://docs.augmentcode.com/cli/subagents
- https://geminicli.com/docs/core/subagents/
## Explore Subagent
The Explore subagent will specialize in researching within a code base, git repository, collection of documents, media content, etc., looking for specific information. The Explore Subagent will author a concise response back to the Master Agent to provide the information it needs to process the Work Order.
This keeps all of the irrelevant information out of the Master Agent's context and conversation. That preserves precious context window space for actual work.
## General Subagent
The General Subagent will specialize in performing finite-scoped and highly-focused tasks within the project. The Master Agent will provide specific instructions in the prompt sent to the General Subagent.
The General Subagent will then use it's tools to complete the task and respond with the status of that task when done.
## Chat History and Audits
The [ChatHistory](../src/models/chat-history.ts) model records turns of chat with the agent and is what we use to assemble the agent context per turn. Subagents will create a `ChatHistory` record, but those records need to be recorded to the `ChatHistory.subagentHistory` array of the MCC's chat turn/history.
In other words, MCC will decide to call the subagent tool with a prompt and selected agent. That will begin to form a `ChatHistory` record for that operation. As the subagent runs and performs its work, it will be recording `ChatHistory` records - and also inserting them into the `subagentHistory` array on the forming MCC's `ChatHistory` record.
## Prompts
The Explore and General subagents are defined by a pair of system prompts located ./data/prompts/subagent/explore/system.md and ./data/prompts/subagent/general/system.md. These prompts define how the subagent behaves generally. The MCC will send a User prompt in when calling the subagent tool to select the agent to run and configure it for processing the work required.
## Subagent Tool
In the system tool group, we need to create a new `subagent` tool that can spawn a subagent, select which agent to run (general or explore), provide the User prompt to the agent specifying the work to perform, and receive the response from the agent when the work is finished.
This tool will make use of a perhaps new path through the [AgentService](../src/services/agent.ts) to provide a SUBagent chat, and not the MCC chat. This is how you can then tie the subagent ChatHistory records to the Master's ChatHistory record and create the hierarchical data structure of "Chat History" in this sprawling-ass app.