{"record":{"id":"6f9b3b2b2647654c","repo":"microsoft/semantic-kernel","slug":"handoffs-cannot-be-empty-please-provide-at-least","errorCode":null,"errorMessage":"Handoffs cannot be empty. Please provide at least one handoff connection.","messagePattern":"Handoffs cannot be empty\\. Please provide at least one handoff connection\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/orchestration/handoffs.py","lineNumber":517,"sourceCode":"                self._get_agent_actor_type(member, internal_topic_type),\n            )\n            for member in self._members\n        ]\n\n        await asyncio.gather(*[runtime.add_subscription(subscription) for subscription in subscriptions])\n\n    def _get_agent_actor_type(self, agent: Agent, internal_topic_type: str) -> str:\n        \"\"\"Get the actor type for an agent.\n\n        The type is appended with the internal topic type to ensure uniqueness in the runtime\n        that may be shared by multiple orchestrations.\n        \"\"\"\n        return f\"{agent.name}_{internal_topic_type}\"\n\n    def _validate_handoffs(self) -> None:\n        \"\"\"Validate the handoffs to ensure all connections are valid.\"\"\"\n        if not self._handoffs:\n            raise ValueError(\"Handoffs cannot be empty. Please provide at least one handoff connection.\")\n\n        member_names = {m.name for m in self._members}\n        for agent_name, connections in self._handoffs.items():\n            if agent_name not in member_names:\n                raise ValueError(f\"Agent {agent_name} is not a member of the handoff group.\")\n            for handoff_agent_name in connections:\n                if handoff_agent_name not in member_names:\n                    raise ValueError(f\"Agent {handoff_agent_name} is not a member of the handoff group.\")\n                if handoff_agent_name == agent_name:\n                    raise ValueError(f\"Agent {agent_name} cannot handoff to itself.\")\n\n\n# endregion HandoffOrchestration\n","sourceCodeStart":499,"sourceCodeEnd":531,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/orchestration/handoffs.py#L499-L531","documentation":"Raised as a ValueError in HandoffOrchestration._validate_handoffs when self._handoffs is empty/falsy. HandoffOrchestration requires at least one handoff connection (a directed edge between two members) to be meaningful; with none, the orchestration is statically unable to transfer control, so construction is rejected.","triggerScenarios":"Constructing HandoffOrchestration without passing any handoff connections, or passing an empty list/dict of handoffs. The validation runs during orchestration setup (typically in __init__ or prepare) and aborts before any invocation.","commonSituations":"Forgetting to pass the handoff tuples (e.g. Handoff(source, target)); building handoffs dynamically and ending with an empty collection; copy-paste from a concurrent/sequential orchestration where handoffs are not required; refactoring that dropped the handoff argument.","solutions":["Pass at least one handoff connection when constructing HandoffOrchestration (e.g. Handoff(agent_a, agent_b)).","If you do not need agent-to-agent transfers, use ConcurrentOrchestration or SequentialOrchestration instead.","Validate the handoffs collection is non-empty before constructing the orchestration."],"exampleFix":"# before\norchestration = HandoffOrchestration(members=[agent_a, agent_b], handoffs=[])\n# after\nfrom semantic_kernel.agents.orchestration import Handoff\norchestration = HandoffOrchestration(\n    members=[agent_a, agent_b],\n    handoffs=[Handoff(agent_a, agent_b)],\n)","handlingStrategy":"validation","validationCode":"# Ensure handoffs is non-empty before constructing:\nassert handoffs, \"HandoffOrchestration requires at least one Handoff connection.\"\nif not handoffs:\n    raise ValueError(\"Provide at least one Handoff(source, target).\")","typeGuard":null,"tryCatchPattern":"try:\n    orchestration = HandoffOrchestration(members=members, handoffs=handoffs)\nexcept ValueError as ex:\n    if \"Handoffs cannot be empty\" in str(ex):\n        # if no transfers are needed, switch orchestration type\n        from semantic_kernel.agents.orchestration import SequentialOrchestration\n        orchestration = SequentialOrchestration(members=members)","preventionTips":["Provide at least one Handoff(source, target) when using HandoffOrchestration.","If no inter-agent transfer is needed, prefer Concurrent/Sequential orchestration.","Validate the handoffs collection is non-empty at construction time."],"tags":["orchestration","handoff","validation","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}