Choosing a structure

You have four ways to organize an agent: one agent with tools, a task, a task group, or a second agent. Each one owns a different boundary. Choose from the brief, before you write files. On this page:

Compare the shapes - the whole trade in one table
The symptom decides the shape - start here if something is already wrong
Task or handoff - the choice people get wrong most
Choosing shapes for a booking flow - one brief, worked through

In a hurry? Two rules carry most of it. A task returns the caller and a handoff does not. And if one agent with good tools can do the job, use one agent with good tools.

Compare the shapes

Every shape trades something for control. This table is the whole trade, side by side.

	Holds the session	Context the receiver sees	Cost in round trips	A caller’s correction	Best for
One agent with tools	the agent, for the whole call	the whole conversation	none beyond the tool call itself	ask again, same turn	one job, one set of rules
Task	the task, until it returns	what `context:` gives it	2 to enter, the same as one tool call	run it again	one job with a definite, typed answer
Task group	the group, across its steps, until it returns	shared across steps, or isolated per step, by `context_scope`	2 to enter the group, once, however many steps run inside	revisit a step inside the group	an order that has to hold, with shared context
Handoff	the receiving agent, for good	only what `context:` carries over	1 to leave, plus the receiving agent’s forced opening turn, every time control changes hands	another handoff back	two roles with genuinely different rules or permissions

These are not exclusive. One agent can run a task in one phase and hand off in another.

Choose the native shape

The brief needs	Native shape	Do not invent
A real external or local action	`tool`	A task used only as an API wrapper
One bounded step that returns	`task`	A second agent or progress flags
Several steps in a fixed order	`flow`	Current-step variables or transition tools
A lasting role or permission change	`agent handoff`	A returning task
A runtime value needed across a boundary	`variable`	Conversation memory or workflow state

If none of these boundaries exists, keep one agent with a clear prompt and its real tools. You describe the job; the coding agent should choose the shape and tell you what it chose. You do not need to ask for a task or flow by name. A server-directed sequence is dynamic, even when its response calls the field nextStep. Put that loop in one task that asks the returned question and calls the real domain tools. If fixed stages surround the loop, those stages can be tasks in a flow. The server owns its dynamic order.

Let the compiler hold the state

Do not create current-step, happy-path, completion, or routing variables. Tasks, flows, handoffs, and an external server already hold that state.
Do not create advance, proceed, dispatcher, or transition tools. A tool does real external or local work; a task, a flow or a handoff moves the conversation.
Keep a variable only when its value really crosses a boundary or feeds a later tool call.

The symptom decides the shape

What you are seeing	The shape that fixes it
the prompt keeps growing and starts contradicting itself	split it: tasks if the parts serve one caller goal, a handoff if they are separate roles
the model does things out of order	a flow: the order is declared, not requested
the model calls a tool it should not have yet	move the tool. Lists are per agent and per task, so a tool the current task does not hold cannot be called at all
a task runs before you have the value it needs	give the task’s own `when:` the clause that names what has to be true first, “once the caller is identified”
you need to keep a value a task produces	`save:` on the task, into a declared variable
two phases need different tools or different permissions	a handoff
the caller needs a person	none of these: that is a human transfer, and what it can do depends on the phone route

A prompt that says “always identify the caller first” is a request. A flow is a guarantee. A when: clause naming the dependency is not a guarantee the same way, but it is cheap: no extra task, no extra prompt site, and nothing the caller has to be spoken through. See Order steps with the prompt for the full pattern, including the tool-level check that catches a task run out of order anyway. Reach for the flow when the order is what must hold. Reach for a when: clause when one value should usually be there before one task runs, and a stray extra turn asking for it is an acceptable cost.

Task or handoff

The difference is whether control comes back. That is why they are two kinds of list rather than one with a kind field: which list a thing is written in is what it is.

agents:
  - name: appointment_desk
    tasks:
      - name: check_customer     # runs, returns a typed result, the agent continues
        when: Identify the caller before handling an appointment request.
        prompt: tasks/check-customer.md
        save:
          - customer_id: result.customer_id
    handoffs:
      - name: to_appointment_manager   # hands the call over, nothing returns
        to: appointment_manager
        when: The caller wants to reschedule or cancel an existing appointment.

Order the task, not the route to it

Say the dependency on the task itself, in its own when::

      - name: send_receipt
        when: The caller asks for a receipt from a past visit, once the caller is identified.

The model reads that clause every time it considers the task. Reference the saved value in the owner’s prompt when the model needs to check it. See Order steps with the prompt for what still catches a task run out of order anyway, and what the caller hears when it does. Do not add an agent whose only job is to hold callers up in front of a task. That agent has to be spoken through, which costs the caller a turn and buys nothing a clause on the task does not already give. And never hold up the route to a person: someone who asks for a manager should not be interviewed first.

	`tasks:`	`handoffs:`
returns	yes	no
saved typed values	yes, through `save:`	existing call state remains available to explicit prompt references
targets	a task, run in place	another agent
where context is set	`context:` on the task	`context:` on the handoff entry

Choosing shapes for a booking flow

A salon booking agent runs into all four decisions in one package. Each lands on a different shape, and together they are examples/salon-concierge. Look up services and answer questions. One job, one set of rules: a single agent with tools handles it. concierge calls look_up_salon_info directly, with no task in between. Confirm who is calling before anything personal. One job with a definite, typed answer: a task. verify_customer holds the one tool that looks the caller up, ends on that tool through an outcome with then: done, and saves customer_phone with save:. The customer_phone variable carries confirm: verify_customer, so until this task has heard the caller agree, the number reaches no other prompt and every tool that needs it refuses. The task keeps a when: of its own for one case only: the caller correcting their phone number. Every other route into verification goes through the flow below. Does identifying the caller have to come before booking, every time? That is the flow question, and here the answer is yes. A booking made against a number nobody agreed to is a booking for a stranger, so the order is not a request to the model. It is something the package has to hold. The flow book runs verify_customer and then manage_booking. A flow’s defaults fit here: its steps share one context, so the booking step hears what verification heard, and it returns the call to the concierge:

flows:
  - name: book
    when: >-
      The caller wants to create, move or cancel a booking. Includes a change to
      an appointment just made.
    steps:
      - task: verify_customer
        skip_when_confirmed: customer_phone
      - manage_booking

Three things follow from the flow.

The second booking on a call skips verification. skip_when_confirmed: customer_phone skips the first step when the number is already confirmed, which is every booking after the first.
The concierge makes one call into the flow instead of choosing between two tasks. Which step runs, and in what order, is the flow’s decision.
manage_booking has no when: of its own, because the flow decides when it runs. A task an agent runs on its own needs a when:. A step inside a flow does not.

Hand a complaint to someone who needs a different tool list and a refund policy the booking agent should never see. A different role with different permissions, not another task in the same role: a handoff. to_complaints moves the caller to complaint_specialist, who alone holds record_complaint and alone reads the refund knowledge base through look_up_refund_policy. Recording a complaint is one action, not an ordered step, so it sits directly on the specialist rather than behind a task. to_concierge carries the reverse direction. The specialist does name verify_customer, as a bare - verify_customer: the definition stays on the concierge, because a task name is one name across the package. It needs the step in reach because record_complaint takes customer_phone through with: and is refused while the caller has not agreed to it, and a caller who opens with a complaint has never been near the booking flow. What is left over goes to a person. A caller who asks for a manager reaches to_manager, a cold transfer, not any of the four shapes above. Both agents hold it, so asking for a person is never gated on identifying yourself first.

Where to go next

Making a task actually run

Why a task you declared never runs, and how to fix it.

Designing declared state

Choosing what a task saves, and the type each value gets.

Run it locally

The dev loop: ports, logs, and picking a target.

Optimize the build

The settings that cut round trips and speed up a call.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Choosing a structure

Compare the shapes

Choose the native shape

Let the compiler hold the state

The symptom decides the shape

Task or handoff

Order the task, not the route to it

Choosing shapes for a booking flow

Where to go next

Making a task actually run

Designing declared state

Run it locally

Optimize the build

​Compare the shapes

​Choose the native shape

​Let the compiler hold the state

​The symptom decides the shape

​Task or handoff

​Order the task, not the route to it

​Choosing shapes for a booking flow

​Where to go next

Making a task actually run

Designing declared state

Run it locally

Optimize the build

Compare the shapes

Choose the native shape

Let the compiler hold the state

The symptom decides the shape

Task or handoff

Order the task, not the route to it

Choosing shapes for a booking flow

Where to go next