fix: correct misleading workflow-agent deprecation messages

SequentialAgent, LoopAgent, and ParallelAgent were deprecated in favor of
Workflow, but Workflow is not a BaseAgent and cannot be used as an LlmAgent
sub_agent, so "use Workflow instead" is incomplete for the sub-agent
composition pattern. Keep recommending Workflow for orchestration, but state
the sub-agent limitation directly in the deprecation message.

Relates to #5872.

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 943529799

Author: GWeale

src/google/adk/agents/loop_agent.py

@@ -51,8 +51,8 @@ class LoopAgentState(BaseAgentState):
 
 
 @deprecated(
-    'LoopAgent is deprecated and will be removed in future versions.'
-    ' Please use Workflow instead.'
+    'LoopAgent is deprecated in favor of Workflow and will be removed in a'
+    ' future version. Workflow cannot yet be used as an LlmAgent sub-agent.'
 )
 class LoopAgent(BaseAgent):
   """A shell agent that run its sub-agents in a loop.
@@ -61,8 +61,8 @@ class LoopAgent(BaseAgent):
   reached, the loop agent will stop.
 
   .. deprecated::
-    LoopAgent is deprecated and will be removed in future versions.
-    Please use Workflow instead.
+    LoopAgent is deprecated in favor of Workflow and will be removed in a
+    future version. Workflow cannot yet be used as an LlmAgent sub-agent.
   """
 
   config_type: ClassVar[type[BaseAgentConfig]] = LoopAgentConfig

src/google/adk/agents/parallel_agent.py

@@ -158,8 +158,8 @@ async def process_an_agent(events_for_one_agent):
 
 
 @deprecated(
-    'ParallelAgent is deprecated and will be removed in future versions.'
-    ' Please use Workflow instead.'
+    'ParallelAgent is deprecated in favor of Workflow and will be removed in'
+    ' a future version. Workflow cannot yet be used as an LlmAgent sub-agent.'
 )
 class ParallelAgent(BaseAgent):
   """A shell agent that runs its sub-agents in parallel in an isolated manner.
@@ -171,8 +171,8 @@ class ParallelAgent(BaseAgent):
   - Generating multiple responses for review by a subsequent evaluation agent.
 
   .. deprecated::
-    ParallelAgent is deprecated and will be removed in future versions.
-    Please use Workflow instead.
+    ParallelAgent is deprecated in favor of Workflow and will be removed in a
+    future version. Workflow cannot yet be used as an LlmAgent sub-agent.
   """
 
   config_type: ClassVar[type[BaseAgentConfig]] = ParallelAgentConfig

src/google/adk/agents/sequential_agent.py

@@ -47,15 +47,16 @@ class SequentialAgentState(BaseAgentState):
 
 
 @deprecated(
-    'SequentialAgent is deprecated and will be removed in future versions.'
-    ' Please use Workflow instead.'
+    'SequentialAgent is deprecated in favor of Workflow and will be removed'
+    ' in a future version. Workflow cannot yet be used as an LlmAgent'
+    ' sub-agent.'
 )
 class SequentialAgent(BaseAgent):
   """A shell agent that runs its sub-agents in sequence.
 
   .. deprecated::
-    SequentialAgent is deprecated and will be removed in future versions.
-    Please use Workflow instead.
+    SequentialAgent is deprecated in favor of Workflow and will be removed in
+    a future version. Workflow cannot yet be used as an LlmAgent sub-agent.
   """
 
   config_type: ClassVar[Type[BaseAgentConfig]] = SequentialAgentConfig

tests/unittests/agents/test_loop_agent.py

@@ -285,3 +285,8 @@ def mock_should_pause(event):
   # Verify that the sub-agent state was NOT reset
   assert agent.name in parent_ctx.agent_states
   assert parent_ctx.agent_states[agent.name] == {'some_key': 'some_value'}
+
+
+def test_deprecation_mentions_sub_agent_limitation():
+  with pytest.warns(DeprecationWarning, match='sub-agent'):
+    LoopAgent(name='deprecated_loop', sub_agents=[])

tests/unittests/agents/test_parallel_agent.py

@@ -409,3 +409,8 @@ async def test_merge_agent_run_pre_3_11_no_aclose_error_on_failure():
   # would raise RuntimeError here.
   for agen in agent_runs:
     await agen.aclose()
+
+
+def test_deprecation_mentions_sub_agent_limitation():
+  with pytest.warns(DeprecationWarning, match='sub-agent'):
+    ParallelAgent(name='deprecated_parallel', sub_agents=[])

tests/unittests/agents/test_sequential_agent.py

@@ -201,3 +201,8 @@ async def test_run_live(request: pytest.FixtureRequest):
   assert events[1].author == agent_2.name
   assert events[0].content.parts[0].text == f'Hello, live {agent_1.name}!'
   assert events[1].content.parts[0].text == f'Hello, live {agent_2.name}!'
+
+
+def test_deprecation_mentions_sub_agent_limitation():
+  with pytest.warns(DeprecationWarning, match='sub-agent'):
+    SequentialAgent(name='deprecated_sequential', sub_agents=[])