> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# خطافات استدعاء الأدوات

> تعلم كيفية استخدام خطافات استدعاء الأدوات لاعتراض وتعديل والتحكم في تنفيذ الأدوات في CrewAI

توفر خطافات استدعاء الأدوات تحكماً دقيقاً في تنفيذ الأدوات أثناء عمليات الوكيل. تتيح لك هذه الخطافات اعتراض استدعاءات الأدوات وتعديل المدخلات وتحويل المخرجات وتنفيذ فحوصات السلامة وإضافة تسجيل أو مراقبة شاملة.

## نظرة عامة

تُنفذ خطافات الأدوات في نقطتين حرجتين:

* **قبل استدعاء الأداة**: تعديل المدخلات، التحقق من المعاملات، أو حظر التنفيذ
* **بعد استدعاء الأداة**: تحويل النتائج، تنقية المخرجات، أو تسجيل تفاصيل التنفيذ

## أنواع الخطافات

### خطافات ما قبل استدعاء الأداة

تُنفذ قبل كل تنفيذ أداة، ويمكن لهذه الخطافات:

* فحص وتعديل مدخلات الأداة
* حظر تنفيذ الأداة بناءً على شروط
* تنفيذ بوابات موافقة للعمليات الخطرة
* التحقق من المعاملات
* تسجيل استدعاءات الأدوات

**التوقيع:**

```python theme={null}
def before_hook(context: ToolCallHookContext) -> bool | None:
    # Return False to block execution
    # Return True or None to allow execution
    ...
```

### خطافات ما بعد استدعاء الأداة

تُنفذ بعد كل تنفيذ أداة، ويمكن لهذه الخطافات:

* تعديل أو تنقية نتائج الأداة
* إضافة بيانات وصفية أو تنسيق
* تسجيل نتائج التنفيذ
* تنفيذ التحقق من النتائج
* تحويل تنسيقات المخرجات

**التوقيع:**

```python theme={null}
def after_hook(context: ToolCallHookContext) -> str | None:
    # Return modified result string
    # Return None to keep original result
    ...
```

## سياق خطاف الأداة

يوفر كائن `ToolCallHookContext` وصولاً شاملاً لحالة تنفيذ الأداة:

```python theme={null}
class ToolCallHookContext:
    tool_name: str                    # Name of the tool being called
    tool_input: dict[str, Any]        # Mutable tool input parameters
    tool: CrewStructuredTool          # Tool instance reference
    agent: Agent | BaseAgent | None   # Agent executing the tool
    task: Task | None                 # Current task
    crew: Crew | None                 # Crew instance
    tool_result: str | None           # Tool result (after hooks only)
```

### تعديل مدخلات الأداة

**مهم:** قم دائماً بتعديل مدخلات الأداة في مكانها:

```python theme={null}
# ✅ Correct - modify in-place
def sanitize_input(context: ToolCallHookContext) -> None:
    context.tool_input['query'] = context.tool_input['query'].lower()

# ❌ Wrong - replaces dict reference
def wrong_approach(context: ToolCallHookContext) -> None:
    context.tool_input = {'query': 'new query'}
```

## طرق التسجيل

### 1. تسجيل الخطافات العامة

تسجيل خطافات تنطبق على جميع استدعاءات الأدوات عبر جميع الأطقم:

```python theme={null}
from crewai.hooks import register_before_tool_call_hook, register_after_tool_call_hook

def log_tool_call(context):
    print(f"Tool: {context.tool_name}")
    print(f"Input: {context.tool_input}")
    return None  # Allow execution

register_before_tool_call_hook(log_tool_call)
```

### 2. التسجيل باستخدام المزخرفات

استخدم المزخرفات لصياغة أنظف:

```python theme={null}
from crewai.hooks import before_tool_call, after_tool_call

@before_tool_call
def block_dangerous_tools(context):
    dangerous_tools = ['delete_database', 'drop_table', 'rm_rf']
    if context.tool_name in dangerous_tools:
        print(f"⛔ Blocked dangerous tool: {context.tool_name}")
        return False  # Block execution
    return None

@after_tool_call
def sanitize_results(context):
    if context.tool_result and "password" in context.tool_result.lower():
        return context.tool_result.replace("password", "[REDACTED]")
    return None
```

### 3. خطافات نطاق الطاقم

تسجيل خطافات لمثيل طاقم محدد:

```python theme={null}
@CrewBase
class MyProjCrew:
    @before_tool_call_crew
    def validate_tool_inputs(self, context):
        # Only applies to this crew
        if context.tool_name == "web_search":
            if not context.tool_input.get('query'):
                print("❌ Invalid search query")
                return False
        return None

    @after_tool_call_crew
    def log_tool_results(self, context):
        # Crew-specific tool logging
        print(f"✅ {context.tool_name} completed")
        return None

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True
        )
```

## حالات الاستخدام الشائعة

### 1. حواجز السلامة

```python theme={null}
@before_tool_call
def safety_check(context: ToolCallHookContext) -> bool | None:
    destructive_tools = [
        'delete_file',
        'drop_table',
        'remove_user',
        'system_shutdown'
    ]

    if context.tool_name in destructive_tools:
        print(f"🛑 Blocked destructive tool: {context.tool_name}")
        return False

    sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment']
    if context.tool_name in sensitive_tools:
        print(f"⚠️  Executing sensitive tool: {context.tool_name}")

    return None
```

### 2. بوابة الموافقة البشرية

```python theme={null}
@before_tool_call
def require_approval_for_actions(context: ToolCallHookContext) -> bool | None:
    approval_required = [
        'send_email',
        'make_purchase',
        'delete_file',
        'post_message'
    ]

    if context.tool_name in approval_required:
        response = context.request_human_input(
            prompt=f"Approve {context.tool_name}?",
            default_message=f"Input: {context.tool_input}\nType 'yes' to approve:"
        )

        if response.lower() != 'yes':
            print(f"❌ Tool execution denied: {context.tool_name}")
            return False

    return None
```

### 3. التحقق من المدخلات وتنقيتها

```python theme={null}
@before_tool_call
def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None:
    if context.tool_name == 'web_search':
        query = context.tool_input.get('query', '')
        if len(query) < 3:
            print("❌ Search query too short")
            return False
        context.tool_input['query'] = query.strip().lower()

    if context.tool_name == 'read_file':
        path = context.tool_input.get('path', '')
        if '..' in path or path.startswith('/'):
            print("❌ Invalid file path")
            return False

    return None
```

### 4. تنقية النتائج

```python theme={null}
@after_tool_call
def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None:
    if not context.tool_result:
        return None

    import re
    result = context.tool_result

    result = re.sub(
        r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+',
        r'\1: [REDACTED]',
        result,
        flags=re.IGNORECASE
    )

    result = re.sub(
        r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
        '[EMAIL-REDACTED]',
        result
    )

    result = re.sub(
        r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b',
        '[CARD-REDACTED]',
        result
    )

    return result
```

### 5. تحليلات استخدام الأدوات

```python theme={null}
import time
from collections import defaultdict

tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0})

@before_tool_call
def start_timer(context: ToolCallHookContext) -> None:
    context.tool_input['_start_time'] = time.time()
    return None

@after_tool_call
def track_tool_usage(context: ToolCallHookContext) -> None:
    start_time = context.tool_input.get('_start_time', time.time())
    duration = time.time() - start_time

    tool_stats[context.tool_name]['count'] += 1
    tool_stats[context.tool_name]['total_time'] += duration

    if not context.tool_result or 'error' in context.tool_result.lower():
        tool_stats[context.tool_name]['failures'] += 1

    print(f"""
    📊 Tool Stats for {context.tool_name}:
    - Executions: {tool_stats[context.tool_name]['count']}
    - Avg Time: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}s
    - Failures: {tool_stats[context.tool_name]['failures']}
    """)

    return None
```

### 6. تحديد المعدل

```python theme={null}
from collections import defaultdict
from datetime import datetime, timedelta

tool_call_history = defaultdict(list)

@before_tool_call
def rate_limit_tools(context: ToolCallHookContext) -> bool | None:
    tool_name = context.tool_name
    now = datetime.now()

    tool_call_history[tool_name] = [
        call_time for call_time in tool_call_history[tool_name]
        if now - call_time < timedelta(minutes=1)
    ]

    if len(tool_call_history[tool_name]) >= 10:
        print(f"🚫 Rate limit exceeded for {tool_name}")
        return False

    tool_call_history[tool_name].append(now)
    return None
```

### 7. تخزين نتائج الأدوات مؤقتاً

```python theme={null}
import hashlib
import json

tool_cache = {}

def cache_key(tool_name: str, tool_input: dict) -> str:
    """Generate cache key from tool name and input."""
    input_str = json.dumps(tool_input, sort_keys=True)
    return hashlib.md5(f"{tool_name}:{input_str}".encode()).hexdigest()

@before_tool_call
def check_cache(context: ToolCallHookContext) -> bool | None:
    key = cache_key(context.tool_name, context.tool_input)
    if key in tool_cache:
        print(f"💾 Cache hit for {context.tool_name}")
    return None

@after_tool_call
def cache_result(context: ToolCallHookContext) -> None:
    if context.tool_result:
        key = cache_key(context.tool_name, context.tool_input)
        tool_cache[key] = context.tool_result
        print(f"💾 Cached result for {context.tool_name}")
    return None
```

### 8. تسجيل التصحيح

```python theme={null}
@before_tool_call
def debug_tool_call(context: ToolCallHookContext) -> None:
    print(f"""
    🔍 Tool Call Debug:
    - Tool: {context.tool_name}
    - Agent: {context.agent.role if context.agent else 'Unknown'}
    - Task: {context.task.description[:50] if context.task else 'Unknown'}...
    - Input: {context.tool_input}
    """)
    return None

@after_tool_call
def debug_tool_result(context: ToolCallHookContext) -> None:
    if context.tool_result:
        result_preview = context.tool_result[:200]
        print(f"✅ Result Preview: {result_preview}...")
    else:
        print("⚠️  No result returned")
    return None
```

## إدارة الخطافات

### إلغاء تسجيل الخطافات

```python theme={null}
from crewai.hooks import (
    unregister_before_tool_call_hook,
    unregister_after_tool_call_hook
)

def my_hook(context):
    ...

register_before_tool_call_hook(my_hook)
success = unregister_before_tool_call_hook(my_hook)
print(f"Unregistered: {success}")
```

### مسح الخطافات

```python theme={null}
from crewai.hooks import (
    clear_before_tool_call_hooks,
    clear_after_tool_call_hooks,
    clear_all_tool_call_hooks
)

count = clear_before_tool_call_hooks()
print(f"Cleared {count} before hooks")

before_count, after_count = clear_all_tool_call_hooks()
print(f"Cleared {before_count} before and {after_count} after hooks")
```

### عرض الخطافات المسجلة

```python theme={null}
from crewai.hooks import (
    get_before_tool_call_hooks,
    get_after_tool_call_hooks
)

before_hooks = get_before_tool_call_hooks()
after_hooks = get_after_tool_call_hooks()

print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after")
```

## أفضل الممارسات

1. **اجعل الخطافات مركزة**: يجب أن يكون لكل خطاف مسؤولية واحدة
2. **تجنب الحسابات الثقيلة**: تُنفذ الخطافات في كل استدعاء أداة
3. **تعامل مع الأخطاء بأناقة**: استخدم try-except لمنع فشل الخطافات
4. **استخدم تلميحات الأنواع**: استفد من `ToolCallHookContext` لدعم أفضل في بيئة التطوير
5. **وثّق شروط الحظر**: وضّح متى ولماذا تُحظر الأدوات
6. **اختبر الخطافات بشكل مستقل**: اختبر الخطافات وحدوياً قبل الاستخدام في الإنتاج
7. **امسح الخطافات في الاختبارات**: استخدم `clear_all_tool_call_hooks()` بين تشغيلات الاختبار
8. **عدّل في المكان**: قم دائماً بتعديل `context.tool_input` في مكانه، ولا تستبدله
9. **سجّل القرارات المهمة**: خاصة عند حظر تنفيذ الأدوات
10. **راعِ الأداء**: خزّن عمليات التحقق المكلفة مؤقتاً عند الإمكان

## معالجة الأخطاء

```python theme={null}
@before_tool_call
def safe_validation(context: ToolCallHookContext) -> bool | None:
    try:
        if not validate_input(context.tool_input):
            return False
    except Exception as e:
        print(f"⚠️ Hook error: {e}")
        return None  # Allow execution despite error
```

## أمان الأنواع

```python theme={null}
from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType

def my_before_hook(context: ToolCallHookContext) -> bool | None:
    return None

def my_after_hook(context: ToolCallHookContext) -> str | None:
    return None

register_before_tool_call_hook(my_before_hook)
register_after_tool_call_hook(my_after_hook)
```

## استكشاف الأخطاء وإصلاحها

### الخطاف لا يُنفذ

* تحقق من أن الخطاف مسجل قبل تنفيذ الطاقم
* تحقق مما إذا كان خطاف سابق أرجع `False` (يحظر التنفيذ والخطافات اللاحقة)
* تأكد من أن توقيع الخطاف يطابق النوع المتوقع

### تعديلات المدخلات لا تعمل

* استخدم التعديلات في المكان: `context.tool_input['key'] = value`
* لا تستبدل القاموس: `context.tool_input = {}`

### تعديلات النتائج لا تعمل

* أرجع السلسلة النصية المعدلة من خطافات ما بعد
* إرجاع `None` يحتفظ بالنتيجة الأصلية
* تأكد من أن الأداة أرجعت نتيجة فعلاً

### أداة محظورة بشكل غير متوقع

* تحقق من جميع خطافات ما قبل بحثاً عن شروط حظر
* تحقق من ترتيب تنفيذ الخطافات
* أضف تسجيل تصحيح لتحديد الخطاف الذي يحظر

## الخاتمة

توفر خطافات استدعاء الأدوات إمكانيات قوية للتحكم في تنفيذ الأدوات ومراقبتها في CrewAI. استخدمها لتنفيذ حواجز السلامة وبوابات الموافقة والتحقق من المدخلات وتنقية النتائج والتسجيل والتحليلات. مع معالجة الأخطاء المناسبة وأمان الأنواع، تُمكّن الخطافات أنظمة وكلاء آمنة وجاهزة للإنتاج مع مراقبة شاملة.