> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Как создать ИИ-агента LlamaIndex с помощью MCP-сервера ClickHouse.

> Узнайте, как создать ИИ-агента LlamaIndex, который может взаимодействовать с MCP-сервером ClickHouse.

В этом руководстве вы узнаете, как создать ИИ-агента [LlamaIndex](https://docs.llamaindex.ai), который
может взаимодействовать с [Песочницей ClickHouse](https://sql.clickhouse.com/) с помощью [MCP-сервера ClickHouse](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Пример ноутбука**

  Этот пример можно найти в виде ноутбука в [репозитории examples](https://github.com/ClickHouse/examples/blob/main/ai/mcp/llamaindex/llamaindex.ipynb).
</Info>

<div id="prerequisites">
  ## Предварительные требования
</div>

* В вашей системе должен быть установлен Python.
* В вашей системе должен быть установлен `pip`.
* Вам понадобится API-ключ Anthropic или API-ключ другого провайдера LLM

Вы можете выполнить следующие шаги либо в Python REPL, либо с помощью скрипта.

<Steps>
  <Step>
    ## Установка библиотек

    Установите необходимые библиотеки, выполнив следующие команды:

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q llama-index clickhouse-connect llama-index-llms-anthropic llama-index-tools-mcp
    ```
  </Step>

  <Step>
    ## Укажите учетные данные

    Далее вам потребуется указать свой API-ключ Anthropic:

    ```python theme={null}
    import os, getpass
    os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
    ```

    ```response title="Response" theme={null}
    Enter Anthropic API Key: ········
    ```

    <Info>
      **Использование другого провайдера LLM**

      Если у вас нет API-ключа Anthropic и вы хотите использовать другого провайдера LLM,
      инструкции по настройке учетных данных можно найти в [документации LlamaIndex "LLMs"](https://docs.llamaindex.ai/en/stable/examples/)
    </Info>
  </Step>

  <Step>
    ## Инициализация MCP-сервера

    Теперь настройте MCP-сервер ClickHouse так, чтобы он указывал на Песочницу ClickHouse.
    Вам потребуется преобразовать их из функций Python в инструменты Llama Index:

    ```python theme={null}
    from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

    mcp_client = BasicMCPClient(
        "uv",
        args=[
            "run",
            "--with", "mcp-clickhouse",
            "--python", "3.13",
            "mcp-clickhouse"
        ],
        env={
            "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
            "CLICKHOUSE_PORT": "8443",
            "CLICKHOUSE_USER": "demo",
            "CLICKHOUSE_PASSWORD": "",
            "CLICKHOUSE_SECURE": "true"
        }
    )

    mcp_tool_spec = McpToolSpec(
        client=mcp_client,
    )

    tools = await mcp_tool_spec.to_tool_list_async()
    ```
  </Step>

  <Step>
    ## Создайте агента

    Теперь вы готовы создать агента, у которого есть доступ к этим инструментам. Установите максимальное
    число вызовов инструментов за один запуск равным 10. При необходимости этот параметр можно изменить:

    ```python theme={null}
    from llama_index.core.agent import AgentRunner, FunctionCallingAgentWorker

    agent_worker = FunctionCallingAgentWorker.from_tools(
        tools=tools,
        llm=llm, verbose=True, max_function_calls=10
    )
    agent = AgentRunner(agent_worker)
    ```
  </Step>

  <Step>
    ## Инициализируйте LLM

    Инициализируйте модель Claude Sonnet 4.0 с помощью следующего кода:

    ```python theme={null}
    from llama_index.llms.anthropic import Anthropic
    llm = Anthropic(model="claude-sonnet-4-0")
    ```
  </Step>

  <Step>
    ## Запустите агент

    Теперь вы можете задать агенту вопрос:

    ```python theme={null}
    response = agent.query("What's the most popular repository?")
    ```

    Ответ довольно длинный, поэтому в примере ниже он сокращён:

    ```response title="Response" theme={null}
    Added user message to memory: What's the most popular repository?
    === LLM Response ===
    Я помогу вам найти самый популярный репозиторий. Сначала давайте изучим доступные базы данных и таблицы, чтобы понять структуру данных.
    === Calling Function ===
    Calling function: list_databases with args: {}
    === Function Output ===
    meta=None content=[TextContent(type='text', text='amazon\nbluesky\ncountry\ncovid\ndefault\ndns\nenvironmental\nfood\nforex\ngeo\ngit\ngithub\nhackernews\nimdb\nlogs\nmetrica\nmgbench\nmta\nnoaa\nnyc_taxi\nnypd\nontime\nopensky\notel\notel_v2\npypi\nrandom\nreddit\nrubygems\nstackoverflow\nstar_schema\nstock\nsystem\ntw_weather\ntwitter\nuk\nwiki\nwords\nyoutube', annotations=None)] isError=False
    === LLM Response ===
    Я вижу базу данных `github`, которая, вероятно, содержит данные о репозиториях. Давайте изучим таблицы в этой базе данных.
    === Calling Function ===
    Calling function: list_tables with args: {"database": "github"}
    === Function Output ===
    ...
    ...
    ...
    === LLM Response ===
    На основе данных GitHub **самым популярным репозиторием является `sindresorhus/awesome`** с **402 292 звёздами**.

    Топ-10 самых популярных репозиториев по количеству звёзд:

    1. **sindresorhus/awesome** - 402,292 stars
    2. **996icu/996.ICU** - 388,413 stars  
    3. **kamranahmedse/developer-roadmap** - 349,097 stars
    4. **donnemartin/system-design-primer** - 316,524 stars
    5. **jwasham/coding-interview-university** - 313,767 stars
    6. **public-apis/public-apis** - 307,227 stars
    7. **EbookFoundation/free-programming-books** - 298,890 stars
    8. **facebook/react** - 286,034 stars
    9. **vinta/awesome-python** - 269,320 stars
    10. **freeCodeCamp/freeCodeCamp** - 261,824 stars

    Репозиторий `sindresorhus/awesome` — это тщательно составленный список «awesome»-списков, что и объясняет его популярность: он служит исчерпывающим каталогом ресурсов по самым разным темам в области разработки программного обеспечения.
    ```
  </Step>
</Steps>