The composable AI thesis

The core observation

If you take a narrow agent role and decompose it into sub-agents, you get the same hierarchical structure as an Envelope team. A "Support Lead agent" and a "support team with an L1, L2, and comms agent" present the same interface to the outside world — the team version just performs better because each piece has one clear job.

This means the agent abstraction is fractal: any leaf node in the hierarchy could, in theory, be expanded into a sub-team without changing anything upstream. The parent doesn't know or care whether the thing it escalates to is one model or five.

Quick answer

Composable AI means designing agent systems from narrow, interchangeable components — each with one job — that can be combined into larger systems without changing how they interface upstream. Any agent role can be expanded into a sub-team of more specialised agents, and the parent system doesn't need to change. Narrow roles outperform broad ones because they have clearer instructions, smaller context, and less ambiguity in every decision.

Diminishing returns on specialisation

Narrow roles are the right design principle. The more focused each agent's job, the better it performs — clearer instructions, smaller context, less ambiguity. Composable AI is designed around this idea and Envelope teams should be too.

Performance gains from narrowing come from:

• Reduced ambiguity in instructions
• Smaller, less noisy context window
• Clearer input/output contract

The practical challenge is a balancing act, not a reason to stop decomposing early. There is a crossover point where coordination overhead — latency, error propagation between sub-agents, more surface area for failures — starts outweighing the remaining specialisation gains. Once a role is narrow enough to be genuinely unambiguous, splitting it further adds seams without adding focus.

Where the boundary sits in practice

The clearest signal that decomposition has gone too far is when two sub-agents always fire together. If your "intent classifier" and "response selector" always run in sequence with no branching between them, they are one agent wearing two hats. Merge them.

The clearest signal that a role hasn't been decomposed enough is when the same agent makes decisions that belong to different time horizons. A customer support agent that simultaneously decides whether an issue is in scope and drafts the reply and decides whether to escalate is doing three different jobs. Each decision has a different failure mode, a different set of tools it needs, and a different threshold for human review. Keeping them fused means the whole agent degrades when any one of those three things is hard.

A concrete example: a document processing pipeline. A single "document analyser" agent that extracts data, validates it against a schema, checks for fraud signals, and formats the output for downstream systems is too broad. The failure modes don't overlap — extraction errors, schema violations, and fraud signals all need different handling. A better decomposition is extraction → validation → risk assessment → formatting, each as a separate agent. Each step has one job. If validation fails, the pipeline halts there; the risk assessment step never runs on bad data. If fraud signals increase, you can replace the risk assessment agent with a more specialised model without touching extraction or formatting.

The inverse mistake is decomposing a single lookup into three agents: one to query a database, one to parse the result, one to format it. These steps have no meaningful independence — they share the same context, the same failure mode, and the same latency budget. Splitting them adds network hops and error-handling complexity with no gain in focus.

The right decomposition boundary is a per-team judgment call. The question is not whether to decompose, but how far — and that depends on the complexity and coherence of the underlying job function. Designing that boundary well is a skill, not just a configuration task. The best Envelope teams will be those where builders have thought carefully about it rather than splitting arbitrarily or stopping too early.

Where orchestration belongs

The question of whether composable AI should be managed at the orchestration layer or the distribution layer has a reasonably clean answer.

The orchestration layer manages the runtime: how agents wake, how tasks route between them, how context passes, how events are handled. Composability at the execution level — which agents collaborate, in what order, with what shared state — belongs here.

When you design an orchestration layer well, you get a few specific things. Agents can be swapped independently — if the model powering your risk assessment step improves, you update that agent's config and nothing else changes. You get granular observability: each agent's inputs, outputs, and latency are logged separately, so you know exactly where a pipeline degraded. You can set different retry and escalation policies per agent, because different failure modes warrant different responses. And you can run agents in parallel where the task structure allows it — a pipeline that runs extraction and metadata tagging at the same time is faster than one that runs them sequentially.

These are not abstract benefits. They matter immediately when something breaks in production, because you have a precise error location rather than a black-box failure in a large agent.

Envelope is the distribution layer. It manages how teams are defined, published, discovered, and installed. Composability at the packaging level — selecting and combining published teams into a workspace — is Envelope's domain.

Trying to build nested team composition into Envelope would mean building orchestration into a distribution product. That is probably the wrong layer for it.

The clean separation

Both layers are composable in their own right. Envelope should ensure the team definitions it publishes are clean and well-structured enough that the runtime can orchestrate them effectively. The runtime should expose enough flexibility that Envelope-installed teams can interoperate without Envelope needing to know about it.

Implications for Envelope

• The current model — team as atomic installable unit — is correct at the distribution layer.
• Narrower, more performant agents deliver better results per task — high-quality specialist teams become premium composable components, valued as much for their composability as their standalone output.
• No need for Envelope to model cross-team nesting at the definition level; that is the runtime's concern.
• The natural language team generation feature could surface existing published teams that match a brief — giving deployers the option to install immediately rather than starting from a generated template. The more teams builders publish, the more useful this becomes. A compounding pull effect for the marketplace.

Practical implications for teams building agent systems today

If you are building agent systems now, the composability framing has direct consequences for how you structure work.

Define roles before you define tools. The most common mistake is attaching tools to an agent and then figuring out what it does. Do it the other way: write a one-sentence job description, then ask what tools that job actually requires. If the job description has an "and" in it — "classifies issues and drafts responses" — split it before you proceed.

Treat handoffs as contracts. Every point where one agent passes work to another is an interface. Write it down explicitly: what is passed, in what format, under what conditions. If you skip this, your agent system is tightly coupled in practice, even if it looks modular on a diagram. Loose coupling at the handoff level is what makes individual agents replaceable.

Build for selective replacement, not wholesale rewrite. The payoff of composable design isn't visible on day one — it shows up when you need to swap the model powering a single step, adjust a prompt for one role without affecting others, or add a new agent to an existing pipeline. Design each agent as if someone will want to replace it independently in six months, because they will.

Instrument each agent separately. Log inputs, outputs, latency, and escalation events at the individual agent level, not just at the pipeline level. This is the only way to distinguish "the pipeline is slow" from "one step is slow." It is also the only way to catch prompt degradation on a specific agent before it affects downstream steps.

Scope human review gates carefully. Not every agent needs a human review gate, and putting one on every step defeats the purpose of automation. The right gates are at decision points where mistakes are hard to reverse — a fraud flag, an escalation to a paid tier, an external communication. Identify those points during design, not after deployment.

Plan for versioning from the start. If a team is a publishable, installable unit, it will have versions. Downstream consumers may be running an older version while you ship a newer one. The cleaner your agent interfaces and handoff contracts, the easier versioning becomes — changing internal logic without changing the interface means downstream consumers don't need to update.

None of this is specific to any particular framework or model provider. These are structural decisions that pay off regardless of what you build on. The tooling will keep changing; the principles for how to decompose work well do not.

Design your AI agents in Envelope

Envelope turns a plain-language description of your workflow into a complete AI agent system — agents with named roles, model assignments, tool access, handoffs, and human review gates. Free to start, no code required.

Start designing →

Frequently asked questions

What is composable AI?

Composable AI is the practice of building specialised agents that each do one thing well, then connecting them into a structure that handles the overall complexity — rather than building one large, generalist agent.

Why does an agent role and a small team performing the same job produce the same interface?

The agent abstraction is fractal: a single "Support Lead" agent and a support team with an L1, L2, and comms agent present the same interface upstream. The team version performs better because each piece has one clear job, but nothing above it needs to know the difference.

Is there a limit to how far you should decompose an agent into sub-agents?

Yes. Specialisation gains taper off once a role is genuinely unambiguous — splitting further adds coordination overhead (latency, error propagation) without adding focus. The right boundary is a per-team judgment call, not a default to maximise.

What's the difference between the orchestration layer and the distribution layer?

The orchestration layer manages the runtime — how agents wake, route tasks, and pass context. The distribution layer manages how teams are defined, published, discovered, and installed. Envelope operates at the distribution layer.

Should Envelope build nested team composition into its orchestration?

No. That would mean building runtime orchestration into a distribution product — the wrong layer for it. Envelope's job is to produce clean, well-structured team definitions that any runtime can orchestrate.

Why does narrow agent design matter for a team marketplace?

Narrower, more performant agents deliver better results per task, which makes high-quality specialist teams more valuable as composable components — both for their standalone output and for how well they combine with other teams.