mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 05:12:12 +02:00
update more languages
Signed-off-by: Alex Jenkins <kjenkins60@gatech.edu>
This commit is contained in:
Alex Jenkins
parent
835acaa70e
commit
16c2f12a54
249 changed files with 117186 additions and 186 deletions
|
|
@ -1,96 +1,471 @@
|
|||
**تعليمات مهمة:**
|
||||
|
||||
- احتفظ بجميع التنسيقات (العناوين، الروابط، علامات HTML) بشكل صحيح.
|
||||
- لا تترجم أي شي داخل علامات backticks أو كتل التعليمات البرمجية.
|
||||
- قم بإخراج النص المترجم فقط، بدون أي مقدمة أو تفسيرات.
|
||||
|
||||
**النص المراد ترجمته:**
|
||||
|
||||
# خدمات الأداة: أدوات الوكلاء القابلة للتوصيل ديناميكيًا
|
||||
# خدمات الأدوات: أدوات وكيل قابلة للتوصيل ديناميكيًا
|
||||
|
||||
## الحالة
|
||||
|
||||
مُنفَّذ
|
||||
تم التنفيذ
|
||||
|
||||
## نظرة عامة
|
||||
|
||||
يحدد هذا المواصفق آلية لأدوات الوكلاء القابلة للتوصيل ديناميكيًا تسمى "خدمات الأدوات". على عكس أنواع الأدوات المدمجة الموجودة (`KnowledgeService`, `McPTool`), لا تتطلب هذه الطريقة إعداد مسبق.
|
||||
تحدد هذه المواصفات آلية لأدوات وكيل قابلة للتوصيل ديناميكيًا تسمى "خدمات الأدوات". على عكس أنواع الأدوات المضمنة الحالية (`KnowledgeQueryImpl`، `McpToolImpl`، إلخ)، تسمح خدمات الأدوات بإدخال أدوات جديدة عن طريق:
|
||||
|
||||
## مفاهيم أساسية
|
||||
1. نشر خدمة جديدة تعتمد على Pulsar
|
||||
2. إضافة وصف تهيئة يخبر الوكيل كيفية استدعائها
|
||||
|
||||
* **خدمات الأدوات:** مكونات قابلة للتوصيل ديناميكيًا يمكن للوكيل استدعائها.
|
||||
* **الوكيل:** التطبيق الذي يستخدم خدمات الأدوات.
|
||||
* **موضوع الرسائل:** قناة اتصال بين الوكيل وخدمة الأدوات.
|
||||
يتيح ذلك إمكانية التوسع دون تعديل إطار عمل الاستجابة الأساسي للوكيل.
|
||||
|
||||
## التصميم
|
||||
## المصطلحات
|
||||
|
||||
يعمل نظام خدمات الأدوات على مبدأ "الطلب والاستجابة". يقوم الوكيل بإنشاء طلب (رسالة) إلى خدمة الأدوات، وتقوم خدمة الأدوات بمعالجة الطلب وإرجاع استجابة (رسالة) إلى الوكيل.
|
||||
| المصطلح | التعريف |
|
||||
|------|------------|
|
||||
| **أداة مضمنة** | أنواع الأدوات الحالية مع تطبيقات مضمنة في `tools.py` |
|
||||
| **خدمة أداة** | خدمة Pulsar التي يمكن استدعاؤها كأداة وكيل، ويتم تعريفها بواسطة وصف الخدمة |
|
||||
| **أداة** | نسخة مُكوّنة تشير إلى خدمة أداة، وتُعرض للوكيل/نموذج اللغة الكبير |
|
||||
|
||||
## بنية الطلب والاستجابة
|
||||
هذا نموذج من مستويين، مماثل لأدوات MCP:
|
||||
MCP: يحدد خادم MCP واجهة الأداة → إعداد الأداة يشير إليها
|
||||
خدمات الأدوات: تحدد خدمة الأداة واجهة Pulsar → إعداد الأداة يشير إليها
|
||||
|
||||
تستخدم خدمات الأدوات تنسيق رسائل بسيط وموحد لتبادل البيانات بين الوكيل وخدمة الأدوات. تتكون كل رسالة من جزئين:
|
||||
## الخلفية: الأدوات الحالية
|
||||
|
||||
* **الطلب:** يحتوي على بيانات الإدخال المطلوبة لخدمة الأدوات.
|
||||
* **الاستجابة:** تحتوي على نتيجة معالجة الطلب من قبل خدمة الأدوات.
|
||||
### تنفيذ الأداة المضمنة
|
||||
|
||||
## مثال
|
||||
يتم تعريف الأدوات حاليًا في `trustgraph-flow/trustgraph/agent/react/tools.py` مع تطبيقات مُصنّفة:
|
||||
|
||||
لنفترض أن الوكيل يريد معرفة الطقس في مدينة معينة. يمكن للوكيل إنشاء طلب يحتوي على اسم المدينة وإرساله إلى خدمة الطقس. تتلقى خدمة الطقس الطلب، وتحقق من بيانات الطقس، وترسل استجابة تحتوي على معلومات الطقس إلى الوكيل.
|
||||
```python
|
||||
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` والذي يربط بتنفيذ:
|
||||
|
||||
* **خدمة الطقس:** تتلقى طلبًا يحتوي على اسم المدينة وترجع معلومات الطقس.
|
||||
* **محرك البحث:** يتلقى طلبًا يحتوي على عبارة بحث ويرجع قائمة بالنتائج.
|
||||
```python
|
||||
if impl_id == "knowledge-query":
|
||||
impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
|
||||
elif impl_id == "text-completion":
|
||||
impl = TextCompletionImpl
|
||||
# ... etc
|
||||
```
|
||||
|
||||
## مزايا
|
||||
## العمارة
|
||||
|
||||
* **مرونة:** يمكن إضافة خدمات أدوات جديدة دون تعديل الوكيل.
|
||||
* **قابلية التوسع:** يمكن للوكيل استخدام العديد من خدمات الأدوات في وقت واحد.
|
||||
* **سهولة الصيانة:** يمكن تحديث خدمات الأدوات بشكل مستقل عن الوكيل.
|
||||
### نموذج ذو طبقتين
|
||||
|
||||
## الاعتبارات
|
||||
#### الطبقة الأولى: مُعرّف خدمة الأداة
|
||||
|
||||
* يجب أن تكون خدمات الأدوات مصممة لتكون خفيفة الوزن وفعالة.
|
||||
* يجب أن تكون خدمات الأدوات قادرة على التعامل مع طلبات متعددة من وكلاء مختلفين.
|
||||
* يجب أن تكون خدمات الأدوات آمنة وموثوقة.
|
||||
تحدد خدمة الأداة واجهة خدمة Pulsar. وهي تُعلن عن:
|
||||
قوائم انتظار Pulsar للطلبات/الاستجابات
|
||||
معلمات التكوين التي تتطلبها من الأدوات التي تستخدمها
|
||||
|
||||
## مثال
|
||||
```json
|
||||
{
|
||||
"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}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
لنفترض أن الوكيل يريد البحث عن معلومات حول موضوع معين. يمكن للوكيل إنشاء طلب يحتوي على عبارة البحث وإرساله إلى محرك البحث. يتلقى محرك البحث الطلب، ويقوم بإجراء البحث، ويرجع قائمة بالنتائج إلى الوكيل.
|
||||
خدمة أداة لا تتطلب أي معلمات تهيئة:
|
||||
|
||||
## الوحدة (Module)
|
||||
```json
|
||||
{
|
||||
"id": "calculator",
|
||||
"request-queue": "non-persistent://tg/request/calc",
|
||||
"response-queue": "non-persistent://tg/response/calc",
|
||||
"config-params": []
|
||||
}
|
||||
```
|
||||
|
||||
يتم تنظيم نظام خدمات الأدوات في وحدات (modules). كل وحدة مسؤولة عن تنفيذ وظيفة معينة. على سبيل المثال، قد يكون هناك وحدة للطقس ومحرك بحث ووحدة للتحقق من صحة البيانات.
|
||||
#### المستوى الثاني: وصف الأداة
|
||||
|
||||
## واجهات برمجة التطبيقات (APIs)
|
||||
تشير الأداة إلى خدمة الأداة وتوفر:
|
||||
قيم معلمات التكوين (التي تلبي متطلبات الخدمة)
|
||||
بيانات وصفية للأداة للوكيل (الاسم، الوصف)
|
||||
تعريفات الوسائط لنموذج اللغة الكبيرة (LLM)
|
||||
|
||||
توفر وحدات خدمات الأدوات واجهات برمجة تطبيقات (APIs) للوكلاء للتفاعل معها. تتضمن هذه الواجهات ما يلي:
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* **واجهة طلب:** تحدد تنسيق الرسائل المستخدمة لإنشاء طلبات.
|
||||
* **واجهة استجابة:** تحدد تنسيق الرسائل المستخدمة لتلقي الاستجابات.
|
||||
يمكن لأدوات متعددة الإشارة إلى نفس الخدمة بتكوينات مختلفة:
|
||||
|
||||
## الأمان
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
|
||||
## التوثيق
|
||||
```json
|
||||
{
|
||||
"user": "alice",
|
||||
"config": "{\"collection\": \"customers\"}",
|
||||
"arguments": "{\"question\": \"What are the top customer complaints?\"}"
|
||||
}
|
||||
```
|
||||
|
||||
يتم توثيق نظام خدمات الأدوات بشكل كامل. يتضمن التوثيق ما يلي:
|
||||
تتلقى خدمة الأداة هذه البيانات كقاموسات مُحللة في الطريقة `invoke`.
|
||||
|
||||
* **وصف للواجهات:** وصف لواجهات برمجة التطبيقات (APIs) المتاحة.
|
||||
* **أمثلة التعليمات البرمجية:** أمثلة للتعليمات البرمجية توضح كيفية استخدام خدمات الأدوات.
|
||||
* **دليل المستخدم:** دليل المستخدم الذي يشرح كيفية استخدام نظام خدمات الأدوات.
|
||||
### تطبيق عام لخدمة الأداة
|
||||
|
||||
## الإصدارات المستقبلية
|
||||
تستدعي فئة `ToolServiceImpl` خدمات الأداة بناءً على التكوين:
|
||||
|
||||
* **التعلم الآلي:** يمكن استخدام التعلم الآلي لتحسين أداء خدمات الأدوات.
|
||||
* **الذكاء الاصطناعي:** يمكن استخدام الذكاء الاصطناعي لتمكين خدمات الأدوات من أداء مهام أكثر تعقيدًا.
|
||||
* **الأمن:** يمكن تحسين أمان نظام خدمات الأدوات باستخدام تقنيات أمان جديدة.
|
||||
```python
|
||||
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 مباشرة دون الحاجة إلى تكوين التدفق. يحدد وصف خدمة الأداة أسماء قائمة الانتظار الكاملة:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [...]
|
||||
}
|
||||
```
|
||||
|
||||
هذا يسمح باستضافة الخدمات في أي مساحة اسم.
|
||||
|
||||
### معالجة الأخطاء: الاصطلاح القياسي للأخطاء.
|
||||
|
||||
تتبع استجابات خدمات الأدوات الاصطلاح الحالي للمخطط مع حقل `error`:
|
||||
|
||||
```python
|
||||
@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`: ما إذا كان يجب توفير المعلمة بواسطة الأدوات (افتراضي: خطأ)
|
||||
|
||||
مثال:
|
||||
```json
|
||||
{
|
||||
"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 (مطلوب)
|
||||
|
||||
مثال:
|
||||
```json
|
||||
{
|
||||
"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` لتحميل الإعدادات:
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```python
|
||||
@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`:
|
||||
|
||||
```python
|
||||
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`:
|
||||
|
||||
```python
|
||||
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/`:
|
||||
|
||||
```python
|
||||
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}"
|
||||
```
|
||||
|
||||
تكوين خدمة الأداة:
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [{"name": "style", "required": false}]
|
||||
}
|
||||
```
|
||||
|
||||
إعدادات الأداة:
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue