كيفية إنشاء وكيل ذكاء اصطناعي باستخدام LlamaIndex وClickHouse MCP server.

في هذا الدليل، ستتعلّم كيفية إنشاء وكيل ذكاء اصطناعي باستخدام LlamaIndex يمكنه التفاعل مع بيئة SQL التفاعلية الخاصة بـ ClickHouse باستخدام ClickHouse MCP server.

دفتر ملاحظات المثاليمكن العثور على هذا المثال على شكل دفتر ملاحظات في مستودع examples.

المتطلبات الأساسية

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

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

تثبيت المكتبات

ثبّت المكتبات المطلوبة بتنفيذ الأوامر التالية:

pip install -q --upgrade pip
pip install -q llama-index clickhouse-connect llama-index-llms-anthropic llama-index-tools-mcp

إعداد بيانات الاعتماد

بعد ذلك، ستحتاج إلى إدخال مفتاح API الخاص بك في Anthropic:

import os, getpass
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")

Response

Enter Anthropic API Key: ········

استخدام موفّر LLM آخرإذا لم يكن لديك مفتاح واجهة برمجة تطبيقات لـ Anthropic، وكنت تريد استخدام موفّر LLM آخر، فيمكنك العثور على إرشادات إعداد بيانات الاعتماد في وثائق LlamaIndex حول “LLMs”

تهيئة خادم MCP

الآن اضبط ClickHouse MCP server ليتصل بـ ClickHouse SQL playground. ستحتاج إلى تحويلها من دوال بايثون إلى أدوات Llama Index:

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()

إنشاء وكيل

أنت الآن جاهز لإنشاء وكيل يمكنه الوصول إلى تلك الأدوات. حدِّد الحد الأقصى لعدد استدعاءات الأدوات في التشغيل الواحد بـ 10. يمكنك تعديل هذه المعلمة إذا أردت:

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)

تهيئة نموذج اللغة الكبير (LLM)

هيِّئ نموذج Claude Sonnet 4.0 باستخدام الكود التالي:

from llama_index.llms.anthropic import Anthropic
llm = Anthropic(model="claude-sonnet-4-0")

تشغيل الوكيل

أخيرًا، يمكنك توجيه سؤال إلى الوكيل:

response = agent.query("What's the most popular repository?")

الاستجابة طويلة، لذا جرى اختصارها في مثال الاستجابة أدناه:

Response

Added user message to memory: What's the most popular repository?
=== LLM Response ===
I'll help you find the most popular repository. Let me first explore the available databases and tables to understand the data structure.
=== 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 ===
I can see there's a `github` database which likely contains repository data. Let me explore the tables in that database.
=== Calling Function ===
Calling function: list_tables with args: {"database": "github"}
=== Function Output ===
...
...
...
=== LLM Response ===
Based on the GitHub data, **the most popular repository is `sindresorhus/awesome`** with **402,292 stars**.

Here are the top 10 most popular repositories by star count:

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

The `sindresorhus/awesome` repository is a curated list of awesome lists, which explains its popularity as it serves as a comprehensive directory of resources across many different topics in software development.

​المتطلبات الأساسية

المتطلبات الأساسية