التشغيل السريع: إنشاء عامل أساسي واختباره

يُرشدك دليل البدء السريع هذا خلال إنشاء عامل محرك مخصص يرد بأي رسالة ترسلها إليه.

المتطلبات

Python 3.9 أو أحدث.
- لتثبيت Python، انتقل إلى https://www.python.org/downloads/، واتبع تعليمات نظام التشغيل.
- للتحقق من الإصدار، في نافذة الطرفية، اكتب python --version.
محرر كود من اختيارك. تستخدم هذه التعليمات تعليمة Visual Studio برمجية.

في حالة استخدام تعليمة Visual Studio برمجية، ثبّت ملحق Python

قم بتهيئة المشروع وتثبيت SDK

أنشئ مشروع Python وثبت التبعيات المطلوبة.

افتح نافذة طرفية وأنشئ مجلدًا جديدًا
```
mkdir echo
cd echo
```
افتح المجلد في تعليمة Visual Studio برمجية باستخدام هذا الأمر:
```
code .
```
أنشئ بيئة افتراضية بالطريقة التي تفضلها، ثم فعّلها إما عبر تعليمة Visual Studio برمجية أو من خلال سطر الأوامر.

عند استخدام تعليمة Visual Studio برمجية، يمكنك استخدام هذه الخطوات مع تثبيت ملحق Python.
1. اضغط على F1, type Python: Create environment، واضغط على Enter.
  1. اختر Venv لإنشاء .venv بيئة افتراضية في مساحة العمل الحالية.
  2. اختر إصدار Python المثبت لإنشاء البيئة الافتراضية.
    
    قد تبدو القيمة كالتالي:
    
    Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
تثبيت Agent SDK

استخدم pip لتثبيت حزمة microsoft-agents-hosting-aiohttp باستخدام هذا الأمر:
```
pip install microsoft-agents-hosting-aiohttp
```

إنشاء تطبيق الخادم واستيراد المكتبات المطلوبة

أنشئ ملف باسم start_server.py، وانسخ الكود التَالي، ثم الصقه فيها:

# start_server.py
from os import environ
from microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration
from microsoft_agents.hosting.aiohttp import (
   start_agent_process,
   jwt_authorization_middleware,
   CloudAdapter,
)
from aiohttp.web import Request, Response, Application, run_app


def start_server(
   agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
):
   async def entry_point(req: Request) -> Response:
      agent: AgentApplication = req.app["agent_app"]
      adapter: CloudAdapter = req.app["adapter"]
      return await start_agent_process(
            req,
            agent,
            adapter,
      )

   APP = Application(middlewares=[jwt_authorization_middleware])
   APP.router.add_post("/api/messages", entry_point)
   APP.router.add_get("/api/messages", lambda _: Response(status=200))
   APP["agent_configuration"] = auth_configuration
   APP["agent_app"] = agent_application
   APP["adapter"] = agent_application.adapter

   try:
      run_app(APP, host="localhost", port=environ.get("PORT", 3978))
   except Exception as error:
      raise error

هذا الكود يعرّف دالة start_server سنستخدمها في الملف التالي.

في نفس الدليل، أنشئ ملفًا باسم app.py مع الكود التالي.

# app.py
from microsoft_agents.hosting.core import (
   AgentApplication,
   TurnState,
   TurnContext,
   MemoryStorage,
)
from microsoft_agents.hosting.aiohttp import CloudAdapter
from start_server import start_server

أنشئ مثيلًا للعامل كمثيل لـ AgentApplication

في app.py، أضف الكود التالي لإنشاء AGENT_APP كمثيل لـ AgentApplication، ونفّذ ثلاث مسارات للاستجابة لثلاثة أحداث:

تحديث المحادثة
الرسالة /help
أي نشاط آخر

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(), adapter=CloudAdapter()
)

async def _help(context: TurnContext, _: TurnState):
    await context.send_activity(
        "Welcome to the Echo Agent sample 🚀. "
        "Type /help for help or send a message to see the echo feature in action."
    )

AGENT_APP.conversation_update("membersAdded")(_help)

AGENT_APP.message("/help")(_help)


@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _):
    await context.send_activity(f"you said: {context.activity.text}")

تشغيل خادم الويب للاستماع في localhost:3978

عند انتهاء app.py، ابدأ خادم الويب باستخدام start_server.

if __name__ == "__main__":
    try:
        start_server(AGENT_APP, None)
    except Exception as error:
        raise error

تشغيل الْوكيل محلياً فِي وضع الْمجهول

من النافذة الطرفية، نفّذ هذا الأمر:

python app.py

يجب أن تعرض النافذة الطرفية ما يلي:

======== Running on http://localhost:3978 ========
(Press CTRL+C to quit)

اختبار العامل محليًا

من نافذة طرفية أخرى (لإبقاء عامل يعمل)، قم بتثبيت Microsoft 365 Agents Playground باستخدام هذا الأمر:
```
npm install -g @microsoft/teams-app-test-tool
```
إشعار

يستخدم هذا الأمر npm لأن Microsoft 365 Agents Playground غير متوفر باستخدام pip.

سيظهر في النافذة الطرفية شيء مماثل لما يلي:
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

شغل أداة الاختبار للتفاعل مع عاملك باستخدام هذا الأمر:

teamsapptester

سيظهر في النافذة الطرفية شيء مماثل لما يلي:

Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}

Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}

Listening on 56150
Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
started web socket client
started web socket client
Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
waiting for 1 resources: http://127.0.0.1:3978/api/messages
wait-on(37568) complete
Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

يفتح الأمر teamsapptester متصفحك الافتراضي ويتصل بعاملك.

بدء تشغيل عاملك في agents playground

الآن يمكنك إرسال أي رسالة لرؤية رد الصدى، أو إرسال الرسالة /help لمعرفة كيف يتم توجيه تلك الرسالة إلى معالج _help.

يُرشدك دليل البدء السريع هذا خلال إنشاء عامل محرك مخصص يرد بأي رسالة ترسلها إليه.

المتطلبات

Node.js v22 أو أحدث
- لتثبيت Node.js انتقل إلى nodejs.org واتبع تعليمات نظام التشغيل الخاص بك.
- للتحقق من الإصدار، في نافذة الطرفية، اكتب node --version.
محرر كود من اختيارك. تستخدم هذه التعليمات تعليمة Visual Studio برمجية.

قم بتهيئة المشروع وتثبيت SDK

استخدم npm لتهيئة مشروع node.js عن طريق إنشاء package.json وتثبيت التبعيات المطلوبة

افتح نافذة طرفية وأنشئ مجلدًا جديدًا
```
mkdir echo
cd echo
```
تهيئة مشروع node.js
```
npm init -y
```

تثبيت Agent SDK

npm install @microsoft/agents-hosting-express

افتح المجلد باستخدام تعليمة Visual Studio برمجية باستخدام هذا الأمر:
```
code .
```

استورد المكتبات المطلوبة

أنشئ الملف index.mjs ثم استورد حزم NPM التالية إلى كود التطبيق الخاص بك:

// index.mjs
import { startServer } from '@microsoft/agents-hosting-express'
import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

نفذ EchoAgent كـ AgentApplication

في index.mjs، أضف الكود التالي لإنشاء EchoAgent ما يوسع AgentApplicationونفّذ ثلاث مسارات للاستجابة لثلاثة أحداث:

تحديث المحادثة
الرسالة /help
أي نشاط آخر

class EchoAgent extends AgentApplication {
  constructor (storage) {
    super({ storage })

    this.onConversationUpdate('membersAdded', this._help)
    this.onMessage('/help', this._help)
    this.onActivity('message', this._echo)
  }

  _help = async context => 
    await context.sendActivity(`Welcome to the Echo Agent sample 🚀. 
      Type /help for help or send a message to see the echo feature in action.`)

  _echo = async (context, state) => {
    let counter= state.getValue('conversation.counter') || 0
    await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
    state.setValue('conversation.counter', counter)
  }
}

تشغيل خادم الويب للاستماع في localhost:3978

في نهاية index.mjs ابدأ خادم الويب باستخدام startServer المبني على express باستخدام MemoryStorage كتخزين لحالة الدور.

startServer(new EchoAgent(new MemoryStorage()))

تشغيل الْوكيل محلياً فِي وضع الْمجهول

من النافذة الطرفية، نفّذ هذا الأمر:

node index.mjs

يجب أن تعرض النافذة الطرفية ما يلي:

Server listening to port 3978 on sdk 0.6.18 for appId undefined debug undefined

اختبار العامل محليًا

من نافذة طرفية أخرى (لإبقاء عامل يعمل)، قم بتثبيت Microsoft 365 Agents Playground باستخدام هذا الأمر:
```
npm install -D @microsoft/teams-app-test-tool
```
سيظهر في النافذة الطرفية شيء مماثل لما يلي:
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

شغل أداة الاختبار للتفاعل مع عاملك باستخدام هذا الأمر:

node_modules/.bin/teamsapptester

سيظهر في النافذة الطرفية شيء مماثل لما يلي:

Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}

Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}

Listening on 56150
Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
started web socket client
started web socket client
Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
waiting for 1 resources: http://127.0.0.1:3978/api/messages
wait-on(37568) complete
Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

يفتح الأمر teamsapptester متصفحك الافتراضي ويتصل بعاملك.

بدء تشغيل عاملك في agents playground

يُرشدك دليل البدء السريع هذا خلال إنشاء عامل محرك مخصص يرد بأي رسالة ترسلها إليه.

المتطلبات

.NET 8.0 SDK أو أحدث
- لتثبيت .NET SDK، انتقل إلى dotnet.microsoft.com، واتبع تعليمات نظام التشغيل الخاص بك.
- للتحقق من الإصدار، في نافذة الطرفية، اكتب dotnet --version.
محرر كود من اختيارك. تستخدم هذه التعليمات تعليمة Visual Studio برمجية.

قم بتهيئة المشروع وتثبيت SDK

استخدم dotnet لإنشاء مشروع ويب جديد وتثبيت التبعيات المطلوبة.

افتح نافذة طرفية وأنشئ مجلدًا جديدًا
```
mkdir echo
cd echo
```
تهيئة مشروع .NET
```
dotnet new web
```

تثبيت Agent SDK

dotnet add package Microsoft.Agents.Hosting.AspNetCore

افتح المجلد في تعليمة Visual Studio برمجية باستخدام هذا الأمر:
```
code .
```

استورد المكتبات المطلوبة

في Program.cs، استبدل المحتوى الحالي وأضف عبارات الاستيراد التالية using لاستيراد حزم SDK إلى شفرتك البرمجية:

// Program.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;

نفذ EchoAgent كـ AgentApplication

في Program.cs، بعد عبارات using، أضف الكود التالي لإنشاء EchoAgent ما يوسع AgentApplication، ونفّذ ثلاث مسارات للاستجابة لثلاثة أحداث:

تحديث المحادثة
أي نشاط آخر

public class EchoAgent : AgentApplication
{
   public EchoAgent(AgentApplicationOptions options) : base(options)
   {
      OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
      OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
   }

   private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken);
            }
        }
    }

   private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
      await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
   }
}

قم بإعداد خادم الويب وسجّل تطبيق العامل

في Program.cs، بعد عبارات using، أضف الكود التالي لتكوين مضيف الويب، وتسجيل العامل، وربط نقطة النهاية /api/messages:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.AddAgentApplicationOptions();
builder.AddAgent<EchoAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();

var app = builder.Build();

app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

app.Run();

ضبط خادم الويب للاستماع في localhost:3978

في launchSettings.json، قم بتحديث applicationURL إلى http://localhost:3978 بحيث يستمع التطبيق على المنفذ الصحيح.

تشغيل الْوكيل محلياً فِي وضع الْمجهول

من النافذة الطرفية، نفّذ هذا الأمر:

dotnet run

سيظهر في النافذة الطرفية شيء مماثل لما يلي:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:3978

اختبار العامل محليًا

من نافذة طرفية أخرى (للحفاظ على تشغيل العامل)، قم بتثبيت Microsoft 365 Agents Playground باستخدام الأمر التالي:
```
npm install -g @microsoft/teams-app-test-tool
```
إشعار

يستخدم هذا الأمر npm لأن Microsoft 365 Agents Playground موزع كحزمة npm.

سيظهر في النافذة الطرفية شيء مماثل لما يلي:
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

شغل أداة الاختبار للتفاعل مع عاملك باستخدام هذا الأمر:

teamsapptester

سيظهر في النافذة الطرفية شيء مماثل لما يلي:

Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}

Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}

Listening on 56150
Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
started web socket client
started web socket client
Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
waiting for 1 resources: http://127.0.0.1:3978/api/messages
wait-on(37568) complete
Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}

يفتح الأمر teamsapptester متصفحك الافتراضي ويتصل بعاملك.

بدء تشغيل عاملك في agents playground

في حقل الْنص، أدخل أي رسالْة وأرسلها لمشاهدة الْرد الْصدى الْمكرر.

الخطوات التالية

Agents Playground متاح بشكل افتراضي إذا كنت تستخدم بالفعل Microsoft 365 Agents Toolkit. يمكنك استخدام أحد الأدلة التالية إذا أردت البدء في استخدام مجموعة الأدوات.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-07-30

التشغيل السريع: إنشاء عامل أساسي واختباره

المتطلبات

قم بتهيئة المشروع وتثبيت SDK

إنشاء تطبيق الخادم واستيراد المكتبات المطلوبة

أنشئ مثيلًا للعامل كمثيل لـ AgentApplication

تشغيل خادم الويب للاستماع في localhost:3978

تشغيل الْوكيل محلياً فِي وضع الْمجهول

اختبار العامل محليًا

المتطلبات

قم بتهيئة المشروع وتثبيت SDK

استورد المكتبات المطلوبة

نفذ EchoAgent كـ AgentApplication

تشغيل خادم الويب للاستماع في localhost:3978

تشغيل الْوكيل محلياً فِي وضع الْمجهول

اختبار العامل محليًا

المتطلبات

قم بتهيئة المشروع وتثبيت SDK

استورد المكتبات المطلوبة

نفذ EchoAgent كـ AgentApplication

قم بإعداد خادم الويب وسجّل تطبيق العامل

ضبط خادم الويب للاستماع في localhost:3978

تشغيل الْوكيل محلياً فِي وضع الْمجهول

اختبار العامل محليًا

الخطوات التالية

الملاحظات

الموارد الإضافية