Cost Management for Multi-Agent Workloads

Running dozens of agents in parallel is fast, but it's important to understand and manage the cost implications.

How Swarm Cost Works

Swarm cost is linear, not exponential. This means:

Approach	Total Tokens	Wall-Clock Time
Sequential (1 agent doing 10 tasks)	~X tokens	10 × T
Swarm (10 agents, 1 task each)	~X + overhead	~T

The total token usage is approximately the same — what you gain is speed. The overhead per agent comes from:

• Each agent's system prompt (role definition + skills)
• Each agent building its own context from scratch
• Results aggregation and synthesis in wrap_up

Strategies to Minimize Cost

1. Keep Prompts Concise

Large prompts not only cost more but risk 413 context-too-long errors — which are non-retryable and instantly fail the agent. Include only what's necessary: the file path, the specific instruction, and key constraints.

2. Restrict Tools Per Role

Use allowedTools when creating roles to give agents only the tools they need:

agent_roles(action: "add", name: "Reader", allowedTools: ["file_read", "grep"], ...)

This reduces the tool definitions injected into the system prompt (each tool's JSON schema costs tokens), and limits what agents can do — reducing risk.

3. Right-Size Your Swarm

Task Size	Recommended Agents
Small (1–3 files)	1–3 agents or just agent()
Medium (5–15 files)	5–15 agents
Large (20+ files)	20–50+ agents

Don't launch 50 agents for a 3-file task — the per-agent overhead outweighs the parallelism benefit.

4. Use Cheaper Models for Simple Tasks

When creating a role, you can specify a cheaper model for tasks that don't need frontier intelligence:

agent_roles(action: "add", name: "FileReader", model: "openai/gpt-4o-mini", ...)

Save your premium model (e.g., Claude Opus) for the Architect or Reviewer roles that need deep reasoning.

5. End with a Single Synthesizer

Instead of having every agent produce a full report, instruct agents to output structured data (bullet points, JSON), then have one final "Synthesizer" agent compile everything. This reduces total output tokens.

6. Monitor with peek Instead of get_results

While a swarm is running, use peek for a lightweight status check. Reserve get_results for when all tasks are done — it returns full results and costs more tokens to process.

Cost Visibility

You can monitor your overall API usage at any time:

openrouter_key_usage()

This shows your usage, limits, remaining credits, and billing periods.

Timeout Economics

Each agent has a 30-minute overall timeout and a 180-second inactivity timeout. Agents that time out have consumed tokens without producing results. To avoid this:

• Set clear, bounded tasks (not open-ended exploration).
• Use retry_failed to relaunch transient failures rather than starting a new plan.
• For long-running tasks, override timeoutSeconds on the role — but only when genuinely needed.

Summary

Strategy	Impact
Concise prompts	Fewer input tokens, avoids 413 errors
Tool restrictions	Smaller system prompts, less risk
Right-sized swarms	Less overhead per useful work unit
Cheaper models for simple roles	Lower cost per token
Structured output + single synthesizer	Fewer output tokens
peek over get_results during execution	Less processing overhead