الدرس 6 من 10

Tool Runner و tool_choice

بعد ما فهمت الـ loop من جوه، استخدم الاختصار.

الـ Tool Runner

الـ loop اللي كتبناه (ابعت، شوف stop_reason، نفّذ، رجّع النتايج، كرر) بيتكرر في كل مشروع. الـ Anthropic SDK فيه Tool Runner بيعمله لوحده: بتكتب الأدوات كدوال عادية بـ decorator اسمه @beta_tool، وهو يطلع الـ schema من الـ type hints والـ docstring (زي اللي بنيناه في الدرس ٣ بالظبط)، ويدير الـ loop والأخطاء.

tool_runner.py
import json
import anthropic
from anthropic import beta_tool
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()

ORDERS = {"1024": {"status": "out for delivery", "eta": "today before 9 PM"}}

@beta_tool
def get_order_status(order_id: str) -> str:
    """Get the status and delivery estimate of an order.

    Args:
        order_id: The 4-digit order number.
    """
    if order_id not in ORDERS:
        raise ValueError(f"No order {order_id}. Ask the customer to check the number.")
    return json.dumps(ORDERS[order_id])

final = client.beta.messages.tool_runner(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[get_order_status],
    messages=[{"role": "user", "content": "أوردر 1024 هيوصل إمتى؟"}],
).until_done()                          # runs the whole loop for you

for block in final.content:
    if block.type == "text":
        print(block.text)

لو الأداة رمت exception، الـ runner بيمسكه ويرجعه للموديل كنتيجة فيها is_error، فالموديل يقدر يتصرف. نفس الـ dispatcher اللي كتبناه بإيدنا.

💡 إمتى تكتب الـ loop بإيدك؟لما تحتاج تتحكم في حاجة جوه الدورة: موافقة بني آدم قبل أداة معينة، أو تسجيل مفصل لكل خطوة، أو حد للتكلفة، أو إنك توقف في النص. في الحالات البسيطة الـ runner أنضف.

التحكم في استخدام الأدوات: tool_choice

القيمةمعناهاإمتى
{"type": "auto"}الموديل يقرر يستخدم أداة ولا يرد على طول (الافتراضي)أغلب الحالات
{"type": "any"}لازم يستخدم أداة، أي واحدةلما لازم يتصرف مش يتكلم
{"type": "tool", "name": "..."}لازم يستخدم الأداة دي بالذاتاستخراج بيانات بشكل ثابت
{"type": "none"}ممنوع يستخدم أدواتخطوة تلخيص في الآخر مثلاً

ولو عايزه يطلب أداة واحدة بس في كل رد (مش كذا واحدة بالتوازي)، ضيف "disable_parallel_tool_use": true جوه الـ tool_choice.

⚠ مش كل الموديلات بتدعم كل دهبعض الموديلات مش بتدعم إجبار استخدام الأدوات (any و tool) وبترجع error. اتأكد من صفحة الموديل في التوثيق، ولو مش مدعوم، استخدم auto ووضّح في الـ prompt إنه لازم يستخدم الأداة.

حيلة: الأداة كطريقة لإخراج بيانات منظمة

لو عايز الموديل يطلع JSON بشكل مضمون، اعمل أداة اسمها مثلاً record_review_analysis بـ schema للشكل اللي عايزه، وأجبره عليها بـ tool_choice. الـ input اللي هيبعته هو الـ JSON بتاعك، ومش محتاج تنفذ أي حاجة.

الدرس اللي فات