Skip to main content
Orchestration is how you split one agent into parts. There are three shapes, and the difference that matters is whether control comes back. On this page: New here? Read How a package fits together first. It is one page, it answers “I want two agents, each with tasks, where do I start?”, and everything below assumes it.

​
The three shapes

The difference that matters most is whether control comes back. A task returns. A handoff does not.
Tasks and flows compile on Pipecat, LiveKit and SLNG. Handoffs need Pipecat or LiveKit, because SLNG writes one agent. Twilio compiles one agent with one prompt and refuses all three. unmute validate says so and names the way out.
None of these is how you reach a person: that is an transfer, and what it can do depends on the phone route. Whichever shape you reach for, you write it the same way: as a name in one of the agent’s five lists. The five things an agent can do shows the lists and which ones come back.

​
What each shape does to the call

Each picture answers two questions: who is talking to the caller, and does control come back to the agent that started.

​
A tool

The agent stays in charge. It calls the tool, reads the result, and keeps talking.

​
A task

The owner enters the task. The task talks to the caller with its own prompt and tools. When the model calls finish, the values in save: are saved and the owner continues, reading them through its own placeholders.

​
A task that ends on a tool

The same, except the tool decides. When the tool’s result matches an outcome with then: done, the task saves and ends by itself. The model makes no finish call, and the owner speaks next.

​
A handoff

The first agent hands the caller to a second agent. The second agent owns the rest of the call. Nothing comes back.

​
Read one example against the other

Two shipped packages are the same salon, built two ways. examples/salon-concierge-single-prompt is one agent with one prompt: no tasks and no handoffs. Its tools, pre-fetch, model and turn taking are the same as the other package’s. examples/salon-concierge is the structured one, with tasks, a flow, handoffs and saved values. Read one against the other to see what the structure bought.

​
Read them in order, then choose

Start with the first page: it adds one task to the package you already have, one key at a time. The next three pages are one shape each, with the example package that uses it. The last page is the one to come back to when you are deciding: it pairs the symptom you have with the shape that fixes it, and says what each shape costs.

Your first task

From no task to a task that says what success looks like, on your own package.

Tasks

Run a step, keep the answer.

Flows

A fixed order, and shared context.

Handoffs

Two agents, two sets of rules.

Choosing a structure

Which split to reach for, and what it costs.