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

# كيفية إنشاء AI Agent باستخدام Agno وخادم ClickHouse MCP

> تعرّف على كيفية إنشاء AI Agent باستخدام Agno وخادم ClickHouse MCP

في هذا الدليل، ستتعلّم كيفية إنشاء AI Agent باستخدام [Agno](https://github.com/agno-agi/agno) يمكنه التفاعل مع
[بيئة SQL التفاعلية الخاصة بـ ClickHouse](https://sql.clickhouse.com/) باستخدام [خادم ClickHouse MCP](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **دفتر ملاحظات المثال**

  يمكن العثور على هذا المثال على شكل دفتر ملاحظات في [مستودع الأمثلة](https://github.com/ClickHouse/examples/blob/main/ai/mcp/agno/agno.ipynb).
</Info>

<div id="prerequisites">
  ## المتطلبات الأساسية
</div>

* ستحتاج إلى تثبيت بايثون على نظامك.
* ستحتاج إلى تثبيت `pip` على نظامك.
* ستحتاج إلى مفتاح API من Anthropic أو مفتاح API من موفّر LLM آخر

يمكنك تنفيذ الخطوات التالية إما من خلال بيئة REPL الخاصة ببايثون أو عبر برنامج نصي.

<Steps>
  <Step title="تثبيت المكتبات" id="install-libraries">
    ثبّت مكتبة Agno عبر تشغيل الأوامر التالية:

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q agno
    pip install -q ipywidgets
    ```
  </Step>

  <Step title="إعداد بيانات الاعتماد" id="setup-credentials">
    بعد ذلك، ستحتاج إلى إدخال مفتاح واجهة برمجة تطبيقات 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 آخر،
      فيمكنك العثور على إرشادات إعداد بيانات الاعتماد في [وثائق Agno](https://docs.agno.com/models/overview)
    </Info>

    بعد ذلك، حدِّد بيانات الاعتماد اللازمة للاتصال بـ ClickHouse SQL playground:

    ```python theme={null}
    env = {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
    }
    ```
  </Step>

  <Step title="تهيئة MCP server ووكيل Agno" id="initialize-mcp-and-agent">
    الآن اضبط ClickHouse MCP server بحيث يشير إلى بيئة ClickHouse SQL التفاعلية،
    وقم أيضًا بتهيئة وكيل Agno واطرح عليه سؤالًا:

    ```python theme={null}
    from agno.agent import Agent
    from agno.tools.mcp import MCPTools
    from agno.models.anthropic import Claude
    ```

    ```python theme={null}
    async with MCPTools(command="uv run --with mcp-clickhouse --python 3.13 mcp-clickhouse", env=env, timeout_seconds=60) as mcp_tools:
        agent = Agent(
            model=Claude(id="claude-3-5-sonnet-20240620"),
            markdown=True,
            tools = [mcp_tools]
        )
    await agent.aprint_response("What's the most starred project in 2025?", stream=True)
    ```

    ```response title="Response" theme={null}
    ▰▱▱▱▱▱▱ Thinking...
    ┏━ Message ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃                                                                                                                 ┃
    ┃ What's the most starred project in 2025?                                                                        ┃
    ┃                                                                                                                 ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
    ┏━ Tool Calls ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃                                                                                                                 ┃
    ┃ • list_tables(database=github, like=%)                                                                          ┃
    ┃ • run_select_query(query=SELECT                                                                                 ┃
    ┃     repo_name,                                                                                                  ┃
    ┃     SUM(count) AS stars_2025                                                                                    ┃
    ┃ FROM github.repo_events_per_day                                                                                 ┃
    ┃ WHERE event_type = 'WatchEvent'                                                                                 ┃
    ┃     AND created_at >= '2025-01-01'                                                                              ┃
    ┃     AND created_at < '2026-01-01'                                                                               ┃
    ┃ GROUP BY repo_name                                                                                              ┃
    ┃ ORDER BY stars_2025 DESC                                                                                        ┃
    ┃ LIMIT 1)                                                                                                        ┃
    ┃                                                                                                                 ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
    ┏━ Response (34.9s) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃                                                                                                                 ┃
    ┃ To answer your question about the most starred project in 2025, I'll need to query the ClickHouse database.     ┃
    ┃ However, before I can do that, I need to gather some information and make sure we're looking at the right data. ┃
    ┃ Let me check the available databases and tables first.Thank you for providing the list of databases. I can see  ┃
    ┃ that there's a "github" database, which is likely to contain the information we're looking for. Let's check the ┃
    ┃ tables in this database.Now that we have information about the tables in the github database, we can query the  ┃
    ┃ relevant data to answer your question about the most starred project in 2025. We'll use the repo_events_per_day ┃
    ┃ table, which contains daily event counts for each repository, including star events (WatchEvents).              ┃
    ┃                                                                                                                 ┃
    ┃ Let's create a query to find the most starred project in 2025:Based on the query results, I can answer your     ┃
    ┃ question about the most starred project in 2025:                                                                ┃
    ┃                                                                                                                 ┃
    ┃ The most starred project in 2025 was deepseek-ai/DeepSeek-R1, which received 84,962 stars during that year.     ┃
    ┃                                                                                                                 ┃
    ┃ This project, DeepSeek-R1, appears to be an AI-related repository from the DeepSeek AI organization. It gained  ┃
    ┃ significant attention and popularity among the GitHub community in 2025, earning the highest number of stars    ┃
    ┃ for any project during that year.                                                                               ┃
    ┃                                                                                                                 ┃
    ┃ It's worth noting that this data is based on the GitHub events recorded in the database, and it represents the  ┃
    ┃ stars (WatchEvents) accumulated specifically during the year 2025. The total number of stars for this project   ┃
    ┃ might be higher if we consider its entire lifespan.                                                             ┃
    ┃                                                                                                                 ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
    ```
  </Step>
</Steps>