Skip to content

Your First Fleet

In this tutorial, you'll compose two agents into a fleet — a coordinator that triages input and a researcher that answers questions. You'll see how delegation works between agents.

Time: ~20 minutes

Prerequisites: Completed Your First Agent. Podman and Ollama running.

Step 1: Scaffold the Fleet

vlinder fleet new my-fleet

This creates a my-fleet/ directory with a starter fleet.toml.

cd my-fleet

Step 2: Add Two Agents

Use vlinder agent new to scaffold agents inside the fleet:

mkdir -p agents
vlinder agent new python agents/coordinator
vlinder agent new python agents/researcher

Your directory now looks like this:

my-fleet/
├── fleet.toml
└── agents/
    ├── coordinator/
    │   ├── agent.toml
    │   ├── agent.py
    │   ├── Dockerfile
    │   ├── build.sh
    │   └── README.md
    └── researcher/
        ├── agent.toml
        ├── agent.py
        ├── Dockerfile
        ├── build.sh
        └── README.md

Step 3: Wire Up fleet.toml

Open fleet.toml and replace the commented-out template with your agents:

fleet.toml
name = "my-fleet"
entry = "coordinator"

[agents.coordinator]
path = "agents/coordinator"

[agents.researcher]
path = "agents/researcher"
  • entry — the agent that receives user input
  • agents.<name>.path — relative path to each agent's directory (must contain an agent.toml)

Step 4: Add Delegation to the Coordinator

The scaffolded agents work standalone, but in a fleet the coordinator should delegate to the researcher. Open agents/coordinator/agent.py and modify the request handler to use the delegate() and wait() bridge helpers:

agents/coordinator/agent.py (handle_request)
def handle_request(user_input):
    lower = user_input.lower()

    # Delegate research questions to the researcher agent
    if any(word in lower for word in ["what", "why", "how", "explain"]):
        handle = delegate("researcher", user_input)
        return wait(handle)

    # Handle greetings directly
    return infer(f"Respond briefly to: {user_input}")

The coordinator now routes questions to the researcher and handles everything else itself. Both delegate() and wait() are already available from the template's bridge helpers.

Step 5: Build the Containers

podman build -t localhost/my-fleet-coordinator:latest agents/coordinator/
podman build -t localhost/my-fleet-researcher:latest agents/researcher/

Update the executable field in each agent.toml to match these image names:

agents/coordinator/agent.toml
executable = "localhost/my-fleet-coordinator:latest"
agents/researcher/agent.toml
executable = "localhost/my-fleet-researcher:latest"

Step 6: Run the Fleet

vlinder fleet run

Vlinder loads fleet.toml, deploys both agents, and starts an interactive session with the coordinator.

Try it out:

❯ hello
Hello! How can I help you today?

❯ what is the fastest land animal?
The cheetah is the fastest land animal, reaching speeds up to 70 mph.

The first message is handled directly by the coordinator. The second is delegated to the researcher — the coordinator recognizes it as a question and passes it along.

Step 7: Observe Delegation

Inspect the timeline to see both agents' interactions:

# See all interactions
vlinder timeline log

# Filter to just the researcher
vlinder timeline log --agent researcher

What You Learned

  • How to scaffold a fleet with vlinder fleet new
  • How to add agents to a fleet using vlinder agent new
  • How to write a fleet.toml manifest
  • How the entry agent delegates work to other agents using delegate() and wait()
  • How to observe delegation in the timeline

Next Steps