From 640311f5debc6dd69cff929be67f37c814456e8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Sun, 21 Jun 2026 04:28:18 +0000 Subject: [PATCH 1/2] docs: update Go SDK RAG toolset section for PR #3184 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #3184 replaced the blank-import opt-in pattern with an explicit toolset registry (pkg/teamloader/toolsets). The RAG toolset is now included in NewDefaultToolsetRegistry() by default. Document the opt-out pattern (delete creators["rag"] from the registry) for binaries that want a load-time warning rather than a deferred runtime error. Note that teamloader.Load() does not return an error for unknown toolset types — failures become load-time warnings attached to the agent. Clarify that pkg/rag/treesitter build-tag guards handle the cgo boundary automatically regardless of CGO_ENABLED. --- docs/guides/go-sdk/index.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md index 6ac81e40b..8c3f4486e 100644 --- a/docs/guides/go-sdk/index.md +++ b/docs/guides/go-sdk/index.md @@ -154,19 +154,28 @@ Requesting a model whose provider was compiled out fails at construction time wi

The Google provider's Vertex Model Garden support also imports the Anthropic SDK, so the Anthropic dependency is only fully removed when both docker_agent_no_anthropic and docker_agent_no_google are set.

-## RAG Toolset (cgo-free builds) +## RAG Toolset (opt-out) -The RAG toolset (`type: rag`) uses a tree-sitter code parser that requires cgo. When building without cgo — or when you want to drop the cgo dependency entirely — do not import the `pkg/rag` package in your binary. +The RAG toolset (`type: rag`) is included in `NewDefaultToolsetRegistry()` (from `pkg/teamloader/toolsets`) and `loaderdefaults.Opts()` (from `pkg/teamloader/defaults`). -By default the RAG toolset is **opt-in**: it is only linked when you blank-import its package: +The underlying tree-sitter code parser uses cgo, but build-tag guards in `pkg/rag/treesitter` mean importing the package is safe regardless of `CGO_ENABLED`: with `CGO_ENABLED=0` the parser stub compiles in and returns a runtime error on first use rather than failing at compile time. + +If you want to exclude the RAG toolset from your binary entirely — surfacing a load-time warning on the agent rather than a deferred runtime error from the `!cgo` stub — remove it from the registry before passing it to `teamloader.Load`: ```go import ( - _ "github.com/docker/docker-agent/pkg/tools/builtin/rag" // register RAG toolset + "github.com/docker/docker-agent/pkg/teamloader" + loadertoolsets "github.com/docker/docker-agent/pkg/teamloader/toolsets" ) + +// Opt out of the RAG toolset; a config that declares type: rag attaches +// a load-time warning to the agent instead of failing at document processing. +creators := loadertoolsets.DefaultToolsetCreators() +delete(creators, "rag") +registry := teamloader.NewToolsetRegistry(creators) ``` -Without this import, a config that declares `type: rag` fails with a "toolset type not registered" error at startup. If your application does not use RAG, simply omit the blank import; the rest of docker-agent works without cgo. +Pass the custom registry via `teamloader.WithToolsetRegistry(registry)` when calling `teamloader.Load`. Note that `teamloader.Load()` does not return an error for unknown toolset types — the failure is recorded as a load-time warning on the agent (`agent.LoadTimeWarnings()`) and surfaced via logging and TUI notifications. ## Basic Example From d99def988f939e0c5c5604fb851363d62ba54aa7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Sun, 21 Jun 2026 04:28:34 +0000 Subject: [PATCH 2/2] docs: add MCP OAuth token persistence section for PR #3189 PR #3189 decoupled the OS keyring token store from the embedder packages. The CLI calls keyringstore.Register() at startup; embedders that want persistent MCP OAuth tokens across restarts must call it before teamloader.Load() on configs with remote MCP toolsets. Document the Register() call, the panic trigger (MCP toolset construction, not OAuth lookup), and when to omit it. --- docs/guides/go-sdk/index.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md index 8c3f4486e..25b93e913 100644 --- a/docs/guides/go-sdk/index.md +++ b/docs/guides/go-sdk/index.md @@ -156,7 +156,7 @@ Requesting a model whose provider was compiled out fails at construction time wi ## RAG Toolset (opt-out) -The RAG toolset (`type: rag`) is included in `NewDefaultToolsetRegistry()` (from `pkg/teamloader/toolsets`) and `loaderdefaults.Opts()` (from `pkg/teamloader/defaults`). +The RAG toolset (`type: rag`) is included in `NewDefaultToolsetRegistry()` (from `pkg/teamloader/toolsets`) and `loaderdefaults.Opts()` (from `pkg/teamloader/defaults`, using the conventional import alias `loaderdefaults`). The underlying tree-sitter code parser uses cgo, but build-tag guards in `pkg/rag/treesitter` mean importing the package is safe regardless of `CGO_ENABLED`: with `CGO_ENABLED=0` the parser stub compiles in and returns a runtime error on first use rather than failing at compile time. @@ -175,7 +175,31 @@ delete(creators, "rag") registry := teamloader.NewToolsetRegistry(creators) ``` -Pass the custom registry via `teamloader.WithToolsetRegistry(registry)` when calling `teamloader.Load`. Note that `teamloader.Load()` does not return an error for unknown toolset types — the failure is recorded as a load-time warning on the agent (`agent.LoadTimeWarnings()`) and surfaced via logging and TUI notifications. +Pass the custom registry via `teamloader.WithToolsetRegistry(registry)` when calling `teamloader.Load`. Note that `teamloader.Load()` does not return an error for unknown toolset types — the failure is recorded as a load-time warning and can be retrieved with `agent.DrainWarnings()`; it is also surfaced via logging and TUI notifications. + +## MCP OAuth Token Persistence + +By default, MCP OAuth tokens are stored in-memory only and are not persisted across process restarts. The CLI registers a keyring-backed store automatically at startup; when embedding docker-agent as a library you must do this yourself if you want tokens to survive restarts. + +Call `keyringstore.Register()` **before** any MCP toolset is initialised to enable the OS keyring-backed token store: + +```go +import "github.com/docker/docker-agent/pkg/tools/mcp/keyringstore" + +func main() { + // Must be called before teamloader.Load() on configs with remote MCP + // toolsets; calling it after the store is created panics. + keyringstore.Register() + // ... rest of your startup code +} +``` + +
+
Call order matters
+

If keyringstore.Register() is called after the default token store has already been lazily initialised, docker-agent panics. The store is initialised when any remote MCP toolset is constructed — which happens inside teamloader.Load(). Always call keyringstore.Register() before calling teamloader.Load() on a config that includes remote MCP toolsets.

+
+ +If you do not need persistent OAuth tokens (for example, in short-lived batch jobs or tests), omit the call and tokens will be kept in-memory for the process lifetime. ## Basic Example