Orchestrating multiple agents

Use casesAdvanced30 min

You'll build a script where a strong model makes a plan, cheap models do the parts in parallel, and an editor merges everything into a report, all on one key.

Task

report topic

Planner

Claude Sonnet 5.5

Worker 1

DeepSeek

Worker 2

DeepSeek

Worker 3

DeepSeek

Editor

Claude Sonnet 5

Finished report

You need: a fetch_... key (create one), a balance (one report costs about a cent), Python 3.10+.

1
Pick the models
Planner and editor: claude-sonnet-5-5 or claude-sonnet-5; for the hardest tasks give the planner claude-opus-5-5. Workers: deepseek-v4.1-flash or claude-haiku-5-5.
2
Save the code
Copy the code below into a file named research.py.

Run it

bash

pip install openai
export ZUKKO_API_KEY="fetch_your_key"
python research.py "The e-scooter market in Europe in 2026"

The report is printed and saved to report.md; the step log goes to the console.

4
Read the log
It shows the cost and time of each step. Workers write poorly: give them claude-haiku-5-5. Report is shallow: use a stronger planner.

1Code

research.py

"""
A team of agents: planner -> workers in parallel -> editor.
pip install openai
python research.py "The e-scooter market in Europe in 2026"
"""
import asyncio
import json
import os
import sys
import time
import urllib.request

from openai import AsyncOpenAI

The code reads the cost of each request from the X-Zukko-Cost-Micros header. Before every request it checks the total against BUDGET_USD and stops when the cap is reached.

A key per role

Create three keys: allow Claude for the planner and the editor, and only cheap models with a small daily cap for the workers. If the workers loop, the cap stops them. Create a client per role and pass the right one to ask():

python

def client_for(role: str) -> AsyncOpenAI:
    # ZUKKO_KEY_PLANNER, ZUKKO_KEY_WORKER, ZUKKO_KEY_EDITOR; falls back to the shared key
    key = os.environ.get(f"ZUKKO_KEY_{role.upper()}") or os.environ["ZUKKO_API_KEY"]
    return AsyncOpenAI(base_url="https://api.zukko.pro/v1", api_key=key, timeout=300)

2Ready-made frameworks

Set base_url and your Zukko key. Exact parameter names depend on the library version.

Library	Setup
OpenAI Agents SDK	`set_default_openai_client(AsyncOpenAI(base_url="https://api.zukko.pro/v1", api_key=...))` and `set_default_openai_api("chat_completions")`
LangGraph (via LangChain)	`ChatOpenAI(model="claude-sonnet-5", base_url="https://api.zukko.pro/v1", api_key=...)`
CrewAI	`LLM(model="openai/claude-sonnet-5", base_url="https://api.zukko.pro/v1", api_key=...)`
AutoGen	`OpenAIChatCompletionClient(model="claude-sonnet-5", base_url="https://api.zukko.pro/v1", api_key=..., model_info={...})`; for non-OpenAI models describe their capabilities in `model_info`

3If it doesn't work

What you see	What to do
"the planner returned an unusable plan"	Tighten the format in `PLANNER_SYSTEM` or use a stronger model
`APITimeoutError`	Raise `timeout` to 300 seconds
"budget used up"	Find the expensive step in the log; raise `BUDGET_USD` or trim the context
`429 key_daily_limit_reached`	Make sure nothing is looping, then raise the key limit
402	Top up; retrying won't help
Made-up numbers in the report	Keep `USE_WEB_SEARCH = True` and the requirement to cite sources

Other errors: API errors.

Agent with tools

LLM as a judge: evaluating answers