feat: support Gemini URL Context

agent-schema.json

@@ -1639,7 +1639,7 @@
         },
         "provider_opts": {
           "type": "object",
-          "description": "Provider-specific options. Anthropic: thinking_prefix_mismatch (error or drop_block; defaults to drop_block on Fable/Mythos 5.1), strict_tools (true for eligible schemas or a tool-name array requiring strict mode), cache_diagnostics (boolean; Claude API only), native_compaction (boolean; synchronous whole-history signed compaction on Claude API), cache_preserving_updates (boolean; native system/tool/effort changes with turn-scoped reminders on supported models), thinking_display: updates (progress updates beta on Fable 5+ and Mythos 5.1). Sampling parameters: top_k (integer, supported by anthropic, google, amazon-bedrock, and custom OpenAI-compatible providers like vLLM/Ollama), repetition_penalty (float, forwarded to custom OpenAI-compatible providers), min_p (float, forwarded to custom providers), seed (integer, forwarded to OpenAI). Lifecycle: unload_api (string) overrides the unload endpoint inherited from the provider config (relative path resolved against base_url's scheme+host, or an absolute URL); used by the runtime's `unload` on_agent_switch builtin hook to release model resources between agent switches. Infrastructure options: http_headers (map of string to string, adds custom HTTP headers to every request; used for OpenAI-compatible providers like github-copilot which requires Copilot-Integration-Id). dmr: runtime_flags; supports_images (boolean) and supports_pdf (boolean) declare which document attachment types the local model accepts. DMR-hosted models are not in the models.dev catalog, so attachment capabilities cannot be detected automatically and default to text-only; set supports_images: true for a vision model so image attachments are forwarded instead of silently dropped. anthropic/amazon-bedrock (Claude): interleaved_thinking (boolean, default true). anthropic: thinking_display ('summarized', 'omitted', 'updates', or 'display') controls whether thinking blocks are returned in responses when thinking is enabled. Claude Opus 4.7 hides thinking by default ('omitted'); set thinking_display: summarized to receive thinking blocks. 'display' (full thinking blocks) is only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); models from the adaptive-thinking generation onward (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) reject it, and docker-agent fails fast with a configuration error (fallbacks models are validated too); fallbacks (array of model ID strings, in priority order; enables the server-side-fallback beta so requests refused by safety classifiers, e.g. on Claude Fable 5, are retried with the listed models in a single round trip). OpenAI-compatible APIs: service_tier (string, forwarded unchanged to Chat Completions and Responses, including WebSocket and reranking; 'fast' or 'priority' enables Fast mode at premium pricing on supported models; omitted or empty leaves the API default, non-string values are ignored). openai/chatgpt: preserve_reasoning (boolean, default false) preserves ordered Responses output and encrypted reasoning for stateless continuation; native_tool_search also enables output replay. openai: cache_diagnostics (boolean, default false) logs Responses prompt-cache comparison results with --debug on GPT-5.6+; comparisons are scoped to the current session and resolved model; ignored for chatgpt and custom base_url endpoints. transport ('sse' or 'websocket') to choose between SSE and WebSocket streaming for the Responses API; native_tool_search (boolean, default false; also enables ordered output replay) declares the agent's deferred tools with defer_loading and a server-executed tool_search tool so OpenAI's hosted tool search discovers them (only openai models supporting deferred tools, gpt-5.4+; ignored on chatgpt, OpenAI-compatible endpoints including a custom base_url, and Chat Completions requests). openai/anthropic/google: rerank_prompt (string) to fully override the system prompt used for RAG reranking (advanced - prefer using results.reranking.criteria for domain-specific guidance). Google: google_search (boolean) enables Google Search grounding, google_maps (boolean) enables Google Maps grounding, code_execution (boolean) enables server-side code execution, output_dimensionality (positive integer) truncates Gemini embedding vectors to that size when the model is used as a RAG embedding_model; service_tier (string, forwarded unchanged as the top-level serviceTier of every generateContent request, including reranking, title generation, and compaction, on the Gemini API, Vertex AI, and the Docker models gateway; 'flex' for discounted, queued processing that may wait up to 15 minutes before the first byte, 'standard' for the default tier, 'priority' for premium processing; omitted or empty leaves the API default, non-string values are ignored; cost estimates are not tier-adjusted, set the model's cost override).",
+          "description": "Provider-specific options. Anthropic: thinking_prefix_mismatch (error or drop_block; defaults to drop_block on Fable/Mythos 5.1), strict_tools (true for eligible schemas or a tool-name array requiring strict mode), cache_diagnostics (boolean; Claude API only), native_compaction (boolean; synchronous whole-history signed compaction on Claude API), cache_preserving_updates (boolean; native system/tool/effort changes with turn-scoped reminders on supported models), thinking_display: updates (progress updates beta on Fable 5+ and Mythos 5.1). Sampling parameters: top_k (integer, supported by anthropic, google, amazon-bedrock, and custom OpenAI-compatible providers like vLLM/Ollama), repetition_penalty (float, forwarded to custom OpenAI-compatible providers), min_p (float, forwarded to custom providers), seed (integer, forwarded to OpenAI). Lifecycle: unload_api (string) overrides the unload endpoint inherited from the provider config (relative path resolved against base_url's scheme+host, or an absolute URL); used by the runtime's `unload` on_agent_switch builtin hook to release model resources between agent switches. Infrastructure options: http_headers (map of string to string, adds custom HTTP headers to every request; used for OpenAI-compatible providers like github-copilot which requires Copilot-Integration-Id). dmr: runtime_flags; supports_images (boolean) and supports_pdf (boolean) declare which document attachment types the local model accepts. DMR-hosted models are not in the models.dev catalog, so attachment capabilities cannot be detected automatically and default to text-only; set supports_images: true for a vision model so image attachments are forwarded instead of silently dropped. anthropic/amazon-bedrock (Claude): interleaved_thinking (boolean, default true). anthropic: thinking_display ('summarized', 'omitted', 'updates', or 'display') controls whether thinking blocks are returned in responses when thinking is enabled. Claude Opus 4.7 hides thinking by default ('omitted'); set thinking_display: summarized to receive thinking blocks. 'display' (full thinking blocks) is only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); models from the adaptive-thinking generation onward (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) reject it, and docker-agent fails fast with a configuration error (fallbacks models are validated too); fallbacks (array of model ID strings, in priority order; enables the server-side-fallback beta so requests refused by safety classifiers, e.g. on Claude Fable 5, are retried with the listed models in a single round trip). OpenAI-compatible APIs: service_tier (string, forwarded unchanged to Chat Completions and Responses, including WebSocket and reranking; 'fast' or 'priority' enables Fast mode at premium pricing on supported models; omitted or empty leaves the API default, non-string values are ignored). openai/chatgpt: preserve_reasoning (boolean, default false) preserves ordered Responses output and encrypted reasoning for stateless continuation; native_tool_search also enables output replay. openai: cache_diagnostics (boolean, default false) logs Responses prompt-cache comparison results with --debug on GPT-5.6+; comparisons are scoped to the current session and resolved model; ignored for chatgpt and custom base_url endpoints. transport ('sse' or 'websocket') to choose between SSE and WebSocket streaming for the Responses API; native_tool_search (boolean, default false; also enables ordered output replay) declares the agent's deferred tools with defer_loading and a server-executed tool_search tool so OpenAI's hosted tool search discovers them (only openai models supporting deferred tools, gpt-5.4+; ignored on chatgpt, OpenAI-compatible endpoints including a custom base_url, and Chat Completions requests). openai/anthropic/google: rerank_prompt (string) to fully override the system prompt used for RAG reranking (advanced - prefer using results.reranking.criteria for domain-specific guidance). Google: google_search (boolean) enables Google Search grounding, google_maps (boolean) enables Google Maps grounding, code_execution (boolean) enables server-side code execution, url_context (boolean) enables reading public URLs during generation, output_dimensionality (positive integer) truncates Gemini embedding vectors to that size when the model is used as a RAG embedding_model; service_tier (string, forwarded unchanged as the top-level serviceTier of every generateContent request, including reranking, title generation, and compaction, on the Gemini API, Vertex AI, and the Docker models gateway; 'flex' for discounted, queued processing that may wait up to 15 minutes before the first byte, 'standard' for the default tier, 'priority' for premium processing; omitted or empty leaves the API default, non-string values are ignored; cost estimates are not tier-adjusted, set the model's cost override).",
           "additionalProperties": true
         },
         "track_usage": {

docs/providers/google/index.md

@@ -160,8 +160,8 @@ models:
 
 ## Built-in Tools (Grounding)
 
-Gemini models support built-in tools that let the model access Google Search and Google Maps
-directly during generation. Enable them via `provider_opts`:
+Gemini models support built-in tools that let the model access Google Search, Google Maps,
+and public URLs, or execute code directly during generation. Enable them via `provider_opts`:
 
 ```yaml
 models:
@@ -179,6 +179,41 @@ models:
 | `google_search`  | Enables Google Search grounding for up-to-date info  |
 | `google_maps`    | Enables Google Maps grounding for location queries   |
 | `code_execution` | Enables server-side code execution for computations  |
+| `url_context`    | Lets Gemini read public URLs supplied in the prompt   |
+
+### URL Context
+
+Enable `url_context` to let Gemini read links supplied in your prompt without a
+separate fetch tool:
+
+```yaml
+models:
+  reader:
+    provider: google
+    model: gemini-3.8-flash
+    provider_opts:
+      url_context: true
+      google_search: true # Optional: discover sources as well as read links
+```
+
+Then ask, for example, `Summarize https://docs.docker.com/ai/docker-agent/`.
+Google fetches the content on its servers; it cannot read local files, private
+network URLs, or pages requiring your browser's authentication. The option is
+opt-in and accepts a YAML boolean, not the string `"true"`.
+
+Docker Agent forwards this tool on the Gemini Developer API, models gateway,
+and native Gemini Vertex AI paths. Model, backend, region, and tool-combination
+support still depend on Google and the gateway. On supported models it can be
+combined with Google Search. Mixing built-in and custom function tools currently
+uses a flag that the Go SDK accepts only on the Gemini Developer API path
+(including gateways forwarding to that API), not Vertex AI. This is not a
+general browser or an alternative to the local fetch tool for authenticated
+requests.
+
+See Google's [URL Context guide](https://ai.google.dev/gemini-api/docs/url-context)
+for supported content types, limits, and models, and
+[`examples/gemini_url_context.yaml`](https://github.com/docker/docker-agent/blob/main/examples/gemini_url_context.yaml)
+for a complete agent.
 
 ## Embeddings
 

examples/README.md

@@ -217,6 +217,7 @@ remote MCP endpoints.
 | [`rule_based_routing.yaml`](rule_based_routing.yaml) | Cheap router model dispatches the user message to fast or capable models. |
 | [`structured-output.yaml`](structured-output.yaml) | Forces the model to return JSON matching a schema. |
 | [`google_search_grounding.yaml`](google_search_grounding.yaml) | Enables Google Search grounding on Gemini models. |
+| [`gemini_url_context.yaml`](gemini_url_context.yaml) | Gemini reads public documentation URLs with its built-in URL Context tool. |
 | [`openai-service-tier.yaml`](openai-service-tier.yaml) | OpenAI Fast mode and service tier selection with `provider_opts.service_tier`. |
 | [`gemini_service_tier.yaml`](gemini_service_tier.yaml) | Gemini Flex/standard/priority service tier selection with `provider_opts.service_tier`. |
 | [`gemini_image_output.yaml`](gemini_image_output.yaml) | Gemini image-output model: generated images are saved into the workspace, stored portably with the session, and rendered inline in the TUI. |

examples/gemini_url_context.yaml

@@ -0,0 +1,14 @@
+models:
+  reader:
+    provider: google
+    model: gemini-3.8-flash
+    provider_opts:
+      url_context: true
+
+agents:
+  root:
+    model: reader
+    description: Read public documentation with Gemini URL Context
+    instruction: |
+      Read the public URLs supplied by the user and answer using their content.
+      Explain when a page cannot be retrieved; do not invent its contents.

pkg/model/provider/gemini/classify.go

@@ -48,7 +48,7 @@ var rejectionKeywords = []struct {
 	}},
 	{RejectionIncompatibleFunctionOrBuiltinTools, []string{
 		"function_declarations", "functiondeclarations",
-		"google_search", "google_maps", "code_execution",
+		"google_search", "google_maps", "code_execution", "url_context", "urlcontext",
 		"built-in tool", "builtin tool",
 	}},
 	{RejectionModelOrAPICapabilityMismatch, []string{

pkg/model/provider/gemini/client.go

@@ -567,8 +567,7 @@ func (c *Client) applyGemini25ThinkingBudget(config *genai.GenerateContentConfig
 	slog.Debug("Gemini request using thinking_budget", "budget_tokens", tokens)
 }
 
-// builtInTools returns Gemini built-in tools (Google Search, Google Maps,
-// Code Execution) enabled via provider_opts.
+// builtInTools returns Gemini built-in tools enabled via provider_opts.
 func (c *Client) builtInTools() []*genai.Tool {
 	entries := []struct {
 		key  string
@@ -577,6 +576,7 @@ func (c *Client) builtInTools() []*genai.Tool {
 		{"google_search", &genai.Tool{GoogleSearch: &genai.GoogleSearch{}}},
 		{"google_maps", &genai.Tool{GoogleMaps: &genai.GoogleMaps{}}},
 		{"code_execution", &genai.Tool{CodeExecution: &genai.ToolCodeExecution{}}},
+		{"url_context", &genai.Tool{URLContext: &genai.URLContext{}}},
 	}
 
 	var builtIn []*genai.Tool
@@ -799,7 +799,7 @@ func (c *Client) CreateChatCompletionStream(
 		applyImageOutputMediaFileInstruction(config)
 	}
 
-	// Start with Google built-in tools (search, maps, code execution) from provider_opts
+	// Start with Google built-in tools from provider_opts
 	builtInTools := c.builtInTools()
 	config.Tools = builtInTools
 

pkg/model/provider/gemini/diagnostics.go

@@ -25,7 +25,7 @@ type RequestShape struct {
 	ResponseModalities    []string
 
 	// BuiltInToolKinds lists which fixed-kind built-in tools (google_search,
-	// google_maps, code_execution) were enabled. BuiltInToolCount is
+	// google_maps, code_execution, url_context) were enabled. BuiltInToolCount is
 	// len(BuiltInToolKinds).
 	BuiltInToolKinds []string
 	BuiltInToolCount int
@@ -124,6 +124,8 @@ func builtInToolKinds(toolsList []*genai.Tool) []string {
 			kinds = append(kinds, "google_maps")
 		case t.CodeExecution != nil:
 			kinds = append(kinds, "code_execution")
+		case t.URLContext != nil:
+			kinds = append(kinds, "url_context")
 		}
 	}
 	return kinds