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

# الأدوات

> عرّف أدوات محلية تم التحقق منها، وأدوات يدوية، وأدوات تعرض التقدم.

استخدم الأدوات عندما يحتاج الوكيل إلى قراءة بيانات التطبيق أو استدعاء خدمة داخلية أو تنفيذ إجراء. يتحقق Agent SDK من حدود الأدوات ويشغّل شيفرتها داخل تطبيقك.

## تعريف أداة محلية

تقبل `defineTool()` وصفًا ومعلمات JSON اختيارية ومدققات وقت التشغيل ومهلة زمنية ودالة `execute()`.

```typescript theme={null}
import { defineTool } from "@phaseo/agent-sdk";

const fetchTicket = defineTool({
  id: "fetch-ticket",
  description: "Load one internal support ticket.",
  parameters: {
    type: "object",
    properties: {
      ticketId: { type: "string" },
    },
    required: ["ticketId"],
    additionalProperties: false,
  },
  timeoutMs: 3_000,
  async execute(input: { ticketId: string }, context) {
    const response = await fetch(
      `https://internal.example/tickets/${input.ticketId}`,
      { signal: context.signal },
    );

    return response.json();
  },
});
```

عند انتهاء المهلة، يوقف وقت التشغيل `context.signal` ويضع علامة فشل على التشغيل ثم يعيد طرح خطأ المهلة.

يمكن أن تكون المخططات دوالًا أو كائنات تعرض `parse()` أو `safeParse()`. تفشل معلمات النموذج غير الصالحة ونتائج الأداة غير الصالحة قبل تجاوز حدود الأداة.

## تنفيذ العمل في تطبيقك

اضبط `execute: false` عندما ينفّذ تطبيقك العمل بدلًا من عملية SDK. تابِع التشغيل المتوقف بإضافة النتيجة إلى `toolOutputs`.

بالنسبة إلى أداة تفاعلية، أعد `null` من `onToolCalled`. بعد متابعة التشغيل، يمكن لـ `onResponseReceived` التحقق من الاستجابة المقدمة أو تحويلها.

## عرض التقدم

يمكن لمولّد غير متزامن إرجاع نتائج أولية قبل إرجاع نتيجة نهائية واحدة:

```typescript theme={null}
const indexRepository = defineTool({
  id: "index-repository",
  async *execute(input: { path: string }) {
    yield { phase: "scan" };
    yield { phase: "embed" };
    return { indexed: 248 };
  },
});
```

يتوفر التقدم عبر أحداث `tool.preliminary_result` و`preliminaryResults` الخاصة بالخطوة.

## تشغيل الأدوات المستقلة بالتوازي

إذا أمكن لدور واحد من النموذج استدعاء عدة أدوات مستقلة بأمان، فاضبط حدًا للتزامن:

```typescript theme={null}
const agent = createAgent({
  id: "research-agent",
  toolExecution: {
    toolConcurrency: 3,
  },
  tools: [fetchDocs, fetchStatus, fetchIncidents],
});
```

يحافظ وقت التشغيل على ترتيب رسائل نتائج الأدوات حتى عند تداخل عمليات التنفيذ المحلية.

## أدلة ذات صلة

* [إيقاف عمليات التشغيل مؤقتًا واعتمادها واستئنافها](./agent-sdk-state-and-approval.mdx)
* [بث نتائج الوكيل](./agent-sdk-streaming.mdx)
* [توزيع استدعاءات الأدوات المحلية بالتوازي](../../cookbook/agent-sdk-parallel-tools.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.