docs(cloud): add ClickHouse Agents

docs/cloud/features/10_AI_ML/AI_chat_overview.md

@@ -1,7 +1,8 @@
 ---
-sidebar_label: 'ClickHouse Assistant agent'
+sidebar_label: 'ClickHouse Assistant'
+sidebar_position: 2
 slug: /cloud/features/ai-ml/ask-ai
-title: 'ClickHouse Assistant agent in Cloud'
+title: 'ClickHouse Assistant in Cloud'
 description: 'Description of the ClickHouse Assistant chat functionality in ClickHouse Cloud'
 doc_type: 'reference'
 ---

docs/cloud/features/10_AI_ML/agents/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "ClickHouse Agents",
+  "collapsible": true,
+  "collapsed": true,
+  "position": 1,
+  "link": { "type": "doc", "id": "cloud/features/AI_ML/agents/index" }
+}

docs/cloud/features/10_AI_ML/agents/builder/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Agent Builder",
+  "collapsible": true,
+  "collapsed": true,
+  "position": 3,
+  "link": { "type": "doc", "id": "cloud/features/AI_ML/agents/builder/index" }
+}

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

@@ -0,0 +1,51 @@
+---
+sidebar_label: 'Code interpreter'
+sidebar_position: 2
+slug: /cloud/features/ai-ml/agents/builder/code-interpreter
+title: 'Code interpreter'
+description: 'Sandboxed code execution in ClickHouse Agents'
+keywords: ['AI', 'ClickHouse Cloud', 'agents', 'code interpreter', 'sandbox', 'python']
+doc_type: 'reference'
+---
+
+import BetaBadge from '@theme/badges/BetaBadge';
+
+<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}
+
+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.
+
+## 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.
+
+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.
+
+## Files {#files}
+
+Users can upload files into a conversation; the code interpreter has access to them in the sandbox working directory. Code can also write output files (CSVs, plots, archives) which appear in the conversation as downloadable attachments.
+
+## Sandbox isolation {#sandbox-isolation}
+
+Each execution runs in an ephemeral sandbox with no network access and no persistent storage. Sessions don't share state — variables and files from one run don't carry into the next unless the agent explicitly re-loads them.
+
+Plan-specific resource limits (memory, files per run, monthly request quotas) apply. Errors and stderr are surfaced in the conversation alongside stdout.
+
+## 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.
+
+Avoid it for tasks the model can answer directly. Code execution adds latency and consumes quota.

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

@@ -0,0 +1,32 @@
+---
+sidebar_label: 'Image generation'
+sidebar_position: 4
+slug: /cloud/features/ai-ml/agents/builder/image-generation
+title: 'Image generation'
+description: 'Generate and edit images inside ClickHouse Agents'
+keywords: ['AI', 'ClickHouse Cloud', 'agents', 'image generation', 'DALL-E', 'Flux', 'Stable Diffusion']
+doc_type: 'reference'
+---
+
+import BetaBadge from '@theme/badges/BetaBadge';
+
+<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}
+
+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.
+
+## Generation {#generation}
+
+When the user asks for an image, the agent calls the generation tool with a prompt and returns the resulting image inline. The agent retains a reference to the image in its context so it can describe or reuse it within the same conversation.
+
+## Editing {#editing}
+
+If the user uploads an image and asks for a modification — change a color, add an object, extend a composition — the agent invokes the editing variant of the tool. The output replaces the relevant region or extends the source as requested.
+
+## Notes {#notes}
+
+- Generated images aren't fed into separate vision analysis automatically. If you need the agent to *interpret* an image, use [vision](/cloud/features/ai-ml/agents/builder/vision) with a user-uploaded image.
+- Provider content policies apply. Prompts that violate the provider's policy return an error rather than an image.

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

@@ -0,0 +1,43 @@
+---
+sidebar_label: 'Overview'
+slug: /cloud/features/ai-ml/agents/builder
+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'
+---
+
+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 panel has three sections:
+
+- **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.
+
+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.

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

@@ -0,0 +1,39 @@
+---
+sidebar_label: 'MCP servers'
+sidebar_position: 8
+slug: /cloud/features/ai-ml/agents/builder/mcp-servers
+title: 'MCP servers'
+description: 'Attaching third-party MCP servers to a ClickHouse Agent'
+keywords: ['AI', 'ClickHouse Cloud', 'agents', 'MCP', 'Model Context Protocol']
+doc_type: 'reference'
+---
+
+import BetaBadge from '@theme/badges/BetaBadge';
+
+<BetaBadge/>
+
+Model Context Protocol (MCP) is the open standard for exposing tools and data sources to an AI model. Attaching an MCP server to a ClickHouse Agent gives the agent access to whatever capabilities that server exposes — issue trackers, observability backends, internal APIs, third-party SaaS, or anything else with an MCP endpoint.
+
+## Attach an MCP server {#attach-an-mcp-server}
+
+In the Agent Builder, open the **MCP servers** section and click **Add server**. Enter the server's URL and authentication settings, then pick which of the server's tools you want this specific agent to use. Save the agent.
+
+You can attach multiple servers to one agent. Each tool the agent calls is logged in the conversation so users can see what the agent did.
+
+## Transport {#transport}
+
+ClickHouse Agents speaks Streamable HTTP — the production-grade MCP transport. The server you attach must be reachable over HTTP(S) from ClickHouse Cloud.
+
+## Authentication {#authentication}
+
+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.
+
+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.
+
+## Limits {#limits}
+
+A single agent run can reference at most 50 distinct MCP server targets and at most 100 expanded tool configurations per request. Agents that need more should be decomposed using [subagents](/cloud/features/ai-ml/agents/builder/subagents).

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

@@ -0,0 +1,55 @@
+---
+sidebar_label: 'Model parameters'
+sidebar_position: 1
+slug: /cloud/features/ai-ml/agents/builder/model-parameters
+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'
+---
+
+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.
+
+## 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 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.
+
+## 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.
+
+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.
+
+## 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.
+
+## 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.
+
+## Reset {#reset}
+
+**Reset Model Parameters** at the bottom of the panel restores every field to system defaults. Use it when you've experimented enough to want a clean starting point.

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

@@ -0,0 +1,69 @@
+---
+sidebar_label: 'Skills'
+sidebar_position: 9
+slug: /cloud/features/ai-ml/agents/builder/skills
+title: 'Skills'
+description: 'Reusable instruction packs for ClickHouse Agents'
+keywords: ['AI', 'ClickHouse Cloud', 'agents', 'skills', 'SKILL.md']
+doc_type: 'reference'
+---
+
+import BetaBadge from '@theme/badges/BetaBadge';
+
+<BetaBadge/>
+
+A skill is a reusable instruction pack an agent can apply on demand. Use skills for procedures that recur across agents — a brand-style guide, a code-review checklist, a runbook for a specific workflow — instead of duplicating the instructions into each agent's system prompt.
+
+## Anatomy of a skill {#anatomy-of-a-skill}
+
+A skill is a Markdown file with a small frontmatter header:
+
+```markdown
+---
+name: revenue-report
+description: Generates the weekly revenue report using our standard segments
+always-apply: false
+user-invocable: true
+---
+
+When asked to generate a revenue report:
+1. Filter to the requested period.
+2. Apply the standard MRR formula:
+     SUM(CASE
+       WHEN billing_cycle = 'monthly' THEN amount
+       WHEN billing_cycle = 'yearly'  THEN amount / 12
+       ELSE 0
+     END)
+3. Break down by segment: Enterprise, Mid-Market, SMB.
+4. Render the result as a Markdown table.
+```
+
+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.
+
+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.
+
+## Manage skills {#manage-skills}
+
+The Skills panel in the Cloud console lets you create skills inline, upload `.md` or `.zip` files, and manage which skills are active for your user. Owned skills default to active; deactivate one to remove it from the popover and the model's catalog without deleting it.
+
+Skills can be shared with other users (see [sharing and access](/cloud/features/ai-ml/agents/sharing-and-access)).
+
+## Skills vs. instructions {#skills-vs-instructions}
+
+- **Agent instructions** define what the agent is and how it behaves overall. Always on for that agent.
+- **Skills** are situational — applied when relevant, scoped to specific workflows.
+
+Reach for a skill when the same set of step-by-step instructions keeps showing up across multiple agents, or when you want it triggered only for specific user requests rather than every turn.

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

@@ -0,0 +1,47 @@
+---
+sidebar_label: 'Subagents'
+sidebar_position: 10
+slug: /cloud/features/ai-ml/agents/builder/subagents
+title: 'Subagents'
+description: 'Delegating work to child agents in ClickHouse Agents'
+keywords: ['AI', 'ClickHouse Cloud', 'agents', 'subagents', 'delegation']
+doc_type: 'reference'
+---
+
+import BetaBadge from '@theme/badges/BetaBadge';
+
+<BetaBadge/>
+
+A subagent is a child agent that a parent agent invokes to handle a self-contained subtask. The child runs with its own context window and its own attached tools, then returns a compact result to the parent. The parent never sees the child's intermediate steps — only the final answer.
+
+Use subagents to keep a parent agent focused. Long research passes, tool-heavy exploration, and specialized review steps work better when their token-heavy intermediate state stays out of the parent's context.
+
+## Enable subagents {#enable-subagents}
+
+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.
+
+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.
+
+Avoid subagents for trivial calls. The handoff adds latency and tokens.
+
+## Subagents vs. agent chain {#subagents-vs-agent-chain}
+
+Subagents are a runtime delegation mechanism — the parent decides on the fly. An agent chain is a pre-defined graph of agents that run in a fixed order. Reach for subagents when the routing is dynamic; reach for a chain when the routing is fixed.
+
+## Limits {#limits}
+
+- Max **10** subagents listed per parent.
+- Max depth of **5** hops from the root agent.
+- Max **50** unique subagent targets loaded for a single run.
+- Max **100** expanded subagent configurations per request.
+
+Subagents you reference must be visible to the user running the parent. References that resolve to an inaccessible or deleted agent are skipped silently — design your parents to handle a missing child gracefully.