From bd0586765811d7451bea2dc9bdd833c87e73c8d8 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/4] 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 20d3c7b90a93004775ded3b70145630e70c5be42 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/4] 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 From ccabc071ab6e085ae35d1c70404027404784e500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 23 Jun 2026 04:03:37 +0000 Subject: [PATCH 3/4] docs: add Miro to remote MCP services list for changes in PR #3192 --- docs/features/remote-mcp/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/remote-mcp/index.md b/docs/features/remote-mcp/index.md index 999b7ec7e..d7b88aee1 100644 --- a/docs/features/remote-mcp/index.md +++ b/docs/features/remote-mcp/index.md @@ -194,6 +194,7 @@ A per-toolset `callbackRedirectURL` (in the YAML) overrides the runtime-wide `-- | Service | URL | Transport | Description | | ---------- | ------------------------------------------------- | ---------- | --------------------------------- | | Canva | `https://mcp.canva.com/mcp` | streamable | Design and graphics platform | +| Miro | `https://mcp.miro.com/` | streamable | Collaborative whiteboard platform (Enterprise plan required; see [official docs](https://developers.miro.com/docs/miro-mcp)) | | Cloudinary | `https://asset-management.mcp.cloudinary.com/sse` | sse | Media management and optimization | | InVideo | `https://mcp.invideo.io/sse` | sse | Video creation platform | | Webflow | `https://mcp.webflow.com/sse` | sse | Website builder and CMS | From bc59ddf9fc44c544b04b0ed79f36413dd867322a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 23 Jun 2026 04:04:07 +0000 Subject: [PATCH 4/4] docs: update --otel flag and document GenAI OTel env vars for changes in PR #2620 --- docs/features/cli/index.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index 30a119998..40773f2e5 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -70,7 +70,7 @@ $ docker agent run [config] [message...] [flags] | `--record [path]` | Record AI API interactions to a cassette file (auto-generates filename if no path given) | | `-d, --debug` | Enable debug logging | | `--log-file ` | Custom debug log location | -| `-o, --otel` | Enable OpenTelemetry tracing | +| `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | ```bash # Examples @@ -521,12 +521,21 @@ These flags are available on every `docker agent` command: | ------------------------- | -------------------------------------------------------------------------------------- | | `-d, --debug` | Enable debug logging (default location: `~/.cagent/cagent.debug.log`) | | `--log-file ` | Custom debug log location (only used with `--debug`) | -| `-o, --otel` | Enable OpenTelemetry tracing | +| `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | | `--cache-dir ` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) | | `--config-dir ` | Override the config directory (default: `~/.config/cagent`) | | `--data-dir ` | Override the data directory (default: `~/.cagent`) | | `--help` | Show help for any command | +### OpenTelemetry environment variables + +When `--otel` is enabled, the standard [OTel SDK env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) are honored (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, etc.). Two additional docker-agent-specific variables control GenAI instrumentation: + +| Variable | Default | Description | +| -------- | ------- | ----------- | +| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | Set to `true` to capture prompt text, model responses, tool arguments, and tool results as span attributes. Off by default because these fields may contain PII. | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | (dual-emit) | Set to `gen_ai_latest_experimental` to emit only the spec-defined `gen_ai.*` keys from the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). The default dual-emit mode emits both `gen_ai.*` and legacy keys so existing dashboards continue working. | + ## Runtime Configuration Flags These flags are accepted by every command that loads an agent (`run`, `run --exec`, `new`, `eval`, `serve api`, `serve mcp`, `serve a2a`, `serve acp`, `serve chat`). They are listed once here to avoid repetition in the per-command tables above.