Skip to content

Navigation Menu

Sign in
Sign up

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

Open
JuanCaCoder wants to merge 1 commit into
main from
GlobalInstructionPlugin_example
Open

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

Conversation

@JuanCaCoder

@JuanCaCoder JuanCaCoder commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Changed the code sample to use the GlobalInstructionPlugin.

Copy link
Copy Markdown
Collaborator Author

📝 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

  1. 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.

  2. 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.").

  3. 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.

  4. 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.

 		
 

 



 

 
 

 

 

 
 
 

 

 
 

 



 

 

 

 

 
 
 

 
 
 
 

 

 
 


 







 

 
 


 
 


 

 

 

 
 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 

 Author

 

 



 

 



 
 

 
 
📝 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


    

  1. 

    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
      • 

    

    2. 

  2. 

    Agent.global_instruction Deprecation Status:
    


    3. 

  3. 

    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
      • 

    

    4. 

  4. 

    Module Imports Verification:
    


    5. 

  5. 

    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
      • 

    

    6. 


 		
 

 



 

 
 

 

 

 
 
 

 

 
 

 



 

 

 

 

 
 
 

 
 
 
 

 

 
 


 







 

 
 

 
 

 
 

 
 

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

 





 

 

 
 

 

 
 @JuanCaCoder
JuanCaCoder
 changed the title
(削除) changed example to plugin (削除ここまで)
(追記) Changed example to use the Global Instruction Plugin (追記ここまで)
 Sep 1, 2026
 

 

 

 

 
 

 

 
 @JuanCaCoder
JuanCaCoder
 changed the title
(削除) Changed example to use the Global Instruction Plugin (削除ここまで)
(追記) Changed example to use the Global Instruction Plugin (#1244) (追記ここまで)
 Sep 1, 2026
 

 



 

 
 

 

 
 

 
 
 
 
 
 
 

 
 

 
 
 
 
 
 
 
 
 

 
 

 
 
 
 
 ```python title="a2a_basic/agent.py"
 
 

 
 
 
 
 from google.adk.agents.llm_agent import Agent
 
 

 
 
 
 
 from google.adk.apps import App
 
 

 




 

 

 

 

 

 

 
 @joefernandez
 
 
 joefernandez
 
 
 
 
 Sep 2, 2026
 
 •
 

 
 

 
 edited
 
 
 
 

 
 
 
 
 
  Loading

 
 
 


 

 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 
 

 



 

 

 

 
 

 
 
 
Choose a reason for hiding this comment

 

 The reason will be displayed to describe this comment to others. Learn more.
 

 

 
 


 


 
 

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

 

 
 


 

 

 
 
 

 
 
 
 

 

 
 



 

 

 

 
 

 

 
 

 



 



 

 



 

 




 





 

 
 

 

 
 

 
 
 
 
 
 
 

 
 

 
 
 
 
 
 
 
 
  ),
 
 

 
 
 
 
 )
 
 

 
 
 
 
 

 
 

 
 
 
 
 app = App(
 
 

 




 

 

 

 

 

 

 
 @joefernandez
 
 
 joefernandez
 
 
 
 
 Sep 2, 2026
 
 

 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 
 

 



 

 

 

 
 

 
 
 
Choose a reason for hiding this comment

 

 The reason will be displayed to describe this comment to others. Learn more.
 

 

 
 


 


 
 

 
don't modify the example code this way. revert

 

 
 


 

 

 
 
 

 
 
 
 

 

 
 



 

 

 

 
 

 

 
 

 



 



 

 



 

 




 





 

 
 

 

 
 

 
 
 
 
 
 
 

 
 

 
 
 
 
 
 
 
 
 )
 
 

 
 
 
 
 ```
 
 

 
 
 
 
 

 
 

 
 
 
 
 !!! note "Global instructions via Plugins"
 
 

 




 

 

 

 

 

 

 
 @joefernandez
 
 
 joefernandez
 
 
 
 
 Sep 2, 2026
 
 •
 

 
 

 
 edited
 
 
 
 

 
 
 
 
 
  Loading

 
 
 


 

 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 
 

 



 

 

 

 
 

 
 
 
Choose a reason for hiding this comment

 

 The reason will be displayed to describe this comment to others. Learn more.
 

 

 
 


 


 
 

 
don't add here. remove.

 

 
 


 

 

 
 
 

 
 
 
 

 

 
 



 

 

 

 
 

 

 
 

 



 



 

 



 

 




 





 

 
 

 

 
 

 
 
 
 
 
 
 

 
 

 
 
 
 
 
 
 
 
 ```
 
 

 
 
 
 
 

 
 

 
 
 
 
 !!! 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.
 
 

 




 

 

 

 

 

 

 
 @joefernandez
 
 
 joefernandez
 
 
 
 
 Sep 2, 2026
 
 •
 

 
 

 
 edited
 
 
 
 

 
 
 
 
 
  Loading

 
 
 


 

 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 
 

 



 

 

 

 
 

 
 
 
Choose a reason for hiding this comment

 

 The reason will be displayed to describe this comment to others. Learn more.
 

 

 
 


 


 
 

 
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:


    

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

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

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




!!! 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.


 

 
 


 

 

 
 
 

 
 
 
 

 

 
 



 

 

 

 
 

 

 
 

 



 



 

 



 

 




 





 

 
 

 

 
 

 
 
 
 
 
 
 

 
 

 
 
 
 
 
 
 
 
  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`:
 
 

 




 

 

 

 

 

 

 
 @joefernandez
 
 
 joefernandez
 
 
 
 
 Sep 2, 2026
 
 

 

 

 

 

  
 
 

 

 
 
 
 
 Copy link
 

 
 
 
 Copy Markdown
 

 
 

 

 

 
 
 Collaborator

 
 

 



 

 

 

 
 

 
 
 
Choose a reason for hiding this comment

 

 The reason will be displayed to describe this comment to others. Learn more.
 

 

 
 


 


 
 

 
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.

 

 
 


 

 

 
 
 

 
 
 
 

 

 
 



 

 

 

 
 

 

 
 

 



 



 

 



 

 




 





 
 

 

 

 







 
 

 
 Sign up for free
 to join this conversation on GitHub.
 Already have an account?
 Sign in to comment
 








 
 

 

 
 
 
 

 Reviewers
 

 
 
 

 

 
 @joefernandez
 
 joefernandez
 
 
 
 
 
 
 joefernandez left review comments


 

 At least 1 approving review is required to merge this pull request.
 




 
 

 

 
 

 Assignees
 

 

 No one assigned



 
 


 
 

 Labels
 

 

 None yet




 
 
 

 

 

 Projects
 

 

 None yet


 

 
 


 

 
 

 Milestone
 

 No milestone


 
 
 


 

 

 
 

 
 

 Development
 

 

Successfully merging this pull request may close these issues.


 
 


 
 

 



 
 
 
 
 
 
 
 
 
 




 


 

 

 

 
 
 
 
 

 


 

 

 

 

 




AltStyle によって変換されたページ (->オリジナル)
/