الدرس 9 من 12

أول أداة للوكيل

نكتب أول أداة للوكيل، وهي حفظ ملاحظة في ملف، ونصفها للنموذج، فيطلبها وينفّذها برنامجنا.

8 دقائق للقراءة

في الدروس السابقة كان الوكيل يتكلم فقط: يقرأ رسالتك، ويكتب رده، ويتذكر المحادثة. ولكنه لا يستطيع أن يفعل شيئًا.

في هذا الدرس نعطيه أداة تحفظ ملاحظاتك في ملف حقيقي على جهازك. وبعدها يصبح الوكيل قادرًا على العمل، لا على الكلام وحده.

ما الأداة؟

النموذج يكتب نصًّا فقط. لا يستطيع أن يحفظ ملفًا، ولا أن يفتح صفحة، ولا أن يشغّل شيئًا على جهازك.

الأداة دالة في برنامجنا، نوضحها للنموذج. فإن احتاج إليها، لا يكتب جوابًا عاديًّا، بل يكتب طلبًا: «شغّل الأداة الفلانية بهذه القيمة». وبرنامجنا هو الذي يقرأ الطلب ويشغّل الدالة.

رحلة الأداةأنت تكتبتذكّر: امتحاني يوم الاثنينالنموذج يطلب أداةsave_noteبرنامجنا يشغّل الدالةsave_note(text)الملف يحفظ الملاحظةnotes.txtالنموذج يطلب، وبرنامجنا هو الذي ينفّذ
رحلة الأداة: تكتب أنت رسالتك، فيطلب النموذج الأداة save_note، ثم يشغّل برنامجنا الدالة، فتُحفظ الملاحظة في الملف notes.txt.

تخيّل مديرًا يملي على مساعدته: «سجّلي هذه الملاحظة». المدير هو النموذج، والمساعدة هي برنامجنا. المدير لا يلمس الخزانة، وإنما المساعدة تفتحها وتضع الورقة فيها.

وللأداة جزءان:

الجزء ما هو؟ في مثالنا
الدالة كود Python الذي يفعل الشيء فعلًا save_note(text) تكتب الملاحظة في ملف
الوصف نص يخبر النموذج باسم الأداة وما تفعل وماذا تحتاج TOOL

وتسمى الأدوات في بعض المصادر استدعاء الدوال (function calling).

نغيّر النموذج

سنستخدم في هذا الدرس النموذج qwen2.5:3b

والسبب أن النموذجين الأصغر، qwen2.5:0.5b وqwen2.5:1.5b، لم يطلبا الأداة في تجاربي، وكانا يردان بجمل عادية. أما qwen2.5:3b فاستطاع طلب الأداة. ويبدو أن استخدام الأدوات يحتاج إلى نموذج أكبر قليلًا.

حمّل النموذج:

ollama pull qwen2.5:3b

حجمه نحو 1.9 GB، وهو أكبر من النموذجين السابقين، وردّه أبطأ.

الخطوة الأولى: ملف الأداة

نضع كل أداة في ملف خاص بها، ونسمّي الملف باسم الأداة. أنشئ ملفًا اسمه save_note.py بجانب agent.py. وأنشئه بالطريقة التي تفضّلها، فلا حاجة إلى أداة معينة.

واكتب فيه الدالة أولًا:

def save_note(text):
    with open("notes.txt", "a") as f:
        f.write(text + "\n")
    return "Saved: " + text
السطر ماذا يفعل؟
def save_note(text): دالة اسمها save_note، تأخذ الملاحظة في المتغير text.
open("notes.txt", "a") يفتح الملف notes.txt لـالإضافة في آخره. الحرف "a" اختصار append، أي «أضف». وهو يبقي ما كُتب سابقًا.
f.write(text + "\n") يكتب الملاحظة ثم ينتقل إلى سطر جديد.
return "Saved: " + text يعيد رسالة قصيرة تقول ماذا حدث.

ثم اكتب تحتها وصف الأداة، وهو ما سيقرؤه النموذج:

TOOL = {
    "type": "function",
    "function": {
        "name": "save_note",
        "description": "Save a note for the user",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {"type": "string", "description": "The note to save"},
            },
            "required": ["text"],
        },
    },
}
الجزء ماذا يعني؟
"type": "function" نوع الأداة: دالة.
"name": "save_note" اسم الأداة، وهو اسم الدالة نفسه.
"description" جملة تشرح للنموذج متى يستخدمها. وكلما كانت واضحة كان اختياره أصح.
"parameters" ما تحتاج الأداة إلى أن يعطيها النموذج.
"properties" الحقول المطلوبة، ولكل حقل اسم ونوع ووصف. عندنا حقل واحد اسمه text، نوعه string أي نص.
"required": ["text"] الحقول التي يجب أن يعطيها النموذج، وهنا text.

ولماذا "type": "object" مع أن لدينا حقلًا واحدًا؟ لأن الأدوات تصف ما تحتاج إليه دائمًا على شكل كائن فيه حقول بأسمائها. فإن أضفنا حقلًا ثانيًا، مثل title، وضعناه بجانب text ولا يتغير شيء آخر.

احفظ الملف.

الخطوة الثانية: نخبر النموذج بالأداة

نعدّل الآن agent.py بثلاثة تغييرات صغيرة. كل سطر باللون الأحمر وعليه - يُحذف، وكل سطر باللون الأخضر وعليه + يُضاف.

أولًا: نستورد الأداة، ونغيّر اسم النموذج:

import jsonimport osimport urllib.requestfrom save_note import save_note, TOOLURL = "http://localhost:11434/v1/chat/completions"MODEL = "qwen2.5:1.5b"MODEL = "qwen2.5:3b"FILE = "memory.json"

ثانيًا: نغيّر رسالة القواعد، لنقول للنموذج متى يستخدم الأداة:

else:    messages = [        {"role": "system", "content": "You are a note keeper, Answer briefly"},        {"role": "system", "content": "You are a note keeper. When the user tells you something to remember, use the save_note tool."},    ]

والترجمة: «أنت حافظ ملاحظات. حين يخبرك المستخدم بشيء ليتذكره، فاستخدم أداة save_note».

ثالثًا: نرسل وصف الأداة مع كل طلب، ونجعل الدالة تعيد الرسالة كلها وليس نصها فقط:

def ask_model(messages):    body = json.dumps({"model": MODEL, "messages": messages}).encode()    body = json.dumps({"model": MODEL, "messages": messages, "tools": [TOOL]}).encode()    request = urllib.request.Request(URL, body, {"Content-Type": "application/json"})    with urllib.request.urlopen(request) as response:        data = json.load(response)        return data["choices"][0]["message"]["content"]        return data["choices"][0]["message"]

الجديد هو "tools": [TOOL]: نرسل قائمة الأدوات بجانب الرسائل. وهي الآن قائمة فيها أداة واحدة.

ونعيد الرسالة كلها لأن طلب الأداة لا يأتي في content، بل في جزء آخر من الرسالة، كما سنرى الآن.

الخطوة الثالثة: ننفّذ طلب النموذج

حين يطلب النموذج أداة، تبدو رسالته هكذا. طبعتُها مرة واحدة بسطر print(message) لأراها:

ما ظهر لي حين جرّبتُ

{'role': 'assistant', 'content': '', 'tool_calls': [{'id': 'call_sadcetuk', 'index': 0, 'type': 'function', 'function': {'name': 'save_note', 'arguments': '{"text":"My exam is on Monday"}'}}]}

وهذه هي الرسالة نفسها بعد أن رتّبتُها في أسطر لتسهل قراءتها. الترتيب مني، والمحتوى كما ظهر:

{
    'role': 'assistant',
    'content': '',
    'tool_calls': [
        {
            'id': 'call_sadcetuk',
            'index': 0,
            'type': 'function',
            'function': {
                'name': 'save_note',
                'arguments': '{"text":"My exam is on Monday"}',
            },
        },
    ],
}

لاحظ ما فيها:

الجزء ماذا يعني؟
'content': '' النص فارغ. لم يكتب النموذج جوابًا عاديًّا.
'tool_calls' قائمة طلبات الأدوات. هذا هو الجزء الذي يهمنا.
'id': 'call_sadcetuk' رقم هذا الطلب. وسنحتاج إليه حين نعيد النتيجة.
'name': 'save_note' الأداة التي يريدها.
'arguments': '{"text":"My exam is on Monday"}' القيم التي يعطيها للأداة، وهي نص بصيغة JSON: الملاحظة هي «My exam is on Monday».

الآن نكتب الجزء الذي يقرأ هذا الطلب وينفّذه. غيّر الحلقة في آخر agent.py هكذا:

while True:    text = input("You: ")    if text == "exit":        break    messages.append({"role": "user", "content": text})    reply = ask_model(messages)    print("Agent: ", reply)    messages.append({"role": "assistant", "content": reply})    message = ask_model(messages)    messages.append(message)    if message.get("tool_calls"):        for call in message["tool_calls"]:            args = json.loads(call["function"]["arguments"])            result = save_note(**args)            print("Tool: ", result)            messages.append({"role": "tool", "tool_call_id": call["id"], "content": result})    else:        print("Agent: ", message["content"])    with open(FILE, "w") as f:        json.dump(messages, f)
السطر ماذا يفعل؟
message = ask_model(messages) نأخذ رسالة النموذج كلها.
messages.append(message) نضيفها إلى القائمة، كما كنا نفعل برده.
if message.get("tool_calls"): هل في الرسالة طلب أداة؟
for call in message["tool_calls"]: نمرّ على كل طلب، وقد يطلب النموذج أكثر من أداة.
args = json.loads(call["function"]["arguments"]) نحوّل نص JSON إلى قاموس Python: {"text": "My exam is on Monday"}.
result = save_note(**args) نشغّل الدالة ونعطيها القيم. والعلامتان ** تفرّقان القاموس إلى حقوله.
print("Tool: ", result) نعرض ما أعادته الدالة.
messages.append({"role": "tool", ...}) نخزّن النتيجة في القائمة بدور جديد اسمه tool، ومعها رقم الطلب.
else: print("Agent: ", ...) وإن لم يكن هناك طلب أداة، فالرد عادي ونعرضه كما كنا.

ولاحظ أن الدور tool رابع الأدوار بعد system وuser وassistant.

الملف كاملًا

import json
import os
import urllib.request
from save_note import save_note, TOOL

URL = "http://localhost:11434/v1/chat/completions"
MODEL = "qwen2.5:3b"
FILE = "memory.json"

if os.path.exists(FILE):
    with open(FILE) as f:
        messages = json.load(f)
else:
    messages = [
        {"role": "system", "content": "You are a note keeper. When the user tells you something to remember, use the save_note tool."},
    ]


def ask_model(messages):
    body = json.dumps({"model": MODEL, "messages": messages, "tools": [TOOL]}).encode()
    request = urllib.request.Request(URL, body, {"Content-Type": "application/json"})
    with urllib.request.urlopen(request) as response:
        data = json.load(response)
        return data["choices"][0]["message"]


while True:
    text = input("You: ")
    if text == "exit":
        break
    messages.append({"role": "user", "content": text})
    message = ask_model(messages)
    messages.append(message)
    if message.get("tool_calls"):
        for call in message["tool_calls"]:
            args = json.loads(call["function"]["arguments"])
            result = save_note(**args)
            print("Tool: ", result)
            messages.append({"role": "tool", "tool_call_id": call["id"], "content": result})
    else:
        print("Agent: ", message["content"])
    with open(FILE, "w") as f:
        json.dump(messages, f)

وإن كان في مجلدك ملف memory.json قديم، فاحذفه قبل أن تبدأ، لأن فيه رسالة القواعد القديمة:

rm -f memory.json

شغّله

python3 agent.py

اكتب Remember, my exam is on Monday، وانتظر، ثم اكتب exit. وبعدها اعرض الملف الذي كتبته الأداة:

cat notes.txt

ما ظهر لي حين جرّبتُ

$ python3 agent.py
You: Remember, my exam is on Monday
Tool:  Saved: my exam is on Monday
You: exit
$ cat notes.txt
my exam is on Monday

ترجمة ما جرى:

  • أنا: «Remember, my exam is on Monday»، أي «تذكّر، امتحاني يوم الاثنين».
  • الأداة: «Saved: my exam is on Monday»، أي «تم الحفظ: امتحاني يوم الاثنين».
  • الملف notes.txt فيه الملاحظة.

هذا هو الفرق الكبير عن الدرس السابق: الملاحظة موجودة الآن في ملف حقيقي، وقد كتبها الوكيل بنفسه حين طلب النموذج الأداة. افتح notes.txt بأي محرر لتراها.

ما الذي ما زال ناقصًا؟

لاحظ أن الوكيل لم يرد علينا بكلام بعد حفظ الملاحظة. طبع سطر Tool: فقط وانتظر.

السبب أن النموذج لا يعرف أن الأداة نُفّذت ونجحت. نحن لم نرسل إليه النتيجة بعد. وفي الدرس القادم نرسلها إليه، فيقرأ «Saved» ثم يجيبك جملة عادية، مثل «سجّلتُ ملاحظتك». وبهذا تكتمل دورة الوكيل: النموذج يطلب، وبرنامجنا ينفّذ، ثم يرجع الجواب إلى النموذج.

ماذا تلاحظ؟

  • كم مرة شغّلتَ الأداة؟ شغّل الوكيل وقل له شيئين مختلفين، ثم افتح notes.txt. هل فيه سطران؟
  • اكتب رسالة لا تطلب فيها حفظ شيء، مثل hello. هل طلب النموذج الأداة؟ أم أجابك بجملة؟
  • افتح memory.json وابحث عن tool_calls. هل وجدت طلب الأداة محفوظًا؟

اختبر نفسك

لماذا يكتب النموذج طلب الأداة ولا يشغّلها بنفسه؟

اعرض الجواب

لأن النموذج يكتب نصًّا فقط. هو لا يملك يدًا تفتح ملفًا. فيكتب طلبًا، وبرنامجنا هو الذي ينفّذه. وهذا يعني أننا نتحكم في ما يستطيع الوكيل فعله: لا يفعل إلا ما كتبنا له من دوال.

ما الذي تعلّمناه؟

  • الأداة دالة في برنامجنا نصفها للنموذج. وهي تتكون من الدالة نفسها ومن وصفها.
  • النموذج يطلب الأداة بنص خاص اسمه tool_calls، وبرنامجنا ينفّذها.
  • وصف الأداة فيه اسمها وشرحها وحقولها، ونرسله مع كل طلب في "tools".
  • نحتاج إلى نموذج أكبر قليلًا ليطلب الأدوات: qwen2.5:3b طلبها في تجاربي، ولم يطلبها النموذجان الأصغر.
  • نخزّن نتيجة الأداة في القائمة بدور جديد اسمه tool.
  • ما زال ينقص أن نرسل النتيجة إلى النموذج، وهذا هو الدرس القادم.