Hızlı Başlangıç: Temel bir aracı oluşturma ve test edin

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

Önkoş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 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. Agentler SDK'sını yükleyin

   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ı örneğini AgentApplication olarak oluşturma

app.py içinde, AGENT_APP'ün bir örneği olarak AgentApplication'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'ta dinlemek için web sunucusunu başlatın:3978

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)

Ajanı 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
   

   Uyarı

   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\"}"}}
   

Komut varsayılan teamsapptester 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 ileti gönderebilir veya bu iletinin /help işleyiciye nasıl yönlendirildiğini görmek için _help iletiyi gönderebilirsiniz.

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

Önkoşullar

• Node.js v22 veya daha yeni

  • 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

package.json oluşturup gerekli bağımlılıkları yükleyerek node.js projesini başlatmak için kullanın npm

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

   mkdir echo
   cd echo
   

2. node.js projesini başlatma

   npm init -y
   

3. Agentler SDK'sını yükleyin

   npm install @microsoft/agents-hosting-express
   

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

   code .
   

Gerekli kitaplıkları içeri aktarma

Dosyasını index.mjs oluşturun ve aşağıdaki NPM paketlerini uygulama kodunuz içine 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'ı AgentApplication olarak uygulama

index.mjs içinde, EchoAgent'ı genişleten 'i 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

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

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

Ajanı 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\"}"}}
   

Komut varsayılan teamsapptester 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 ileti gönderebilir veya bu iletinin /help işleyiciye nasıl yönlendirildiğini görmek için _help iletiyi gönderebilirsiniz.

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

Önkoşullar

• .NET 8.0 SDK veya daha yenisi

  • .NET SDK'sını yüklemek için dotnet.microsoft.com gidin ve işletim sisteminizin yönergelerini 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 kullanın dotnet .

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

   mkdir echo
   cd echo
   

2. .NET projesini başlatma

   dotnet new web
   

3. Agentler SDK'sını yükleyin

   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

içinde Program.cs, mevcut içeriği değiştirin ve SDK paketlerini uygulama kodunuza aktarmak için aşağıdaki using deyimleri 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'ı AgentApplication olarak uygulama

ifadesinden sonra açıklamalarını bitirdikten sonra, 'yi genişleten bir AgentApplication oluşturmak ve olaylara yanıt verecek yolları uygulamak için 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 ayarlama ve aracı uygulamasını kaydetme

Program.cs'den sonra, using deyimlerinden sonra, web konağı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();

Web sunucusunu localhost'ta dinleyecek şekilde ayarlama:3978

launchSettings.json içinde, uygulamanın doğru bağlantı noktasında dinleyebilmesi için applicationURL öğesini http://localhost:3978 olarak güncelleştirin.

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

Ajanı yerel olarak test edin

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

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

   Uyarı

   Microsoft 365 Agents Playground bir npm paketi olarak dağıtıldığı için 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\"}"}}
   

Komut varsayılan teamsapptester tarayıcınızı açar ve aracınıza bağlanır.

Metin girişinde, yankı yanıtını görmek için herhangi bir ileti girin ve gönderin.

Sonraki Adımlar

• GitHub'da Aracılar SDK örneklerine göz atın
• Etkinlikler ve Etkinliklerle çalışma hakkında daha fazla bilgi edinin
• İstemciden yanıtlayabileceğiniz AgentApplication olaylarını gözden geçirin
• İstemciye geri gönderebileceğiniz TurnContext olaylarını gözden geçirin
• Aracılar SDK'sı ile kullanılacak Azure Bot kaynaklarını sağlama
• .NET Ajanınızı OAuth kullanacak şekilde yapılandırın

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

• Microsoft 365 Aracıları Araç Seti'ni kullanarak Visual Studio'da .NET aracıları oluşturma
• Microsoft 365 Aracıları Araç Seti ile Visual Studio Code'da JavaScript aracıları oluşturma