openai-agents 0.2.4，主 agent 配了 handoffs=[billing_agent]，运行到转交时报 handoff 目标没有注册，billing_agent 是另一个模块里新建的实例。
原因不止一个，得分开看。handoffs 里传的是 agent 名字而不是实例；两个 agent 分属不同 Runner，上下文没有共享；handoff 的 input_filter 抛异常被当成注册失败；SDK 升级后 handoffs 参数改成了 handoff。
动手时先打印主 agent 的 handoffs 配置
python -c "from app.agents import triage;print(triage.handoffs)"然后确认目标 agent 能独立运行
python -c "from app.agents import billing;from agents import Runner;print(Runner.run_sync(billing,'退款').final_output)"接着用同一 Runner 跑主 agent
python -c "from app.agents import triage;from agents import Runner;print(Runner.run_sync(triage,'退款').final_output)"剩下的就是看日志里的 handoff 事件
grep -i handoff app.log | tail -5白天有业务在跑，能验证的部分都压到了晚上做。
当时还开着另一个排查窗口，两边日志对照着看才定位到。
同一份数据我导出了两份，一份留底，一份拿来试。
这类问题以前遇到过，但这次的触发条件和上次不一样。
改完先别撤，确认这几项。主 agent 能把请求转给 billing，最终输出带退款单号，日志里能看到一次 handoff 事件。
提醒一点。handoff 是对象引用不是名字路由，跨模块共享 agent 实例比共享名字可靠。监控比日志更早给出信号，事后回看经常能提前半小时发现异常。