Orchestrating multiple agents
As you get more comfortable building with agents, you’ll likely start using multiple agents at once to solve separate problems at the same time. Just like any human project, adding more people doesn’t necessarily lead to a better result every time. Keep the number of agents relatively small. If you have multiple agents all working on the same project, remember you are managing them all. They will request permissions from you, get stuck, and possibly suggest fully rewriting a piece of code your other agents are relying on. The more agents you run at once, the more distant you are from the actual code they’re producing, making it harder to understand what changes need to be made where, which can cause you to become dependent on AI to understand your own project.Parallel work
When having multiple agents working in your project at once, you should aim to keep them separate so they’re not touching the same code. Reasonable candidates for multi-agent work include:- Running multiple agents to update app features that don’t overlap. If you’re unsure about whether there’s potential overlap, you can have an agent review your project first. For example, an agent editing an app card on a contact record is unlikely to touch an app page, so you could run a second agent on the app page at the same time.
- Fixing minor bugs in one part of the app while another agent writes unit tests.
- Running a code review on completed features while another agent scaffolds a new extension point.
INVESTIGATIONS.md. The main agent can then consult that file when you’re ready to act on the findings, without having spent context on the investigation itself.
The more agents running in parallel, the more important it is to keep your prompts specific to avoid agent collision or accidental overwrites. Having one agent deploy several subagents is usually more effective then manually starting new agent instances or chats, since the first agent will typically have more context to coordinate the changes. For agents that don’t support deploying subagents, include more detail in your prompt for each agent, as shown below:
In the MyContactListing app card, add the contact details section that we planned, along with the other minor fixes we identified. Keep your changes to the app card file only, as another agent will be working on the serverless function code at the same time.
Use Git worktrees
For larger or more complex parallel work, Git worktrees give each agent its own isolated branch and working directory. Unlike basic parallel work where agents share the same files, a worktree keeps each agent’s changes completely separate until you’re ready to bring them together, reducing the risk of conflicts or one agent undoing another’s work. To use worktrees, Git must be set up in your project. Your main agent can create a worktree and a new branch in a single step, then hand the work off to a subagent. When the subagent finishes, you review its changes and merge the branch back into your main branch. If you’re connected to GitHub, you can have the agent open a pull request instead.Create a new git worktree on a branch called feature/app-page and deploy a subagent to work in it. The subagent's task is to add the new app page component that we planned. Before starting, have it read the project spec files for context. When the subagent finishes, summarize what was built so I can review the changes and merge the branch.