AI Agents · درس

إرجاع النتائج إلى النموذج

نسّق مخرجات الأدوات كرسائل ذات دور tool حتى يتمكن النموذج من قراءتها ومواصلة المحادثة.

الدرس 4 من 413 خطوة

إرجاع النتائج إلى النموذج درس مجاني في AI Agents على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في AI Agents، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة AI Agents 4 دروس في المجموع.

رسالة نتيجة الأداة

بعد تشغيل أداة، أخبروا النموذج بالنتيجة باستخدام رسالة أداة:

messages.append({
    'role': 'tool',
    'tool_call_id': tool_call.id,    # MUST match the assistant's tool_call.id
    'content': json.dumps(result)
})

يجب أن يكون المحتوى سلسلة نصية

يتوقع OpenAI أن يكون content سلسلة نصية. حوّلوا الكائنات إلى نص باستخدام json.dumps:

# Bad — will error
messages.append({'role': 'tool', 'tool_call_id': id, 'content': {'temp': 18}})

# Good
messages.append({'role': 'tool', 'tool_call_id': id, 'content': '{"temp": 18}'})

تنسيق Anthropic

يستخدم Anthropic كتلة محتوى داخل رسالة من المستخدم:

messages.append({
    'role': 'user',
    'content': [{
        'type': 'tool_result',
        'tool_use_id': 'toolu_abc',
        'content': json.dumps(result)
    }]
})

إرجاع الأخطاء

إذا فشلت الأداة، فأعيدوا الخطأ — لا تتظاهروا بنجاحها. يستطيع النموذج معالجة الخطأ:

try:
    result = run_tool(...)
    content = json.dumps({'ok': True, 'data': result})
except Exception as e:
    content = json.dumps({'ok': False, 'error': str(e)})

messages.append({'role': 'tool', 'tool_call_id': id, 'content': content})

نمط النتائج المتعددة

بالنسبة إلى استدعاءات الأدوات المتوازية، أضيفوا كل نتيجة مع المعرّف المطابق لها:

for tc in message.tool_calls:
    result = dispatch(tc)
    messages.append({
        'role': 'tool',
        'tool_call_id': tc.id,
        'content': json.dumps(result)
    })

المخرجات الكبيرة: تلخيصها

إذا أعادت أداة 100KB من HTML، فإن إرسالها كاملةً إلى النموذج يهدر الرموز ويشتت الانتباه. لخّصوها أو اقتطعوها أولًا:

def truncate(text, max_chars=4000):
    if len(text) <= max_chars:
        return text
    return text[:max_chars] + f'\n...[truncated, {len(text)-max_chars} more chars]'

sample = "x" * 4500
result = truncate(sample, max_chars=50)
print(result)

مخطط ثابت دائمًا

حتى عندما تختلف النتائج (نجاح / خطأ / غير موجود)، حافظوا على ثبات مخطط المخرجات. يكون النموذج أكثر موثوقية مع البنى المتسقة:

from typing import TypedDict, Literal, Optional, Any

class ToolResult(TypedDict):
    status: Literal['ok', 'not_found', 'error']
    data: Optional[Any]
    error: Optional[str]

def make_result(status, data=None, error=None) -> ToolResult:
    return {'status': status, 'data': data, 'error': error}

print(make_result('ok', data={'temp': 72}))
print(make_result('not_found', error='city not found'))

تضمين تلميحات البيانات الوصفية

ساعدوا النموذج على تفسير النتائج من خلال تضمين تلميحات في المحتوى:

content = json.dumps({
    'data': rows,
    'note': 'Returned 50 rows (most recent first). There may be more matches.'
})

البيانات الثنائية

لا تضعوا الكتل الكبيرة بترميز base64 داخل رسائل الأدوات. بدلًا من ذلك، احفظوها في وحدة تخزين وأعيدوا عنوان URL أو معرّفًا:

result = {
    'image_path': '/tmp/chart-abc.png',
    'thumbnail_url': 'https://...',
    'caption': 'Sales by quarter, 2024'
}
for k, v in result.items():
    print(f"{k}: {v}")

استدعاء النموذج مجددًا

بعد إضافة جميع نتائج الأدوات، استدعوا النموذج مجددًا — فإما أن ينتج إجابة نهائية أو يستدعي أدوات أخرى:

class Msg:
    def __init__(self, tool_calls=None, content=None):
        self.tool_calls = tool_calls or []
        self.content = content

class ToolCall:
    def __init__(self, name, args):
        self.name = name
        self.args = args

def call_model(messages, tools):
    if len(messages) < 4:
        return Msg(tool_calls=[ToolCall('get_weather', {'city': 'Paris'})])
    return Msg(content='It is sunny in Paris.')

messages = [{'role': 'user', 'content': 'Weather in Paris?'}]
tools = ['get_weather']
message = call_model(messages, tools)

while message.tool_calls:
    for tc in message.tool_calls:
        result = f'Result of {tc.name}({tc.args})'
        messages.append({'role': 'tool', 'name': tc.name, 'content': result})
        print('Tool call:', tc.name, '->', result)
    message = call_model(messages, tools)

print('Final answer:', message.content)

تدقيق مخرجات الأدوات

سجّلوا كل زوج (tool_call_id، args، result) لأغراض تصحيح الأخطاء. عندما يتصرف الوكيل بطريقة غريبة، يكون سجل نتائج الأدوات أول مكان ينبغي فحصه.

تنسيق نتيجة الأداة

إلى ماذا يشير tool_call_id في رسالة أداة؟

مراجعة

أصبحتم الآن تملكون دورة استدعاء الأدوات الكاملة ذهابًا وإيابًا. الدورة التالية: الذاكرة — الركيزة الثالثة للوكلاء.

البدء مجانًا

تعلم AI Agents مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات
60
الدروس
239

الأسئلة الشائعة

هل درس «إرجاع النتائج إلى النموذج» مجاني؟

نعم — نص درس «إرجاع النتائج إلى النموذج» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة AI Agents، انتقل إلى CoddyKit PRO. تتضمن دورة AI Agents 4 دروس في المجموع.

ماذا ستتعلم في «إرجاع النتائج إلى النموذج»؟

نسّق مخرجات الأدوات كرسائل ذات دور tool حتى يتمكن النموذج من قراءتها ومواصلة المحادثة. تتمرن على AI Agents مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ AI Agents؟

لا تُشترط خبرة سابقة. AI Agents على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «إرجاع النتائج إلى النموذج»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس AI Agents هذا؟

نعم. كل درس في AI Agents يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. كيف يعمل استدعاء الدوال
  2. تعريف مخططات الأدوات (JSON Schema)
  3. اختيار الأدوات أثناء التشغيل
  4. إرجاع النتائج إلى النموذج
← العودة إلى AI Agents