AutoGen 交接目标名带空格，运行时才报 Invalid name

Handoff(target="Support Desk") 可以构造出来，加入 AssistantAgent 后，却在转换工具或第一次模型调用时失败：

ValueError: Invalid name: transfer_to_support desk

先看报错里的名称。transfer_to_support desk 是交接工具名，包含空格；它与目标 Agent 是否已经加入团队是两项不同的检查。

本文针对 Python 3.13、AutoGen 的 autogen-agentchat、autogen-core、autogen-ext 0.7.5，模型客户端为 OpenAIChatCompletionClient。其他客户端接受的名称规则可能不同，不把这条错误推广成所有服务商的行为。

默认生成的工具名没有走同一项校验

0.7.5 的 Handoff 在未提供 name 时，将 transfer_to_ 与 target 拼接再转成小写。这个默认路径不会像显式名称那样检查 isidentifier()，所以目标中的空格会直接进入工具名。

OpenAI 客户端随后转换工具时，要求名称只包含 ASCII 字母、数字、下划线和连字符，并检查长度不超过 64 个字符。因而构造交接配置成功，不证明它能送到该模型客户端。

下面的示例只查看配置和工具 schema，不请求模型：

from autogen_agentchat.base import Handoff

handoff = Handoff(target="Support Desk")
print(repr(handoff.name))
print(handoff.handoff_tool.schema["name"])

定位时把生成的工具名、target 和实际参与者名称分别记下。错误出现在工具转换阶段时，给提示词补一句“正确交接”不会改变已生成的工具 schema；也不需要先怀疑 API 密钥或网络连接。

用合法标识路由，把显示文字放进描述

在团队内部，target 应与接收方 Agent 的 name 一致。这个版本的普通聊天 Agent 名称也要求有效的 Python 标识符，不能为了保留界面上的“Support Desk”，直接把带空格的文字当作 Agent 名。

下面给出一个完整的团队构造函数。model_client 由应用传入，需支持工具调用；函数只构建对象，不启动会话，也不关闭调用方的客户端：

from autogen_core.models import ChatCompletionClient
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.base import Handoff
from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)
from autogen_agentchat.teams import Swarm

def build_support_team(model_client: ChatCompletionClient) -> Swarm:
    support_name = "support_desk"
    route = Handoff(
        target=support_name,
        name="transfer_to_support_desk",
        description="Transfer the request to Support Desk.",
    )
    triage = AssistantAgent(
        name="triage",
        model_client=model_client,
        handoffs=[route],
        system_message="Transfer support requests to support_desk.",
    )
    support = AssistantAgent(
        name=support_name,
        model_client=model_client,
        description="Support Desk handles support requests.",
        system_message=(
            "Answer the support request. "
            "When the answer is complete, finish with DONE."
        ),
    )
    stop = (
        TextMentionTermination("DONE", sources=[support_name])
        | MaxMessageTermination(8)
    )
    return Swarm([triage, support], termination_condition=stop)

这里界面可继续显示“Support Desk”，但路由使用 support_desk，工具使用 transfer_to_support_desk。三者用途清楚，接收方也确实出现在团队参与者中。终止词和八条消息上限是示例设置，需要按实际业务调整；构造成功不证明模型一定会交接或完整答复。

如果目标属于外部用户而非团队 Agent，应按应用的人工交接流程设计停止与恢复，不把这个内部参与者示例直接照搬。若保存后再加载上面的终止条件，还要核对来源限制是否保留；它不能因为本次修正了工具名就被忽略。

检查长度、重名，再检查实际交接

自定义 Handoff.name 的 Python 标识符检查与模型客户端的规则并不完全相同。例如某些非 ASCII 名称可以是 Python 标识符，仍会被该 OpenAI 客户端拒绝；反过来，也不能把客户端允许的连字符直接当成自定义 Handoff 一定接受的名称。选择短的 ASCII 标识符，并同时满足两边规则。

同一个 Agent 的多个交接工具不能重名，也不能与普通工具冲突。自动替换非法字符时，两个不同显示名称可能变成相同的工具名，因此批量规范化以后仍需检查唯一性。仅截断超长名称也可能制造冲突。

验收顺序是：生成的工具 schema 名称合格，运行时不再出现名称转换异常，交接消息的 target 与实际接收方相符，接收方确实继续处理任务。不要只验证异常消失，就把交接认作成功。改名也会影响已有交接消息、持久化会话或配置里的目标标识，迁移前应保留原配置并核对这些引用。

0.7.5 的默认名称路径仍有这个限制。不能仅因存在修正代码就认定已经进入可安装版本；升级时应核对目标版本的实际行为。回退配置时恢复相互匹配的 Agent 名称、交接目标和工具名称，不能只恢复界面显示文字。