Agent Teams

Multi-agent coordination. Run teams of agents together with three coordination modes: sequential, collaborative, and hierarchical.

Teams require primitivesEnabled: true. Each agent in the team runs in its own sandbox with isolated state. Use sharedContext: true to let agents read each other's outputs.

Creating a team

Call session.teams.create() with a name, an array of agent roles, your coordination mode, and optional configuration.

team.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })

const session = await theazo.sessions.forUser(class="cb-str">'user_123')

const team = await session.teams.create({
  name: class="cb-str">'research-pipeline',
  agents: [
    { role: class="cb-str">'researcher', agent: class="cb-str">'web-researcher', instructions: class="cb-str">'Find primary sources and data' },
    { role: class="cb-str">'analyst', agent: class="cb-str">'data-analyst', instructions: class="cb-str">'Synthesize findings into insights' },
    { role: class="cb-str">'writer', agent: class="cb-str">'content-writer', instructions: class="cb-str">'Produce a polished report' },
  ],
  coordination: class="cb-str">'sequential',
  sharedContext: true,
  maxRounds: class="cb-num">3,
})

Coordination modes

The coordination field determines how agents interact during a team run.

ModeBehavior

sequential

Agents run one at a time in order. Each agent receives the previous agent's output as context. Best for pipelines where each step builds on the last.

collaborative

Agents discuss in parallel, sharing context each round. After maxRounds, an arbiter agent summarizes all outputs into a final result.

hierarchical

A manager agent delegates subtasks to team members, collects results, and produces a final output. The first agent in the array acts as the manager.

Running a team

Call team.run() with a task string. The team coordinates according to its mode and returns a unified result with per-agent outputs.

run.ts

const result = await team.run(class="cb-str">'Analyze the AI infrastructure market and produce a report')

console.log(result.output)         class="cb-cmt">// Final synthesized output
console.log(result.agentOutputs)   class="cb-cmt">// { researcher: '...', analyst: '...', writer: '...' }
console.log(result.cost)           class="cb-cmt">// { amount: 4200, currency: 'usd' }
console.log(result.duration)       class="cb-cmt">// 87 (seconds)
console.log(result.rounds)         class="cb-cmt">// number of coordination rounds used

Sequential example

A three-stage pipeline: researcher gathers data, analyst extracts insights, writer produces the final report. Each agent receives the previous agent's output automatically.

sequential-pipeline.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })
const session = await theazo.sessions.forUser(class="cb-str">'user_456')

const team = await session.teams.create({
  name: class="cb-str">'market-research',
  agents: [
    {
      role: class="cb-str">'researcher',
      agent: class="cb-str">'web-researcher',
      instructions: class="cb-str">'Search for recent funding rounds, market size estimates, and competitor data',
    },
    {
      role: class="cb-str">'analyst',
      agent: class="cb-str">'data-analyst',
      instructions: class="cb-str">'Identify key trends, calculate growth rates, and rank competitors by traction',
    },
    {
      role: class="cb-str">'writer',
      agent: class="cb-str">'report-writer',
      instructions: class="cb-str">'Write a concise 2-page market brief with executive summary and recommendations',
    },
  ],
  coordination: class="cb-str">'sequential',
  sharedContext: true,
})

const result = await team.run(class="cb-str">'AI agent infrastructure market Q2 2025')

// researcher output → fed into analyst → fed into writer
console.log(result.output)                      class="cb-cmt">// Final polished report
console.log(result.agentOutputs.researcher)     class="cb-cmt">// Raw research data
console.log(result.agentOutputs.analyst)        class="cb-cmt">// Structured analysis
console.log(result.agentOutputs.writer)         class="cb-cmt">// Final report (same as result.output)

Hierarchical example

A manager agent breaks down the task and delegates to specialists. The manager decides which agents to invoke and how to combine their outputs.

hierarchical-team.ts

const team = await session.teams.create({
  name: class="cb-str">'due-diligence',
  agents: [
    {
      role: class="cb-str">'manager',
      agent: class="cb-str">'project-manager',
      instructions: class="cb-str">'Break the task into subtasks. Delegate to researcher and analyst. Synthesize a final brief.',
    },
    {
      role: class="cb-str">'researcher',
      agent: class="cb-str">'web-researcher',
      instructions: class="cb-str">'Gather data on the assigned topic when asked by the manager',
    },
    {
      role: class="cb-str">'analyst',
      agent: class="cb-str">'financial-analyst',
      instructions: class="cb-str">'Analyze financial data and produce projections when asked by the manager',
    },
  ],
  coordination: class="cb-str">'hierarchical',
  sharedContext: true,
  maxRounds: class="cb-num">5,
})

const result = await team.run(class="cb-str">'Due diligence on Acme Corp Series B')

// Manager delegated:
//   researcher → 'Find Acme Corp revenue, team size, and competitors'
//   analyst    → 'Model 3-year revenue projections from the research data'
// Then synthesized both outputs into the final brief

console.log(result.output)       class="cb-cmt">// Combined due diligence brief
console.log(result.rounds)       class="cb-cmt">// 3 (manager → delegates → synthesize)

Edge cases

Sequential failure

If an agent fails in a sequential pipeline, the team pauses immediately. Downstream agents are never started. You can retry the failed agent or cancel the team.

Collaborative deadlock

If collaborative agents produce no new information across a round, the arbiter forces a summarize step to prevent infinite loops. The maxRounds cap ensures termination regardless.

Hierarchical max rounds

The maxRounds limit prevents a manager from delegating indefinitely. When the limit is reached, the manager must synthesize whatever results have been collected.

Always set maxRounds for collaborative and hierarchical teams. Without it, the default is 10 rounds, which may be more than you need and will increase cost.

API reference

session.teams.create(config)Promise<Team>Create a team with named agent roles and a coordination mode.

team.run(task)Promise<TeamResult>Run the team on a task. Returns unified output, per-agent outputs, cost, and duration.

team.cancel()Promise<void>Cancel a running team. In-flight agents complete, pending agents are skipped.

session.teams.list()Promise<Team[]>List all teams for this session.

session.teams.get(teamId)Promise<Team>Fetch a team by ID.