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

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

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

## Pré-requisitos

* 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](https://clickhouse.com/docs/pt-BR/agents/sharing-and-access.md).

## Crie o agente

**1. Inicie o ClickHouse 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.

![Navegação do serviço Cloud com ClickHouse agents (Beta) selecionado, mostrando a central dos agentes com o botão Launch ClickHouse agents](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. Crie o agente**

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.

![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](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/agent-builder.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=b18a3db920e9ec695938613037a72578)

**3. Adicione recursos e ferramentas**

Os recursos e as ferramentas do agente ficam em dois lugares.

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

![Seção Capabilities do painel do Agent Builder mostrando os controles de Run Code, Web Search, File Context, Artifacts, MCP Servers e Skills](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/capabilities.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=b82e23e834b7b1a8321f80ffc526c936)

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

![Parte inferior do painel do Agent Builder com o botão Add Tools destacado](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/tools-button.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=42c611769822a510b7b372437b0ddd70)

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

![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](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/pt-BR/agents/builder/subagents.md) 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.

**4. Execute uma consulta**

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.

![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](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/chat-query.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=09fc2481502e3af9c35a59641528c8aa)

## Próximos passos

* [Compartilhe o agente](https://clickhouse.com/docs/pt-BR/agents/sharing-and-access.md) com a equipe.
* Publique no [marketplace](https://clickhouse.com/docs/pt-BR/agents/marketplace.md) quando o agente estiver estável.
