Guidance for GDK users on most mature library
Describe the bug Right now the GDK doc only mentions that the overal GDK is in alpha but does not differentiate the mature of the different language bindings. Right now, the Rust library is the most mature and exposes the most functionality while Python and Kotlin follow on afterwards and are designed rather than just directly exposed from Rust intermediately.
For a developer who cares about the most up to date features there is no guidance on which language they should choose. When I ask various agents which language I should use to write a custom agentic application with goose they are unaware of this difference.
Expected behavior/fix
Best location: documentation/docs/gdk/sdk/index.md
This is the actual GDK SDK "Getting Started"/Quickstart page — the first stop for anyone building an agentic app with the SDK in any language.
- Lines 8–16 explain the SDK architecture: "One Rust crate, goose-sdk, is the source of every language binding. Python and Kotlin are generated from it with UniFFI." This is exactly where a maturity caveat belongs, since it's the moment a reader learns Python/Kotlin are derived, not first-class.
- Lines 21–24 already have an :::info Alpha admonition, but it only says the SDK surface may change between 0.x releases — nothing about Rust vs. Python/Kotlin maturity.
- Lines 36–77 (Install) and 79–181 (Quickstart) show Rust/Python/Kotlin side-by-side with no differentiation — implying parity that doesn't actually exist.
Proposed placement: extend the existing Alpha admonition (lines 21–24) or add a new admonition right after line 16, before the reader picks a language for Install/Quickstart.
Draft text:
Custom agentic applications looking for the most complete or recent features should currently prefer Rust. Python and Kotlin bindings are generated from the goose-sdk crate via UniFFI, but only a subset of the Rust API is exposed today — features are surfaced to bindings deliberately, one at a time, to keep each language binding idiomatic and well-designed rather than a raw mirror of the Rust API. If you need full functionality now, build directly against the Rust goose-sdk crate.
Secondary locations worth the same one-liner
- crates/goose-sdk/README.md (lines 3–10) — catches developers who land on the crate/GitHub before the docs site.
- crates/goose-sdk/python/README.md — only 16 lines total; likely the only thing some PyPI-first Python developers ever read, so easy to miss if skipped.
Source: aaif-goose/goose