docs(agents): add system-instruction sample and guide section

Add a runnable sample under
contributing/samples/managed_agent/system_instruction demonstrating the new
ManagedAgent.instruction field, and document the field in the ManagedAgent
guide.

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

Author: haranrk

contributing/samples/managed_agent/system_instruction/README.md

@@ -0,0 +1,60 @@
+# Managed Agent — System Instruction
+
+> For setup, authentication, backends, and background on `ManagedAgent`, see the
+> [ManagedAgent guide](../../../../docs/guides/agents/managed_agent/index.md).
+
+## Overview
+
+This sample runs a `ManagedAgent` whose behavior is shaped by its `instruction`
+field. `instruction` is forwarded to the Managed Agents API as the interaction's
+system instruction (the same role `LlmAgent.instruction` plays for a local
+model). Here it pins a persona and output format, so its effect is visible in
+every reply.
+
+`instruction` accepts either a plain string (which may embed `{state_var}`
+placeholders resolved from session state) or an `InstructionProvider` callable.
+This sample uses an **`InstructionProvider`**: `persona_instruction` takes a
+`ReadonlyContext`, reads the reply language from `state['response_language']`
+(defaulting to English), and returns the instruction string. Because a provider
+is invoked on every turn, the instruction is rebuilt each turn from the current
+state; unlike a string, it bypasses `{placeholder}` injection, so you build the
+final text yourself. A provider may also be `async` (return an awaitable `str`).
+
+## Sample Inputs
+
+- `What is the capital of France?`
+
+  The reply obeys the instruction: a single terse sentence ending with a
+  relevant emoji, in the language from `state['response_language']` (English by
+  default).
+
+- `And Japan?`
+
+  A follow-up turn that reuses the recovered remote sandbox and previous
+  interaction. The provider runs again on this turn, demonstrating that the
+  system instruction is resolved and sent on chained turns too — and would pick
+  up any change to `response_language` in session state.
+
+## Graph
+
+```mermaid
+graph LR
+    User -->|message| ManagedAgent
+    ManagedAgent -->|interactions.create + system_instruction| ManagedAgentsAPI
+    ManagedAgentsAPI -->|streamed events| ManagedAgent
+    ManagedAgent -->|reply shaped by the instruction| User
+```
+
+## How To
+
+- **Set the instruction**: pass `instruction=...` to `ManagedAgent`. A string is
+  sent as-is (after `{placeholder}` resolution); an `InstructionProvider`
+  callable is invoked per turn and bypasses placeholder injection.
+- **Use an `InstructionProvider`**: define a callable that takes a
+  `ReadonlyContext` and returns a `str` (or an awaitable `str`), then pass it as
+  `instruction`. Read `readonly_context.state` to build the instruction
+  dynamically — here `state['response_language']` selects the reply language.
+- **Observe the effect**: every reply follows the persona/format the instruction
+  specifies, on the first turn and on chained follow-up turns.
+- **Drive it**: a `ManagedAgent` is a `BaseAgent`, so a standard `Runner` runs it
+  just like any other agent.

contributing/samples/managed_agent/system_instruction/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent

contributing/samples/managed_agent/system_instruction/agent.py

@@ -0,0 +1,72 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A ManagedAgent with an ``InstructionProvider`` system instruction.
+
+``ManagedAgent.instruction`` is forwarded to the Managed Agents API as the
+interaction's system instruction, the same way ``LlmAgent.instruction`` shapes a
+local model. It accepts either a plain string (which may embed ``{state_var}``
+placeholders resolved from session state) or an ``InstructionProvider`` — a
+callable invoked with a ``ReadonlyContext`` that returns the instruction string
+and bypasses placeholder injection.
+
+This sample uses an ``InstructionProvider`` so the instruction is built
+dynamically, per turn, from session state: it pins a terse persona and reads the
+reply language from ``state['response_language']`` (defaulting to English). The
+persona keeps the effect visible in every reply, and because the provider runs
+on every turn the instruction adapts if the state changes on a later turn.
+
+Run with ``adk web`` / ``adk run
+contributing/samples/managed_agent/system_instruction``. See the README for the
+required environment / auth setup.
+"""
+
+import os
+
+from google.adk.agents import ManagedAgent
+from google.adk.agents.readonly_context import ReadonlyContext
+
+# The Managed Agent id served by the Managed Agents API. Override with the
+# MANAGED_AGENT_ID environment variable if your project has access to a
+# different agent.
+_DEFAULT_AGENT_ID = 'antigravity-preview-05-2026'
+
+
+def persona_instruction(readonly_context: ReadonlyContext) -> str:
+  """Builds the system instruction dynamically from session state.
+
+  An ``InstructionProvider`` is any callable that takes a ``ReadonlyContext``
+  and returns the instruction (a ``str``, or an awaitable ``str`` for async
+  providers). It is invoked on every turn, so the instruction can adapt to the
+  current session state, and — unlike a plain string — it bypasses
+  ``{placeholder}`` injection, leaving you to build the final string yourself.
+  """
+  language = readonly_context.state.get('response_language', 'English')
+  return (
+      'You are a terse assistant. Always answer in a single sentence, in'
+      f' {language}, and end every reply with a relevant emoji.'
+  )
+
+
+root_agent = ManagedAgent(
+    name='managed_persona_agent',
+    agent_id=os.environ.get('MANAGED_AGENT_ID', _DEFAULT_AGENT_ID),
+    # Provision a remote sandbox; the environment id is recovered from prior
+    # events so follow-up turns reuse the same sandbox.
+    environment={'type': 'remote'},
+    # Pass an InstructionProvider callable instead of a plain string: it is
+    # invoked per turn with a ReadonlyContext and returns the resolved
+    # instruction that is forwarded as the interaction's system_instruction.
+    instruction=persona_instruction,
+)

docs/guides/agents/managed_agent/index.md

@@ -125,6 +125,28 @@ Response text appears in both places (the local ADK events and the remote
 interaction history), but ADK stores only the ids it needs to recover and reuse
 the remote state; it never re-sends prior turns.
 
+### System instruction
+
+Set `instruction` on `ManagedAgent` to send a system instruction to the Managed
+Agents API, mirroring `LlmAgent.instruction`. It accepts a plain string — which
+may embed `{state_var}` / `{artifact.name}` / `{var?}` placeholders resolved
+from session state and artifacts at request time — or an `InstructionProvider`
+callable that is invoked with a `ReadonlyContext` and bypasses placeholder
+injection. The resolved instruction is forwarded as the interaction's
+`system_instruction` on every turn, including chained turns; an empty
+`instruction` (the default) sends none.
+
+```python
+from google.adk.agents import ManagedAgent
+
+root_agent = ManagedAgent(
+    name='managed_persona_agent',
+    agent_id='antigravity-preview-05-2026',
+    environment={'type': 'remote'},
+    instruction='You are a terse assistant. Answer in a single sentence.',
+)
+```
+
 ## Advanced applications
 
 ### Tool encapsulation for orchestration
@@ -154,3 +176,4 @@ the remote state; it never re-sends prior turns.
 
 *   [Managed Agent Basic](../../../../contributing/samples/managed_agent/basic)
 *   [Managed Agent Code Execution](../../../../contributing/samples/managed_agent/code_execution)
+*   [Managed Agent System Instruction](../../../../contributing/samples/managed_agent/system_instruction)