شرح Raindrop Workshop: أداة تصحيح AI Agents محلياً

تخيّل الساعة الواحدة صباحاً، AI Agent الخاص بمشروعك فشل فجأة في الإنتاج. traces مبعثرة في dashboard سحابي، الـ eval suite في مكان آخر، وأداة الـ debugging على جهازك — وكل هذا في ثلاثة أماكن مختلفة لا يرى أيٌّ منها ما يراه الآخر. هذا بالضبط ما دفع فريق Raindrop AI لبناء Workshop: أداة مفتوحة المصدر لتصحيح أخطاء AI agents محلياً، تجمع كل شيء في مكان واحد، مباشرةً على جهازك.

ما هو Raindrop Workshop؟

Raindrop Workshop هو debugger محلي مفتوح المصدر مصمم خصيصاً لـ AI Agents. بدلاً من إرسال traces إلى سيرفر سحابي خارجي، يُشغّل Workshop daemon (خدمة خلفية) على جهازك ويعرض كل شيء في dashboard محلي عبر المتصفح على العنوان localhost:5899.

كل token، كل tool call، وكل قرار يتخذه الـ agent يظهر في الواجهة فور حدوثه — بدون polling، بدون تحديث يدوي للصفحة. يُخزّن Workshop كل هذه البيانات في ملف قاعدة بيانات واحد خفيف الوزن من نوع .db (SQLite)، مما يجعله سريعاً وغير مُكلف على موارد جهازك.

الأداة صادرة برخصة MIT، ما يعني أنها مجانية تماماً وستبقى كذلك، مع الحرية الكاملة في التعديل والاستخدام حتى في المشاريع التجارية.

لماذا تهتم بـ Raindrop Workshop؟

إذا كنت تبني AI Agent بأي من الـ frameworks الشائعة — سواء Vercel AI SDK، أو LangChain، أو Anthropic SDK، أو OpenAI Agents SDK — فأنت تعرف جيداً هذه الحلقة المؤلمة:

1. تُشغّل الـ agent
2. يفشل بطريقة غير متوقعة
3. تحاول تتبع الخطأ عبر logs مبعثرة
4. تُصلح الكود
5. تُعيد التشغيل وتنتظر

Brian Rhindress، مهندس AI في GC.AI، وصف الأمر بدقة: “الحلقة القديمة كانت: شغّل الـ evals، انتظر، تصفّح الـ traces، صلّح المشكلة، أعد التشغيل. مع Workshop أصبح الـ coding agent في الحلقة وهو يرى الـ run يحدث أمامه.”

المشكلة الأعمق أن أدوات الـ observability (مراقبة الأداء) التقليدية صُممت لـ distributed systems عامة، لا لـ AI agents تحديداً. Workshop يحل هذه الفجوة بتصميم مبني من الأساس لطبيعة عمل الـ agents: النماذج، الـ tools، القرارات، والـ traces.

كيف تبدأ؟

التثبيت أمر واحد في Terminal:

curl -fsSL https://raindrop.sh/install | bash

بعد التثبيت، تُشغّل Workshop بأمر بسيط:

raindrop workshop

هذا سيفتح الـ UI تلقائياً في المتصفح على localhost:5899.

ربط مشروعك بـ Workshop

في TypeScript / Node.js:

import { Raindrop } from "@raindrop-ai/node";

// تهيئة Raindrop مع تفعيل Local Debugger
const raindrop = new Raindrop({
  apiKey: process.env.RAINDROP_API_KEY,
});

// أي Raindrop SDK يرى متغير البيئة هذا سيُرسل traces لـ Workshop
process.env.RAINDROP_LOCAL_DEBUGGER = "true";

ببساطة، أضف RAINDROP_LOCAL_DEBUGGER=true في ملف .env الخاص بمشروعك. من تلك اللحظة، كل trace يُرسله الـ agent يظهر في الـ dashboard المحلي فورياً.

في Python:

import os
from raindrop import Raindrop

os.environ["RAINDROP_LOCAL_DEBUGGER"] = "true"

client = Raindrop(api_key=os.getenv("RAINDROP_API_KEY"))
# كودك العادي يعمل بدون أي تغيير

لا يتطلب تعديل منطق الـ agent نفسه — فقط متغير بيئة واحد يُحوّل الـ traces إلى Workshop.

إعداد .env تلقائياً

Workshop يوفر أمراً مساعداً يكتب إعدادات .env لك:

raindrop workshop setup

مثال تطبيقي كامل

لنفترض أنك تبني agent بسيطاً باستخدام Anthropic SDK يجيب على أسئلة المستخدمين ويستدعي tool خارجي:

import Anthropic from "@anthropic-ai/sdk";
import { Raindrop } from "@raindrop-ai/node";

// تفعيل Workshop
process.env.RAINDROP_LOCAL_DEBUGGER = "true";
const raindrop = new Raindrop({ apiKey: process.env.RAINDROP_API_KEY! });

const client = new Anthropic();

// تعريف Tool خارجي
const tools: Anthropic.Tool[] = [
  {
    name: "check_database",
    description: "البحث في قاعدة البيانات عن معلومة محددة",
    input_schema: {
      type: "object",
      properties: {
        query: { type: "string", description: "نص البحث" },
      },
      required: ["query"],
    },
  },
];

async function runAgent(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    tools,
    messages: [{ role: "user", content: userMessage }],
  });

  // كل هذا يظهر في Workshop dashboard فوراً:
  // - الـ token المُرسلة والمُستقبلة
  // - استدعاء tool check_database وقيمه
  // - وقت الاستجابة والتكلفة
  console.log(response.content);
}

runAgent("ما هو رصيد حساب المستخدم رقم 42؟");

ما ستراه في Workshop:

افتح localhost:5899 وستجد:

• Timeline يوضح تسلسل الأحداث بالميلي ثانية
• Tool Calls مع الـ inputs والـ outputs لكل استدعاء
• Token Usage والتكلفة لكل run
• Errors مع السياق الكامل لحظة حدوثها

الميزة الأقوى: Self-Healing Eval Loop

الميزة التي تُميّز Workshop عن أي أداة أخرى هي تكاملها مع coding agents مثل Claude Code:

# بعد رؤية الخطأ في Workshop، افتح Claude Code وقل:
# "انظر إلى الـ trace الأخير في Workshop واكتب eval يكشف هذا الخطأ"

Claude Code يقرأ الـ traces مباشرة عبر MCP (Model Context Protocol)، يكتب eval، يُشغّل الـ agent، يرى الفشل، يُصلح الكود، ويُعيد التشغيل — حتى تنجح جميع الـ assertions. هذه الحلقة الذاتية تُحرّر ساعات من العمل اليدوي.

---

الـ Frameworks المدعومة

Workshop يتكامل مع كل ما تستخدمه تقريباً:

Framework	الدعم
Anthropic SDK	✅
OpenAI Agents SDK	✅
Vercel AI SDK	✅
LangChain / LangGraph	✅
CrewAI	✅
Pydantic AI	✅
Google ADK	✅
DSPy	✅

---

نصائح ومزالق يجب تجنبها

✅ افعل:

• استخدم raindrop workshop status للتحقق من أن الـ daemon يعمل قبل تشغيل أي agent
• استفد من أمر raindrop workshop setup لتوليد إعدادات .env تلقائياً بدلاً من كتابتها يدوياً
• احتفظ بملف .db لكل مشروع بشكل منفصل لتتبع تطور الأداء عبر الزمن
• استخدم ميزة Replay لإعادة تشغيل نفس الـ trace بـ prompts أو نماذج مختلفة دون تشغيل الـ agent من البداية

❌ تجنّب:

• لا تنسَ إزالة RAINDROP_LOCAL_DEBUGGER=true من بيئة الإنتاج — الأداة مصممة للتطوير المحلي فقط
• لا تعتمد على Workshop كبديل كامل لـ monitoring في الإنتاج — Raindrop لديها منتج سحابي منفصل لذلك
• لا تتجاهل استخدام MCP integration مع Claude Code — هي القلب الحقيقي للأداة وأكثر ميزاتها قيمة
• لا تترك ملفات .db تتراكم بدون تنظيف — استخدم raindrop workshop reset عند الحاجة

الخلاصة والرأي

بصراحة تامة: Raindrop Workshop يستحق التثبيت الآن، وليس لاحقاً.

المشكلة التي يحلها حقيقية ومؤلمة لكل من يبني AI agents جدياً. فكرة تصحيح أخطاء AI agents محلياً بدلاً من الاعتماد على dashboards سحابية بعيدة ليست مجرد ميزة مريحة — هي تغيير جوهري في كيفية التفكير في debugging هذا النوع من التطبيقات.

الشيء الذي يجعله مختلفاً حقاً ليس الـ UI الجميل، بل حلقة Self-Healing المدمجة مع Claude Code: بدلاً من أن تجلس أنت وتحلل الـ traces يدوياً، تُكلّف الـ coding agent بهذا وتذهب لشرب قهوتك.

إذا كنت تبني مشاريع AI agents بأي SDK — سواء Anthropic أو OpenAI أو LangChain — جرّب Workshop الآن:

curl -fsSL https://raindrop.sh/install | bash

ثم شغّل مشروعك وافتح localhost:5899. أخبرنا في التعليقات: كم من الوقت وفّرت في أول جلسة debugging؟

---