feat: Support static instructions

Static instructions:
Always added to system instructions for context caching

Dynamic instructions:
Added to system instructions when no static instruction exists (for backward compatibility), OR inserted before last batch of continuous user content when static instructions exist

PiperOrigin-RevId: 809170679

Author: seanzhougoogle

src/google/adk/agents/llm_agent.py

@@ -134,7 +134,18 @@ class LlmAgent(BaseAgent):
   """The config type for this agent."""
 
   instruction: Union[str, InstructionProvider] = ''
-  """Instructions for the LLM model, guiding the agent's behavior."""
+  """Dynamic instructions for the LLM model, guiding the agent's behavior.
+
+  These instructions can contain placeholders like {variable_name} that will be
+  resolved at runtime using session state and context.
+
+  **Behavior depends on static_instruction:**
+  - If static_instruction is None: instruction goes to system_instruction
+  - If static_instruction is set: instruction goes to user content in the request
+
+  This allows for context caching optimization where static content (static_instruction)
+  comes first in the prompt, followed by dynamic content (instruction).
+  """
 
   global_instruction: Union[str, InstructionProvider] = ''
   """Instructions for all the agents in the entire agent tree.
@@ -145,6 +156,48 @@ class LlmAgent(BaseAgent):
   or personality.
   """
 
+  static_instruction: Optional[types.Content] = 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.
+  It's sent directly to the model without any processing or variable substitution.
+
+  This field is primarily for context caching optimization. Static instructions
+  are sent as system instruction at the beginning of the request, allowing
+  for improved performance when the static portion remains unchanged. Live API
+  has its own cache mechanism, thus this field doesn't work with Live API.
+
+  **Impact on instruction field:**
+  - When static_instruction is None: instruction → system_instruction
+  - When static_instruction is set: instruction → user content (after static content)
+
+  **Context Caching:**
+  - **Implicit Cache**: Automatic caching by model providers (no config needed)
+  - **Explicit Cache**: Cache explicitly created by user for instructions, tools and contents
+
+  See below for more information of Implicit Cache and Explicit Cache
+  Gemini API: https://ai.google.dev/gemini-api/docs/caching?lang=python
+  Vertex API: https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview
+
+  Setting static_instruction alone does NOT enable caching automatically.
+  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:**
+  ```python
+  static_instruction = types.Content(
+      role='user',
+      parts=[
+          types.Part(text='You are a helpful assistant.'),
+          types.Part(file_data=types.FileData(...))
+      ]
+  )
+  ```
+  """
+
   tools: list[ToolUnion] = Field(default_factory=list)
   """Tools available to this agent."""
 
@@ -462,9 +515,7 @@ def __maybe_save_output_to_state(self, event: Event):
     ):
 
       result = ''.join(
-          part.text
-          for part in event.content.parts
-          if part.text and not part.thought
+          [part.text if part.text else '' for part in event.content.parts]
       )
       if self.output_schema:
         # If the result from the final chunk is just whitespace or empty,
@@ -600,6 +651,8 @@ def _parse_config(
       kwargs['model'] = config.model
     if config.instruction:
       kwargs['instruction'] = config.instruction
+    if config.static_instruction:
+      kwargs['static_instruction'] = config.static_instruction
     if config.disallow_transfer_to_parent:
       kwargs['disallow_transfer_to_parent'] = config.disallow_transfer_to_parent
     if config.disallow_transfer_to_peers:

src/google/adk/agents/llm_agent_config.py

@@ -53,7 +53,25 @@ class LlmAgentConfig(BaseAgentConfig):
       ),
   )
 
-  instruction: str = Field(description='Required. LlmAgent.instruction.')
+  instruction: str = Field(
+      description=(
+          'Required. LlmAgent.instruction. Dynamic instructions with'
+          ' placeholder support. Behavior: if static_instruction is None, goes'
+          ' to system_instruction; if static_instruction is set, goes to user'
+          ' content after static content.'
+      )
+  )
+
+  static_instruction: Optional[types.Content] = 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).'
+      ),
+  )
 
   disallow_transfer_to_parent: Optional[bool] = Field(
       default=None,

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

@@ -58,6 +58,11 @@ async def run_async(
           agent.name,
       )
 
+    # Add dynamic instructions to the last user content if static instructions exist
+    await _add_dynamic_instructions_to_user_content(
+        invocation_context, llm_request
+    )
+
     # Maintain async generator behavior
     if False:  # Ensures it behaves as a generator
       yield  # This is a no-op but maintains generator structure
@@ -557,3 +562,49 @@ def _is_live_model_audio_event(event: Event) -> bool:
     if part.file_data and part.file_data.mime_type == 'audio/pcm':
       return True
   return False
+
+
+async def _add_dynamic_instructions_to_user_content(
+    invocation_context: InvocationContext, llm_request: LlmRequest
+) -> None:
+  """Add dynamic instructions to the last user content when static instructions exist."""
+  from ...agents.readonly_context import ReadonlyContext
+  from ...utils import instructions_utils
+
+  agent = invocation_context.agent
+
+  dynamic_instructions = []
+
+  # Handle agent dynamic instructions if static instruction exists
+  if agent.static_instruction and agent.instruction:
+    # Static instruction exists, so add dynamic instruction to content
+    raw_si, bypass_state_injection = await agent.canonical_instruction(
+        ReadonlyContext(invocation_context)
+    )
+    si = raw_si
+    if not bypass_state_injection:
+      si = await instructions_utils.inject_session_state(
+          raw_si, ReadonlyContext(invocation_context)
+      )
+    if si:  # Only add if not empty
+      dynamic_instructions.append(si)
+
+  if not dynamic_instructions:
+    return
+
+  # Find the start of the last continuous batch of user content
+  # Walk backwards to find the first non-user content, then insert before next user content
+  insert_index = len(llm_request.contents)
+  for i in range(len(llm_request.contents) - 1, -1, -1):
+    if llm_request.contents[i].role != 'user':
+      insert_index = i + 1
+      break
+    elif i == 0:
+      # All content from start is user content
+      insert_index = 0
+      break
+
+  # Create new user content with dynamic instructions
+  instruction_parts = [types.Part(text=instr) for instr in dynamic_instructions]
+  new_content = types.Content(role='user', parts=instruction_parts)
+  llm_request.contents.insert(insert_index, new_content)

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

@@ -16,16 +16,13 @@
 
 from __future__ import annotations
 
-import re
 from typing import AsyncGenerator
-from typing import Generator
 from typing import TYPE_CHECKING
 
 from typing_extensions import override
 
 from ...agents.readonly_context import ReadonlyContext
 from ...events.event import Event
-from ...sessions.state import State
 from ...utils import instructions_utils
 from ._base_llm_processor import BaseLlmRequestProcessor
 
@@ -50,10 +47,8 @@ async def run_async(
 
     root_agent: BaseAgent = agent.root_agent
 
-    # Appends global instructions if set.
-    if (
-        isinstance(root_agent, LlmAgent) and root_agent.global_instruction
-    ):  # not empty str
+    # Handle global instructions
+    if isinstance(root_agent, LlmAgent) and root_agent.global_instruction:
       raw_si, bypass_state_injection = (
           await root_agent.canonical_global_instruction(
               ReadonlyContext(invocation_context)
@@ -66,8 +61,14 @@ async def run_async(
         )
       llm_request.append_instructions([si])
 
-    # Appends agent instructions if set.
-    if agent.instruction:  # not empty str
+    # Handle static_instruction - add via append_instructions
+    if agent.static_instruction:
+      llm_request.append_instructions(agent.static_instruction)
+
+    # Handle instruction based on whether static_instruction exists
+    if agent.instruction and not agent.static_instruction:
+      # Only add to system instructions if no static instruction exists
+      # If static instruction exists, content processor will handle it
       raw_si, bypass_state_injection = await agent.canonical_instruction(
           ReadonlyContext(invocation_context)
       )
@@ -79,8 +80,8 @@ async def run_async(
       llm_request.append_instructions([si])
 
     # Maintain async generator behavior
-    if False:  # Ensures it behaves as a generator
-      yield  # This is a no-op but maintains generator structure
+    return
+    yield  # This line ensures it behaves as a generator but is never reached
 
 
 request_processor = _InstructionsLlmRequestProcessor()

src/google/adk/models/llm_request.py

@@ -14,7 +14,9 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Optional
+from typing import Union
 
 from google.genai import types
 from pydantic import BaseModel
@@ -86,17 +88,73 @@ class LlmRequest(BaseModel):
   cache_metadata: Optional[CacheMetadata] = None
   """Cache metadata from previous requests, used for cache management."""
 
-  def append_instructions(self, instructions: list[str]) -> None:
+  def append_instructions(
+      self, instructions: Union[list[str], types.Content]
+  ) -> None:
     """Appends instructions to the system instruction.
 
     Args:
-      instructions: The instructions to append.
+      instructions: The instructions to append. Can be:
+        - list[str]: Strings to append/concatenate to system instruction
+        - types.Content: Content object to append to system instruction
+
+    Note: Only text content is supported. Model API requires system_instruction
+    to be a string. Non-text parts in Content will be handled differently.
+
+    Behavior:
+      - list[str]: concatenates with existing system_instruction using \\n\\n
+      - types.Content: extracts text from parts and concatenates
     """
 
-    if self.config.system_instruction:
-      self.config.system_instruction += '\n\n' + '\n\n'.join(instructions)
-    else:
-      self.config.system_instruction = '\n\n'.join(instructions)
+    # Handle Content object - extract only text parts
+    if isinstance(instructions, types.Content):
+      # TODO: Handle non-text contents in instruction by putting non-text parts
+      # into llm_request.contents and adding a reference in the system instruction
+      # that references the contents.
+
+      # Extract text from all text parts
+      text_parts = [part.text for part in instructions.parts if part.text]
+
+      if not text_parts:
+        return  # No text content to append
+
+      new_text = "\n\n".join(text_parts)
+      if not self.config.system_instruction:
+        self.config.system_instruction = new_text
+      elif isinstance(self.config.system_instruction, str):
+        self.config.system_instruction += "\n\n" + new_text
+      else:
+        # Log warning for unsupported system_instruction types
+        logging.warning(
+            "Cannot append to system_instruction of unsupported type: %s. "
+            "Only string system_instruction is supported.",
+            type(self.config.system_instruction),
+        )
+      return
+
+    # Handle list of strings
+    if isinstance(instructions, list) and all(
+        isinstance(inst, str) for inst in instructions
+    ):
+      if not instructions:  # Handle empty list
+        return
+
+      new_text = "\n\n".join(instructions)
+      if not self.config.system_instruction:
+        self.config.system_instruction = new_text
+      elif isinstance(self.config.system_instruction, str):
+        self.config.system_instruction += "\n\n" + new_text
+      else:
+        # Log warning for unsupported system_instruction types
+        logging.warning(
+            "Cannot append to system_instruction of unsupported type: %s. "
+            "Only string system_instruction is supported.",
+            type(self.config.system_instruction),
+        )
+      return
+
+    # Invalid input
+    raise TypeError("instructions must be list[str] or types.Content")
 
   def append_tools(self, tools: list[BaseTool]) -> None:
     """Appends tools to the request.
@@ -138,4 +196,4 @@ def set_output_schema(self, base_model: type[BaseModel]) -> None:
     """
 
     self.config.response_schema = base_model
-    self.config.response_mime_type = 'application/json'
+    self.config.response_mime_type = "application/json"