Teams

teams/triage.yaml

name: Triage
description: Routes a request to the member best able to answer it.
goal: Answer the request correctly, involving as few members as possible.
instructions: null
coordinationMode: handoff
status: active
leadType: managed
leadLlmSlot: reasoning
leadModelId: null
leadInstructions: |
  Decide which member should answer. Prefer intake when the request is unclear.
leadMember: null
leadMemberDelegateEligible: false
leadMemberCanAnswerDirectly: false
determineInputForMembers: true
addTeamHistoryToMembers: true
shareMemberInteractions: false
addNameToContext: true
addDatetimeToContext: false
addHistoryToContext: true
numHistoryRuns: 5
maxIterations: null
budgetCapJson: null
policyJson: null
members:
  - agent: agents.intake
    role: Establishes what is being asked.
    sortOrder: 0
    delegateEligible: true
    configOverrides: null
  - agent: agents.specialist
    role: Answers once the request is clear.
    sortOrder: 1
    delegateEligible: true
    configOverrides: null

This is the Team npx @elizon/cli example team prints, without its comments and placeholder line. Every field above is required except addHistoryToContext and numHistoryRuns, and a field that is not listed on this page is refused (PORTABLE_DEFINITION_INVALID).

Key fields

Field	Meaning
`goal`, `instructions`	What the Team is for, and optional shared instructions.
`coordinationMode`	How the lead works with members: `handoff`, `dynamic_delegation`, `parallel` or `plan_execute`. See Coordination modes.
`status`	`active`, `draft`, `paused` or `archived`. See `status`.
`leadType`	`managed`: a lead the platform runs on `leadLlmSlot` with `leadInstructions` (`leadLlmSlot` required). `member`: one of the member Agents leads, named in `leadMember` (required). See The lead.
`leadLlmSlot`	The `llm` Slot a managed lead thinks with.
`leadMember`	For a member-led Team: the member Agent (`agents.<name>`) that leads.
`members[]`	Each member's `agent` reference, `role`, order, whether it can be delegated to, and optional `configOverrides`. See Members.
`maxIterations`	The iteration cap of a `plan_execute` Team (1–20). Other modes do not read it.
Context flags	Whether members see the Team's history, each other's work, names and the date. See Context and history.
`addHistoryToContext`, `numHistoryRuns`	Whether the lead sees the earlier messages of the conversation, and how many (0–100, each message counts once). Optional: left out, they install as `true` and `5`, so Packages written before these fields existed keep working.
`budgetCapJson`, `policyJson`	Carried as written. See Budget and policy.

These mirror the Team editor in Studio.

Coordination modes

coordinationMode decides what the lead does with a request. Studio, the Team run chat and the Teams guide call each mode by its Studio name. All four run today. Every mode has a lead; there is no leaderless Team.

`coordinationMode`	Studio name	What the lead does	Use it when
`handoff`	Route	Picks exactly one member and hands it the whole turn. That member's answer is the Team's answer; the lead does not edit or combine it.	One member can answer each request, and the job is choosing which: a front desk, a triage step.
`dynamic_delegation`	Delegate & Synthesize	Splits the request into subtasks, delegates them to one or more members, then writes one answer from what they send back.	A request may need several members, and which ones depends on the request.
`parallel`	Parallel Fan-out	Sends the same task to every member at once, then combines all of their answers. The most expensive mode per turn: every member runs.	You want every member's view on every request: a review panel, several independent checks.
`plan_execute`	Plan & Execute	Treats the request as a goal: writes its own task list, assigns tasks to members, reviews the results and loops until the goal is met or `maxIterations` is reached.	The work is multi-step and its steps are not known in advance. If they are known, use a Workflow.

How the iteration cap and the lead's history apply in each mode:

`coordinationMode`	`maxIterations`	`numHistoryRuns`
`handoff`	Not read. Write `null`.	The lead's memory of earlier messages, when it routes.
`dynamic_delegation`	Not read. Write `null`.	The lead's memory, when it delegates and synthesizes.
`parallel`	Not read. Write `null`.	The lead's memory, when it combines the answers.
`plan_execute`	Required. The most planning rounds the lead runs (1–20; Studio's default is 6). A run that reaches it ends as `max_iterations_reached`.	The lead's memory, when it plans.

numHistoryRuns applies only while addHistoryToContext is true. A value that is not read is still checked: a maxIterations above 20 is refused in every mode.

`handoff` (Route)

teams/front-desk.yaml

coordinationMode: handoff
maxIterations: null
# Studio greys these two out for Route, but the run still passes them on: with
# determineInputForMembers false, the chosen member gets the raw request.
determineInputForMembers: true
shareMemberInteractions: false

`dynamic_delegation` (Delegate & Synthesize)

teams/research-desk.yaml

coordinationMode: dynamic_delegation
maxIterations: null
determineInputForMembers: true
shareMemberInteractions: true

`parallel` (Parallel Fan-out)

teams/review-panel.yaml

coordinationMode: parallel
maxIterations: null
# Every member is sent the same task.
determineInputForMembers: false
shareMemberInteractions: false

`plan_execute` (Plan & Execute)

teams/onboarding-planner.yaml

coordinationMode: plan_execute
goal: Onboard the new customer end to end.
maxIterations: 6

Studio asks for a goal before it saves a Plan & Execute Team; set one. This mode does not read determineInputForMembers; shareMemberInteractions it does read.

`status`

Install creates the Team with the status you write, and nothing in the install changes it.

`status`	What the installed Team is
`active`	Live. Use this for every Team the Package runs. Stored and carried; Studio does not offer it.
`draft`	Not yet activated. Stored and carried; Studio does not offer it (the Team editor has no Activate or Move to Draft).
`paused`	Stored and carried; Studio does not offer it. Nothing in the install sets it.
`archived`	Shown in Studio's Teams list as "Archived", and found by its Archived filter: a Team kept for reference. Studio's Archive sets it.

Studio's Teams list shows a status only for an archived Team, and its status filter offers Not archived and Archived. A Studio save writes the stored status back unchanged.

status is a label today: the run endpoints, the Team run chat and a Workflow's Team step run a Team whatever its status. To keep a Team from running, keep it out of the entry point and out of every Workflow, rather than relying on draft or archived.

The lead

Every Team has exactly one lead. leadType and the six fields below describe it, and which ones apply depends on leadType:

Field	Type	`leadType: managed`	`leadType: member`
`leadLlmSlot`	An `llm` Slot id, or `null`	Required. The model the lead thinks with.	Write `null`. The lead thinks with its own Agent's model.
`leadModelId`	A model id, or `null`	A preference: used when the Configuration bound to `leadLlmSlot` offers it, otherwise that Configuration's first text model is.	Write `null`.
`leadInstructions`	Text, or `null`	How the lead decides: who to route to, how to split work, how to combine.	Write `null`. The lead uses its own Agent's instructions (and its tools).
`leadMember`	`agents.<name>`, or `null`	Write `null`.	Required. The member Agent that leads.
`leadMemberDelegateEligible`	`true` or `false`	Write `false`.	`true` lets the lead also receive delegated work, as a member. Default `false`: it only leads. If the lead is also listed in `members`, that row's own `delegateEligible` is stored, but only this flag counts, at run time and in the save rule.
`leadMemberCanAnswerDirectly`	`true` or `false`	Write `false`.	Stored and carried; Studio does not offer it, and a Studio save keeps it. The current runtime does not read it.

A promoted member lead brings its own tools, knowledge and skills into the lead role, which helps when deciding who should answer itself needs a tool call. A managed lead is cheaper: a routing decision does not carry a full Agent into every turn. The lead may also be listed in members (a Team exported from Studio lists it there); at run time that row is skipped and leadMemberDelegateEligible decides whether the lead also works.

teams/account-desk.yaml

leadType: member
leadLlmSlot: null
leadModelId: null
leadInstructions: null
leadMember: agents.account-manager
leadMemberDelegateEligible: false
leadMemberCanAnswerDirectly: false

What `build` refuses

build and install validate a Team the same way, so these never reach an Organization. Each refusal names the database constraint it stands for:

A Team file with	Is refused with
`leadType: managed` and `leadLlmSlot: null`	`PORTABLE_CONSTRAINT_VIOLATION` (`teams_lead_managed_llm_config_check`)
`leadType: member` and `leadMember: null`	`PORTABLE_CONSTRAINT_VIOLATION` (`teams_lead_member_agent_check`)
`coordinationMode: plan_execute` and `maxIterations: null`	`PORTABLE_CONSTRAINT_VIOLATION` (`teams_plan_execute_max_iterations_check`)
`maxIterations` above 20, in any mode	`PORTABLE_CONSTRAINT_VIOLATION` (`teams_max_iterations_ceiling_check`)
`numHistoryRuns` below 0 or above 100	`PORTABLE_CONSTRAINT_VIOLATION` (`teams_num_history_runs_check`)
`maxIterations` of 0 or less	`PORTABLE_DEFINITION_INVALID`
a `leadMember` or member `agent` that is not `agents.<name>`	`PORTABLE_DEFINITION_INVALID`
the same Agent twice in `members`	`PORTABLE_DEFINITION_INVALID`
a `coordinationMode`, `status` or `leadType` not listed on this page	`PORTABLE_DEFINITION_INVALID`
a field not listed on this page	`PORTABLE_DEFINITION_INVALID`
an id-shaped value anywhere, such as a UUID inside `configOverrides`	`PORTABLE_DEFINITION_INVALID`

Other lead combinations are accepted. A field the table above says to write as null or false for your leadType is not read at run time, but a leadLlmSlot that is set must still be bound at install, and a leadMember that is set must still name an Agent in the Package. Otherwise install refuses the Team with PORTABLE_UNRESOLVED_BINDING.

Context and history

Five toggles shape what the lead and members see during a run, and two set the lead's own memory. Each is required in a Team file except the last two; the default is what Studio sets for a new Team.

Field	Type	Default	What it does
`determineInputForMembers`	`true` or `false`	`true`	The lead writes each member its own input, instead of forwarding the raw request. Read in every mode except `plan_execute`; Studio greys it out for Route and Plan & Execute.
`addTeamHistoryToMembers`	`true` or `false`	`false`	Each member's context includes the Team conversation so far, not only its own task. Read in every mode.
`shareMemberInteractions`	`true` or `false`	`false`	Members see each other's answers within the same run. Read in every mode; Studio greys it out for Route and Plan & Execute.
`addNameToContext`	`true` or `false`	`true`	The Team's name is in the context the lead receives.
`addDatetimeToContext`	`true` or `false`	`false`	The current date and time are in the context the lead receives.
`addHistoryToContext`	`true` or `false`	`true`	The lead sees the earlier messages of the conversation. Optional; left out, it installs as `true`.
`numHistoryRuns`	An integer, 0–100	`5`	How many earlier messages the lead sees (a question and its answer are two). Optional; left out, `5`.

teams/research-desk.yaml

determineInputForMembers: true
addTeamHistoryToMembers: true
shareMemberInteractions: true
addNameToContext: true
addDatetimeToContext: true
addHistoryToContext: true
numHistoryRuns: 10

Members

Field	Type	What it is
`agent`	`agents.<name>`	The member Agent, declared under `agents:` in the manifest. Each Agent at most once.
`role`	Text, or `null`	What the member is for. Stored and carried; Studio does not offer it, a Studio save keeps it, and it is not read at run time.
`sortOrder`	An integer	The member's place in the roster. Members are handed to the lead in this order.
`delegateEligible`	`true` or `false`	Stored and carried (default `true`); Studio does not offer it, a Studio save keeps it, and it is not read at run time: the lead can delegate to every member.
`configOverrides`	An object, or `null` (default)	Per-member settings for this Team. Carried as written, with no id-shaped values, and kept by a Studio save; the current runtime does not apply them, so write `null`.

Studio and the Team API save a Team only when it has at least two members a run can delegate to: every regular member counts, and a promoted lead counts when leadMemberDelegateEligible is true.

A member whose own Agent budget is already exceeded is left out of the run before it starts, and the Team proceeds with the rest.

Budget and policy

Field	Type	Default	What it does
`budgetCapJson`	An object, or `null`	`null`	Carried as written and not enforced. A Team's spend cap is set by the operator in Settings → Budgets, with `team` scope.
`policyJson`	An object, or `null`	`null`	The Team's run policy, read before and during each run. The keys below.

policyJson keys:

Key	Type	What it does
`hitl_threshold.enabled`	`true` or `false`	Turns the approval gate on. With no threshold set, every run asks for approval before it starts.
`hitl_threshold.threshold_iterations`	An integer	Only `plan_execute` checks it: the run asks for approval once it reaches this many iterations. In any other mode, a Team with it set never asks.
`hitl_threshold.threshold_usd`	A number	The cost limit per run, in USD (Studio: "When a run's cost reaches $…"). The run's cost is estimated between steps, and once it reaches the limit the run asks for approval before the lead's next tool call (a delegation, a task, or its own tool); no step starts while approval is pending. A member's run that is already under way is not interrupted, so one long delegation, or several tool calls from one lead turn running together, can take the run well past the limit. It asks once; after approval it runs to the end, and with `threshold_iterations` also set the run still asks only once. The estimate covers model tokens only, priced at each member's and the lead's configured primary model (a round trip a policy routes to another model is priced at the model that served it); tokens of a model with no price count as $0, so they cannot trigger the limit (for a routed round trip, a failed price lookup also counts as $0 and is not retried during the run). `0` asks before the first step (Studio requires more than 0). A value that is not a number of 0 or more (`null`, a string, a negative number) counts as unset, so every run asks before it starts (unless `threshold_iterations` is set). Teams saved before this change with Studio's "Above $10 per turn" now ask once a run reaches $10, routed to the owners and admins until reviewers are chosen.
`hitl_threshold.reviewers.user_ids`	A list of user ids	The members who answer this Team's approvals. Checked when a request is created: a user who is no longer an active member, or cannot open reviews, is dropped. Not exported: a Package carries `all_admins` only.
`hitl_threshold.reviewers.all_admins`	`true` or `false`	Sends approvals to every active owner and admin of the organization as well. If neither this nor any chosen member is left, the request goes to the owners and admins anyway. If the organization has no active owner or admin either, no request is created and the run ends `failed`: "No one can approve this Team's runs: the organization has no active owner or admin".
`block_rules`	A list of `{ reason }`	Any entry stops every run before it starts, with status `policy_blocked` and the first entry's `reason`. An admin pause switch.
`allow_cross_org`	`true` or `false`	Stored; not enforced yet.

teams/onboarding-planner.yaml

policyJson:
  hitl_threshold:
    enabled: true
    threshold_iterations: 4
budgetCapJson: null

A cost limit, answered by the installing organization's admins:

teams/claims-desk.yaml

policyJson:
  hitl_threshold:
    enabled: true
    threshold_usd: 0.5
    reviewers:
      all_admins: true

The estimate prices each model's tokens the way billing does (an admin-entered price first, then the synced catalog price), using each member's configured model and the lead's model. It is an estimate for the gate only: the billed figure is computed separately, after the run.

A Team run that is rejected, or not answered within 24 hours, ends as failed.

Approvals and Workflow steps

A Team-run approval is answered where a Workflow's Human Review is: on the Reviews page in Studio, grouped by Team, with a link to the run. See Responding to a review.

A Workflow runs a Team with a team_step node. Its data names the Team as team: teams.<name> (the Team must be declared under teams: in the manifest) and passes the Team its input:

workflows/handle-request.yaml

name: Handle request
description: Hands the incoming request to the triage Team.
graph:
  nodes:
    - id: start
      type: trigger_manual
      position:
        x: 0
        y: 0
      data:
        description: Start with a request.
    - id: triage
      type: team_step
      position:
        x: 240
        y: 0
      data:
        team: teams.triage
        teamName: Triage
        inputExpression: '{{ trigger.request }}'
  edges:
    - id: start-triage
      source: start
      target: triage

The node's output carries the Team's answer as text. A Team run that is blocked by policy or stopped by a budget fails the node instead of passing on an empty answer. See Workflows → References inside nodes.

Team, Workflow or single Agent?

One Agent when one actor with one set of instructions can do the whole job.
A Team when which specialist should act depends on the request, and a lead should decide at run time.
A Workflow when the steps and their order are known in advance: a sequence, a branch, a human approval, a schedule.

Schedules and webhooks can only start a Workflow. If a Team needs to run on a schedule, make the entry point a Workflow whose step calls the Team.

Install rules

Every member Agent is installed before the Team. A member-lead Team whose lead is declared after it in the manifest still installs correctly, because order comes from the references, not the listing.

Teams

On this page