> ## 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.

# Início rápido

> Crie e execute seu primeiro ClickHouse Agent em um serviço do ClickHouse Cloud

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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>
                Funcionalidade Beta. 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        Saiba mais.
                    </a>
                </u>
            </span>
        </div>;
};

<BetaBadge />

Crie um agente personalizado no Cloud Console e execute uma consulta em linguagem natural no seu serviço.

<div id="prerequisites">
  ## Pré-requisitos
</div>

* Um serviço do ClickHouse Cloud que você possa consultar.
* A opção **Criar agente** no Agent Builder. Se ela não aparecer, peça a um administrador da organização para conceder permissão para criar agentes em Configurações do Admin, conforme detalhado em [compartilhamento e acesso](/docs/pt-BR/products/cloud/features/ai-ml/agents/sharing-and-access).

<div id="build-the-agent">
  ## Crie o agente
</div>

<Steps>
  <Step title="Inicie o ClickHouse Agents" id="launch-agents">
    No seu serviço Cloud, clique em **ClickHouse agents** na barra lateral esquerda para abrir a central dos agentes. Clique em **Launch ClickHouse agents** para abrir o Agent Builder.

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/launch-ch-agents.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=9b9c85a6e599f3c8e09648ab69d7aba5" alt="Navegação do serviço Cloud com ClickHouse agents (Beta) selecionado, mostrando a central dos agentes com o botão Launch ClickHouse agents" size="lg" width="3836" height="1938" data-path="images/cloud/agent-builder/launch-ch-agents.webp" />
  </Step>

  <Step title="Crie o agente" id="create-the-agent">
    No Agent Builder, clique em **Create New Agent** na parte superior do painel esquerdo. Preencha os campos principais:

    * **Name** - um identificador curto para o seu agente.
    * **Description** - uma descrição da finalidade do agente, que ficará visível para os colegas da equipe.
    * **Category** - uma categoria para o seu agente. Você pode deixar como `General`, a menos que sua organização tenha categorias personalizadas.
    * **Instructions** - o system prompt, que descreve a função do agente, as perguntas que ele deve responder e quaisquer regras de negócio que precise seguir.
    * **Model** - escolha um modelo na lista suspensa.

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/agent-builder.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=25965d81bfc34402ffcc63bcd10ab82b" alt="Painel do Agent Builder mostrando o menu suspenso Create New Agent, os campos do formulário (Name, Description, Category, Instructions, Model) e a seção Capabilities" size="lg" width="3834" height="1932" data-path="images/cloud/agent-builder/agent-builder.webp" />
  </Step>

  <Step title="Adicione recursos e ferramentas" id="attach-tools">
    Os recursos e as ferramentas do agente ficam em dois lugares.

    **Capabilities** no painel principal — recursos nativos como [Run Code](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/code-interpreter), [Web Search](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/web-search), File Context, Artifacts, [MCP Servers](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/mcp-servers) e [Skills](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/skills). Ative os que o agente precisar.

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/capabilities.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=295b4657156542294fa374fc96c6dac2" alt="Seção Capabilities do painel do Agent Builder mostrando os controles de Run Code, Web Search, File Context, Artifacts, MCP Servers e Skills" size="sm" width="616" height="1412" data-path="images/cloud/agent-builder/capabilities.webp" />

    **Tools** no botão **Add Tools** na parte inferior do painel — integrações de terceiros como [image generation](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/image-generation), [vision](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/vision), APIs de busca e serviços externos.

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/tools-button.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=2796d5f96e5943751ed4d04098bd791a" alt="Parte inferior do painel do Agent Builder com o botão Add Tools destacado" size="sm" width="596" height="836" data-path="images/cloud/agent-builder/tools-button.webp" />

    Clique em **Add Tools** para navegar pelo catálogo:

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/tools-modal.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=e98e46712afcbb5aa6347c8b7446ffd2" alt="Modal Agent Tools mostrando uma grade de integrações de terceiros, incluindo Google, OpenAI Image Tools, Wolfram, DALL-E-3, Tavily Search, Calculator e Stable Diffusion" size="lg" width="2560" height="1280" data-path="images/cloud/agent-builder/tools-modal.webp" />

    [Subagents](/docs/pt-BR/products/cloud/features/ai-ml/agents/builder/subagents) são configurados em **Advanced settings** — consulte a página de Subagents para mais detalhes.

    Você pode alterar os recursos e as ferramentas adicionados a qualquer momento.
  </Step>

  <Step title="Execute uma consulta" id="run-a-query">
    Salve o agente, abra uma nova conversa e selecione seu agente no seletor de agentes. Digite uma pergunta — por exemplo, *"Quais são minhas 10 principais tabelas por contagem de linhas nesta semana?"* — e o agente planeja, chama ferramentas conforme necessário e retorna uma resposta.

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/agent-builder/chat-query.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=c3dcfe8f94d8348a1bae938cb8c04f3d" alt="Conversa no chat mostrando a pergunta 'What are my top 10 tables by row count this week?' e a resposta do agente — uma tabela em Markdown classificando as 10 principais tabelas entre os serviços por contagem de linhas, com Key Observations abaixo" size="lg" width="2722" height="1882" data-path="images/cloud/agent-builder/chat-query.webp" />
  </Step>
</Steps>

<div id="next-steps">
  ## Próximos passos
</div>

* [Compartilhe o agente](/docs/pt-BR/products/cloud/features/ai-ml/agents/sharing-and-access) com a equipe.
* Publique no [marketplace](/docs/pt-BR/products/cloud/features/ai-ml/agents/marketplace) quando o agente estiver estável.