Skip to content

Feature request: OKF (Open Knowledge Format) bundle support for ADKΒ #7597

Description

@ALDRIN121

πŸ”΄ 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 with truncated: 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 requires SKILL.md and 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_search

Additional 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

  1. Parthiv-06 commented on Oct 21, 2026

    @Parthiv-06

    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.

  2. added
    core[Component] This issue is related to the core interface and implementation
    on Oct 22, 2026
  3. sanketpatil06 commented on Oct 22, 2026

    @sanketpatil06

    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.

  4. added
    needs review[Status] The PR/issue is awaiting review from the maintainer
    on Oct 22, 2026
  5. ALDRIN121 commented on Oct 28, 2026

    @ALDRIN121
    ContributorAuthor

    Routing update, and a scope note.

    Route. I framed this as core-vs-adk-docs-catalog. main has since answered it: src/google/adk/integrations/ exists (README from Feb 2026; sub-packages include langchain/, 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 β€” pyyaml is already core β€” so integrations/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-tool OkfToolset (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_tier never 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.py predates the rule), and every new re-exported module needs a unit guide under docs/guides/ plus a line in docs/guides/README.md or the check-docs hook fails.

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

Metadata

Metadata

Assignees

Labels

core[Component] This issue is related to the core interface and implementationneeds review[Status] The PR/issue is awaiting review from the maintainer

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions