> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build and run your first ClickHouse Agent against a ClickHouse Cloud service

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

Build a custom agent in the Cloud console and run a natural-language query against your service.

## Prerequisites

* A ClickHouse Cloud service you can query.
* The **Create agent** option in the Agent Builder. If it's missing, ask an org admin to grant agent creation via Admin Settings as detailed in [sharing and access](https://clickhouse.com/docs/agents/sharing-and-access.md).

## Build the agent

**1. Launch ClickHouse Agents**

From your Cloud service, click **ClickHouse agents** in the left sidebar to open the agents launchpad. Click **Launch ClickHouse agents** to open the Agent Builder.

![Cloud service navigation with ClickHouse agents (Beta) selected, showing the launchpad with the Launch ClickHouse agents button](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/launch-ch-agents.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=7b76b7220ae2e5848fefb70d25e6401c)

**2. Create the agent**

In the Agent Builder, click **Create New Agent** at the top of the left panel. Fill in the core fields:

* **Name** - a short identifier for your agent.
* **Description** - a description of what the agent is for, which will be visible to teammates.
* **Category** - a category for your agent. You can leave this as `General` unless your org has custom categories.
* **Instructions** - the system prompt, which describe the agent's role, the questions it should answer, and any business rules it must follow.
* **Model** - pick a model from the dropdown.

![Agent Builder panel showing the Create New Agent dropdown, the form fields (Name, Description, Category, Instructions, Model), and the Capabilities section](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/agent-builder.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=b18a3db920e9ec695938613037a72578)

**3. Attach capabilities and tools**

The agent's capabilities and tools live in two places.

**Capabilities** in the main panel — first-party features like [Run Code](https://clickhouse.com/docs/agents/builder/code-interpreter.md), [Web Search](https://clickhouse.com/docs/agents/builder/web-search.md), File Context, Artifacts, [MCP Servers](https://clickhouse.com/docs/agents/builder/mcp-servers.md), and [Skills](https://clickhouse.com/docs/agents/builder/skills.md). Toggle the ones the agent needs.

![Capabilities section of the Agent Builder panel showing Run Code, Web Search, File Context, Artifacts, MCP Servers, and Skills toggles](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/capabilities.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=b82e23e834b7b1a8321f80ffc526c936)

**Tools** behind the **Add Tools** button at the bottom of the panel — third-party integrations like [image generation](https://clickhouse.com/docs/agents/builder/image-generation.md), [vision](https://clickhouse.com/docs/agents/builder/vision.md), search APIs, and external services.

![Bottom of the Agent Builder panel with the Add Tools button highlighted](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/tools-button.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=42c611769822a510b7b372437b0ddd70)

Click **Add Tools** to browse the catalog:

![Agent Tools modal showing a grid of third-party integrations including Google, OpenAI Image Tools, Wolfram, DALL-E-3, Tavily Search, Calculator, and Stable Diffusion](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/tools-modal.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=31187ed13e978de4ad88020c060ab2d5)

[Subagents](https://clickhouse.com/docs/agents/builder/subagents.md) are configured under **Advanced settings** — see the subagents page for details.

You can change attached capabilities and tools any time.

**4. Run a query**

Save the agent, open a new conversation, and select your agent from the agent picker. Type a question — for example, *"What are my top 10 tables by row count this week?"* — and the agent plans, calls tools as needed, and returns an answer.

![Chat exchange showing the question 'What are my top 10 tables by row count this week?' and the agent's response — a Markdown table ranking the top 10 tables across services by row count, with Key Observations below](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/chat-query.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=09fc2481502e3af9c35a59641528c8aa)

## Next steps

* [Share the agent](https://clickhouse.com/docs/agents/sharing-and-access.md) with teammates.
* Publish to the [marketplace](https://clickhouse.com/docs/agents/marketplace.md) once the agent is stable.
