refactor(agents): move InstructionProvider alias into instructions_utils

Move the InstructionProvider type alias out of llm_agent.py into the
existing utils/instructions_utils.py module, and re-export it from
llm_agent so existing imports (and the public API) are unaffected. This
lets other agents (e.g. ManagedAgent) reuse the alias without importing
the heavy llm_agent module, and colocates it with inject_session_state,
the helper that consumes an InstructionProvider's output.

Co-authored-by: Haran Rajkumar <haranrk@google.com>
PiperOrigin-RevId: 951007235

Author: haranrk

src/google/adk/agents/llm_agent.py

@@ -59,6 +59,7 @@
 from ..utils._schema_utils import SchemaType
 from ..utils._schema_utils import validate_schema
 from ..utils.context_utils import Aclosing
+from ..utils.instructions_utils import InstructionProvider as InstructionProvider
 from .base_agent import BaseAgent
 from .base_agent import BaseAgentState
 from .base_agent_config import BaseAgentConfig as BaseAgentConfig
@@ -130,9 +131,6 @@
     list[_SingleOnToolErrorCallback],
 ]
 
-InstructionProvider: TypeAlias = Callable[
-    [ReadonlyContext], Union[str, Awaitable[str]]
-]
 ToolUnion: TypeAlias = Union[Callable, BaseTool, BaseToolset]
 
 

src/google/adk/utils/instructions_utils.py

@@ -16,16 +16,28 @@
 
 import logging
 import re
+from typing import Awaitable
+from typing import Callable
+from typing import Union
+
+from typing_extensions import TypeAlias
 
 from ..agents.readonly_context import ReadonlyContext
 from ..sessions.state import State
 
 __all__ = [
+    'InstructionProvider',
     'inject_session_state',
 ]
 
 logger = logging.getLogger('google_adk.' + __name__)
 
+# Type alias for agent instruction providers: a callable that receives a
+# ReadonlyContext and returns an instruction string (sync or async).
+InstructionProvider: TypeAlias = Callable[
+    [ReadonlyContext], Union[str, Awaitable[str]]
+]
+
 
 async def inject_session_state(
     template: str,

tests/unittests/utils/test_instructions_utils.py

@@ -13,9 +13,11 @@
 # limitations under the License.
 
 from google.adk.agents.llm_agent import Agent
+from google.adk.agents.llm_agent import InstructionProvider as LlmAgentInstructionProvider
 from google.adk.agents.readonly_context import ReadonlyContext
 from google.adk.sessions.session import Session
 from google.adk.utils import instructions_utils
+from google.adk.utils.instructions_utils import InstructionProvider
 import pytest
 
 from .. import testing_utils
@@ -280,3 +282,13 @@ async def test_inject_session_state_with_optional_missing_state_returns_empty():
       instruction_template, invocation_context
   )
   assert populated_instruction == "Optional value: "
+
+
+def test_module_exposes_instruction_provider_alias():
+  assert instructions_utils.InstructionProvider is InstructionProvider
+
+
+def test_llm_agent_reexports_same_instruction_provider():
+  # Existing importers rely on `from ...llm_agent import InstructionProvider`;
+  # it must remain the exact same object after moving the alias here.
+  assert LlmAgentInstructionProvider is InstructionProvider