حل الكابتشا
لوكلاء OpenAI Agents SDK
الوكيل الذي يصادف تحديًا لا يملك في مجموعة أدواته ما يجيب عنه، فيتوقف أو يلتف عليه بالهلوسة. زوّده بأداة حل، فيصبح العائق مجرد استدعاء آخر.
import time
import requests
CAPTCHANO_KEY = "cn-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {CAPTCHANO_KEY}"}
def solve(task: dict) -> dict:
"""Block until solved; returns e.g. {"token": "...", "userAgent": "..."}."""
r = requests.post(
"https://api.captchano.com/v1/solve",
params={"wait": 60},
json=task,
headers=HEADERS,
timeout=75,
)
data = r.json()
# A solve can outlast the 60 s wait: poll the task until it finishes.
while data.get("status") in ("queued", "solving"):
time.sleep(5)
data = requests.get(
f"https://api.captchano.com/v1/task/{data['id']}",
headers=HEADERS,
timeout=30,
).json()
if data.get("status") != "ready":
raise RuntimeError(data.get("error") or data)
return data["solution"]
from agents import Agent, function_tool
@function_tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Return a token for a captcha blocking the current page."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
agent = Agent(name="browser", tools=[solve_captcha])لماذا يحتاج الوكلاء إلى هذا تحديدًا
أداة الـ scraping التي تصطدم بتحدٍّ تفشل بشكل واضح فتصلحها. أما الوكيل فيفشل بصمت: يستنتج حول الصفحة المحجوبة، ويختلق خطوة تالية معقولة، ويبلّغ عن تقدم لم يحققه قط. والفشل هنا أسوأ لأنه صامت. أداة حل محددة النوع تحوّل الطريق المسدود الغامض إلى نتيجة حتمية يستطيع الوكيل بناء قراراته عليها.
ما الذي تعيده الأداة
- رمز token أو ملف cookie — بحسب نوع التحدي. الأنظمة التي تقيّم الجلسة تعيد ملف cookie مع مجموعة الترويسات (headers) المستخدمة للحصول عليه.
- وكيل المستخدم المستخدَم، كي يعيد الوكيل استخدامه عند الإرسال.
- تكلفة عملية الحل، كي يتمكن الوكيل العامل ضمن ميزانية من احتسابها بدلًا من الإنفاق دون رؤية.
إبقاء الحلقة محدودة
امنح الوكيل ميزانية حل لكل تشغيل. تبلّغ كل استجابة عن تكلفتها، لذا يمكن لجهة الإشراف قطع الحلقة عندما يتجاوز الإنفاق حدًا معينًا بدلًا من اكتشاف ذلك في الفاتورة. بسعر $0.00598 لكل عملية حل، تكلف عملية تشغيل الوكيل المعتادة بضعة سنتات أو أقل، لكن حلقة إعادة المحاولة غير المحدودة تبقى حلقة غير محدودة.
اجعل استدعاء الأداة متزامنًا (blocking)
تستدعي الأمثلة ?wait=60، فتعيد الأداة رمز token جاهزًا في خطوة واحدة. وهذا أهم للوكلاء منه للسكربتات: الأداة التي تعيد "ما زال الحل جاريًا" تجبر النموذج على التفكير في الاستطلاع الدوري (polling)، وهو ما يجيده بشكل سيئ. إذا احتجت إلى سقف أطول، فارفع wait حتى 120 ثانية. أشكال الطلبات لكل أنواع التحديات موجودة في مرجع API.
كيف تندمج عملية الحل في OpenAI Agents SDK
يحوّل OpenAI Agents SDK دالة Python محددة النوع إلى أداة باستخدام function_tool. فتصبح أداة الحل إحدى أدوات الوكيل.
- 01زخرف دالة
غلّف استدعاء API باستخدام @function_tool مع وسائط محددة النوع.
- 02أضفها إلى الوكيل
مرّرها في قائمة أدوات الوكيل.
- 03وجّه الوكيل
أخبره بأن يستدعي الأداة عندما تعرض الصفحة كابتشا، مع sitekey وعنوان URL.
- 04تتبّعها
يعرض التتبع (tracing) في SDK كل استدعاء أداة ونتيجته، بما في ذلك التكلفة التي نعيدها.
إدخال الرمز token في الصفحة
يتلقى الوكيل الرمز token ويمرره إلى أداة المتصفح أو أداة HTTP الخاصة به.
أين تخطئ عمليات التكامل عادةً
حدّد نوع كل وسيط كي يكون المخطط المُنشأ دقيقًا ويملأه النموذج بشكل صحيح.
اضبط مهلة HTTP فوق قيمة wait كي لا تفشل الأداة بينما لا تزال عملية الحل جارية.
الأسئلة الشائعة حول الكابتشا في OpenAI Agents SDK
هل يعمل مع نماذج غير نماذج OpenAI؟
يدعم SDK مزوّدين آخرين من خلال واجهة النماذج الخاصة به، والأداة نفسها مجرد HTTP، لذا نعم.
هل يمكنني استخدامه مع handoffs؟
نعم. أعطِ الأداة للوكيل الذي يتحكم في المتصفح؛ ويمكن للوكلاء الآخرين تسليم المهمة إليه.
أين يجب أن يوجد مفتاح API؟
في متغير بيئة يُقرأ داخل دالة الأداة، وليس في تعليمات الوكيل أبدًا.
كيف أضع سقفًا للإنفاق؟
تتبّع الحقل cost من كل نتيجة في سياق التشغيل، وارفض أي عمليات حل إضافية بعد تجاوز الميزانية.
أدلة مفيدة
هل أنت مستعد للبناء؟
ابدأ بفترة تجريبية مجانية لمدة 3 أيام، ثم ادفع مقابل كل عملية حل ناجحة مع نمو حركة المرور لديك. لا حاجة إلى بطاقة للفترة التجريبية.