Agent Docs - Iterate

docs/cloud/features/10_AI_ML/agents/builder/code-interpreter.md

@@ -9,26 +9,34 @@
 ---
 
 import BetaBadge from '@theme/badges/BetaBadge';
+import Image from '@theme/IdealImage';
+import runCode from '@site/static/images/cloud/agent-builder/run-code/run-code.png';
 
 <BetaBadge/>
 
 The code interpreter lets an agent execute code in a managed sandbox. Use it for computation, data transformation, format conversion, plotting, and anything else better done in code than in natural language.
 
-## Enable it {#enable-it}
+## Enable the code interpreter {#enable-it}
 
-Toggle **Code interpreter** in the Agent Builder's capabilities section, then save. The agent decides when to run code based on the user's request and the agent's instructions.
+In the Agent Builder, enable **Run Code** in the **Capabilities** section, then save. The agent decides when to run code based on the user's request and the agent's instructions.
+
+<Image img={runCode} alt="Run Code section of the Capabilities panel with the Run Code checkbox enabled and an Upload to Code Environment button" size="sm"/>
 
 ## Supported languages {#supported-languages}
 
 The sandbox is a Unix environment with two general-purpose runtimes and a few shell utilities:
 
-- **Python 3** — the default for data tasks.
-- **Node.js (JavaScript)** — when an agent prefers JS for the job.
-- **Bash** and **sh** — shell scripting for chaining commands and quick I/O.
-- **AWK** and **sed** — line-oriented text processing.
-- **bc** — arbitrary-precision math.
+- **Python 3** - the default for data tasks.
+- **Node.js (JavaScript)** - when an agent prefers JS for the job.
+- **Bash** and **sh** - shell scripting for chaining commands and quick I/O.
+- **AWK** and **sed** - line-oriented text processing.
+- **bc** - arbitrary-precision math.
+
+Agents reach for Python first for anything involving data parsing, transformation, or computation.
 
-Agents reach for Python first for anything involving data parsing, transformation, or computation. Reserve the shell tools for tasks that genuinely benefit from a one-liner.
+:::tip
+Reserve the shell tools for tasks that genuinely benefit from a one-liner.
+:::
 
 ## Files {#files}
 
@@ -42,10 +50,15 @@
 
 ## When to use it {#when-to-use-it}
 
-- Parse a CSV or JSON the user uploaded.
-- Compute summary statistics or run a quick simulation.
-- Convert between formats (Parquet, JSON, CSV).
-- Generate a plot from query results.
-- Anything where deterministic computation beats LLM reasoning.
+Reach for the code interpreter when the answer requires deterministic computation that a language model can't produce reliably by reasoning alone.
+Typical cases include:
+
+- Parsing a CSV or JSON file the user uploaded.
+- Computing summary statistics or running a quick simulation.
+- Converting between formats (Parquet, JSON, CSV).
+- Generating a plot from query results.
 
-Avoid it for tasks the model can answer directly. Code execution adds latency and consumes quota.
+:::tip
+Avoid it for tasks the model can already answer from context.
+Code execution adds latency and consumes quota.
+:::

docs/cloud/features/10_AI_ML/agents/builder/image-generation.md

@@ -9,14 +9,18 @@
 ---
 
 import BetaBadge from '@theme/badges/BetaBadge';
+import Image from '@theme/IdealImage';
+import toolsModal from '@site/static/images/cloud/agent-builder/tools-modal.png';
 
 <BetaBadge/>
 
 Image generation lets an agent produce new images from a text prompt or edit images the user has uploaded. The agent picks between generation and editing based on what was asked and the available context.
 
-## Enable it {#enable-it}
+## Enable image generation {#enable-it}
 
-Toggle the image-generation tool in the Agent Builder's capabilities section. Some agents have access to multiple image providers (for example DALL-E and Flux); the agent picks the appropriate one or you can restrict it in instructions.
+Image generation is added through the **Add Tools** modal in the Agent Builder (not the Capabilities section). Click **Add Tools** at the bottom of the Agent Builder panel, then add one of the image-model tools — for example **OpenAI Image Tools**, **DALL-E-3**, or **Stable Diffusion**. The agent picks the appropriate one based on the request, or you can restrict it in instructions.
+
+<Image img={toolsModal} alt="Agent Tools modal showing image-model integrations including OpenAI Image Tools, DALL-E-3, and Stable Diffusion alongside other third-party tools" size="md"/>
 
 ## Generation {#generation}
 

docs/cloud/features/10_AI_ML/agents/builder/index.md

@@ -4,40 +4,27 @@
 title: 'Agent Builder'
 description: 'Create and configure ClickHouse Agents in the Agent Builder'
 keywords: ['AI', 'ClickHouse Cloud', 'agents', 'agent builder', 'tools', 'instructions']
-doc_type: 'reference'
+doc_type: 'landing-page'
 ---
 
 import BetaBadge from '@theme/badges/BetaBadge';
 
 <BetaBadge/>
 
-The Agent Builder is where you create and configure agents. It opens as a side panel in the Cloud console.
+The Agent Builder is where you create and configure agents.
 
-The panel has three sections:
+:::tip New to ClickHouse Agents?
+Start with the [Quickstart](/cloud/features/ai-ml/agents/quickstart). The pages below cover each part of the builder in detail.
+:::
 
-- **Identity** at the top — name, description, avatar, and the instructions field (the system prompt).
-- **Model configuration** in the middle — provider, model, and generation parameters.
-- **Capabilities** at the bottom — the tools, MCP servers, skills, and subagents you attach.
+This section covers each part of the Agent Builder and contains the following pages:
 
-Save from the footer button. Edits take effect on the next conversation; in-flight runs aren't interrupted.
-
-## Identity {#identity}
-
-The instructions field is the agent's system prompt. Describe the role, the kinds of questions it should answer, and any rules it must follow. Be specific about schema conventions, calculated metrics, and terminology if the agent will query your ClickHouse service — the model can't infer your business definitions on its own.
-
-## Core configuration {#core-configuration}
-
-- [Model parameters](/cloud/features/ai-ml/agents/builder/model-parameters) — Pick a model and tune generation parameters. Save a configuration as a named preset to reuse it.
-
-## Built-in tools {#built-in-tools}
-
-- [Code interpreter](/cloud/features/ai-ml/agents/builder/code-interpreter) — Sandboxed code execution.
-- [Web search](/cloud/features/ai-ml/agents/builder/web-search) — Public-web lookups.
-- [Image generation](/cloud/features/ai-ml/agents/builder/image-generation) — Generate images from text.
-- [Vision](/cloud/features/ai-ml/agents/builder/vision) — Accept image inputs.
-
-## Extensibility {#extensibility}
-
-- [MCP servers](/cloud/features/ai-ml/agents/builder/mcp-servers) — Attach third-party MCP servers to an agent.
-- [Skills](/cloud/features/ai-ml/agents/builder/skills) — Reusable instruction packs.
-- [Subagents](/cloud/features/ai-ml/agents/builder/subagents) — Delegate work to child agents.
+| Page | Description |
+|------|-------------|
+| [Code interpreter](/cloud/features/ai-ml/agents/builder/code-interpreter) | Sandboxed code execution. |
+| [Web search](/cloud/features/ai-ml/agents/builder/web-search) | Public-web lookups. |
+| [Image generation](/cloud/features/ai-ml/agents/builder/image-generation) | Generate images from text. |
+| [Vision](/cloud/features/ai-ml/agents/builder/vision) | Accept image inputs. |
+| [MCP servers](/cloud/features/ai-ml/agents/builder/mcp-servers) | Attach third-party MCP servers to an agent. |
+| [Skills](/cloud/features/ai-ml/agents/builder/skills) | Reusable instruction packs. |
+| [Subagents](/cloud/features/ai-ml/agents/builder/subagents) | Delegate work to child agents. |

docs/cloud/features/10_AI_ML/agents/builder/mcp-servers.md

@@ -28,9 +28,9 @@ ClickHouse Agents speaks Streamable HTTP — the production-grade MCP transport.
 
 MCP servers can require credentials. ClickHouse Agents supports:
 
-- **Bearer tokens** and other static headers — fixed values you provide when configuring the server.
-- **OAuth 2.0** — interactive flow. The first time you (or any user with access) calls a tool on the server, the browser opens a sign-in window; tokens are managed and refreshed automatically.
-- **Per-user credentials** — variables in the server config substituted from the calling user's profile, so each user authenticates with their own identity rather than a shared service account.
+- **Bearer tokens** and other static headers - fixed values you provide when configuring the server.
+- **OAuth 2.0** - interactive flow. The first time you (or any user with access) calls a tool on the server, the browser opens a sign-in window; tokens are managed and refreshed automatically.
+- **Per-user credentials** - variables in the server config substituted from the calling user's profile, so each user authenticates with their own identity rather than a shared service account.
 
 User-provided credentials are stored encrypted and scoped to the user who entered them. One user's credentials are never visible to another user's agent runs.
 

docs/cloud/features/10_AI_ML/agents/builder/model-parameters.md

@@ -6,49 +6,52 @@ title: 'Model parameters'
 description: 'Configure model selection and generation parameters for ClickHouse Agents'
 keywords: ['AI', 'ClickHouse Cloud', 'agents', 'model parameters', 'temperature', 'top-p', 'top-k', 'thinking', 'prompt caching']
 doc_type: 'reference'
+draft: true
 ---
 
 import BetaBadge from '@theme/badges/BetaBadge';
 
 <BetaBadge/>
 
-Model parameters control which model an agent uses and how that model generates responses. Configure them in the Agent Builder's **Model Parameters** panel.
+Model parameters control which model an agent uses and how that model generates responses.
+From the **Agent Builder** tab, click **Select a model** under the **Model** heading.
+This will open the **Model Parameters** window.
 
 ## Provider and model {#provider-and-model}
 
-- **Provider** — the upstream LLM provider.
-- **Model** — the specific model from that provider. Different models have different strengths: large reasoning models for planning-heavy tasks, faster small models for routine queries.
+- **Provider** - select the upstream LLM provider.
+- **Model** - select the specific model from that provider. Different models have different strengths: large reasoning models for planning-heavy tasks, faster small models for routine queries.
 
-Provider and model are required. The rest of the panel adapts based on what the selected model supports.
+Both **Provider** and **Model** are required. The rest of the panel adapts based on what the selected model supports.
 
 ## Context and output limits {#context-and-output-limits}
 
-- **Max Context Tokens** — caps total context the agent sends to the model. Leave as **System** to use the model's default. Lower it to reduce cost; raise it for agents that need to reason over large inputs.
-- **Max Output Tokens** — caps the size of the agent's response. **System** uses the model's default. Set lower if responses are too long, higher if they're being cut off.
-- **File Token Limit** — caps how many tokens a single uploaded file contributes to context. Useful when users attach large files and you don't want them to crowd out the rest of the conversation.
+- **Max Context Tokens** - caps total context the agent sends to the model. Leave as **System** to use the model's default. Lower it to reduce cost; raise it for agents that need to reason over large inputs.
+- **Max Output Tokens** - caps the size of the agent's response. **System** uses the model's default. Set lower if responses are too long, higher if they're being cut off.
+- **File Token Limit** - caps how many tokens a single uploaded file contributes to context. Useful when users attach large files and you don't want them to crowd out the rest of the conversation.
 
 ## Sampling {#sampling}
 
-- **Temperature** — randomness. Higher values (0.7–1.0) = more random, while lower values (0.0–0.3) = more focused and deterministic. We recommend altering this or Top P but not both.
-- **Top P** — nucleus sampling. Changes how the model selects tokens for output.
-- **Top K** — restricts sampling to the top K most likely tokens at each step. Supported by some providers; controls determinism along a different axis than temperature.
+- **Temperature** - randomness. Higher values (0.7–1.0) = more random, while lower values (0.0–0.3) = more focused and deterministic. We recommend altering this or Top P but not both.
+- **Top P** - nucleus sampling. Changes how the model selects tokens for output.
+- **Top K** - restricts sampling to the top K most likely tokens at each step. Supported by some providers; controls determinism along a different axis than temperature.
 
-If you're not tuning for a specific behavior, leave the sliders near their defaults — small changes here rarely move the needle and large ones can degrade output quality.
+If you're not tuning for a specific behavior, leave the sliders near their defaults as small changes rarely move the needle and large ones can degrade output quality.
 
 ## Reasoning controls {#reasoning-controls}
 
 Available on models that expose extended reasoning. The exact set varies by provider.
 
-- **Thinking** — toggles the model's extended reasoning mode. When on, the model produces internal thinking tokens before its final answer; this usually improves accuracy on hard tasks at the cost of latency and tokens.
-- **Thinking Budget** — token budget for the thinking phase. The model stops thinking and answers once it has spent this many tokens.
-- **Effort** — high-level reasoning effort dial (**Auto**, low, medium, high). Used by reasoning models that don't expose a thinking-token budget directly.
-- **Thought Visibility** — controls whether the model's thinking is shown to the user inline, hidden behind a collapsed view, or omitted entirely.
+- **Thinking** - this toggles the model's extended reasoning mode. When on, the model produces internal thinking tokens before its final answer; this usually improves accuracy on hard tasks at the cost of latency and tokens.
+- **Thinking Budget** - sets a token budget for the thinking phase. The model stops thinking and answers once it has spent this many tokens.
+- **Effort** - high-level reasoning effort dial (**Auto**, low, medium, high). Used by reasoning models that don't expose a thinking-token budget directly.
+- **Thought Visibility** - this controls whether the model's thinking is shown to the user inline, hidden behind a collapsed view, or omitted entirely.
 
 ## Conversation behavior {#conversation-behavior}
 
-- **Resend Files** — when on, files attached in earlier turns are re-sent on every subsequent turn so the model doesn't lose track of them. Turn off to save tokens if the conversation is short or the model is summarizing files as it goes.
-- **Use Prompt Caching** — when supported by the provider, caches reusable parts of the prompt to reduce cost and latency on conversations where instructions and tool descriptions repeat across turns.
-- **Web Search** — toggles provider-native web search on supported models. This is distinct from the [Web search tool](/cloud/features/ai-ml/agents/builder/web-search), which runs as one of the agent's tools rather than as a provider capability.
+- **Resend Files** - when on, files attached in earlier turns are re-sent on every subsequent turn so the model doesn't lose track of them. Turn off to save tokens if the conversation is short or the model is summarizing files as it goes.
+- **Use Prompt Caching** - when supported by the provider, caches reusable parts of the prompt to reduce cost and latency on conversations where instructions and tool descriptions repeat across turns.
+- **Web Search** - toggles provider-native web search on supported models. This is distinct from the [Web search tool](/cloud/features/ai-ml/agents/builder/web-search), which runs as one of the agent's tools rather than as a provider capability.
 
 ## Reset {#reset}
 

docs/cloud/features/10_AI_ML/agents/builder/skills.md

@@ -40,20 +40,20 @@ When asked to generate a revenue report:
 
 The frontmatter knobs that matter most:
 
-- **`name`** — kebab-case identifier.
-- **`description`** — short summary used by the model to decide when this skill is relevant. Treat this as the most important field. Write it specifically; vague descriptions lead to wrong-skill invocations.
-- **`always-apply`** — when `true`, the skill is primed into every turn instead of being selected. Use sparingly; always-apply skills consume context on every message.
-- **`user-invocable`** — when `true` (the default), the skill appears in the `$` popover for manual selection.
+- **`name`** - kebab-case identifier.
+- **`description`** - short summary used by the model to decide when this skill is relevant. Treat this as the most important field. Write it specifically; vague descriptions lead to wrong-skill invocations.
+- **`always-apply`** - when `true`, the skill is primed into every turn instead of being selected. Use sparingly; always-apply skills consume context on every message.
+- **`user-invocable`** - when `true` (the default), the skill appears in the `$` popover for manual selection.
 
 You can bundle supporting files alongside the skill — reference docs, sample queries, small scripts — by uploading a `.zip` containing the `SKILL.md` and its assets.
 
 ## Use a skill {#use-a-skill}
 
 Three ways an agent reaches for a skill in a conversation:
 
-- **User invocation** — press `$` in the composer and pick the skill from the popover. The skill's content is primed for the next turn.
-- **Model auto-selection** — based on the skill's `description`, the agent decides on its own when to apply it.
-- **Always-apply** — primed on every turn for skills configured that way.
+- **User invocation** - press `$` in the composer and pick the skill from the popover. The skill's content is primed for the next turn.
+- **Model auto-selection** - based on the skill's `description`, the agent decides on its own when to apply it.
+- **Always-apply** - primed on every turn for skills configured that way.
 
 ## Manage skills {#manage-skills}
 

docs/cloud/features/10_AI_ML/agents/builder/subagents.md

@@ -20,16 +20,16 @@ Use subagents to keep a parent agent focused. Long research passes, tool-heavy e
 
 In the Agent Builder, open **Advanced settings** and toggle **Subagents**. Two more controls appear:
 
-- **Allow self-spawn** — when on, the agent can spawn copies of itself for parallel work. Useful for fan-out patterns (one parent, several identical workers).
-- **Additional subagents** — pick specific other agents this parent is allowed to delegate to. The parent decides at runtime which subagent (if any) to call based on the task.
+- **Allow self-spawn** - when on, the agent can spawn copies of itself for parallel work. Useful for fan-out patterns (one parent, several identical workers).
+- **Additional subagents** - pick specific other agents this parent is allowed to delegate to. The parent decides at runtime which subagent (if any) to call based on the task.
 
 Save. When the agent runs, it has a new tool available for invoking subagents.
 
 ## When a subagent helps {#when-a-subagent-helps}
 
-- **Research subtasks** — the parent decomposes a complex question, hands a slice to a subagent specialized for that slice, and synthesizes the responses.
-- **Tool-heavy passes** — code interpreter sessions, multi-step web search loops, or anything that would consume the parent's context with intermediate tool output.
-- **Specialized review** — one agent generates, another reviews, the reviewer's full reasoning stays in its own context window.
+- **Research subtasks** - the parent decomposes a complex question, hands a slice to a subagent specialized for that slice, and synthesizes the responses.
+- **Tool-heavy passes** - code interpreter sessions, multi-step web search loops, or anything that would consume the parent's context with intermediate tool output.
+- **Specialized review** - one agent generates, another reviews, the reviewer's full reasoning stays in its own context window.
 
 Avoid subagents for trivial calls. The handoff adds latency and tokens.