Merge branch 'main' into fix/support-opentelemetry-1.43.0

Author: rohityan

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -45,15 +45,15 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: '3.11'
 
       - name: Load adk-bot SSH Private Key
-        uses: webfactory/ssh-agent@v0.9.1
+        uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1
         with:
           ssh-private-key: ${{ secrets.ADK_BOT_SSH_PRIVATE_KEY }}
 
@@ -64,7 +64,7 @@ jobs:
 
       - name: Restore session DB from cache
         if: ${{ github.event.inputs.resume == 'true' }}
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
           key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}
@@ -102,7 +102,7 @@ jobs:
 
       - name: Save session DB to cache
         if: always()
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
           key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}

.github/workflows/release-finalize.yml

@@ -59,7 +59,7 @@ jobs:
             echo "manifest_file=.github/.release-please-manifest.json" >> $GITHUB_OUTPUT
           fi
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         if: steps.check.outputs.is_release_pr == 'true'
         with:
           ref: ${{ github.event.pull_request.base.ref }}

.github/workflows/release-update-adk-web.yaml

@@ -36,7 +36,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
       with:
         persist-credentials: false
 
@@ -78,7 +78,7 @@ jobs:
         echo "email=$(echo "$USER_JSON" | jq -r '.id')+$(echo "$USER_JSON" | jq -r '.login')@users.noreply.github.com" >> $GITHUB_OUTPUT
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v6
+      uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6
       with:
         token: ${{ secrets.RELEASE_PAT }}
         commit-message: "Update compiled adk web files from ${{ github.event.inputs.adk_web_repo }}@${{ github.event.inputs.adk_web_tag || 'latest' }}"

src/google/adk/agents/_managed_agent.py

@@ -51,6 +51,8 @@
 from ..utils.content_utils import to_user_content
 from ..utils.context_utils import Aclosing
 from ..utils.env_utils import is_enterprise_mode_enabled
+from ..utils.instructions_utils import inject_session_state
+from ..utils.instructions_utils import InstructionProvider
 from .base_agent import BaseAgent
 from .context import Context
 from .invocation_context import InvocationContext
@@ -144,6 +146,16 @@ class ManagedAgent(BaseAgent):
   agent_config: Optional[CreateAgentInteractionAgentConfigParam] = None
   """Runtime configuration passed to interactions.create."""
 
+  instruction: Union[str, InstructionProvider] = ''
+  """The system instruction sent to the Managed Agent.
+
+  A plain string may embed ``{var}``, ``{artifact.name}``, or ``{var?}``
+  placeholders that are resolved from session state / artifacts at request time
+  (see ``inject_session_state``). An ``InstructionProvider`` callable is invoked
+  with a ``ReadonlyContext`` and bypasses placeholder injection (it manages
+  state itself). Empty by default, in which case no system instruction is sent.
+  """
+
   tools: list[
       Union[types.Tool, BaseTool, Callable[..., Any], RemoteMcpServer]
   ] = Field(default_factory=list)
@@ -197,6 +209,29 @@ def api_client(self) -> Client:
         )
     return self._api_client
 
+  async def canonical_instruction(
+      self, ctx: ReadonlyContext
+  ) -> tuple[str, bool]:
+    """Resolves ``self.instruction`` for the current context.
+
+    Mirrors ``LlmAgent.canonical_instruction``.
+
+    Args:
+      ctx: The read-only context used to resolve an InstructionProvider.
+
+    Returns:
+      A tuple of (instruction, bypass_state_injection).
+      ``bypass_state_injection``
+      is True when the instruction came from an ``InstructionProvider`` callable
+      (which manages state itself), False for a plain string.
+    """
+    if isinstance(self.instruction, str):
+      return self.instruction, False
+    instruction = self.instruction(ctx)
+    if inspect.isawaitable(instruction):
+      instruction = await instruction
+    return instruction, True
+
   async def _resolve_backend_tools(
       self, ctx: InvocationContext
   ) -> list[ToolParam]:
@@ -360,6 +395,15 @@ async def _run_async_impl(
     )
     interaction_tools = await self._resolve_backend_tools(ctx)
 
+    raw_si, bypass_state_injection = await self.canonical_instruction(
+        ReadonlyContext(ctx)
+    )
+    system_instruction = raw_si
+    if not bypass_state_injection:
+      system_instruction = await inject_session_state(
+          raw_si, ReadonlyContext(ctx)
+      )
+
     create_kwargs: dict[str, Any] = {
         'agent': self.agent_id,
         'input': input_steps,
@@ -377,6 +421,8 @@ async def _run_async_impl(
       create_kwargs['agent_config'] = self.agent_config
     if prev_interaction_id:
       create_kwargs['previous_interaction_id'] = prev_interaction_id
+    if system_instruction:
+      create_kwargs['system_instruction'] = system_instruction
 
     # Request-time header merge, parity with google_llm.generate_content_async:
     # combine any RunConfig headers with ADK tracking headers, non-destructively.
@@ -402,7 +448,7 @@ async def _run_async_impl(
         build_interactions_request_log(
             model=self.agent_id,
             input_steps=input_steps,
-            system_instruction=None,
+            system_instruction=system_instruction or None,
             tools=interaction_tools if interaction_tools else None,
             generation_config=None,
             previous_interaction_id=prev_interaction_id,

src/google/adk/agents/langgraph_agent.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+from typing import Any
 from typing import AsyncGenerator
 from typing import Union
 
@@ -23,7 +24,7 @@
 from langchain_core.messages import HumanMessage
 from langchain_core.messages import SystemMessage
 from langchain_core.runnables.config import RunnableConfig
-from langgraph.graph.graph import CompiledGraph
+from langgraph.graph.state import CompiledStateGraph
 from pydantic import ConfigDict
 from typing_extensions import override
 
@@ -53,14 +54,20 @@ def _get_last_human_messages(
 
 
 class LangGraphAgent(BaseAgent):
-  """Currently a concept implementation, supports single and multi-turn."""
+  """Adapts a compiled LangGraph state graph for single or multi-turn use.
+
+  When using a persistent checkpointer, set ``LANGGRAPH_STRICT_MSGPACK=true``
+  before importing LangGraph and compiling the graph. LangGraph's patched
+  releases provide schema-derived checkpoint allowlisting, but do not enable
+  strict deserialization by default.
+  """
 
   model_config = ConfigDict(
       arbitrary_types_allowed=True,
   )
   """The pydantic model config."""
 
-  graph: CompiledGraph
+  graph: CompiledStateGraph
 
   instruction: str = ''
 
@@ -73,13 +80,16 @@ async def _run_async_impl(
     # Needed for langgraph checkpointer (for subsequent invocations; multi-turn)
     config: RunnableConfig = {'configurable': {'thread_id': ctx.session.id}}
 
-    # Add instruction as SystemMessage if graph state is empty
-    current_graph_state = self.graph.get_state(config)
-    graph_messages = (
-        current_graph_state.values.get('messages', [])
-        if current_graph_state.values
-        else []
-    )
+    # Add instruction as SystemMessage if graph state is empty. State lookup is
+    # only valid when the compiled graph has a checkpointer.
+    graph_messages: list[Any] = []
+    if self.graph.checkpointer:
+      current_graph_state = await self.graph.aget_state(config)
+      graph_messages = (
+          current_graph_state.values.get('messages', [])
+          if current_graph_state.values
+          else []
+      )
     messages: list[BaseMessage] = (
         [SystemMessage(content=self.instruction)]
         if self.instruction and not graph_messages
@@ -89,7 +99,7 @@ async def _run_async_impl(
     messages += self._get_messages(ctx.session.events)
 
     # Use the Runnable
-    final_state = self.graph.invoke({'messages': messages}, config)
+    final_state = await self.graph.ainvoke({'messages': messages}, config)
     result = final_state['messages'][-1].content
 
     result_event = Event(

src/google/adk/agents/live_request_queue.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 import asyncio
+from typing import Any
 from typing import Optional
 
 from google.genai import types
@@ -32,32 +33,41 @@ class LiveRequest(BaseModel):
   """If set, send the content to the model in turn-by-turn mode.
 
   When multiple fields are set, they are processed by priority (highest first):
-  activity_start > activity_end > blob > content.
+  activity_start > activity_end > blob > content. state_delta, if set, is always
+  applied regardless of the other fields.
   """
   blob: Optional[types.Blob] = None
   """If set, send the blob to the model in realtime mode.
 
   When multiple fields are set, they are processed by priority (highest first):
-  activity_start > activity_end > blob > content.
+  activity_start > activity_end > blob > content. state_delta, if set, is always
+  applied regardless of the other fields.
   """
   activity_start: Optional[types.ActivityStart] = None
   """If set, signal the start of user activity to the model.
 
   When multiple fields are set, they are processed by priority (highest first):
-  activity_start > activity_end > blob > content.
+  activity_start > activity_end > blob > content. state_delta, if set, is always
+  applied regardless of the other fields.
   """
   activity_end: Optional[types.ActivityEnd] = None
   """If set, signal the end of user activity to the model.
 
   When multiple fields are set, they are processed by priority (highest first):
-  activity_start > activity_end > blob > content.
+  activity_start > activity_end > blob > content. state_delta, if set, is always
+  applied regardless of the other fields.
   """
   close: bool = False
   """If set, close the queue. queue.shutdown() is only supported in Python 3.13+."""
 
   partial: bool = False
   """If set, the content is a partial turn update that does not complete the current model turn."""
 
+  state_delta: Optional[dict[str, Any]] = None
+  """If set, these state changes are applied to the session, so they take
+  effect even when the request carries no content or a partial/
+  function-response turn."""
+
 
 class LiveRequestQueue:
   """Queue used to send LiveRequest in a live(bidirectional streaming) way."""

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/apps/_configs.py

@@ -58,11 +58,11 @@ class EventsCompactionConfig(BaseModel):
   summarizer: Optional[BaseEventsSummarizer] = None
   """The event summarizer to use for compaction."""
 
-  compaction_interval: int
+  compaction_interval: Optional[int] = Field(default=None, gt=0)
   """The number of *new* user-initiated invocations that, once
   fully represented in the session's events, will trigger a compaction."""
 
-  overlap_size: int
+  overlap_size: Optional[int] = Field(default=None, ge=0)
   """The number of preceding invocations to include from the
   end of the last compacted range. This creates an overlap between consecutive
   compacted summaries, maintaining context."""
@@ -85,11 +85,22 @@ class EventsCompactionConfig(BaseModel):
   """
 
   @model_validator(mode="after")
-  def _validate_token_params(self) -> EventsCompactionConfig:
+  def _validate_trigger_params(self) -> EventsCompactionConfig:
     token_threshold_set = self.token_threshold is not None
     retention_size_set = self.event_retention_size is not None
     if token_threshold_set != retention_size_set:
       raise ValueError(
           "token_threshold and event_retention_size must be set together."
       )
+    compaction_interval_set = self.compaction_interval is not None
+    overlap_size_set = self.overlap_size is not None
+    if compaction_interval_set != overlap_size_set:
+      raise ValueError(
+          "compaction_interval and overlap_size must be set together."
+      )
+    if not (token_threshold_set or compaction_interval_set):
+      raise ValueError(
+          "At least one compaction trigger must be configured: the"
+          " token-threshold pair or the sliding-window pair."
+      )
     return self

src/google/adk/auth/auth_handler.py

@@ -215,6 +215,8 @@ def generate_auth_uri(
     }
     if auth_credential.oauth2.audience:
       params["audience"] = auth_credential.oauth2.audience
+    if auth_credential.oauth2.nonce:
+      params["nonce"] = auth_credential.oauth2.nonce
 
     # If using PKCE with S256, ensure a code_verifier exists.
     # If not provided in the credential, generate a cryptographically secure