trustgraph/docs/tech-specs/tool-services.ar.md

layout	title	parent
default	خدمات الأدوات: أدوات وكيل قابلة للتوصيل ديناميكيًا	Arabic (Beta)

خدمات الأدوات: أدوات وكيل قابلة للتوصيل ديناميكيًا

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

الحالة

تم التنفيذ

نظرة عامة

تحدد هذه المواصفات آلية لأدوات وكيل قابلة للتوصيل ديناميكيًا تسمى "خدمات الأدوات". على عكس أنواع الأدوات المضمنة الحالية (KnowledgeQueryImpl، McpToolImpl، إلخ)، تسمح خدمات الأدوات بإدخال أدوات جديدة عن طريق:

1. نشر خدمة جديدة تعتمد على Pulsar
2. إضافة وصف تهيئة يخبر الوكيل كيفية استدعائها

يتيح ذلك إمكانية التوسع دون تعديل إطار عمل الاستجابة الأساسي للوكيل.

المصطلحات

المصطلح	التعريف
أداة مضمنة	أنواع الأدوات الحالية مع تطبيقات مضمنة في tools.py
خدمة أداة	خدمة Pulsar التي يمكن استدعاؤها كأداة وكيل، ويتم تعريفها بواسطة وصف الخدمة
أداة	نسخة مُكوّنة تشير إلى خدمة أداة، وتُعرض للوكيل/نموذج اللغة الكبير

هذا نموذج من مستويين، مماثل لأدوات MCP: MCP: يحدد خادم MCP واجهة الأداة → إعداد الأداة يشير إليها خدمات الأدوات: تحدد خدمة الأداة واجهة Pulsar → إعداد الأداة يشير إليها

الخلفية: الأدوات الحالية

تنفيذ الأداة المضمنة

يتم تعريف الأدوات حاليًا في trustgraph-flow/trustgraph/agent/react/tools.py مع تطبيقات مُصنّفة:

class KnowledgeQueryImpl:
    async def invoke(self, question):
        client = self.context("graph-rag-request")
        return await client.rag(question, self.collection)

كل نوع أداة: لديه خدمة Pulsar مُبرمجة مسبقًا والتي يستدعيها (مثل: graph-rag-request) يعرف بالضبط الطريقة التي يجب استدعاؤها على العميل (مثل: client.rag()) لديه وسائط مُعرّفة من النوع في التنفيذ

تسجيل الأدوات (service.py:105-214)

يتم تحميل الأدوات من ملف التكوين باستخدام حقل type والذي يربط بتنفيذ:

if impl_id == "knowledge-query":
    impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
elif impl_id == "text-completion":
    impl = TextCompletionImpl
# ... etc

العمارة

نموذج ذو طبقتين

الطبقة الأولى: مُعرّف خدمة الأداة

تحدد خدمة الأداة واجهة خدمة Pulsar. وهي تُعلن عن: قوائم انتظار Pulsar للطلبات/الاستجابات معلمات التكوين التي تتطلبها من الأدوات التي تستخدمها

{
  "id": "custom-rag",
  "request-queue": "non-persistent://tg/request/custom-rag",
  "response-queue": "non-persistent://tg/response/custom-rag",
  "config-params": [
    {"name": "collection", "required": true}
  ]
}

خدمة أداة لا تتطلب أي معلمات تهيئة:

{
  "id": "calculator",
  "request-queue": "non-persistent://tg/request/calc",
  "response-queue": "non-persistent://tg/response/calc",
  "config-params": []
}

المستوى الثاني: وصف الأداة

تشير الأداة إلى خدمة الأداة وتوفر: قيم معلمات التكوين (التي تلبي متطلبات الخدمة) بيانات وصفية للأداة للوكيل (الاسم، الوصف) تعريفات الوسائط لنموذج اللغة الكبيرة (LLM)

{
  "type": "tool-service",
  "name": "query-customers",
  "description": "Query the customer knowledge base",
  "service": "custom-rag",
  "collection": "customers",
  "arguments": [
    {
      "name": "question",
      "type": "string",
      "description": "The question to ask about customers"
    }
  ]
}

يمكن لأدوات متعددة الإشارة إلى نفس الخدمة بتكوينات مختلفة:

{
  "type": "tool-service",
  "name": "query-products",
  "description": "Query the product knowledge base",
  "service": "custom-rag",
  "collection": "products",
  "arguments": [
    {
      "name": "question",
      "type": "string",
      "description": "The question to ask about products"
    }
  ]
}

تنسيق الطلب

عندما يتم استدعاء أداة، يتضمن الطلب المرسل إلى خدمة الأداة ما يلي: user: من طلب الوكيل (دعم تعدد المستأجرين) config: قيم التكوين المشفرة بتنسيق JSON والمستمدة من وصف الأداة arguments: وسائط مشفرة بتنسيق JSON والمستمدة من نموذج اللغة الكبير (LLM)

{
  "user": "alice",
  "config": "{\"collection\": \"customers\"}",
  "arguments": "{\"question\": \"What are the top customer complaints?\"}"
}

تتلقى خدمة الأداة هذه البيانات كقاموسات مُحللة في الطريقة invoke.

تطبيق عام لخدمة الأداة

تستدعي فئة ToolServiceImpl خدمات الأداة بناءً على التكوين:

class ToolServiceImpl:
    def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
        self.request_queue = request_queue
        self.response_queue = response_queue
        self.config_values = config_values  # e.g., {"collection": "customers"}
        # ...

    async def invoke(self, **arguments):
        client = await self._get_or_create_client()
        response = await client.call(user, self.config_values, arguments)
        if isinstance(response, str):
            return response
        else:
            return json.dumps(response)

قرارات التصميم

نموذج التكوين ثنائي الطبقات

تتبع خدمات الأدوات نموذجًا ثنائي الطبقات مشابهًا لأدوات MCP:

1. خدمة الأداة: تحدد واجهة خدمة Pulsar (الموضوع، ومعلمات التكوين المطلوبة).
2. الأداة: تشير إلى خدمة أداة، وتوفر قيم التكوين، وتحدد وسائط LLM.

يسمح هذا الفصل بما يلي: يمكن لخدمة أداة واحدة أن تستخدمها أدوات متعددة بتكوينات مختلفة. تمييز واضح بين واجهة الخدمة وتكوين الأداة. إمكانية إعادة استخدام تعريفات الخدمة.

تعيين الطلبات: تمرير مع الغلاف

الطلب إلى خدمة الأداة هو غلاف منظم يحتوي على: user: يتم تمريره من طلب الوكيل لخدمة العملاء المتعددة. قيم التكوين: من وصف الأداة (مثل collection). arguments: وسائط LLM، يتم تمريرها كقاموس.

يقوم مدير الوكيل بتحليل استجابة LLM إلى act.arguments كقاموس (agent_manager.py:117-154). يتم تضمين هذا القاموس في غلاف الطلب.

معالجة المخططات: غير مُعَرَّفة الأنواع

تستخدم الطلبات والاستجابات قواميس غير مُعَرَّفة الأنواع. لا يوجد تحقق من صحة المخطط على مستوى الوكيل - خدمة الأداة مسؤولة عن التحقق من صحة مدخلاتها. يوفر هذا أقصى قدر من المرونة لتعريف خدمات جديدة.

واجهة العميل: مواضيع Pulsar مباشرة

تستخدم خدمات الأدوات مواضيع Pulsar مباشرة دون الحاجة إلى تكوين التدفق. يحدد وصف خدمة الأداة أسماء قائمة الانتظار الكاملة:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [...]
}

هذا يسمح باستضافة الخدمات في أي مساحة اسم.

معالجة الأخطاء: الاصطلاح القياسي للأخطاء.

تتبع استجابات خدمات الأدوات الاصطلاح الحالي للمخطط مع حقل error:

@dataclass
class Error:
    type: str = ""
    message: str = ""

هيكل الاستجابة: النجاح: إذا كانت error تساوي None، تحتوي الاستجابة على النتيجة. الخطأ: يتم ملء error بـ type و message.

هذا يتوافق مع النمط المستخدم في مخططات الخدمة الحالية (مثل: PromptResponse، QueryResponse، AgentResponse).

الارتباط بين الطلبات والاستجابات

يتم ربط الطلبات والاستجابات باستخدام id في خصائص رسائل Pulsar:

يتضمن الطلب id في الخصائص: properties={"id": id}. تتضمن الاستجابة (أو الاستجابات) نفس id: properties={"id": id}.

هذا يتبع النمط الحالي المستخدم في قاعدة التعليمات البرمجية بأكملها (مثل: agent_service.py، llm_service.py).

دعم التدفق

يمكن لخدمات الأدوات إرجاع استجابات متدفقة:

رسائل استجابة متعددة بنفس id في الخصائص. تتضمن كل استجابة حقل end_of_stream: bool. تحتوي الاستجابة النهائية على end_of_stream: True.

هذا يتوافق مع النمط المستخدم في AgentResponse وخدمات التدفق الأخرى.

معالجة الاستجابة: إرجاع سلسلة نصية

تتبع جميع الأدوات الموجودة نفس النمط: استقبال الوسائط كقاموس، وإرجاع الملاحظة كسلسلة نصية.

الأداة	معالجة الاستجابة
KnowledgeQueryImpl	إرجاع client.rag() مباشرة (سلسلة نصية)
TextCompletionImpl	إرجاع client.question() مباشرة (سلسلة نصية)
McpToolImpl	إرجاع سلسلة نصية، أو json.dumps(output) إذا لم تكن سلسلة نصية
StructuredQueryImpl	تنسيق النتيجة إلى سلسلة نصية
PromptImpl	إرجاع client.prompt() مباشرة (سلسلة نصية)

تتبع خدمات الأدوات نفس العقد: تقوم الخدمة بإرجاع استجابة سلسلة نصية (الملاحظة). إذا لم تكن الاستجابة سلسلة نصية، يتم تحويلها عبر json.dumps(). لا يلزم وجود تكوين استخراج في الوصف.

هذا يبقي الوصف بسيطًا ويضع المسؤولية على الخدمة لإرجاع استجابة نصية مناسبة للوكيل.

دليل التكوين

لإضافة خدمة أداة جديدة، يلزم وجود عنصرين في التكوين:

1. تكوين خدمة الأداة

يتم تخزينها تحت مفتاح التكوين tool-service. تحدد قوائم انتظار Pulsar والمعلمات التكوين المتاحة.

الحقل	مطلوب	الوصف
id	نعم	معرف فريد لخدمة الأداة
request-queue	نعم	موضوع Pulsar الكامل للطلبات (مثل: non-persistent://tg/request/joke)
response-queue	نعم	موضوع Pulsar الكامل للاستجابات (مثل: non-persistent://tg/response/joke)
config-params	لا	مصفوفة من معلمات التكوين التي تقبلها الخدمة

يمكن لكل معلمة تكوين تحديد: name: اسم المعلمة (مطلوب) required: ما إذا كان يجب توفير المعلمة بواسطة الأدوات (افتراضي: خطأ)

مثال:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [
    {"name": "style", "required": false}
  ]
}

2. إعدادات الأداة

يتم تخزينها تحت مفتاح التكوين tool. تحدد أداة يمكن للوكيل استخدامها.

الحقل	مطلوب	الوصف
type	نعم	يجب أن يكون "tool-service"
name	نعم	اسم الأداة المعروضة لنظام LLM
description	نعم	وصف لما تفعله الأداة (يُعرض لنظام LLM)
service	نعم	معرف خدمة الأداة التي سيتم استدعاؤها
arguments	لا	مصفوفة من تعريفات الوسائط لنظام LLM
(معلمات التكوين)	يختلف	أي معلمات تكوين معرفة بواسطة الخدمة

يمكن لكل وسيط تحديد: name: اسم الوسيط (مطلوب) type: نوع البيانات، على سبيل المثال، "string" (مطلوب) description: الوصف المعروض لنظام LLM (مطلوب)

مثال:

{
  "type": "tool-service",
  "name": "tell-joke",
  "description": "Tell a joke on a given topic",
  "service": "joke-service",
  "style": "pun",
  "arguments": [
    {
      "name": "topic",
      "type": "string",
      "description": "The topic for the joke (e.g., programming, animals, food)"
    }
  ]
}

تحميل الإعدادات

استخدم tg-put-config-item لتحميل الإعدادات:

# Load tool-service config
tg-put-config-item tool-service/joke-service < joke-service.json

# Load tool config
tg-put-config-item tool/tell-joke < tell-joke.json

يجب إعادة تشغيل الوكيل الإداري لاستيعاب التكوينات الجديدة.

تفاصيل التنفيذ

المخطط

أنواع الطلبات والاستجابات في trustgraph-base/trustgraph/schema/services/tool_service.py:

@dataclass
class ToolServiceRequest:
    user: str = ""           # User context for multi-tenancy
    config: str = ""         # JSON-encoded config values from tool descriptor
    arguments: str = ""      # JSON-encoded arguments from LLM

@dataclass
class ToolServiceResponse:
    error: Error | None = None
    response: str = ""       # String response (the observation)
    end_of_stream: bool = False

الخادم: خدمة DynamicToolService

الفئة الأساسية في trustgraph-base/trustgraph/base/dynamic_tool_service.py:

class DynamicToolService(AsyncProcessor):
    """Base class for implementing tool services."""

    def __init__(self, **params):
        topic = params.get("topic", default_topic)
        # Constructs topics: non-persistent://tg/request/{topic}, non-persistent://tg/response/{topic}
        # Sets up Consumer and Producer

    async def invoke(self, user, config, arguments):
        """Override this method to implement the tool's logic."""
        raise NotImplementedError()

جانب العميل: ToolServiceImpl

التنفيذ في trustgraph-flow/trustgraph/agent/react/tools.py:

class ToolServiceImpl:
    def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
        # Uses the provided queue paths directly
        # Creates ToolServiceClient on first use

    async def invoke(self, **arguments):
        client = await self._get_or_create_client()
        response = await client.call(user, config_values, arguments)
        return response if isinstance(response, str) else json.dumps(response)

الملفات

الملف	الغرض
trustgraph-base/trustgraph/schema/services/tool_service.py	مخططات الطلبات والاستجابات
trustgraph-base/trustgraph/base/tool_service_client.py	عميل لاستدعاء الخدمات
trustgraph-base/trustgraph/base/dynamic_tool_service.py	الفئة الأساسية لتنفيذ الخدمة
trustgraph-flow/trustgraph/agent/react/tools.py	فئة ToolServiceImpl
trustgraph-flow/trustgraph/agent/react/service.py	تحميل التكوين

مثال: خدمة النكت

مثال لخدمة في trustgraph-flow/trustgraph/tool_service/joke/:

class Processor(DynamicToolService):
    async def invoke(self, user, config, arguments):
        style = config.get("style", "pun")
        topic = arguments.get("topic", "")
        joke = pick_joke(topic, style)
        return f"Hey {user}! Here's a {style} for you:\n\n{joke}"

تكوين خدمة الأداة:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [{"name": "style", "required": false}]
}

إعدادات الأداة:

{
  "type": "tool-service",
  "name": "tell-joke",
  "description": "Tell a joke on a given topic",
  "service": "joke-service",
  "style": "pun",
  "arguments": [
    {"name": "topic", "type": "string", "description": "The topic for the joke"}
  ]
}

التوافق مع الإصدارات السابقة

تظل أنواع الأدوات المدمجة الحالية تعمل دون تغيير. tool-service هو نوع أداة جديد بالإضافة إلى الأنواع الموجودة (knowledge-query، mcp-tool، إلخ).

اعتبارات مستقبلية

الخدمات ذات الإعلان الذاتي

يمكن أن تسمح ترقية مستقبلية للخدمات بنشر أوصافها الخاصة:

تنشر الخدمات إلى موضوع tool-descriptors معروف عند بدء التشغيل. يشترك الوكيل ويسجل الأدوات ديناميكيًا. يتيح ذلك إمكانية التوصيل والتشغيل الحقيقية دون تغييرات في التكوين.

هذا خارج نطاق التنفيذ الأولي.

المراجع

التنفيذ الحالي للأداة: trustgraph-flow/trustgraph/agent/react/tools.py تسجيل الأداة: trustgraph-flow/trustgraph/agent/react/service.py:105-214 مخططات الوكيل: trustgraph-base/trustgraph/schema/services/agent.py