تدخل بشري مع OpenAI Agents SDK

أوقف الأداة. احصل على موافقة العميل من هاتفه.

يتوقف وكيل OpenAI قبل رد مبلغ. يوافق المستخدم على هاتفه، فيستأنف التشغيل.

ما يقدمه OpenAI Agents SDK

needsApproval ومقاطعات التشغيل

علّم أداة دالة باستخدام needsApproval، فيتوقف SDK قبل تنفيذها. يعيد التشغيل result.interruptions وحالة RunState قابلة للحفظ. يوافق كودك على كل مقاطعة أو يرفضها، ثم يشغّل الوكيل مجددًا من تلك الحالة.

أين يتوقف

  • تحدد needsApproval الحاجة إلى شخص، لكنها لا تسأل أحدًا؛ معالجة المقاطعة مسؤوليتك.
  • الانتظار الطويل يتطلب حفظ RunState واستعادتها بالوكيل وإصدار SDK نفسيهما.
  • لا يعرف أي مستخدم يجب أن يجيب ولا كيف يصل إليه.

الحل

يتلقى Pushary إجابة مستخدمك.

يستطيع Agents SDK إيقاف استدعاء أداة، لكنه لا يُبلغ أحدًا. يرسل Pushary كل استدعاء متوقف إلى هاتف المستخدم ويعيد الإجابة إلى التشغيل.

تتطلب issue_refund موافقة، لذا يتوقف التشغيل قبل تنفيذها. تسأل resolvePusharyInterruptions المستخدم عن كل استدعاء متوقف بالتتابع. الموافقة تنفّذ رد المبلغ؛ أما الرفض أو انتهاء الصلاحية أو غياب الإجابة فيمنع رد المبلغ ويعطي النموذج السبب. إذا غطّت قاعدة Pushary لديك issue_refund، تجيب القاعدة أولًا.

bash
npm i @pushary/openai-agents @openai/agents zod
موافقة على الأداة الحساسة
import { Agent, run, tool } from "@openai/agents"
import { z } from "zod"
import { pusharyNeedsApproval, resolvePusharyInterruptions } from "@pushary/openai-agents"

const issueRefund = tool({
  name: "issue_refund",
  description: "Refund an order",
  parameters: z.object({ amount: z.number() }),
  needsApproval: pusharyNeedsApproval(),
  execute: async ({ amount }) => chargeBack(amount),
})

const agent = new Agent({ name: "Refunds", instructions: "Refund orders when asked.", tools: [issueRefund] })

let result = await run(agent, "Refund order 1234")
while (result.interruptions?.length) {
  const outcome = await resolvePusharyInterruptions(
    { externalId: user.id },
    { interruptions: result.interruptions, state: result.state },
  )
  result = await run(agent, result.state)
  if (!outcome.allApproved) break
}

يحفظ البث وResponses API بيانات مختلفة

في التشغيل المتدفق، اقرأ الأحداث وانتظر result.completed قبل فحص المقاطعات وحفظ الحالة. يحفظ مثال Responses API المنفصل معرّف الاستجابة وطلب موافقة MCP الدقيق، ثم يرسل mcp_approval_response مع previous_response_id. يشرح الدليل المسارين مع خدمات حقيقية.

انتظر اكتمال البث قبل الحفظ
const result = await runner.run(agent, input, { stream: true });
for await (const event of result) {
  // Display appropriate events; output is not permission to act.
}
await result.completed;
// Now inspect result.interruptions and persist result.state.
// The complete recipe binds this state to customer + action.

كيف يعمل

من التثبيت إلى أول إجابة

اربط مستخدمك مرة واحدة، واشترط الموافقة عند الخطوة الحساسة. يرسل Pushary السؤال وينتظر الإجابة ويحفظها.

  1. 01

    ثبّت المحوّل

    شغّل npm i @pushary/openai-agents @openai/agents zod وضع مفتاح API في PUSHARY_API_KEY. لـ Python: pip install pushary-openai-agents.

  2. 02

    اربط مستخدمك مرة واحدة

    يعيد connect() رابطًا يفتحه المستخدم على هاتفه بالتطبيق المجاني. احتفظ بمفتاح API ومعرّفه على خادمك.

  3. 03

    اشترط الموافقة على الأداة الحساسة

    اضبط needsApproval: pusharyNeedsApproval() على الأداة. يتوقف التشغيل قبل تنفيذها، وترسل resolvePusharyInterruptions كل استدعاء متوقف إلى المستخدم.

  4. 04

    تصرّف وفق الإجابة

    عند الموافقة شغّل الوكيل مجددًا من result.state. عند الرفض أو غياب الإجابة يُرفض الاستدعاء. للانتظار الطويل، احفظ الحالة واستأنف عند وصول الإجابة.

يمكن أن يكون السؤال بنعم أو لا، أو اختيارًا من قائمة، أو إجابة مكتوبة. تُحفظ كل إجابة.

قبل الإطلاق

نقاط يجب الانتباه إليها في OpenAI Agents SDK

أداة السؤال التي يمكن تجاوزها ليست حاجزًا
يختار النموذج استدعاء pusharyTool، وهذا مناسب لطلب «اذهب واسأل». أما «لا يجوز حدوث هذا دون نعم»، فضع needsApproval على الأداة الحساسة نفسها. توجيه «اسأل أولًا» لا يمنع شيئًا.
حفظ الإجابة لا يحفظ الوكيل
احفظ حالة التشغيل والاستدعاء الدقيق والمستخدم وإصدار الإجراء قبل السؤال. يحتفظ Pushary بالإجابة، لكنه لا يعيد بناء العملية ولا يجدول الاستئناف. يتولى نظام المهام لديك ذلك.
الموافقة تخص الاستدعاء الذي رآه المستخدم
اقرأ الإجابة من Pushary مجددًا وتحقق من مطابقتها للاستدعاء المحفوظ. وحدها نعم لسؤال نعم/لا تسمح بالتنفيذ. إذا تغيرت المسودة فاسأل مجددًا. لا تُحتسب الطلبات المنتظرة أو المنتهية أو الملغاة أو المرفوضة.
قد تنفّذ إعادة المحاولة الإجراء مرتين
ينفّذ المثال كل استئناف مرة واحدة، لكن API رد المبلغ يحتاج مفتاح عملية خاصًا به حتى لا يفعل التكرار شيئًا. إذا كانت نتيجة الشبكة غير واضحة، افحص ما حدث قبل المحاولة. يعالج المثال استدعاء متوقفًا واحدًا لكل عملية محفوظة.

خطة Partner

وكيلك يسأل مستخدميك، وليس أنت وحدك

قدّم وكيلك لمستخدميك. يوافق كل منهم على إجراءاته الحساسة من هاتفه، تحت علامتك التجارية.

$99/ شهريًا، مع جميع أطر العمل
Start free

لا ينشئ مستخدموك حسابًا في Pushary ولا يدفعون لنا.

يجيب مستخدموك من هواتفهم

اربط كل مستخدم مرة واحدة برابط. يثبّت تطبيق Pushary المجاني ويجيب من شاشة القفل، دون إنشاء حساب.

غياب الإجابة يعني الرفض

لا تنفّذ الإجراء إلا بعد موافقة صريحة. الطلب المنتظر أو المنتهي أو الملغى لا يُعد موافقة أبدًا. يحتفظ Pushary بكل طلب كي يستأنفه كودك بعد إعادة التشغيل.

يصل إليهم على هواتفهم

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

تُحفظ كل إجابة

تُحفظ كل إجابة مع هوية صاحبها ووقتها. يمكنك البحث فيها وتصديرها. وعند إضافة عنوان URL لاستقبال الرد، تُرسل كل إجابة أيضًا إلى خادمك عبر webhook موقّع.

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

إجابات عن أسئلتك

ما حزم OpenAI المتاحة؟
@pushary/openai-agents لـ TypeScript وpushary-openai-agents لـ Python. توفران connect() وأداة سؤال وحاجز موافقة لـ needsApproval (pusharyNeedsApproval وresolvePusharyInterruptions، أو الأسماء بصيغة snake_case في Python). أمثلة الحالة المحفوظة والبث وResponses API مكتوبة بـ TypeScript.
هل يستدعي مثال البث نموذجًا أو هاتفًا حقيقيًا؟
لا. يشغّل Agents SDK الحقيقي مع أحداث نموذج واستجابات HTTP وعمليات رد مبلغ محاكاة، باستخدام SQLite وعمّال جدد. لا يحتاج حسابًا أو مفتاح API. يوضح الدليل ربط الخدمات الحقيقية؛ ولا تثبت هذه الفحوص أن هاتفًا تلقى إشعارًا.
كيف يستأنف مثال MCP مع Responses API؟
يحفظ معرّف استجابة مكتملة وmcp_approval_request الدقيق، ويتحقق من إجابة المستخدم، ثم يرسل mcp_approval_response مع previous_response_id. يبقي require_approval مضبوطًا على always. هذا منفصل عن RunState في Agents SDK ويتطلب استجابات مخزنة.
ماذا لو لم يُجب العميل أبدًا؟
لا يُنفّذ الاستدعاء. الطلب المنتظر ليس موافقة، ويرفض العامل الطلبات المنتهية أو الملغاة أو المرفوضة. يستعلم تطبيقك دوريًا أو ينتظر webhook موقّعًا ويحفظ حالة SDK بنفسه؛ Pushary يحتفظ بالطلب، لا بالعملية.
هل يحل Pushary محل التفويض أو Codex Auto-review؟
لا. تُضاف إجابة المستخدم إلى تفويضك وفحوص المدخلات وحدود الأدوات. التطبيقات المبنية على Responses API أو Agents SDK لا تحصل على Codex Auto-review تلقائيًا.

دع وكيلك على OpenAI Agents SDK يسأل قبل أن يتصرف.

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

Start free

خطة Partner بسعر $99 شهريًا. لا ينشئ مستخدموك حسابًا في Pushary ولا يدفعون لنا.