Workers and Subagents
Workers and subagents are both mechanisms for handing work off to a different agent. They let a manager session keep coordinating the workflow while another specialized agent takes on a focused sub-task. Use them when a workflow needs parallel or delegated execution, such as Project Builder launching implementation workers or Incident Investigator launching a PR Author for an approved fix. There is also a third pattern: Expert → integration → Expert. Two Experts can coordinate through events in an external integration, such as a pull request being created or review comments being posted.Why delegate work?
The main reason to delegate work is focus. In theory, one very broad Expert could try to do every task in a workflow. In practice, specialized Experts produce better results because the system prompt sets what the agent pays attention to. For example, PR Author is focused on building: implementing the requested change, opening the pull request or merge request, fixing CI failures, resolving merge conflicts, and driving the change toward merge. Deep Reviewer has a different focus. Its prompt is tuned to be critical and to catch bugs. It asks questions like: can this interface be an attack vector, are there inputs that will crash this code, and are there corner cases the implementation missed? Those are not the questions PR Author reasons about as thoroughly, because PR Author is optimized for a different job.How they are similar
- They have their own context window.
- They have their own system prompt.
- They can define their own model.
- They run in parallel with the manager session and report progress back.
How they are different
The most important difference is that a worker is an Expert, while a subagent is just an agent. Because a worker is an Expert, it has its own Environment, integrations, runtime configuration, and permissions. A subagent has its own prompt and context, but it does not carry the same Cosmos Expert configuration surface. Workers are more heavyweight. A worker is a separate Cosmos session with its own VM and Environment. Workers can define their own integrations and can take side-effecting actions, such as posting comments, creating tickets, or writing to external systems, depending on their permissions. Workers are scoped to either the whole organization or to the Space they are part of. Subagents are more lightweight. They are the standard delegation concept used by many coding tools: focused agents that help with research, validation, implementation, or review inside the same broader coding workflow. Subagents are scoped to a repo. See Subagents in the Auggie documentation for how subagents are configured and used. Sessions are generally prompted to use subagents as they see fit. Workers are different: the session should be explicitly prompted about when to launch a worker, because workers are separate sessions with their own runtime environment and external permissions.Expert-to-Expert interaction through integrations
Experts do not always need a direct worker relationship to interact. They can also communicate through the systems they already work in. For example, PR Author can create a pull request. Deep Reviewer is triggered by the pull request creation event, analyzes the change, and posts review comments on the pull request. PR Author subscribes to events on that pull request, including newly posted comments, and then responds to the review feedback. This pattern is often conceptually simpler than using workers. The integration becomes the shared coordination surface, so humans can inspect the interaction between agents — for example, by reading the pull request comments — and intervene whenever they want.Prefer workers for Cosmos workflows
For Cosmos, prefer workers over subagents when delegation is needed. Workers are more natively supported in Cosmos: each worker is a real session that you can open in the browser, inspect in depth, and reason about independently. Use workers carefully. Worker orchestration can get complicated for the same reasons multi-threading is complicated: coordination, complex interleavings, data races, deadlocks, and unclear ownership. Prefer a single Expert when the whole workflow can be completed in one context window. If workers are necessary, prefer one or two workers with clean handoff boundaries.When to use workers
- The parent Expert should coordinate the workflow but not do every task itself.
- A sub-task needs its own Environment, integrations, or external side effects.
- Multiple independent tasks can run in parallel as separate Cosmos sessions.
- You want a clear parent session that tracks delegated work.