Repository navigation
Description
π΄ Required Information
Is your feature request related to a specific problem?
ADK has strong primitives for procedural knowledge (Skills / SKILL.md), but no first-class way to consume a local directory of declarative, typed knowledge β markdown files with YAML frontmatter describing concepts, carrying trust / lifecycle / staleness metadata. Today an agent grounding itself in such a corpus must either load everything into context (no progressive disclosure, no filtering) or build its own indexing and RAG layer, throwing away the structure the corpus already carries.
Open Knowledge Format (OKF) v0.2 (GoogleCloudPlatform/open-knowledge-format) is a small spec for exactly that corpus shape: every concept is markdown with frontmatter such as type, sources, generated, verified, status, stale_after. ADK already tolerates these keys on SKILL.md (Frontmatter uses extra="allow"), so the formats are compatible β but ADK has no tool that ingests a bundle as knowledge.
Describe the Solution You'd Like
A toolset that exposes an OKF bundle to an agent progressively:
- L1
okf_index(directory, type, tags, trust_tier, include_deprecated, include_stale)β frontmatter summaries only, never bodies, so discovery stays cheap. - L2
okf_read(path)β one concept's body plus frontmatter. - L3
okf_resource(concept_path, file)β a referenced resource, path-guarded, 64 KiB cap withtruncated: true. okf_search(query, ...)β deterministic scan with the same filter predicate as the index.
Optionally, a one-way bridge that emits an ADK-loadable SKILL.md from an OKF concept (using the existing extra="allow" tolerance), so one git tree can serve both formats without duplication.
Security contract: a bundle is untrusted input. Tool docstrings label concept bodies as data, never instructions; trust tiers are advisory and never gate actions; every path resolves through a bundle-root guard including symlinks.
Impact on your work
We maintain a downstream consumer that grounds agents in a versioned knowledge corpus with human/machine verification signals and staleness. We built a standalone implementation to validate the shape β ADK-free core plus a thin ADK toolset, 108 tests, strict mypy, offline fixtures vendored from the four published OKF sample bundles. Verified against ADK 2.11/2.12: BaseToolset has a single abstract method (get_tools), Frontmatter preserves OKF extras, and list_skills_in_dir fetches L1 without pulling bodies.
Willingness to contribute
Yes. Happy to contribute either as (a) an external package listed in google/adk-docs β docs/integrations/, or (b) core ADK code, if maintainers prefer that. Asking first because this adds a new tool surface and a new dependency concept.
π‘ Recommended Information
Describe Alternatives You've Considered
- Vector store / RAG: loses typed frontmatter and trust/staleness signals, adds embeddings and infrastructure.
- Load every concept into the system prompt: no progressive disclosure; cost grows linearly with the corpus.
SkillToolset: good for procedural skills, but it requiresSKILL.mdand kebab-case directory names and does no indexing or frontmatter filtering β it is not a knowledge-corpus consumer.
Proposed API / Implementation
from okf_adk.toolset import OkfToolset
agent = Agent(
model="gemini-flash-latest",
name="knowledge_agent",
instruction="Answer using the knowledge bundle.",
tools=[OkfToolset(bundle="./knowledge", tool_name_prefix="okf")],
)
# -> okf_index, okf_read, okf_resource, okf_searchAdditional Context
The core is deliberately ADK-free so it can be tested offline and reused by non-ADK consumers; only the toolset module imports google.adk, under an optional extra.
Question for maintainers: is this something ADK wants in core, or should it stay an external integration listed in the docs catalog? I am happy to adjust scope to whatever you prefer.
Activity
Parthiv-06 commentedon Oct 21, 2026
Hi @ALDRIN121, Iβd like to help land this. Iβve put together an implementation in core under src/google/adk/integrations/okf/, following the integrations README. It adds no new dependency (pyyaml is already in core) and sits behind an experimental OKF_TOOLSET flag. It has okf_list_concepts, okf_search_concepts, okf_read_concept and okf_read_resource, the OKF v0.2 trust, status and staleness rules, a symlink-aware path guard, a unit guide, a sample, and 93 unit tests checked against the four published OKF bundles. Iβm happy to open it as a PR, fold in your implementation and tests, or hold off if youβre already preparing one. If maintainers would rather keep this out of core, I can turn it into an external package instead.
sanketpatil06 commentedon Oct 22, 2026
Hi @ALDRIN121 , thank you for your feature request. It is currently under review, and we will let you know if we need any further information. We appreciate your understanding.
ALDRIN121 commentedon Oct 28, 2026
Routing update, and a scope note.
Route. I framed this as core-vs-
adk-docs-catalog.mainhas since answered it:src/google/adk/integrations/exists (README from Feb 2026; sub-packages includelangchain/,crewai/,mongodb/,e2b/, β¦), and per that README a sub-package there manages its own internal structure and takes optional third-party deps as extras. An OKF consumer needs no third-party dep βpyyamlis already core β sointegrations/okf/is where I've put it, and the "new dependency" question doesn't arise. @sanketpatil06 β if that destination is wrong, say so and I'll retarget; otherwise nothing further is needed from you on routing.The PR is up: #7796.
integrations/okf/with a four-toolOkfToolset(okf_index/okf_read/okf_resource/okf_search), the parsing/trust/traversal core beside it, 107 tests, and the four published OKF sample bundles vendored so the golden tests run offline.@Parthiv-06 β the offer to fold your work in stands. Push your branch, or tell me where your code is, and I'll bring your implementation and your 93 tests onto #7796 with you in the commits. The part I'd most like a second pair of eyes on is the adversarial half: symlink escape refused at load as well as at call time, one guard behind concept-relative-then-bundle-relative resolution, structured error dicts instead of exceptions,
trust_tiernever gating an action, and an index that provably never returns a body. If you'd rather land yours, say so early and we'll pick one β I opened this because the issue had been quiet for a week, not to race you.Two conventions worth knowing before you push anything, in case they save you the same afternoon: new modules under
src/google/adk/need_-prefixed basenames with public symbols exported via__init__.py/__all__(integrations/is not exempt;crewai/crewai_tool.pypredates the rule), and every new re-exported module needs a unit guide underdocs/guides/plus a line indocs/guides/README.mdor thecheck-docshook fails.