feature: pluggable policy & taxonomy for more accurate and more deterministic skill/tool execution

[ViktorVeselov]

Read the contribution guide and file the issues in the right place.
Contribution guide.

🔴 Required Information

Is your feature request related to a specific problem?

Yes. Currently, the Agent Development Kit (ADK) lacks a native, modular way to define, resolve, and bind a Domain Taxonomy within the framework to shape capabilities, skill execution dynamically, dynamic prompting + dynamic tool's description based on taxonomy classes and their subclasses.

This proposal is a concrete community implementation referencing the original core SDK design discussion in google/adk-python/discussions/5891 and the PR feedback in google/adk-python/pull/5898.

Without a pluggable taxonomy layer:

1. No Standard Schema/Parser: Developers cannot parse standard structures (such as Flat JSON configurations or rich semantic JSON-LD with SKOS representations) into a nested, traversable organizational registry.
2. Capability Access Control: Skills cannot be restricted dynamically on a per-domain basis depending on context.
3. Instruction & Prompt Shaping: There is no standard primitive to append context-aware prompts or dynamically alter skill instructions based on resolved domain contexts (e.g., adding strict regulatory guardrails on the fly).

---

Describe the Solution You'd Like

We have designed and fully verified a Modular, Pluggable Policy & Taxonomy Security Engine (TaxonomyPlugin) as a 100% opt-in community extension.

By utilizing the standard ADK BasePlugin hook interface, we encapsulate all taxonomy checks inside a pluggable event interceptor without making intrusive modifications to the core SDK loop.

Key highlights of this proposed architecture:

1. TaxonomyPlugin (BasePlugin hook): Intercepts tool callbacks (such as list_skills and load_skill) to dynamically filter capability visibility with zero overhead to core agent flows when the plugin is inactive.
2. TaxonomyResolver & TaxonomyPipeline: Abstract interfaces and composite pipelines to dynamically resolve active domains from conversation history, thinking traces, or multi-agent dialogues.
3. SkillPolicy: Orchestrates permission validation (is_skill_allowed) and dynamic instruction shaping (shape_instructions).
4. TaxonomyRegistry: Standard parser for Flat JSON maps and JSON-LD with SKOS vocabularies.
5. Safety Guards: Reuses the core ADK's internal path validation (_validate_path_segment) in Frontmatter metadata validation to protect against parameter injection and directory traversal attacks.

---

Impact on your work

This core taxonomy primitive empowers several downstream capabilities:

• Ecosystem Integration: Standardizes metadata tagging, allowing future tooling like AntigravityCLI to index and route prompts dynamically.
• More Accurate Tool Execution: Enables describing tools, prompts, and their descriptions based on user input, agent output, LLM thinking, and retrieved information from DB(can be RAG in our case).
• Thought-Stream Auditing: Standardizes taxonomy extraction from raw conversation turns or thinking outputs.
• Scalability: Seamlessly handles hierarchical tree-traversals (nesting children taxonomy nodes under parent nodes) to avoid flat policy list bloat.

---

Willingness to contribute

Yes, I have already developed a complete implementation footprint (~400 lines of fully tested Python code), including a comprehensive unit test suite and core SDK integration validation scripts, which I have submitted under the associated Pull Request linked below.

---

🟡 Recommended Information

Describe Alternatives You've Considered

1. Ad-hoc system prompts: Lossy, doesn't scale, and cannot be conditionally restricted to discrete metadata nodes.
2. Host-application wrapper filters: Brittle and fails to capture deep agent execution cycles or multi-agent A2A dialog transitions.
3. Core SDK Framework Integration: We originally proposed adding this framework feature directly into the core google-adk package in google/adk-python/pull/5898. However, as noted in the maintainer discussions (e.g., pull/5898#issuecomment-4579149780), to maintain strict core pluggability rules, avoid intrusive core loop modifications, and keep the core SDK lightweight, this feature is best delivered as an opt-in plugin (BasePlugin) within this community repository. This preserves 100% core compatibility while keeping the implementation modular.

---

Proposed API / Implementation

1. Core Interfaces (google/adk_community/plugins/taxonomy/policy.py)

from abc import ABC, abstractmethod
from google.adk.agents.readonly_context import ReadonlyContext
from google.adk.models.llm_request import LlmRequest
from google.adk.skills.models import Skill

class TaxonomyResolver(ABC):
    """Abstract interface for resolving active taxonomy domains from context and history."""
    @abstractmethod
    async def resolve_taxonomies(self, context: ReadonlyContext, llm_request: LlmRequest) -> list[str]:
        pass

class SkillPolicy(ABC):
    """Abstract base class for dynamic skill validation and instruction shaping based on resolved taxonomy."""
    @abstractmethod
    def is_skill_allowed(self, skill: Skill, context: ReadonlyContext, active_taxonomies: list[str]) -> bool:
        pass
        
    @abstractmethod
    def shape_instructions(self, skill: Skill, context: ReadonlyContext, original_instructions: str) -> str:
        pass

2. Client Integration (Pluggable and fully opt-in)

from google.adk_community.plugins.taxonomy import TaxonomyPlugin, TaxonomyRegistry, DefaultSkillPolicy
from google.adk.agents import Runner

# Parse standard flat or JSON-LD SKOS taxonomies
registry = TaxonomyRegistry.from_flat_json(my_taxonomy_data)

# Define custom resolver using the abstract interface
class MyCustomTaxonomyResolver(TaxonomyResolver):
    async def resolve_taxonomies(self, context: ReadonlyContext, llm_request: LlmRequest) -> list[str]:
        # Perform dynamic context audits
        return ["urn:adk:domain:regulatory_strict"]

# Instantiate opt-in taxonomy security plugin
taxonomy_plugin = TaxonomyPlugin(
    taxonomy_registry=registry,
    resolver=MyCustomTaxonomyResolver(),
    policy=DefaultSkillPolicy()
)

# Inject to runner with zero overhead
runner = Runner(
    ...,
    plugins=[taxonomy_plugin]
)

---

Associated Pull Request & Closing Plan

This issue is fully addressed and implemented in adk-python-community/pull/151.

The implementation contains:

• Complete implementation files in google/adk_community/plugins/taxonomy/.
• Passing pytest unit test suites under tests/plugins/test_taxonomy_plugin.py.

Requesting maintainer review directly on PR #151. Once approved and merged, this issue can be successfully closed.