docs: clarify shallow copy behavior in docstring and add isolation test

- Add note in docstring about shallow copy behavior for nested objects
- Add test_metadata_shallow_copy_isolation to verify:
  - Top-level changes are isolated from original dict
  - Nested object modifications affect original (shallow copy)

Author: donggyun112

src/google/adk/runners.py

@@ -478,6 +478,10 @@ async def run_async(
       metadata: Optional per-request metadata that will be passed to callbacks.
         This allows passing request-specific context such as user_id, trace_id,
         or memory context keys to before_model_callback and other callbacks.
+        Note: A shallow copy is made of this dictionary, so top-level changes
+        within callbacks won't affect the original. However, modifications to
+        nested mutable objects (e.g., nested dicts or lists) will affect the
+        original.
 
     Yields:
       The events generated by the agent.

tests/unittests/test_runners.py

@@ -1375,6 +1375,67 @@ def test_llm_request_without_metadata(self):
 
     assert llm_request.metadata is None
 
+  @pytest.mark.asyncio
+  async def test_metadata_shallow_copy_isolation(self):
+    """Test that shallow copy isolates top-level changes but shares nested objects."""
+    # Track modifications made in callback
+    callback_received_metadata = None
+
+    def before_model_callback(callback_context, llm_request):
+      nonlocal callback_received_metadata
+      callback_received_metadata = llm_request.metadata
+      # Modify top-level key (should NOT affect original due to shallow copy)
+      llm_request.metadata["top_level_key"] = "modified_in_callback"
+      # Modify nested object (WILL affect original due to shallow copy)
+      llm_request.metadata["nested"]["inner_key"] = "modified_nested"
+      return LlmResponse(
+          content=types.Content(
+              role="model", parts=[types.Part(text="Test response")]
+          )
+      )
+
+    agent_with_callback = LlmAgent(
+        name="callback_agent",
+        model="gemini-2.0-flash",
+        before_model_callback=before_model_callback,
+    )
+
+    runner_with_callback = Runner(
+        app_name="test_app",
+        agent=agent_with_callback,
+        session_service=self.session_service,
+        artifact_service=self.artifact_service,
+    )
+
+    await self.session_service.create_session(
+        app_name=TEST_APP_ID, user_id=TEST_USER_ID, session_id=TEST_SESSION_ID
+    )
+
+    # Original metadata with nested mutable object
+    original_metadata = {
+        "top_level_key": "original_value",
+        "nested": {"inner_key": "original_nested"},
+    }
+
+    async for event in runner_with_callback.run_async(
+        user_id=TEST_USER_ID,
+        session_id=TEST_SESSION_ID,
+        new_message=types.Content(
+            role="user", parts=[types.Part(text="Hello")]
+        ),
+        metadata=original_metadata,
+    ):
+      pass
+
+    # Verify callback received metadata
+    assert callback_received_metadata is not None
+
+    # Top-level changes in callback should NOT affect original (shallow copy)
+    assert original_metadata["top_level_key"] == "original_value"
+
+    # Nested object changes in callback WILL affect original (shallow copy behavior)
+    assert original_metadata["nested"]["inner_key"] == "modified_nested"
+
 
 if __name__ == "__main__":
   pytest.main([__file__])