> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/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

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

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

<h2 id="prerequisites">
  Prerequisites
</h2>

* 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](/products/cloud/features/ai-ml/agents/sharing-and-access).

<h2 id="build-the-agent">
  Build the agent
</h2>

<Steps>
  <Step>
    <h3 id="launch-agents">
      Launch ClickHouse Agents
    </h3>

    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.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/launch-ch-agents.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=eb003c363ea35ae4b3a128e7c05aa0f7" alt="Cloud service navigation with ClickHouse agents (Beta) selected, showing the launchpad with the Launch ClickHouse agents button" size="lg" width="3836" height="1938" data-path="images/cloud/agent-builder/launch-ch-agents.png" />
  </Step>

  <Step>
    <h3 id="create-the-agent">
      Create the agent
    </h3>

    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.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/agent-builder.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=d0b3a2968764d7409ca639eb0f338d59" alt="Agent Builder panel showing the Create New Agent dropdown, the form fields (Name, Description, Category, Instructions, Model), and the Capabilities section" size="lg" width="3834" height="1932" data-path="images/cloud/agent-builder/agent-builder.png" />
  </Step>

  <Step>
    <h3 id="attach-tools">
      Attach capabilities and tools
    </h3>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/capabilities.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=377d128f77dee49749200261eee7a2c3" alt="Capabilities section of the Agent Builder panel showing Run Code, Web Search, File Context, Artifacts, MCP Servers, and Skills toggles" size="sm" width="616" height="1412" data-path="images/cloud/agent-builder/capabilities.png" />

    **Tools** behind the **Add Tools** button at the bottom of the panel — third-party integrations like [image generation](/products/cloud/features/ai-ml/agents/builder/image-generation), [vision](/products/cloud/features/ai-ml/agents/builder/vision), search APIs, and external services.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/tools-button.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=4b18f52a2aa9663c09cc719e6bdffffb" alt="Bottom of the Agent Builder panel with the Add Tools button highlighted" size="sm" width="596" height="836" data-path="images/cloud/agent-builder/tools-button.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/tools-modal.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=80cb90aa3290765aeb07f2f9b7420c80" alt="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" size="lg" width="2560" height="1280" data-path="images/cloud/agent-builder/tools-modal.png" />

    [Subagents](/products/cloud/features/ai-ml/agents/builder/subagents) are configured under **Advanced settings** — see the subagents page for details.

    You can change attached capabilities and tools any time.
  </Step>

  <Step>
    <h3 id="run-a-query">
      Run a query
    </h3>

    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.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/cloud/agent-builder/chat-query.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=d55ce37870027c47d6f71d90585cd09e" alt="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" size="lg" width="2722" height="1882" data-path="images/cloud/agent-builder/chat-query.png" />
  </Step>
</Steps>

<h2 id="next-steps">
  Next steps
</h2>

* [Share the agent](/products/cloud/features/ai-ml/agents/sharing-and-access) with teammates.
* Publish to the [marketplace](/products/cloud/features/ai-ml/agents/marketplace) once the agent is stable.