feat: Support ContentUnion as static instruction

PiperOrigin-RevId: 817278990

Author: seanzhougoogle

src/google/adk/agents/llm_agent.py

@@ -196,7 +196,7 @@ class LlmAgent(BaseAgent):
  or personality.
  """
 
- static_instruction: Optional[types.Content] = None
+ static_instruction: Optional[types.ContentUnion] = None
  """Static instruction content sent literally as system instruction at the beginning.
 
  This field is for content that never changes and doesn't contain placeholders.
@@ -223,11 +223,20 @@ class LlmAgent(BaseAgent):
  For explicit caching control, configure context_cache_config at App level.
 
  **Content Support:**
- Can contain text, files, binaries, or any combination as types.Content
- supports multiple part types (text, inline_data, file_data, etc.).
-
- **Example:**
+ Accepts types.ContentUnion which includes:
+ - str: Simple text instruction
+ - types.Content: Rich content object
+ - types.Part: Single part (text, inline_data, file_data, etc.)
+ - PIL.Image.Image: Image object
+ - types.File: File reference
+ - list[PartUnion]: List of parts
+
+ **Examples:**
  ```python
+ # Simple string instruction
+ static_instruction = "You are a helpful assistant."
+
+ # Rich content with files
  static_instruction = types.Content(
  role='user',
  parts=[

src/google/adk/agents/llm_agent_config.py

@@ -35,6 +35,10 @@ class LlmAgentConfig(BaseAgentConfig):
 
  model_config = ConfigDict(
  extra='forbid',
+ # Allow arbitrary types to support types.ContentUnion for static_instruction.
+ # ContentUnion includes PIL.Image.Image which doesn't have Pydantic schema
+ # support, but we validate it at runtime using google.genai._transformers.t_content()
+ arbitrary_types_allowed=True,
  )
 
  agent_class: str = Field(
@@ -62,14 +66,15 @@ class LlmAgentConfig(BaseAgentConfig):
  )
  )
 
- static_instruction: Optional[types.Content] = Field(
+ static_instruction: Optional[types.ContentUnion] = Field(
  default=None,
  description=(
  'Optional. LlmAgent.static_instruction. Static content sent literally'
  ' at position 0 without placeholder processing. When set, changes'
  ' instruction behavior to go to user content instead of'
- ' system_instruction. Supports context caching and rich content'
- ' (text, files, binaries).'
+ ' system_instruction. Supports context caching. Accepts'
+ ' types.ContentUnion (str, types.Content, types.Part,'
+ ' PIL.Image.Image, types.File, or list[PartUnion]).'
  ),
  )
 

src/google/adk/flows/llm_flows/instructions.py

@@ -19,6 +19,7 @@
 from typing import AsyncGenerator
 from typing import TYPE_CHECKING
 
+from google.genai import _transformers
 from typing_extensions import override
 
 from ...agents.readonly_context import ReadonlyContext
@@ -84,7 +85,9 @@ async def run_async(
 
  # Handle static_instruction - add via append_instructions
  if agent.static_instruction:
- llm_request.append_instructions(agent.static_instruction)
+ # Convert ContentUnion to Content using genai transformer
+ static_content = _transformers.t_content(agent.static_instruction)
+ llm_request.append_instructions(static_content)
 
  # Handle instruction based on whether static_instruction exists
  if agent.instruction and not agent.static_instruction:

tests/unittests/flows/llm_flows/test_instructions.py

@@ -551,6 +551,56 @@ def test_static_instruction_field_exists(llm_backend):
  assert agent.static_instruction == static_content
 
 
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+def test_static_instruction_supports_string(llm_backend):
+ """Test that static_instruction field supports simple strings."""
+ static_str = "This is a static instruction as a string"
+ agent = LlmAgent(name="test_agent", static_instruction=static_str)
+ assert agent.static_instruction == static_str
+ assert isinstance(agent.static_instruction, str)
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+def test_static_instruction_supports_part(llm_backend):
+ """Test that static_instruction field supports types.Part."""
+ static_part = types.Part(text="This is a static instruction as Part")
+ agent = LlmAgent(name="test_agent", static_instruction=static_part)
+ assert agent.static_instruction == static_part
+ assert isinstance(agent.static_instruction, types.Part)
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+def test_static_instruction_supports_file(llm_backend):
+ """Test that static_instruction field supports types.File."""
+ static_file = types.File(uri="gs://bucket/file.txt", mime_type="text/plain")
+ agent = LlmAgent(name="test_agent", static_instruction=static_file)
+ assert agent.static_instruction == static_file
+ assert isinstance(agent.static_instruction, types.File)
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+def test_static_instruction_supports_list_of_parts(llm_backend):
+ """Test that static_instruction field supports list[PartUnion]."""
+ static_parts_list = [
+ types.Part(text="First part"),
+ types.Part(text="Second part"),
+ ]
+ agent = LlmAgent(name="test_agent", static_instruction=static_parts_list)
+ assert agent.static_instruction == static_parts_list
+ assert isinstance(agent.static_instruction, list)
+ assert len(agent.static_instruction) == 2
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+def test_static_instruction_supports_list_of_strings(llm_backend):
+ """Test that static_instruction field supports list of strings."""
+ static_strings_list = ["First instruction", "Second instruction"]
+ agent = LlmAgent(name="test_agent", static_instruction=static_strings_list)
+ assert agent.static_instruction == static_strings_list
+ assert isinstance(agent.static_instruction, list)
+ assert all(isinstance(s, str) for s in agent.static_instruction)
+
+
 @pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
 def test_static_instruction_supports_multiple_parts(llm_backend):
  """Test that static_instruction supports multiple parts including files."""
@@ -607,6 +657,91 @@ async def test_static_instruction_added_to_contents(llm_backend):
  assert llm_request.config.system_instruction == "Static instruction content"
 
 
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+@pytest.mark.asyncio
+async def test_static_instruction_string_added_to_system(llm_backend):
+ """Test that string static instructions are added to system_instruction."""
+ agent = LlmAgent(
+ name="test_agent", static_instruction="Static instruction as string"
+ )
+
+ invocation_context = await _create_invocation_context(agent)
+
+ llm_request = LlmRequest()
+
+ # Run the instruction processor
+ async for _ in request_processor.run_async(invocation_context, llm_request):
+ pass
+
+ # Static instruction should be added to system instructions, not contents
+ assert len(llm_request.contents) == 0
+ assert llm_request.config.system_instruction == "Static instruction as string"
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+@pytest.mark.asyncio
+async def test_static_instruction_part_converted_to_system(llm_backend):
+ """Test that Part static instructions are converted and added to system_instruction."""
+ static_part = types.Part(text="Static instruction from Part")
+ agent = LlmAgent(name="test_agent", static_instruction=static_part)
+
+ invocation_context = await _create_invocation_context(agent)
+ llm_request = LlmRequest()
+
+ # Run the instruction processor
+ async for _ in request_processor.run_async(invocation_context, llm_request):
+ pass
+
+ # Part should be converted to Content and text extracted to system instruction
+ assert llm_request.config.system_instruction == "Static instruction from Part"
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+@pytest.mark.asyncio
+async def test_static_instruction_list_of_parts_converted_to_system(
+ llm_backend,
+):
+ """Test that list of Parts is converted and added to system_instruction."""
+ static_parts_list = [
+ types.Part(text="First part"),
+ types.Part(text="Second part"),
+ ]
+ agent = LlmAgent(name="test_agent", static_instruction=static_parts_list)
+
+ invocation_context = await _create_invocation_context(agent)
+ llm_request = LlmRequest()
+
+ # Run the instruction processor
+ async for _ in request_processor.run_async(invocation_context, llm_request):
+ pass
+
+ # List of parts should be converted to Content with text extracted
+ assert llm_request.config.system_instruction == "First part\n\nSecond part"
+
+
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+@pytest.mark.asyncio
+async def test_static_instruction_list_of_strings_converted_to_system(
+ llm_backend,
+):
+ """Test that list of strings is converted and added to system_instruction."""
+ static_strings_list = ["First instruction", "Second instruction"]
+ agent = LlmAgent(name="test_agent", static_instruction=static_strings_list)
+
+ invocation_context = await _create_invocation_context(agent)
+ llm_request = LlmRequest()
+
+ # Run the instruction processor
+ async for _ in request_processor.run_async(invocation_context, llm_request):
+ pass
+
+ # List of strings should be converted to Content with text extracted
+ assert (
+ llm_request.config.system_instruction
+ == "First instruction\n\nSecond instruction"
+ )
+
+
 @pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
 @pytest.mark.asyncio
 async def test_dynamic_instruction_without_static_goes_to_system(llm_backend):
@@ -658,6 +793,36 @@ async def test_dynamic_instruction_with_static_not_in_system(llm_backend):
  assert llm_request.contents[0].parts[0].text == "Dynamic instruction content"
 
 
+@pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
+@pytest.mark.asyncio
+async def test_dynamic_instruction_with_string_static_not_in_system(
+ llm_backend,
+):
+ """Test that dynamic instructions go to user content when string static_instruction exists."""
+ agent = LlmAgent(
+ name="test_agent",
+ instruction="Dynamic instruction content",
+ static_instruction="Static instruction as string",
+ )
+
+ invocation_context = await _create_invocation_context(agent)
+
+ llm_request = LlmRequest()
+
+ # Run the instruction processor
+ async for _ in request_processor.run_async(invocation_context, llm_request):
+ pass
+
+ # Static instruction should be in system instructions
+ assert llm_request.config.system_instruction == "Static instruction as string"
+
+ # Dynamic instruction should be added as user content
+ assert len(llm_request.contents) == 1
+ assert llm_request.contents[0].role == "user"
+ assert len(llm_request.contents[0].parts) == 1
+ assert llm_request.contents[0].parts[0].text == "Dynamic instruction content"
+
+
 @pytest.mark.parametrize("llm_backend", ["GOOGLE_AI", "VERTEX"])
 @pytest.mark.asyncio
 async def test_dynamic_instructions_added_to_user_content(llm_backend):