docs(adk): add NOT RECOMMENDED advisory to agent transfer and workflow APIs

[shentongmartin]

Summary

Problem	Impact	Fix
Agent transfer / workflow agent APIs lack guidance on recommended alternatives	Users may adopt transfer-based patterns without knowing simpler alternatives exist	Add NOT RECOMMENDED: advisory comments to all transfer/workflow exported APIs

Key Insight

Agent transfer with full context sharing between agents has not proven to be more effective empirically. The recommended patterns are ChatModelAgent with AgentTool or DeepAgent. Rather than formally deprecating these APIs (which triggers IDE strikethroughs and linter warnings), we use a NOT RECOMMENDED: advisory — stronger than NOTE: but softer than Deprecated: — to guide users without breaking existing code or tooling.

What Changed

Added NOT RECOMMENDED: doc comments to ~25 exported APIs across 9 files in the adk package:

Core transfer APIs (flow.go, interface.go, deterministic_transfer.go):

• SetSubAgents, AgentWithOptions, AgentWithDeterministicTransferTo
• WithDisallowTransferToParent, WithHistoryRewriter, AgentOption
• HistoryEntry, HistoryRewriter, DeterministicTransferConfig
• TransferToAgentAction, NewTransferToAgentAction, NewExitAction
• RunStep, RunPath field, OnSubAgents interface

ChatModelAgent transfer fields (chatmodel.go):

• Exit field, OutputKey field, ExitTool type
• OnSetSubAgents, OnSetAsSubAgent, OnDisallowTransferToParent

Workflow agents (workflow.go):

• SequentialAgentConfig, ParallelAgentConfig, LoopAgentConfig
• NewSequentialAgent, NewParallelAgent, NewLoopAgent
• BreakLoopAction, NewBreakLoopAction, WorkflowInterruptInfo

Helpers (utils.go, call_option.go, interrupt.go):

• GenTransferMessages, WithSkipTransferMessages

Prebuilt agents (supervisor/, planexecute/):

• supervisor.Config, supervisor.New
• planexecute.Config, planexecute.New

Also includes a minor formatting fix for struct field alignment in compose/graph_run.go (drift from prior FromGraphInterrupt removal).

Test Results

All existing tests pass with -race — no behavioral changes, comment-only updates.

---

概要

问题	影响	修复
Agent Transfer / Workflow Agent 相关 API 缺少推荐替代方案的引导	用户可能在不了解更简单替代方案的情况下采用 transfer 模式	为所有 transfer/workflow 导出 API 添加 NOT RECOMMENDED: 建议性注释

核心思路

Agent Transfer 及其全上下文共享模式在实践中并未被证明更有效。推荐使用 ChatModelAgent + AgentTool 或 DeepAgent。我们没有使用正式的 Deprecated: 标记（会触发 IDE 删除线和 linter 警告），而是选择 NOT RECOMMENDED: —— 比 NOTE: 更强，但比 Deprecated: 更温和 —— 在不影响现有代码和工具链的前提下引导用户。

变更内容

在 adk 包的 9 个文件中为约 25 个导出 API 添加了 NOT RECOMMENDED: 文档注释，覆盖核心 transfer API、ChatModelAgent transfer 字段、Workflow Agent、辅助函数以及预构建 Agent（Supervisor、PlanExecute）。

同时修复了 compose/graph_run.go 中因先前移除 FromGraphInterrupt 字段导致的结构体对齐问题。

测试结果

所有现有测试通过 -race 检测 —— 仅注释变更，无行为变化。

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (alpha/09@dcc5658). Learn more about missing BASE report.

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #970   +/-   ##
===========================================
  Coverage            ?   82.26%           
===========================================
  Files               ?      162           
  Lines               ?    20589           
  Branches            ?        0           
===========================================
  Hits                ?    16938           
  Misses              ?     2458           
  Partials            ?     1193           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.