النظرة العامة على الواجهة الأمامية

امنح وكلاءك واجهة مستخدم

يشغّل CrewAI وكلاءك. ويمنحهم CopilotKit واجهة أمامية. معًا يتيحان لك بناء تطبيقات يحادث فيها المستخدمون Crew أو Flow، ويشاهدونه يعمل في الوقت الفعلي، ويوافقون على قراراته، ويرون مخرجاته معروضة كواجهة حيّة بدلًا من جدران من النص. يتصل الاثنان عبر بروتوكول AG-UI. تكشف حزمة ag-ui-crewai أي Crew أو Flow كنقطة نهاية AG-UI. وتستهلك خطافات (hooks) ومكوّنات React من CopilotKit تلك النقطة. يفتح ذلك تجارب تتجاوز بكثير صندوق المحادثة:

واجهة المستخدم التوليدية (Generative UI)

اعرض استدعاءات أدوات الوكيل وحالته كمكوّنات React خاصة بك.

التدخل البشري (Human-in-the-Loop)

أوقف الوكيل مؤقتًا لجمع موافقة المستخدم أو مدخلاته في منتصف التشغيل.

الحالة المشتركة (Shared State)

أبقِ حالة الوكيل وواجهة تطبيقك متزامنتين في الاتجاهين.

القنوات (Channels)

شغّل نفس الوكيل كروبوت على Slack أو Discord أو Teams.

يجعل هذا الدليل Crew أو Flow يتحدث مع واجهة أمامية بـ Next.js من البداية إلى النهاية. تبني بقية القسم على التطبيق الذي تعدّه هنا.

البنية

هناك ثلاثة أجزاء:

خادم وكيل CrewAI — عملية Python تقدّم الـ Crew أو الـ Flow الخاص بك عبر AG-UI (FastAPI + ag-ui-crewai).
وقت تشغيل CopilotKit — مسار Next.js يسجّل وكيلك ويوكّل الطلبات إليه.
الواجهة الأمامية بـ React — مزوّد <CopilotKit> إلى جانب مكوّنات المحادثة والواجهة التوليدية.

React app  ──►  CopilotKit runtime (/api/copilotkit)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow

يغطي هذا الدليل المسار الذاتي الاستضافة: تشغّل خادم وكيل CrewAI بنفسك باستخدام ag-ui-crewai، ويعمل محليًا دون أي خدمة مُدارة. يقدّم CopilotKit أيضًا مسارًا مُدارًا (CopilotKit Cloud / Enterprise Intelligence) بخيوط مستضافة وأداة فحص — راجع دليل البدء السريع لـ CopilotKit مع CrewAI إن أردت ذلك بدلًا منه. كود الواجهة الأمامية في هذا القسم هو نفسه في الحالتين؛ الاختلاف فقط في كيفية استضافة الوكيل وتسجيله.

يعمل CrewAI خلف AG-UI بثلاثة أشكال: الـ Flows العادية (المستخدمة في هذه الأدلة)، و**الـ Flows المحادثية (Conversational Flows)** (أصلية، مدركة للجلسة، قائمة على الأدوار، بتكافؤ كامل في الميزات)، والـ Crews (محادثة أساسية). الواجهة الأمامية في هذا القسم متطابقة عبرها جميعًا — الاختلاف فقط في تأليف الخلفية وتسجيلها.

دليل التكامل

قدّم وكيلك عبر AG-UI

ثبّت حزمة التكامل في مشروع CrewAI الخاص بك:

pip install ag-ui-crewai

اكشف وكيلك من تطبيق FastAPI. تستخدم الـ Flows دالة add_crewai_flow_fastapi_endpoint؛ وتستخدم الـ Crews دالة add_crewai_crew_fastapi_endpoint. يمكنك تسجيل ما تشاء منها، كلٌّ على مساره الخاص.

# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
from my_agents.recipe_flow import RecipeFlow

app = FastAPI(title="CrewAI Agent Server")

add_crewai_flow_fastapi_endpoint(
    app=app,
    flow=RecipeFlow(),
    path="/recipe",
)

# server.py
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_crew_fastapi_endpoint
from my_agents.research_crew import ResearchCrew

app = FastAPI(title="CrewAI Agent Server")

add_crewai_crew_fastapi_endpoint(
    app=app,
    crew=ResearchCrew().crew(),
    path="/research",
)

شغّله:

uvicorn server:app --port 8000

اضبط متغيّرات البيئة الخاصة بمزوّد الـ LLM الخاص بك (على سبيل المثال OPENAI_API_KEY) قبل بدء الخادم.

أنشئ تطبيق Next.js

إن لم تكن لديك واجهة أمامية بعد، أنشئ هيكلًا:

npx create-next-app@latest my-app
cd my-app

ثبّت CopilotKit وعميل CrewAI AG-UI:

npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai

أضف وقت تشغيل CopilotKit

أنشئ مسارًا يسجّل وكيل (أو وكلاء) CrewAI مع وقت تشغيل CopilotKit. يشير كل وكيل إلى مسار على خادم Python الخاص بك عبر CrewAIAgent.

// app/api/copilotkit/route.ts
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { CrewAIAgent } from "@ag-ui/crewai";
import { handle } from "hono/vercel";

const runtime = new CopilotRuntime({
  agents: {
    recipe: new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

const handler = handle(app);
export const GET = handler;
export const POST = handler;

غلّف تطبيقك بالمزوّد

وجّه <CopilotKit> إلى مسار وقت التشغيل واذكر اسم الوكيل الذي سجّلته.

// app/page.tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="recipe">
      <YourApp />
      <CopilotSidebar agentId="recipe" labels={{ modalHeaderTitle: "Assistant" }} />
    </CopilotKit>
  );
}

شغّله

ابدأ العمليتين وافتح التطبيق. تشغّل المحادثة في الشريط الجانبي الآن الـ Crew أو الـ Flow الخاص بك.

uvicorn server:app --port 8000   # terminal 1
npm run dev                       # terminal 2

خيارات واجهة المحادثة

يشحن CopilotKit ثلاثة أسطح محادثة قابلة للتبديل. بدّل المكوّن؛ يبقى التوصيل متطابقًا.

import { CopilotSidebar } from "@copilotkit/react-core/v2";

<CopilotSidebar agentId="recipe" />

import { CopilotPopup } from "@copilotkit/react-core/v2";

<CopilotPopup agentId="recipe" />

import { CopilotChat } from "@copilotkit/react-core/v2";

<CopilotChat agentId="recipe" />

إلى أين تذهب بعد ذلك

واجهة المستخدم التوليدية (Generative UI)

اعرض استدعاءات الأدوات وحالة الوكيل كمكوّنات مخصّصة.

إجراءات الواجهة الأمامية (Frontend Actions)

دع الوكيل يستدعي دوالًا تعمل في المتصفح.

التدخل البشري (Human-in-the-Loop)

قيّد إجراءات الوكيل خلف موافقة المستخدم.

الحالة التنبؤية (Predictive State)

ابثّ الحالة قيد التنفيذ إلى الواجهة أثناء عمل الوكيل.

البدء

الأدلّة

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

تكامل MCP

الأدوات

Observability

التعلّم

Telemetry

النظرة العامة على الواجهة الأمامية

امنح وكلاءك واجهة مستخدم

واجهة المستخدم التوليدية (Generative UI)

التدخل البشري (Human-in-the-Loop)

الحالة المشتركة (Shared State)

القنوات (Channels)

البنية

دليل التكامل

خيارات واجهة المحادثة

إلى أين تذهب بعد ذلك

واجهة المستخدم التوليدية (Generative UI)

إجراءات الواجهة الأمامية (Frontend Actions)

التدخل البشري (Human-in-the-Loop)

الحالة التنبؤية (Predictive State)

​امنح وكلاءك واجهة مستخدم

واجهة المستخدم التوليدية (Generative UI)

التدخل البشري (Human-in-the-Loop)

الحالة المشتركة (Shared State)

القنوات (Channels)

​البنية

​دليل التكامل

​خيارات واجهة المحادثة

​إلى أين تذهب بعد ذلك

واجهة المستخدم التوليدية (Generative UI)

إجراءات الواجهة الأمامية (Frontend Actions)

التدخل البشري (Human-in-the-Loop)

الحالة التنبؤية (Predictive State)

امنح وكلاءك واجهة مستخدم

البنية

دليل التكامل

خيارات واجهة المحادثة

إلى أين تذهب بعد ذلك