Update installation and quickstart documentation for JSON-first crew projects

- Revised the installation guide to reflect the new JSON-first project structure, detailing the creation of `crew.jsonc` and `agents/*.jsonc` files. - Updated the quickstart guide to demonstrate setting up agents and tasks using JSONC format, replacing previous YAML examples. - Enhanced the agents and tasks documentation to clarify the transition from YAML to JSONC, including examples and explanations of the new structure. - Added notes on the classic YAML structure for legacy projects and provided guidance on migrating to the new format.
2026-07-26 17:25:10 +00:00 · 2026-06-16 08:28:37 -07:00
parent e9d568dc69
commit 5b766f999f
60 changed files with 2022 additions and 2814 deletions
--- a/docs/ar/quickstart.mdx
+++ b/docs/ar/quickstart.mdx
@@ -39,84 +39,60 @@ mode: "wide"
  يُنشئ ذلك تطبيق Flow ضمن `src/latest_ai_flow/`، بما في ذلك طاقمًا أوليًا في `crews/content_crew/` ستستبدله بطاقم بحث **بوكيل واحد** في الخطوات التالية.
  </Step>

-  <Step title="اضبط وكيلًا واحدًا في `agents.yaml`">
-  استبدل محتوى `src/latest_ai_flow/crews/content_crew/config/agents.yaml` بباحث واحد. تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`.
+  <Step title="اضبط وكيلًا واحدًا في JSONC">
+  أنشئ `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (أنشئ مجلد `agents/` إذا لزم). تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`.

-    ```yaml agents.yaml
-    # src/latest_ai_flow/crews/content_crew/config/agents.yaml
-    researcher:
-      role: >
-        باحث بيانات أول في {topic}
-      goal: >
-        اكتشاف أحدث التطورات في {topic}
-      backstory: >
-        أنت باحث مخضرم تكشف أحدث المستجدات في {topic}.
-        تجد المعلومات الأكثر صلة وتعرضها بوضوح.
+    ```jsonc agents/researcher.jsonc
+    {
+      "role": "باحث بيانات أول في {topic}",
+      "goal": "اكتشاف أحدث التطورات في {topic}",
+      "backstory": "أنت باحث يجد المعلومات الأكثر صلة ويعرضها بوضوح.",
+      "tools": ["SerperDevTool"],
+      "settings": {
+        "verbose": true
+      }
+    }
    ```

  </Step>

-  <Step title="اضبط مهمة واحدة في `tasks.yaml`">
-    ```yaml tasks.yaml
-    # src/latest_ai_flow/crews/content_crew/config/tasks.yaml
-    research_task:
-      description: >
-        أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات
-        حديثة وموثوقة. السنة الحالية 2026.
-      expected_output: >
-        تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة،
-        والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود.
-      agent: researcher
-      output_file: output/report.md
+  <Step title="اضبط الـ crew في `crew.jsonc`">
+  أنشئ `src/latest_ai_flow/crews/content_crew/crew.jsonc`:
+
+    ```jsonc crew.jsonc
+    {
+      "name": "Research Crew",
+      "agents": ["researcher"],
+      "tasks": [
+        {
+          "name": "research_task",
+          "description": "أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات حديثة وموثوقة. السنة الحالية 2026.",
+          "expected_output": "تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة، والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود.",
+          "agent": "researcher",
+          "output_file": "output/report.md",
+          "markdown": true
+        }
+      ],
+      "process": "sequential",
+      "verbose": true
+    }
    ```

  </Step>

-  <Step title="اربط صف الطاقم (`content_crew.py`)">
-  اجعل الطاقم المُولَّد يشير إلى YAML وأرفق `SerperDevTool` بالباحث.
+  <Step title="حمّل crew JSON (`content_crew.py`)">
+  استبدل `content_crew.py` المُولّد بمحمل صغير يحول `crew.jsonc` إلى `Crew`.

    ```python content_crew.py
    # src/latest_ai_flow/crews/content_crew/content_crew.py
-    from typing import List
+    from pathlib import Path

-    from crewai import Agent, Crew, Process, Task
-    from crewai.agents.agent_builder.base_agent import BaseAgent
-    from crewai.project import CrewBase, agent, crew, task
-    from crewai_tools import SerperDevTool
+    from crewai.project import load_crew


-    @CrewBase
-    class ResearchCrew:
-      """طاقم بحث بوكيل واحد داخل Flow."""
-
-      agents: List[BaseAgent]
-      tasks: List[Task]
-
-      agents_config = "config/agents.yaml"
-      tasks_config = "config/tasks.yaml"
-
-      @agent
-      def researcher(self) -> Agent:
-        return Agent(
-          config=self.agents_config["researcher"],  # type: ignore[index]
-          verbose=True,
-          tools=[SerperDevTool()],
-        )
-
-      @task
-      def research_task(self) -> Task:
-        return Task(
-          config=self.tasks_config["research_task"],  # type: ignore[index]
-        )
-
-      @crew
-      def crew(self) -> Crew:
-        return Crew(
-          agents=self.agents,
-          tasks=self.tasks,
-          process=Process.sequential,
-          verbose=True,
-        )
+    def kickoff_content_crew(inputs: dict):
+      crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+      return crew.kickoff(inputs={**default_inputs, **inputs})
    ```

  </Step>
@@ -130,7 +106,7 @@ mode: "wide"

    from crewai.flow import Flow, listen, start

-    from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew
+    from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew


    class ResearchFlowState(BaseModel):
@@ -149,7 +125,7 @@ mode: "wide"

      @listen(prepare_topic)
      def run_research(self):
-        result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic})
+        result = kickoff_content_crew(inputs={"topic": self.state.topic})
        self.state.report = result.raw
        print("اكتمل طاقم البحث.")

@@ -171,7 +147,7 @@ mode: "wide"
    ```

  <Tip>
-  إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `ResearchCrew` ليطابق مسار الوحدة في مشروعك.
+  إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `kickoff_content_crew` ليطابق مسار الوحدة في مشروعك.
  </Tip>
  </Step>

@@ -219,7 +195,7 @@ mode: "wide"
 ## كيف يترابط هذا

 1. **Flow** — يشغّل `LatestAiFlow` أولًا `prepare_topic` ثم `run_research` ثم `summarize`. الحالة (`topic`، `report`) على Flow.
-2. **الطاقم** — يشغّل `ResearchCrew` مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير.
+2. **الطاقم** — يحمّل `kickoff_content_crew` ملف `crew.jsonc` ويشغّل مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير.
 3. **المُخرَج** — يكتب `output_file` للمهمة التقرير في `output/report.md`.

 للتعمق في أنماط Flow (التوجيه، الاستمرارية، الإنسان في الحلقة)، راجع [ابنِ أول Flow](/ar/guides/flows/first-flow) و[Flows](/ar/concepts/flows). للطواقم دون Flow، راجع [Crews](/ar/concepts/crews). لوكيل `Agent` واحد و`kickoff()` بلا مهام، راجع [Agents](/ar/concepts/agents#direct-agent-interaction-with-kickoff).
@@ -230,7 +206,10 @@ mode: "wide"

 ### اتساق التسمية

-يجب أن تطابق مفاتيح YAML (`researcher`، `research_task`) أسماء الدوال في صف `@CrewBase`. راجع [Crews](/ar/concepts/crews) لنمط الديكورات الكامل.
+يجب أن تطابق الأسماء في `crew.jsonc` الملفات والمراجع:
+
+- `agents: ["researcher"]` يحمّل `agents/researcher.jsonc`
+- `context: ["research_task"]` يشير إلى مهمة سابقة اسمها `research_task`

 ## النشر