{"record":{"id":"4c0d831853b66e67","repo":"microsoft/semantic-kernel","slug":"agent-agent-name-is-not-a-member-of-the-handoff","errorCode":null,"errorMessage":"Agent {agent_name} is not a member of the handoff group.","messagePattern":"Agent (.+?) is not a member of the handoff group\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/orchestration/handoffs.py","lineNumber":522,"sourceCode":"        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":504,"sourceCodeEnd":531,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/orchestration/handoffs.py#L504-L531","documentation":"Raised as a ValueError in _validate_handoffs when an agent that is the SOURCE of a handoff connection is not in the orchestration's members. The validation builds member_names from the members list and checks each handoff's source; a source not present means the handoff graph references an unknown agent, which would break routing.","triggerScenarios":"A Handoff(agent_name_or_object, target) is provided where the source agent's name does not match any member's name. Happens when handoffs reference agents by a different name string, or when members were changed but handoffs were not updated.","commonSituations":"Renaming an agent after wiring handoffs; typos in handoff source names; passing a Handoff built against a different agent instance; dynamically building members and forgetting to add the source; name collisions or trailing spaces in agent names.","solutions":["Ensure every handoff source name matches exactly a member's .name.","Pass agent objects directly in Handoff(...) instead of bare strings to avoid typos.","Rebuild handoffs whenever the members list changes.","Trim/normalize agent names to avoid whitespace or casing mismatches."],"exampleFix":"# before - 'triage' is not a member\norchestration = HandoffOrchestration(\n    members=[agent_a, agent_b],\n    handoffs=[Handoff(\"triage\", agent_b)],\n)\n# after - source matches a member\norchestration = HandoffOrchestration(\n    members=[agent_a, agent_b],\n    handoffs=[Handoff(agent_a, agent_b)],\n)","handlingStrategy":"validation","validationCode":"# Validate all handoff sources are members before constructing:\nmember_names = {m.name for m in members}\nfor h in handoffs:\n    src = h.source.name if hasattr(h.source, \"name\") else h.source\n    assert src in member_names, f\"Handoff source '{src}' is not a member\"","typeGuard":null,"tryCatchPattern":"try:\n    orchestration = HandoffOrchestration(members=members, handoffs=handoffs)\nexcept ValueError as ex:\n    if \"is not a member\" in str(ex):\n        # reconcile handoffs with current members and retry\n        ...","preventionTips":["Pass agent objects (not name strings) in Handoff(...) to avoid typos.","Rebuild handoffs whenever the members list changes.","Add a unit test asserting handoff sources are members."],"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"}