Scaling to cloud deplooyment?

[philjestin]

The Mental Model

A Team is itself a Handler — it takes a Task and returns a Result. This is the key design
choice: teams and individual agents share the same interface, so they nest arbitrarily.

What Handle() Actually Does

When you call team.Handle(ctx, task), five things happen in order:

1. Routing — The Router decides which agents get the task.

selections, err := t.router.Select(ctx, task, t.agents)

This returns a []Selection — each pairing an agent with the task it should handle. Different
routers make different decisions:

• AllRouter — gives the task to every agent (fan-out)
• FirstMatchRouter — gives it to the first agent whose predicate matches
• RoundRobinRouter — rotates through agents across calls
• DescriptionRouter — keyword-matches task description against agent descriptions

2. Guard Check — Before each agent runs, the TeamGuard is consulted. If the guard returns an
   error (e.g., cost limit exceeded), the agent is skipped or the whole thing aborts (depending
   on ErrorPolicy).

3. Execution — Selected agents run either sequentially or in parallel:

• Sequential: iterate through selections, run each agent's Handler.Handle(), check guard
  before each one, respect FailFast/CollectErrors
• Parallel: pre-flight guard check on all agents, then sync.WaitGroup with each goroutine
  writing to its own index in a pre-allocated slice (no mutex needed — cost.Tracker.Add()
  handles its own locking)

4. Aggregation — The Aggregator combines the []Result into a single *Result:

• ConcatAggregator — joins outputs, merges file lists, sums token usage
• FirstResultAggregator — returns first non-error result
• BestResultAggregator — uses a scoring function to pick the best

Individual results are always preserved in Result.Children for observability.

5. Observer notifications — OnTeamStart, OnRouteDecision, OnAgentStart/Complete,
   OnTeamComplete fire at each stage for logging/metrics.

Nesting

Because Team implements Handler, you can call team.AsAgent() to get an Agent wrapping the
team:

devTeam := team.New("dev-team",
team.WithAgents(backendAgent, frontendAgent),
team.WithStrategy(team.Parallel),
)

superTeam := team.New("delivery",
team.WithAgents(devTeam.AsAgent(), reviewAgent),
team.WithStrategy(team.Sequential),
)

When superTeam.Handle() routes to devTeam.AsAgent(), it calls devTeam.Handle() recursively —
that inner team does its own route/execute/aggregate cycle. The outer team sees a single
Result with Children containing the inner results.

Plugging Into the Pipeline

The adapters (DeveloperTeam, PlannerTeam, etc.) bridge the gap between the team's generic
Task/Result types and the pipeline's typed interfaces. For example, DeveloperTeam.Execute():

1. Converts runner.Request + runner.Plan → team.Task (plan details go into Task.Input)
2. Calls team.Handle()
3. Converts team.Result → runner.ExecuteResult (pulling FilesChanged, Diff, Summary from the
   result)

This means you can replace any single-agent pipeline stage with a multi-agent team without
changing the pipeline orchestration at all:

// Before: single developer
runner.WithDeveloper(myDev)

// After: team of specialists
devTeam := team.New("dev-team",
team.WithAgents(backendAgent, frontendAgent),
team.WithStrategy(team.Parallel),
)
runner.WithDeveloper(team.NewDeveloperTeam(devTeam))

The pipeline doesn't know or care that it's talking to a team instead of a single agent.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
boatmanmode	Ready	Preview, Comment	Mar 4, 2026 5:52pm