وكيل Taskflow الخاص بـ GitHub Security Lab

وكيل Taskflow الخاص بـ Security Lab هو إطار عمل متعدد الوكلاء مُفعَّل بـ MCP لسير عمل وكيلي تصريحي مدفوع بـ YAML.

مبني على OpenAI Agents SDK، ويستخدم Pydantic للتحقق من صحة القواعد و Jinja2 لعرض القوالب.

المفاهيم الأساسية

يستفيد وكيل Taskflow من قواعد نحوية مبنية على YAML على غرار GitHub Workflow لتنفيذ سلسلة من المهام باستخدام مجموعة من الوكلاء.

تكمن قيمته الأساسية في كونه أداة CLI تتيح للمستخدمين تعريف وبرمجة سير عمل وكيلي بسرعة دون الحاجة إلى كتابة أي كود.

يتم تعريف الوكلاء من خلال شخصيات، تتلقى مهمة لإنجازها، مع مجموعة من الأدوات.

يمكن للوكلاء التعاون لإكمال تسلسلات من المهام من خلال ما يُسمى taskflows.

يمكنك العثور على نظرة عامة مفصلة عن قواعد taskflow هنا وأمثلة على taskflows هنا.

البنية

┌─────────────────────────────────────────────────────┐
│                   CLI (cli.py)                      │
│  Typer-based entry point: -p, -t, -l, -g, -m, --resume, --lint│
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              Runner (runner.py)                     │
│  Taskflow execution loop, model resolution,         │
│  template rendering, session checkpointing          │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│          MCP Lifecycle (mcp_lifecycle.py)           │
│  Server connection, cleanup, process management     │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│            Agent (agent.py)                         │
│  TaskAgent wrapper, hooks, OpenAI Agents SDK bridge │
└─────────────────────────────────────────────────────┘

Supporting modules:
  models.py          — Pydantic v2 grammar models (validation)
  session.py         — Task-level checkpoint / resume
  available_tools.py — YAML resource loader with caching
  template_utils.py  — Jinja2 template environment
  mcp_utils.py       — MCP client parameter resolution
  mcp_transport.py   — MCP transport implementations (stdio, streamable)
  mcp_prompt.py      — System prompt construction
  prompt_parser.py   — Legacy prompt argument parser
  capi.py            — AI API endpoint and token management
  path_utils.py      — Platform-aware data/log directories

أنواع API

يدعم الوكيل كلاً من واجهات Chat Completions وResponses الخاصة بـ OpenAI. يمكن تكوين نوع API بشكل عام أو لكل نموذج على حدة في ملف model_config:

seclab-taskflow-agent:
  version: "1.0"
  filetype: model_config
api_type: chat_completions        # default for all models
models:
  gpt_default: gpt-4.1
  gpt_responses: gpt-5.1
model_settings:
  gpt_responses:
    api_type: responses           # override for this model
    endpoint: https://api.githubcopilot.com
    token: CAPI_TOKEN             # env var name containing the API key

يمكن أن يتضمن model_settings لكل نموذج ما يلي:

• api_type — "chat_completions" (افتراضي) أو "responses"
• endpoint — تجاوز عنوان URL الأساسي لواجهة API لهذا النموذج
• token — اسم متغير بيئة يحتوي على مفتاح API

الواجهات الخلفية

يمكن للمشغّل تشغيل ثلاث مجموعات SDK خلف واجهة موحّدة:

• openai_agents (افتراضي) — OpenAI Agents Python SDK. يدعم عمليات تسليم الشخصيات المتعددة، وكلًا من chat_completions وresponses لنوع api_type، وtemperature، وparallel_tool_calls، وexclude_from_context، وMCP عبر stdio وSSE وHTTP القابل للبث.
• copilot_sdk — GitHub Copilot Python SDK. يدعم البث، وreasoning_effort، وMCP عبر stdio/SSE/HTTP، وبوابة أذونات لكل أداة. تختار مجموعة SDK بروتوكول الاتصال الخاص بها لكل نموذج، لذا لا يُحترم حقل api_type في YAML؛ كما لا تتوفر عمليات تسليم الشخصيات المتعددة، وtemperature، وparallel_tool_calls. تفشل مهام سير العمل التي تستخدم حقولًا غير مدعومة عند التحميل مع BackendCapabilityError يسمّي الحقل المخالف.
• anthropic_sdk — Anthropic Python SDK، الذي يشغّل واجهة Messages API الأصلية (/v1/messages). يدعم البث، واستدعاء الأدوات عبر MCP، والتفكير التكيفي مع reasoning.effort قابل للتهيئة (low، medium، high، max). لا تُدعم عمليات التسليم. مصمّم للاستخدام مع نقطة نهاية Anthropic الخاصة بـ CAPI؛ يستخدم المصادقة Authorization: Bearer (وليس x-api-key).

أسبقية الاختيار (من الأعلى إلى الأدنى):

1. backend: لكل مهمة في كتلة model_settings الخاصة بالمهمة نفسها (يتجاوز قيمة مستوى النموذج لتلك المهمة الواحدة؛ انظر _resolve_task_model()).
2. backend: لكل نموذج في model_settings الخاصة بتهيئة النموذج (يسمح بواجهات خلفية مختلطة في مهمة سير عمل واحدة).
3. حقل backend: في المستوى الأعلى من مستند تهيئة النموذج (الافتراضي العام).
4. متغير البيئة SECLAB_TASKFLOW_BACKEND.
5. openai_agents.

seclab-taskflow-agent:
  version: "1.0"
  filetype: model_config
models:
  code_analysis: claude-opus-4.7
  general_tasks: gpt-5.4-mini
model_settings:
  code_analysis:
    api_type: messages
    backend: anthropic_sdk
    reasoning:
      effort: high
  general_tasks:
    api_type: responses
    backend: openai_agents

استعادة الجلسة

يتم إنشاء نقاط تفتيش تلقائيًا لتشغيلات Taskflow على مستوى المهمة. إذا فشلت مهمة بعد استنفاد محاولات الإعادة، يتم حفظ الجلسة ويمكن استئنافها:

** 🤖💾 Session saved: abc123def456
** 🤖💡 Resume with: --resume abc123def456

استئناف من آخر نقطة تفتيش ناجحة:

python -m seclab_taskflow_agent --resume abc123def456

يُبقي نقطة تفتيش الجلسة على قيمة --model-config المقدَّمة من CLI (إن وُجدت)، لذا تستخدم عمليات الاستئناف نفس إعدادات النموذج افتراضيًا. لتجاوز إعدادات النموذج عند الاستئناف، مرِّر --model-config / -m صراحةً:

python -m seclab_taskflow_agent --resume abc123def456 -m examples.model_configs.responses_api

تُعاد المهام الفاشلة تلقائيًا حتى 3 مرات مع تراجع متزايد قبل حفظ الجلسة. تُخزَّن نقاط تفتيش الجلسة في دليل بيانات التطبيق الخاص بالمنصة.

بيان التشغيل

ينتج كل تشغيل بيانًا قابلًا للقراءة آليًا يلخّص ما حدث: حالة كل مهمة (ok / failed / skipped)، والنماذج التي شُغّلت عليها كل مهمة، والتوقيت، والمخرجات outputs المسمّاة التي أنتجتها كل مهمة (بما في ذلك سجلات تجميع لكل نموذج للمهام متعددة النماذج). لا يحتوي على أي نقاط نهاية أو رموز.

يُكتب البيان في دليل مخرجات خاص بالتشغيل عند انتهاء التشغيل أو فشله، ويمكن طباعته لأي جلسة بواسطة المعرّف:

python -m seclab_taskflow_agent --manifest abc123def456

مخرجات الأخطاء

بشكل افتراضي، تُعرض الأخطاء كرسائل موجزة من سطر واحد. استخدم --debug (أو عيّن TASK_AGENT_DEBUG=1) للحصول على تتبعات كاملة:

# Concise (default)
Error: [BadRequestError] model 'foo' not found
(use --debug for full traceback)

# Full traceback
python -m seclab_taskflow_agent --debug -t examples.taskflows.echo

التحقق من الصحة والمخطط

يمكن التحقق من صحة تدفقات المهام دون اتصال، دون إجراء أي استدعاءات للنموذج، باستخدام --lint. يقوم هذا بحل تدفق المهام وكل مستند يشير إليه (الشخصيات، وصناديق الأدوات، وإعدادات النموذج، وتدفقات المهام القابلة لإعادة الاستخدام)، ويتحقق من أسماء النماذج مقابل إعدادات النموذج، ويتحقق من صحة صيغة قالب prompt/over، ويبلغ عن الحقول غير المعروفة (الأخطاء المطبعية المحتملة):

# Validate a taskflow and its references
python -m seclab_taskflow_agent --lint -t examples.taskflows.echo