{"record":{"id":"42c602bed0a741ae","repo":"microsoft/semantic-kernel","slug":"agent-handoff-agent-name-is-not-a-member-of-the","errorCode":null,"errorMessage":"Agent {handoff_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":525,"sourceCode":"        \"\"\"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":507,"sourceCodeEnd":531,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/orchestration/handoffs.py#L507-L531","documentation":"Raised as a ValueError in _validate_handoffs when the TARGET of a handoff connection is not among the orchestration's members. For each handoff source, every declared target (connection) is checked against member_names; a target not present means the agent would hand off to a non-existent agent, so construction fails.","triggerScenarios":"A Handoff(source, target) is supplied where target's name does not match any member. Occurs when a target agent was removed/renamed but the handoff still points to the old name, or when a target name string is misspelled.","commonSituations":"Renaming/removing a target agent without updating handoffs; typos in target names; referencing a target by a stale name after refactor; building handoffs against a different members set.","solutions":["Ensure every handoff target name matches exactly a member's .name.","Use agent objects in Handoff(...) rather than name strings to avoid typos.","Keep handoffs in sync when members are added/removed/renamed.","Add unit tests asserting all handoff endpoints exist in members."],"exampleFix":"# before - 'reviewer' is not a member\nhandoffs = [Handoff(agent_a, \"reviewer\")]\n# after - target is a real member\nhandoffs = [Handoff(agent_a, agent_c)]","handlingStrategy":"validation","validationCode":"# Validate all handoff targets are members before constructing:\nmember_names = {m.name for m in members}\nfor h in handoffs:\n    tgt = h.target.name if hasattr(h.target, \"name\") else h.target\n    assert tgt in member_names, f\"Handoff target '{tgt}' 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 handoff targets with members and retry\n        ...","preventionTips":["Pass agent objects in Handoff(...) rather than name strings.","Keep handoffs in sync when members are added/removed/renamed.","Unit-test that all handoff targets exist in 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"}