Changed example to use the Global Instruction Plugin (#1244) by JuanCaCoder · Pull Request #2177 · google/adk-docs

JuanCaCoder · 2026-08-26T19:54:40Z

Changed the code sample to use the GlobalInstructionPlugin.

JuanCaCoder · 2026-08-26T19:59:19Z

📝 Executive Summary

Migrates the Python A2A Consuming Quickstart sample from the deprecated Agent.global_instruction parameter to GlobalInstructionPlugin registered via App(plugins=[...]).
Aligns the quickstart with the modern ADK application architecture and prevents runtime DeprecationWarning exceptions while preserving global instruction behavior across sub-agents.
Target doc: docs/a2a/quickstart-consuming.md (rendered under /a2a/quickstart-consuming/).

🗂️ PR Consolidation & Verification Mapping

PR / Source Reference	Original Section	New Section	Change Description	Codebase Verification
`docs/a2a/quickstart-consuming.md`	`#### How it works` (Snippet)	`#### How it works` (Snippet)	Removed deprecated `global_instruction` from `root_agent = Agent(...)`; added `App(name="a2a_basic", root_agent=root_agent, plugins=[GlobalInstructionPlugin(...)])`.	`✅ PASS` `google/adk/plugins/global_instruction_plugin.py:L58-L85` `google/adk/apps/app.py:L53-L83`
`docs/a2a/quickstart-consuming.md`	`#### How it works` (Prose)	`#### How it works` (Admonition)	Added `!!! note "Global instructions via Plugins"` note explaining deprecation of `Agent.global_instruction` and pointing to `GlobalInstructionPlugin`.	`✅ PASS` `google/adk/agents/llm_agent.py:L758-L766` `docs/agents/llm-agents.md:L206-L210`
`docs/a2a/quickstart-consuming.md`	Introductory text	Introductory text	Added link to `GlobalInstructionPlugin` under `/plugins/#prebuilt-plugins`.	`✅ PASS` `docs/plugins/index.md:L67-L68`

🔍 Technical Verification Report

GlobalInstructionPlugin Implementation & Lifecycle:
- Source: src/google/adk/plugins/global_instruction_plugin.py:L58-L115
- Verified: GlobalInstructionPlugin inherits from BasePlugin. Its constructor accepts global_instruction: Union[str, InstructionProvider] = "" and name: str = "global_instruction". In before_model_callback, it resolves static strings or InstructionProvider callables and prepends the instruction to llm_request.config.system_instruction.
Agent.global_instruction Deprecation:
- Source: src/google/adk/agents/llm_agent.py:L288-L299, L758-L766
- Verified: The field is marked deprecated in docstrings and emits a runtime DeprecationWarning ("global_instruction field is deprecated and will be removed in a future version. Use GlobalInstructionPlugin instead for the same functionality at the App level.").
App Container Architecture:
- Source: src/google/adk/apps/app.py:L53-L83
- Verified: App requires name: str and root_agent: Union[BaseAgent, Any, None]. It accepts plugins: list[BasePlugin] = Field(default_factory=list), which applies registered plugins application-wide across all local and remote sub-agents.
Runner plugins Deprecation:
- Source: src/google/adk/runners.py:L285-L286, L386-L387
- Verified: Passing plugins directly to Runner is deprecated in favor of App(plugins=[...]), confirming App as the canonical entry point for plugin registration.

JuanCaCoder · 2026-08-31T22:42:53Z

📝 Executive Summary

Updates the A2A Consuming Quickstart sample to replace the deprecated Agent.global_instruction parameter with the modular GlobalInstructionPlugin registered at the App level.
Aligns the guide with ADK's modern architecture, ensuring application-wide instructions and personality persist across hierarchical sub-agents without runtime deprecation warnings.
Targets: Target Doc: docs/a2a/quickstart-consuming.md

🗂️ PR Consolidation & Verification Mapping

PR / Source Reference	Original Section	New / Updated Section	Change Description	Codebase Verification & GitHub Source
PR #2177 / Branch	`docs/a2a/quickstart-consuming.md`	`docs/a2a/quickstart-consuming.md`	Deprecate `Agent(global_instruction=...)` and adopt `App(plugins=[GlobalInstructionPlugin(...)])`	`✅ PASS` – global_instruction_plugin.py:L58-L124

🔍 Technical Verification Report

GlobalInstructionPlugin Plugin Architecture:
- Claimed Doc Behavior: Replaces the deprecated global_instruction field on Agent by providing system instruction injection across the agent hierarchy via GlobalInstructionPlugin registered on App.
- Verified Code Implementation: GlobalInstructionPlugin extends BasePlugin and hooks into before_model_callback to prepend the global instruction to llm_request.config.system_instruction.
- GitHub Source Link: src/google/adk/plugins/global_instruction_plugin.py#L58-L124
- Status: ✅ PASS
Agent.global_instruction Deprecation Status:
- Claimed Doc Behavior: States that the global_instruction parameter on Agent is deprecated in favor of GlobalInstructionPlugin.
- Verified Code Implementation: LlmAgent.global_instruction is explicitly marked deprecated in docstrings and triggers a DeprecationWarning in _get_global_instruction.
- GitHub Source Link: src/google/adk/agents/llm_agent.py#L288-L299, src/google/adk/agents/llm_agent.py#L758-L767
- Status: ✅ PASS
App Container Initialization & Plugin Support:
- Claimed Doc Behavior: Encapsulates root_agent and plugins inside an App(name="a2a_basic", root_agent=root_agent, plugins=[...]) definition.
- Verified Code Implementation: App defines fields name: str, root_agent: Union[BaseAgent, Any, None], and plugins: list[BasePlugin] = Field(default_factory=list).
- GitHub Source Link: src/google/adk/apps/app.py#L53-L83
- Status: ✅ PASS
Module Imports Verification:
- Claimed Doc Behavior:
  - from google.adk.apps import App
  - from google.adk.plugins.global_instruction_plugin import GlobalInstructionPlugin
  - from google.adk.agents.llm_agent import Agent
- Verified Code Implementation:
  - App is exported in google.adk.apps.__all__.
  - GlobalInstructionPlugin is defined in google.adk.plugins.global_instruction_plugin.
  - Agent is defined as TypeAlias = LlmAgent in google.adk.agents.llm_agent.
- GitHub Source Link: src/google/adk/apps/__init__.py#L20-L27, src/google/adk/plugins/global_instruction_plugin.py#L58-L74, src/google/adk/agents/llm_agent.py#L1322
- Status: ✅ PASS
Internal Anchor Reference:
- Claimed Doc Behavior: Links to [GlobalInstructionPlugin](/plugins/#prebuilt-plugins).
- Verified Code Implementation: Section ## Prebuilt Plugins exists in docs/plugins/index.md and indexes GlobalInstructionPlugin.
- GitHub Source Link: docs/plugins/index.md#L56-L73
- Status: ✅ PASS

joefernandez · 2026-09-02T02:18:05Z


 ```python title="a2a_basic/agent.py"
 from google.adk.agents.llm_agent import Agent
+from google.adk.apps import App


don't add either of these new imports here. revert

joefernandez · 2026-09-02T02:33:05Z

    ),
 )
+
+app = App(


don't modify the example code this way. revert

joefernandez · 2026-09-02T02:33:09Z

+)
 ```

+!!! note "Global instructions via Plugins"


don't add here. remove.

joefernandez · 2026-09-02T02:33:15Z

 ```

+!!! note "Global instructions via Plugins"
+    The `global_instruction` parameter on `Agent` is deprecated. Use `GlobalInstructionPlugin` registered on your `App` or `Runner` to apply consistent rules or identity across all agents in your workflow.


A. Don't add this "note" here, remove it.
B. revise this to be a tip (see revision below)
C. Add this as a tip in the following locations:

just ahead of the Known Limitations heading in: https://adk.dev/graphs/#known-limitations

just ahead of Operating Considerations* heading in: https://adk.dev/workflows/collaboration/#operating-considerations

At the end of the template workflow pages (after code example):

https://adk.dev/agents/workflow-agents/sequential-agents/

https://adk.dev/agents/workflow-agents/loop-agents/

https://adk.dev/agents/workflow-agents/parallel-agents/

!!! tip "Global instructions for all agents" Apply consistent rules or identity across all agents in your workflow using `GlobalInstructionPlugin` registered on your `App` or `Runner` object. Do not use the `global_instruction` parameter on `Agent` which is deprecated since ADK Python v1.16.0.

joefernandez · 2026-09-02T02:42:49Z

    The `use_legacy` parameter defaults to `True`, so the sample above uses the legacy path. Set `use_legacy=False` to use the new ADK-A2A integration, which sends the [A2A extension](a2a-extension.md) to the remote agent.

-Then, you can simply use the `RemoteA2aAgent` in your agent. In this case, `prime_agent` is used as one of the sub-agents in the `root_agent` below:
+Then, you can simply use the `RemoteA2aAgent` in your agent. In this case, `prime_agent` is used as one of the sub-agents in `root_agent`. To apply a shared identity or global rules across the entire agent hierarchy, configure the [`GlobalInstructionPlugin`](/plugins/#prebuilt-plugins) in your `App`:


revert this change.

Placing this update here basically hides it. No one is going to look for it here. See the comment below about where to place a "tip"-only version of this information in a few places where it would be helpful.

changed example to plugin

d3bd075

JuanCaCoder marked this pull request as ready for review September 1, 2026 17:56

JuanCaCoder changed the title ~~changed example to plugin~~ Changed example to use the Global Instruction Plugin Sep 1, 2026

JuanCaCoder changed the title ~~Changed example to use the Global Instruction Plugin~~ Changed example to use the Global Instruction Plugin (#1244) Sep 1, 2026

joefernandez reviewed Sep 2, 2026

View reviewed changes

Navigation Menu

Uh oh!

Changed example to use the Global Instruction Plugin (#1244) - #2177

Changed example to use the Global Instruction Plugin (#1244)#2177
JuanCaCoder wants to merge 1 commit into
mainfrom
GlobalInstructionPlugin_example

JuanCaCoder commented Aug 26, 2026

Uh oh!

JuanCaCoder commented Aug 26, 2026

Uh oh!

JuanCaCoder commented Aug 31, 2026

Uh oh!

joefernandez Sep 2, 2026 •

edited

Loading

Uh oh!

joefernandez Sep 2, 2026

Uh oh!

joefernandez Sep 2, 2026 •

edited

Loading

Uh oh!

joefernandez Sep 2, 2026 •

edited

Loading

Uh oh!

joefernandez Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

JuanCaCoder commented Aug 26, 2026

Uh oh!

JuanCaCoder commented Aug 26, 2026

📝 Executive Summary

🗂️ PR Consolidation & Verification Mapping

🔍 Technical Verification Report

Uh oh!

JuanCaCoder commented Aug 31, 2026

📝 Executive Summary

🗂️ PR Consolidation & Verification Mapping

🔍 Technical Verification Report

Uh oh!

joefernandez Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joefernandez Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

joefernandez Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joefernandez Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joefernandez Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joefernandez Sep 2, 2026 •

edited

Loading

joefernandez Sep 2, 2026 •

edited

Loading

joefernandez Sep 2, 2026 •

edited

Loading