Hızlı başlangıç: Temel aracı oluşturma ve test etme

Bu hızlı başlangıç, gönderdiğiniz mesajla cevap veren özel bir motor aracısı oluşturma konusunda size yol gösterir.

Ön koşullar

• Python 3.9 veya üzeri.

  • Python'u yüklemek için https://www.python.org/downloads/ adresine gidin ve işletim sisteminize yönelik talimatları izleyin.
  • Sürümü doğrulamak için bir terminal penceresinde python --version yazın.

• Seçtiğiniz bir kod düzenleyicisi. Bu yönergeler Visual Studio Code'u kullanır.

  Visual Studio Code kullanıyorsanız Python uzantısını yükleyin

Projeyi başlatma ve SDK'yi yükleme

Bir Python projesi oluşturun ve gerekli bağımlılıkları yükleyin.

1. Terminal açma ve yeni klasör oluşturma

   mkdir echo
   cd echo
   

2. Bu komutu kullanarak Visual Studio Code kullanarak klasörü açın:

   code .
   

3. İstediğiniz yöntemle bir sanal ortam oluşturun ve Visual Studio Code aracılığıyla veya bir terminalde etkinleştirin.

   Visual Studio Code'u kullanırken, Python uzantısı yüklü olarak bu adımları kullanabilirsiniz.

   1. F1 tuşuna basın, Python: Create environment yazın ve Enter'a basın.

      1. Geçerli çalışma alanında .venv sanal ortam oluşturmak için Venv öğesini seçin.

      2. Sanal ortamı oluşturmak için bir Python yüklemesi seçin.

         Değer şu şekilde görünebilir:

         Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe

4. Aracılar SDK'sını yükleme

   pip komutunu kullanarak microsoft-agents-hosting-aiohttp paketini şu komutla yükleyin:

   pip install microsoft-agents-hosting-aiohttp
   

Sunucu uygulamasını oluşturma ve gerekli kitaplıkları içeri aktarma

1. start_server.py adlı bir dosya oluşturun, aşağıdaki kodu kopyalayın ve yapıştırın:

   # 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
   

   Bu kod, sonraki dosyada kullanacağımız bir start_server işlevi tanımlar.

2. Aynı dizinde aşağıdaki kodla app.py adlı bir dosya oluşturun.

   # 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
   

Aracının bir örneğini AgentApplication olarak oluşturma

app.py içinde, AgentApplication'ün bir örneği olarak AGENT_APP'yi oluşturmak için aşağıdaki kodu ekleyin ve üç olaya yanıt vermek için üç rota uygulayın:

• Konuşma Güncelleştirmesi
• ileti /help
• diğer tüm etkinlikler

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'de dinlemek için web sunucusunu başlatın

app.py sonunda, start_server kullanarak web sunucusunu başlatın.

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

Aracıyı anonim modda yerel olarak çalıştırma

Terminalinizde şu komutu çalıştırın:

python app.py

Terminal aşağıdakileri döndürmelidir:

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

Aracıyı yerel olarak test edin

1. Başka bir terminalden (aracıyı çalışır durumda tutmak için) şu komutla Microsoft 365 Agents Playground'ı yükleyin:

   npm install -g @microsoft/teams-app-test-tool
   

   Not

   Microsoft 365 Agents Playground pip kullanılarak kullanılamadığından bu komut npm kullanır.

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Şu komutu kullanarak aracınızla etkileşime geçmek için test aracını çalıştırın:

   teamsapptester
   

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   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 komutu varsayılan tarayıcınızı açar ve aracınıza bağlanır.

Artık yankı yanıtını görmek için herhangi bir mesaj gönderebilir veya /help mesajını göndererek bu mesajın _help işleyicisine nasıl yönlendirildiğini görebilirsiniz.

Bu hızlı başlangıç, gönderdiğiniz mesajla cevap veren özel bir motor aracısı oluşturma konusunda size yol gösterir.

Ön koşullar

• Node.js v22 veya üzeri

  • Node.js yüklemek için nodejs.org'a gidin ve işletim sisteminize uygun talimatları izleyin.
  • Sürümü doğrulamak için bir terminal penceresinde node --version yazın.

• Seçtiğiniz bir kod düzenleyicisi. Bu yönergeler Visual Studio Code'u kullanır.

Projeyi başlatma ve SDK'yi yükleme

Node.js projesini başlatmak için npm komutunu kullanarak bir package.json oluşturun ve gerekli bağımlılıkları yükleyin

1. Terminal açma ve yeni klasör oluşturma

   mkdir echo
   cd echo
   

2. Node.js projesini başlatın

   npm init -y
   

3. Aracılar SDK'sını yükleme

   npm install @microsoft/agents-hosting-express
   

4. Bu komutu kullanarak Visual Studio Code kullanarak klasörü açın:

   code .
   

Gerekli kitaplıkları içeri aktarma

Dosyayı index.mjs oluşturun ve aşağıdaki NPM paketlerini uygulama kodunuza içe aktarın:

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

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

EchoAgent'i AgentApplication olarak uygulayın

index.mjs içinde, AgentApplication'ü genişleten EchoAgent'yi oluşturmak ve üç olaya yanıt vermek için üç rota uygulamak üzere aşağıdaki kodu ekleyin:

• Konuşma Güncelleştirmesi
• ileti /help
• diğer tüm etkinlikler

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'de dinlemek için web sunucusunu başlatın

index.mjs sonunda startServer kullanarak web sunucusunu başlatın ve dönüş durumu depolaması olarak MemoryStorage'ı kullanarak express'e dayalı hale getirin.

startServer(new EchoAgent(new MemoryStorage()))

Aracıyı anonim modda yerel olarak çalıştırma

Terminalinizde şu komutu çalıştırın:

node index.mjs

Terminal şunu döndürmelidir:

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

Aracıyı yerel olarak test edin

1. Başka bir terminalden (aracıyı çalışır durumda tutmak için) şu komutla Microsoft 365 Agents Playground'ı yükleyin:

   npm install -D @microsoft/teams-app-test-tool
   

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Şu komutu kullanarak aracınızla etkileşime geçmek için test aracını çalıştırın:

   node_modules/.bin/teamsapptester
   

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   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 komutu varsayılan tarayıcınızı açar ve aracınıza bağlanır.

Artık yankı yanıtını görmek için herhangi bir mesaj gönderebilir veya /help mesajını göndererek bu mesajın _help işleyicisine nasıl yönlendirildiğini görebilirsiniz.

Bu hızlı başlangıç, gönderdiğiniz mesajla cevap veren özel bir motor aracısı oluşturma konusunda size yol gösterir.

Ön koşullar

• .NET 8.0 SDK veya daha yeni bir sürüm

  • .NET SDK'yı yüklemek için dotnet.microsoft.com adresine gidin ve işletim sisteminize uygun talimatları izleyin.
  • Sürümü doğrulamak için bir terminal penceresinde dotnet --version yazın.

• Seçtiğiniz bir kod düzenleyicisi. Bu yönergeler Visual Studio Code'u kullanır.

Projeyi başlatma ve SDK'yi yükleme

Yeni bir web projesi oluşturmak ve gerekli bağımlılıkları yüklemek için dotnet kullanın.

1. Terminal açma ve yeni klasör oluşturma

   mkdir echo
   cd echo
   

2. .NET projesini başlat

   dotnet new web
   

3. Aracılar SDK'sını yükleme

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Bu komutu kullanarak Visual Studio Code kullanarak klasörü açın:

   code .
   

Gerekli kitaplıkları içeri aktarma

Program.cs dosyasında mevcut içeriği değiştirin ve SDK paketlerini uygulama kodunuza aktarmak için aşağıdaki using ifadelerini ekleyin.

// 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'i AgentApplication olarak uygulayın

Program.cs içinde, using ifadelerinden sonra, AgentApplication'i genişleten EchoAgent'ü oluşturmak ve olaylara yanıt vermek için rotaları uygulamak üzere aşağıdaki kodu ekleyin:

• Konuşma Güncelleştirmesi
• Diğer tüm etkinlikler

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);
   }
}

Web sunucusunu kur ve aracı uygulamasını kaydet

Program.cs içinde using deyimlerinden sonra, web ana bilgisayarını yapılandırmak, aracıyı kaydetmek ve /api/messages uç noktasını eşlemek için aşağıdaki kodu ekleyin:

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'de dinlemek için web sunucusunu ayarlayın

launchSettings.json dosyasında, uygulamanın doğru portta dinlemesi için applicationURL değerini http://localhost:3978 olarak güncelleyin.

Aracıyı anonim modda yerel olarak çalıştırma

Terminalinizde şu komutu çalıştırın:

dotnet run

Terminal aşağıdaki gibi bir şey döndürmelidir:

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

Aracıyı yerel olarak test edin

1. Başka bir terminalden (aracıyı çalışır durumda tutmak için) şu komutla Microsoft 365 Agents Playground'ı yükleyin:

   npm install -g @microsoft/teams-app-test-tool
   

   Not

   Microsoft 365 Agents Playground bir npm paketi olarak dağıtıldığından bu komut npm kullanır.

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Şu komutu kullanarak aracınızla etkileşime geçmek için test aracını çalıştırın:

   teamsapptester
   

   Terminal aşağıdaki gibi bir şey döndürmelidir:

   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 komutu varsayılan tarayıcınızı açar ve aracınıza bağlanır.

Metin giriş alanına herhangi bir mesajı girip gönderin; echo yanıtını göreceksiniz.

Sonraki adımlar

• GitHub'da Agents SDK örneklerine göz atın
• Faaliyetler ve Faaliyetlerle Çalışma hakkında daha fazla bilgi edinin
• İstemciden yanıt verebileceğiniz AgentApplication olaylarını gözden geçirin
• İstemciye geri gönderebileceğiniz TurnContext olaylarını gözden geçirin
• Agents SDK ile kullanılmak üzere Azure Bot kaynaklarını tahsis edin
• .NET Aracınızı OAuth kullanacak şekilde yapılandırma

Agents Playground, zaten Microsoft 365 Agents Toolkit'i kullanıyorsanız varsayılan olarak mevcut. Araç setini kullanmaya başlamak istiyorsanız aşağıdaki kılavuzlardan birini kullanabilirsiniz:

• Microsoft 365 Agents Toolkit'i kullanarak Visual Studio'da .NET aracıları oluşturun
• Microsoft 365 Agents Toolkit ile Visual Studio Code'da JavaScript aracıları oluşturma