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.

Terminal açma ve yeni klasör oluşturma
```
mkdir echo
cd echo
```
Bu komutu kullanarak Visual Studio Code kullanarak klasörü açın:
```
code .
```
İ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
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

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.

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, 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ırın

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

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
```

Ş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.

Temsilciniz ajanlar için oyun alanında

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.

Sonraki Adımlar

Aracılar SDK'sı ile kullanılacak Azure Bot kaynaklarını sağlama

Bu hızlı başlangıç, yalnızca gönderdiğiniz her şeyi yanıtlayan özel bir altyapı 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

Terminal açma ve yeni klasör oluşturma
```
mkdir echo
cd echo
```
node.js projesini başlatma
```
npm init -y
```

Agentler SDK'sını yükleyin

npm install @microsoft/agents-hosting-express

Ş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:

// 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ırın

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

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

Ş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.

Temsilciniz ajanlar için oyun alanında

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.

Sonraki Adımlar

Aracılar SDK'sı ile kullanılacak Azure Bot kaynaklarını sağlama

Bu hızlı başlangıç, GitHub'dan Quickstart/Empty Agent örneğini nasıl indirip çalıştıracağınızı gösteriyor.

Microsoft 365 Aracıları SDK'sını kullanmaya başlamanın iki ana yolu vardır:

GitHub'da bulunan Hızlı Başlangıç/Boş Aracı aracı örneğini kopyalama ve çalıştırma
Microsoft 365 Aracılar Araç Seti'ni kullanın. Aracılar Araç Seti, Visual Studio ve Visual Studio Code için Microsoft 365 Aracıları SDK'sını kullanarak başlangıçta bir QuickStart/Empty Agent ve Semantic Kernel veya LangChain ile Azure Foundry veya OpenAI Hizmetleri kullanan bir Weather Agent için iki yerleşik şablona sahiptir.

Önkoşullar

Başlamadan önce birkaç şeye ihtiyacınız var. Bu adımlarda .NET hızlı başlangıcında Hızlı Başlangıç/Boş Aracı örneği kullanılır, ancak herhangi bir Aracı SDK örneğini de kullanabilirsiniz.

.NET 8.0 SDK
Visual Studio veya Visual Studio Code
C#'de ASP.NET Core ve zaman uyumsuz programlama bilgisi
quickstart Örneği GitHub'dan indirin

Çözümü açma

Çözüm dosyasını QuickStart.csproj Visual Studio'da açın.
Projeyi çalıştırın.

Bu noktada aracınız 3978 numaralı bağlantı noktasını kullanarak yerel olarak çalışır.

Ajanınızı yerel olarak test edin

Henüz yüklemediyseniz Agents Playground'u yükleyin.
```
winget install agentsplayground
```
Aracıyı Visual Studio veya Visual Studio Code'da başlatma
Teams Uygulama Test Aracı'nı başlatın. Komut isteminde: agentsplayground
- Araç, aracınıza ileti göndermeye hazır olan Teams Uygulama Test Aracını gösteren bir web tarayıcısı açar.
3978 numaralı bağlantı noktasında çalışan aracınız tarayıcınızdaki aracı oyun parkına otomatik olarak bağlanmalıdır ve yerel olarak çalışan aracınızla etkileşim kurabilmeniz gerekir

Etmen nasıl çalışır?

Aracılar SDK'sı ile AgentApplication ve AgentApplicationOptions sınıfları kullanılarak bir aracı oluşturulur. Bu, örnek dosyanın Program.cs satırında yerleşiktir.

Aracılarınızı geliştirin

Örnekte, aracı oluşturma sürecinde AgentApplicationOptions yüklendiğini ve MyAgent.cs öğesinden devralan özel aracınız olan AgentApplication sınıfının yüklendiğini görebilirsiniz.

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

Ardından depolama varsayılan olarak MemoryStorage sınıfı kullanılarak yüklenir. Bu, TurnState kullanılırken farklı turlar arasında bağlamın izlenmesini sağlar, ancak üretimde, BlobsStorage veya CosmosDbPartitionedStorage gibi daha kalıcı depolamalarla değiştirilmelidir.

builder.Services.AddSingleton<IStorage, MemoryStorage>();

Aracı uygulamasının geri kalanı standart .NET barındırma desenlerini kullanır ve belirli bir uç noktadaki iletileri kabul etmek için yollar ekler. Bu yollar aracı etkinliğini kabul etmek için IAgent arabirimini kullanır ve geliştiricilere, kanaldan/istemciden geçirilen AgentApplication yüküyle çalışmak için nesnesini sağlar. Etkinlikler ve Etkinliklerle çalışma hakkında daha fazla bilgi edinin

// This receives incoming messages from Azure Bot Service or other SDK Agents
var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

Yönteme yeni özel mantık ekleme

Geliştiriciler, MyAgent.cs'ı uygulayan AgentApplication sınıfına özel mantık ekler. Bu sınıf, yapılandırmanızdan belirli ayarları yapılandırmak için AgentApplicationOptions kullanır ve Program.cs öğesini kullanarak, bu olaylar istemci tarafından tetiklendiğinde ilgili özel yöntemine başvurup Agents SDK'sında yer alan AgentApplication olay dinleyicilerini kaydeder.

Aşağıdaki örnekte , OnConversationUpdate yöntemini tetikler WelcomeMessageAsync ve OnActivity yöntemini OnMessageAsynctetikler.

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

Bu olaylar, içinde MyProgram.cs yapılandırılan uç nokta üzerinden yönlendirilir ve kullanabileceğiniz çok sayıda olay vardır. En yaygın olanıdır OnActivity. SDK'nın uyguladığı olaylar hakkında daha fazla bilgi edinmek için etkinliklerle çalışma ve Etkinlik protokolü belirtimi hakkında daha fazla bilgi edinin.

Metodunuz tetiklendiğinde, örneğin OnMessageAsync hamleyi sonlandırmak üzere, aşağıdaki örnekte gösterildiği gibi metodunuzda bir parametre olarak bulunması gereken TurnContext sınıfı örneğindeki yöntemleri kullanarak istemciye yanıt olarak mesaj göndermeyi özel mantığınızda tercih edebilirsiniz.

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

Tip

İstemciye dönmek için kullanılabilecek diğer TurnContext yöntemlerini gözden geçirin.

Artık temel bilgileri biliyorsunuz, sonraki adımları gözden geçirin ve aracınıza özel işleyici mantığı eklemek ve farklı olayları geri göndermek için çalışın.

Sonraki Adımlar

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:

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-18

Aracılığıyla paylaş

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

Önkoşullar

Projeyi başlatma ve SDK'yi yükleme

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

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

Localhost'ta dinlemek için web sunucusunu başlatın:3978

Aracıyı anonim modda yerel olarak çalıştırın

Ajanı yerel olarak test edin

Sonraki Adımlar

Önkoşullar

Projeyi başlatma ve SDK'yi yükleme

Gerekli kitaplıkları içeri aktarma

EchoAgent'ı AgentApplication olarak uygulama

Localhost'ta dinlemek için web sunucusunu başlatın:3978

Aracıyı anonim modda yerel olarak çalıştırın

Ajanı yerel olarak test edin

Sonraki Adımlar

Önkoşullar

Çözümü açma

Ajanınızı yerel olarak test edin

Etmen nasıl çalışır?

Aracılarınızı geliştirin

Yönteme yeni özel mantık ekleme

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar