Skip to main content

Agencies and Orchestration Strategies

agency() returns an Agent that coordinates a roster. Each roster member is an agent config or a built Agent (so an agency can hold another agency), and a strategy decides who runs when. The strategies are compiled from src/api/runtime/strategies.

StrategyWhat it does
sequentialMembers run one after another; each receives the output of the one before.
parallelMembers run at the same time on the same prompt; a synthesizer built from the agency's own model or provider merges their outputs, leaving out a member that failed.
debateMembers argue over maxRounds rounds (3 by default); in each round every member sees every prior argument; a synthesizer built from the agency's own model or provider distils the result. N members over R rounds cost N×R calls plus one.
review-loopThe first member produces or revises, the second reviews and answers { "approved": true or false, "feedback": "..." }; the loop runs until approval or maxRounds (3 by default); a reply that is not valid JSON counts as not approved.
hierarchicalA manager sees every member as a delegate_to_<name> tool and decides what to delegate and in what order; with emergent.enabled on the agency, it can also call spawn_specialist.
graphMembers declare dependsOn; the strategy sorts the roster topologically, runs each topological tier concurrently (a member waits for its whole previous tier) and feeds each the outputs of its predecessors.
panelEvery member answers the same prompt at once on its own model, under an optional per-seat deadline and concurrency cap; the members that returned text are counted against quorum, and a chair synthesizes their answers without seeing a model or vendor name (chair: false returns the answers labelled). The result carries seats, chair, quorum and seating.

parallel and debate need model or provider on the agency itself; compiling either without one throws AgencyConfigError. On the parallel and panel strategies, a quorum can require a minimum number of successful agents, of distinct providers and (under panel) of distinct vendors; onShortfall: 'proceed' turns a shortfall into a line through the host's logger, and the default throws. A modelPool with seating fills every seat that names neither provider nor model from named models on each call, with strict per-seat credentials and every key redacted from the records (Model Pools, Seating and the Panel Strategy). agency().session() keeps per-session message history and usage totals only. agency() warns when it receives cognitiveMechanisms, which the lightweight helper does not run, and when it receives agencies, a gmi() agent's option that an agency applies to neither itself nor its seats: an agency launches no team, and a seat that may launch teams is a gmi() agent with agencies set on its own options. At the agency level it applies output, the hitl approval gates (after an approval, the code-safety and pii-redaction pattern checks run over the approved tool arguments, agent input or final text), controls, provenance and, on hierarchical (or with adaptive: true), emergent. It accepts guardrails and evaluates none of them: each guardrail id is reported through on.guardrailResult with enforced: false and the text passes unchanged. It accepts rag and adds no retrieved context: with a vectorStore the retrieval step returns nothing, and with documents it logs that the full runtime does the indexing (agency.ts, runGuardrails() and injectRagContext()). voice.enabled attaches a listen() method that takes JSON text frames over a local WebSocket, and channels attaches a connect() that always rejects. agency() builds no shared memory store; members share only what the strategy passes between them.

Fixed pipelines with explicit stages belong to the mission and workflow compilers (Orchestration Guide, mission() API, workflow() DSL); the roster API is documented in Multi-Agent Agency API.

Seats served by GMIs​

agency({ runtime: 'gmi' }) serves every config seat with a GMI (GMIs from agent()): each roster config, the panel chair and each specialist the hierarchical manager spawns, unless its config sets a runtime of its own, which wins. runtime takes 'legacy' (the default) or 'gmi'; any other value throws AgencyConfigError. The hierarchical manager and the parallel and debate synthesizers stay on the generateText() path, and a pre-built member keeps the engine it was built with. A strategy runs a config seat through its generate() or stream(), which run the 'light' profile, so the agency takes no cognition. A pre-built member may carry description, which the hierarchical manager reads into its roster (without it the manager reads "General purpose"), and dependsOn, which selects and orders the graph strategy as a config's does.

sessionSeat(member, options) seats a persistent gmi() agent as itself, with its own persona, cognition profile and tools, through one session of its own for the run, so a manager that delegates to it twice finds the first exchange in the second:

import { agency, gmi, sessionSeat } from '@framers/agentos';

const tutor = gmi({ provider: 'openai', model: 'gpt-4o', name: 'Tutor', instructions: 'You are a patient maths tutor.', cognition: 'full' });
const team = agency({
provider: 'openai',
model: 'gpt-4o',
strategy: 'hierarchical',
agents: { tutor: sessionSeat(tutor, { brief: 'Check each step of the proof.' }) },
});

options take sessionId (prefixed seat:; a seat whose id the member has open fails its first call with a TypeError that names the id), description (by default the member's persona description: the first line of its instructions, else its name), dependsOn, tools and brief (put before every input the seat receives, at most 1,000 characters). tools defaults to the member's own tools but the five self-modification tools, launch_agency, the ten memory tools (the eight cognitive-memory tools, read_working_memory and update_working_memory) and a composed tool whose step tools are not all among the rest; naming one of those, or a tool the member does not have, throws a TypeError, and so does a member that is not a gmi() agent. The seat's session has its memory scoped to itself and no learner: the member recalls nothing of its users there and files nothing under them, and its memoryProvider is neither asked for context nor told the turns. Each of the seat's calls is checked against the member's own budget, when it has one, beside the budget the agency's call carries, and charged to both. agency().close() closes the seat's session and leaves the member serving its own sessions; the seat's usage stays in the member's agent total.

Teams a GMI launches​

A GMI with agencies.launch has a launch_agency tool. Each call builds a temporary agency() team, runs its goal once, closes the team and returns one tool result; one seat makes a subagent.

import { gmi } from '@framers/agentos';

const lead = gmi({
provider: 'openai',
model: 'gpt-4o',
instructions: 'You plan research and hand parts of it to teams.',
tools: { search },
maxTokens: 2_000,
agencies: { launch: true, maxLaunchTokens: 100_000 },
});
ArgumentWhat it holds
goalWhat the team must produce, in full (1 to 8,000 characters); the team sees nothing of the launching conversation.
strategysequential (the default), parallel, debate, review-loop, hierarchical or graph: the strategies above but panel. review-loop takes exactly two seats, and parallel and debate at least two.
seats{ role, instructions } for a temporary member (instructions of at most 8,192 characters); { role, agentKey, brief? } for a member of agencies.members (gmi()); { role, personaId, brief? } for a registered persona (the full runtime). A brief holds at most 1,000 characters. Each seat may name tools (default: none) and dependsOn, the other seats it waits for, with no cycle among them, which the graph strategy reads: a launch that names no strategy runs sequential. A role is unique in the team, starts with a letter, holds only letters, digits, _ and -, is at most 52 characters, and is none of the names the hierarchical strategy uses: spawn_specialist, final_answer, plan and any name that starts with delegate_to_.
budgetUsd, maxTokensCaps the model asks for, each above 0; the launch takes the least of them and its own bounds.
deadlineMsA wall deadline of at least 1,000 ms, held to maxDeadlineMs; defaultDeadlineMs when unset.
maxRoundsRounds of debate and review-loop: 1 to 3, default 3.

An argument or a seat key the table does not name is refused.

The bounds are agencies on the agent (or AgentOSConfig.agencies), checked when it is built, launch on or off: a value outside its range throws a RangeError naming the field (on the full runtime, initialization fails with the code SYS_CONFIGURATION_ERROR), and a field set to null takes its default.

OptionDefaultRange
maxDepth2an integer from 1 to 4
maxSeats5an integer from 1 to 12
maxConcurrent1an integer from 1 to 4
budgetShare0.5above 0, at most 1
maxLaunchTokens200,000at least 2,000
maxLaunchCostUSDnoneabove 0
defaultDeadlineMs120,000, or maxDeadlineMs when that is lower1,000 to maxDeadlineMs
maxDeadlineMs600,0001,000 to 3,600,000

agencies also takes hitl, the approval policy of the team a root launch builds (approvals with no handler throw AgencyConfigError, as on agency()), members on gmi() and coordinator on the full runtime, both below.

  • Depth. A turn no launch sits over is at depth 0, and its team is level 1; a seat at level d may launch only when d + 1 ≤ maxDepth. At the defaults a GMI's team may launch one more level of teams. A nested launch takes its tree's bounds from the root launch, never from the launching member's own options.
  • Concurrency. At most maxConcurrent launches are in flight at once per scope: the launching session at the root, the launching team below it. A launch whose team outlived its grace counts until its seats are released, and no seat of it launches meanwhile (parent_launch_closed).
  • Spend. All the root launches of one parent turn draw on one launch pool (maxLaunchTokens, maxLaunchCostUSD), their nested launches included. A root launch's budget is the least of its arguments, budgetShare of what the launching turn's budget has left (on gmi() the agent's budget or the send's; a full-runtime turn carries none), what the pool has left and maxLaunchTokens; a nested launch draws on its parent launch's budget the same way, and on a persistent member's own budget as well when the member launches it from its seat. A launch whose token cap cannot cover one call of the seat whose calls are largest, or that has no dollars left, is refused budget_unavailable. One call counts 2,000 tokens for the prompt and the output cap the seat's calls are sent with, held to its model's output ceiling, or 4,096 when they carry none: for a temporary seat the launching agent's maxTokens on gmi() and its persona's on the full runtime, for a member's seat the member's own (its maxTokens, else its controls.maxTotalTokens, on gmi(); its persona's on the full runtime). gmi() warns at construction when maxLaunchTokens cannot cover one call of the agent's own route. Every completion call of the team, the seats' and the coordinator's, is checked against the launch's budget before it is sent and charged to it; seats that run at once can each pass the cap by one call. A persistent member's memory embeddings are not counted.
  • Time. One wall deadline per launch. At the deadline, or when the launching turn stops, each seat's model call in flight ends; a tool call already running finishes, and one whose checks or approval finish after that is refused (STEP_ABORTED). The launch then waits at most 5 seconds for the team to settle and close, and returns; a seat still running then is released when it settles.
  • Tools. A seat's tools are its tools allowlist, among the launching agent's own (at a nested launch, the launching seat's). On gmi() a member's seat names only tools the member also has. On the full runtime the launching persona's tools are those its capabilities allow, and a persona's seat names only tools its own capabilities allow. A call to any other tool is answered that the tool is not available in this seat, and the tool does not run. The five self-modification tools (forge_tool, create_workflow, manage_skills, self_evaluate, adapt_personality) and the ten memory tools are never a seat's, launch_agency only where the seat's level can launch, and a composed tool only with every tool its steps call. launch_agency is never a step of a composition or a workflow (Emergent Capabilities).
  • Approval. A team runs under the approval gate the launching turn carries (an agency's, when the agent is one of its members), asked first on every seat's tool call, then under agencies.hitl at a root launch. A nested launch passes on the gate it received, so agencies.hitl's beforeTool covers every seat of every team below the root, each call asked once, while its beforeAgent and beforeReturn are asked in the root team alone. A call whose turn has already stopped is refused without asking anyone. On the full runtime a seat's call to a composition the runtime's emergent engine holds is asked by the composition's name, and each step the composition reaches by the step tool's name, before the step runs; the runtime's own checks (the persona's capabilities, the approval of a tool with side effects) still apply to every call, and the output guardrails that judge the launching turn's tool calls (a guardrail's config.evaluateToolCalls) judge every seat's (Human-in-the-loop). On gmi() every seat's tool call runs the launching turn's onBeforeToolExecution hooks first and a member's own hook after them.

A launch that started returns, whatever its status, { status, agencyId, text, truncated, seats, usage, coordinatorUsage, durationMs, reason?, provenance }. status is the first that holds of budget_exhausted (a budget a call drew on refused it), timed_out, cancelled (the launching turn stopped first), completed and failed, and reason says why for every status but completed. text holds at most 16,000 characters (truncated says whether it was cut) and each seat's summary 1,000. A seat's status is completed, cut (the deadline, a budget or the launching turn's stop ended its last call, or that call was still running when the launch returned), failed or not_run. usage adds the seats' calls, each the usage its turn reported, coordinatorUsage the manager's and the synthesizers', and provenance.budget everything the launch's budget counted, nested launches included. A metaprompt or self-reflection call a seat's GMI makes after its turn is not in its turn's usage, as on any GMI, so usage leaves it out; the launch's budget counts it. A failed seat is named by its error's name and code, never its message, so no model of the team and no result reads a provider's or a handler's words; where the error itself goes is below. A launch that cannot start is a tool error, <code>: <reason>, with one of the codes invalid_arguments, depth_exceeded, too_many_seats, concurrency_exceeded, unknown_tool, tool_not_allowed, seat_form_unsupported, unknown_member, member_unavailable (a member that cannot take a seat, or a seat that cannot be built), duplicate_member, budget_unavailable and parent_launch_closed. A call the tool's input schema refuses (a strategy it does not list, a value that cannot take its type, a missing goal or seats) never reaches the launch: its error reads Invalid arguments for tool 'launch_agency', with no code.

  • On gmi() (and agent({ runtime: 'gmi' })): a temporary seat is a gmi() agent of its own, built from the launching agent's route (the provider and model its persona resolved, its key, base URL, fallback and router settings), completion settings, onBeforeGeneration and onAfterGeneration hooks and controls.maxDurationMs, with the seat's instructions and the launching agent's own tool instances its allowlist names, on the 'light' profile with no memory and no learner, in one session that closes with the seat. agencies.members holds the persistent members a launch may seat by agentKey, each a gmi() agent, listed under its learning.agentKey when it has one; the agent reads the record once, when it is built. A member takes its seat as through sessionSeat(), the seat's role and brief put before every input. The team's manager and synthesizers run on the launching agent's provider and model with its key and base URL alone. The agent's on callbacks see each team as launch:<agencyId>; the agent's own turns fire none of them. A seat's failed call reaches on.error with its original error under launch_agency seat <role>, and a team whose run fails reports it there once, under launch:<agencyId>, with the error it rejected with (a failed seat's by its name and code); without on.error the console gets both, the run under launch_agency run, and the content-safe mode turns each into an event. A callback that throws or rejects fails no launch. The agent's usage ledger, when it has one, records the temporary seats' and the coordinator's calls under the source launch_agency; a member's own ledger records its seat's calls.
  • On the full runtime (AgentOSConfig.agencies): the tool requires the agency:launch capability, so only a persona granted it lists and calls it, and a config tool of the host's own named launch_agency fails initialization. A seat is a GMI of the runtime's GMIManager with no cognitive memory, no retrieval and no learner, running as the launching turn's user ('system' when it names none) and organization: a registered persona by personaId, checked as a session's persona is (strict validation, the user's tier), or, for a temporary seat, a persona made from the launching GMI's (its route, completion options, capabilities and hard limits, with the seat's instructions as its prompt and no metaprompts or sentiment tracking). The team's manager and synthesizers call generateText() on agencies.coordinator ({ provider, model, apiKey?, baseUrl? }), else on the launching persona's provider and model (the GMIs' defaults, gmiManagerConfig.defaultGMIBaseConfigDefaults, when it names none; when neither names a provider, the one the runtime serves that model from, as for the launching GMI itself); a route that names neither apiKey nor baseUrl takes the key of the entry in modelProviderManagerConfig.providers the runtime serves its provider from, and sends it where the runtime's provider sends it: to that entry's base URL, else to the provider's own endpoint, never to a base URL a global default or an environment variable names (an Ollama route takes an entry's base URL with no key too). What such a route takes nothing for, generateText() resolves for the provider, key and base URL together; a route that names either keeps what it names and takes nothing of the entry. A seat's failed call reaches the runtime's logger (the one AgentOS.create takes, else its own) at warn, with its original error, under launch_agency seat <role>, and a failed run under launch_agency run. While a team runs it is in the runtime's agency registry, and AgentOS.listAgencies() returns it: its entry's metadata is a LaunchRecordMetadata (kind: 'launched'), each seat names its GMI and persona, each seat call adds a history entry, and the entry goes once every seat is released. A seat's session (seat:<agencyId>:<role>) is its team's until the seat is released: a request that names it is refused, whatever persona it names, an unknown one included (the GMIManager refuses the session with PERMISSION_DENIED before it looks the persona up, and the turn ends with an error chunk carrying that message), so no request runs a turn on a seat's GMI or shuts a running seat down, and feedback that names it (receiveFeedback()) is not recorded. The idle cleanup (GMIManager.cleanupInactiveGMIs()) passes a seat by: its launch releases it. The usage the runtime's spend meter (spendMeter) records for the launching turn is that turn's own model calls; the team's calls are in the launch's result.

On both, a seat's GMI whose turn fails also writes its own diagnostic of the failed turn to the console, the error's message included, as any GMI's failed turn does; the content-safe mode leaves that line as it is (Logging).

A launched team shares only what its strategy passes between its seats. Once every seat is released (by the launch's return, or later for a seat still running then), nothing of the team remains but the result the parent received, the usage its calls recorded and, for a persistent member on gmi(), the seat session's memory traces, which no later turn reads.

The package root and @framers/agentos/api export sessionSeat(), SessionSeatOptions, SeatHandle, SeatMetadata, LAUNCH_AGENCY_TOOL_NAME and the launch's types: AgencyLaunchOptions (agencies on an agent), RuntimeAgencyLaunchOptions (AgentOSConfig.agencies), LaunchLimits, LaunchAgencyArgs, LaunchSeatSpec, LaunchAgencyResult, LaunchSeatRecord, LaunchUsage, LaunchStatus, LaunchRefusal, LaunchRefusalCode, AgencyLaunchFrame, CallerTurnContext, ToolCallHook and LaunchRecordMetadata (a launched team's registry entry).