Mulai cepat: Membuat dan menguji agen dasar

Panduan Memulai Cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan yang sama persis dengan yang Anda kirimkan.

Prasyarat

Python 3.9 atau yang lebih baru.
- Untuk menginstal Python, buka https://www.python.org/downloads/, dan ikuti instruksi untuk sistem operasi Anda.
- Untuk memverifikasi versi, ketikkan python --version di dalam jendela terminal.
Editor kode pilihan Anda. Instruksi ini menggunakan Visual Studio Code.

Jika Anda menggunakan Visual Studio Code, instal ekstensi Python

Menginisialisasi proyek dan menginstal SDK

Buat proyek Python dan instal dependensi yang diperlukan.

Buka terminal dan buat folder baru
```
mkdir echo
cd echo
```
Buka folder menggunakan Visual Studio Code menggunakan perintah ini:
```
code .
```
Buat lingkungan virtual dengan metode pilihan Anda dan aktifkan melalui Visual Studio Code atau di terminal.

Saat menggunakan Visual Studio Code, Anda dapat menggunakan langkah-langkah ini dengan ekstensi Python yang diinstal.
1. Tekan F1, ketik Python: Create environment, dan tekan Enter.
  1. Pilih Venv untuk membuat .venv lingkungan virtual di ruang kerja saat ini.
  2. Pilih penginstalan Python untuk membuat lingkungan virtual.
    
    Nilainya mungkin terlihat seperti ini:
    
    Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
Menginstal SDK Agen

Gunakan pip untuk menginstal paket microsoft-agents-hosting-aiohttp dengan perintah ini:
```
pip install microsoft-agents-hosting-aiohttp
```

Membuat aplikasi server dan mengimpor pustaka yang diperlukan

Buat file bernama start_server.py, salin kode berikut, dan tempelkan di:

# 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

Kode ini mendefinisikan fungsi yang start_server akan kita gunakan dalam file berikutnya.

Di direktori yang sama, buat file bernama app.py dengan kode berikut.

# 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

Membuat instans agen sebagai AgentApplication

Dalam app.py, tambahkan kode berikut untuk membuat AGENT_APP sebagai instans , AgentApplicationdan terapkan tiga rute untuk merespons tiga peristiwa:

Pembaruan Percakapan
pesan /help
aktivitas lainnya

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

Mulai server web untuk mendengarkan di localhost:3978

Di akhir app.py, mulai server web menggunakan start_server.

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

Menjalankan agen secara lokal dalam mode anonim

Dari terminal Anda, jalankan perintah ini:

python app.py

Terminal harus mengembalikan hal berikut:

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

Menguji agen di lingkungan lokal

Dari terminal lain (untuk menjaga agen tetap berjalan) instal Microsoft 365 Agents Playground dengan perintah ini:
```
npm install -g @microsoft/teams-app-test-tool
```
Nota

Perintah ini menggunakan npm karena Microsoft 365 Agents Playground tidak tersedia menggunakan pip.

Terminal harus mengembalikan sesuatu seperti:
```
added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities
```

Jalankan alat pengujian untuk berinteraksi dengan agen Anda menggunakan perintah ini:

teamsapptester

Terminal harus mengembalikan sesuatu seperti:

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

Perintah teamsapptester membuka browser default Anda dan terhubung ke agen Anda.

Agen Anda di playground agen

Sekarang Anda dapat mengirim pesan apa pun untuk melihat balasan echo, atau mengirim pesan /help untuk melihat bagaimana pesan tersebut dirutekan ke _help handler.

Panduan Memulai Cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan yang sama persis dengan yang Anda kirimkan.

Prasyarat

Node.js v22 atau yang lebih baru
- Untuk menginstal Node.js buka nodejs.org, dan ikuti instruksi untuk sistem operasi Anda.
- Untuk memverifikasi versi, ketikkan node --version di dalam jendela terminal.
Editor kode pilihan Anda. Instruksi ini menggunakan Visual Studio Code.

Menginisialisasi proyek dan menginstal SDK

Gunakan npm untuk menginisialisasi proyek node.js dengan membuat package.json dan menginstal dependensi yang diperlukan

Buka terminal dan buat folder baru
```
mkdir echo
cd echo
```
Menginisialisasi proyek node.js
```
npm init -y
```

Menginstal SDK Agen

npm install @microsoft/agents-hosting-express

Buka folder menggunakan Visual Studio Code menggunakan perintah ini:
```
code .
```

Mengimpor pustaka yang diperlukan

Buat file index.mjs dan impor paket NPM berikut ke dalam kode aplikasi Anda:

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

Menerapkan EchoAgent sebagai AgentApplication

Di index.mjs, tambahkan kode berikut untuk membuat EchoAgent perluasan AgentApplication, dan terapkan tiga rute untuk merespons tiga peristiwa:

Pembaruan Percakapan
pesan /help
aktivitas lainnya

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

Mulai server web untuk mendengarkan di localhost:3978

Di akhir index.mjs, mulai server web menggunakan startServer berdasarkan Express dengan MemoryStorage sebagai penyimpanan status giliran.

startServer(new EchoAgent(new MemoryStorage()))

Menjalankan agen secara lokal dalam mode anonim

Dari terminal Anda, jalankan perintah ini:

node index.mjs

Terminal harus mengembalikan ini:

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

Menguji agen di lingkungan lokal

Dari terminal lain (untuk menjaga agen tetap berjalan) instal Microsoft 365 Agents Playground dengan perintah ini:

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

Terminal harus mengembalikan sesuatu seperti:

added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

Jalankan alat pengujian untuk berinteraksi dengan agen Anda menggunakan perintah ini:

node_modules/.bin/teamsapptester

Terminal harus mengembalikan sesuatu seperti:

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

Perintah teamsapptester membuka browser default Anda dan terhubung ke agen Anda.

Agen Anda di playground agen

Sekarang Anda dapat mengirim pesan apa pun untuk melihat balasan echo, atau mengirim pesan /help untuk melihat bagaimana pesan tersebut dirutekan ke _help handler.

Panduan Memulai Cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan yang sama persis dengan yang Anda kirimkan.

Prasyarat

.NET 8.0 SDK atau yang lebih baru
- Untuk menginstal .NET SDK, buka dotnet.microsoft.com, dan ikuti instruksi untuk sistem operasi Anda.
- Untuk memverifikasi versi, ketikkan dotnet --version di dalam jendela terminal.
Editor kode pilihan Anda. Instruksi ini menggunakan Visual Studio Code.

Menginisialisasi proyek dan menginstal SDK

Gunakan dotnet untuk membuat proyek web baru dan menginstal dependensi yang diperlukan.

Buka terminal dan buat folder baru
```
mkdir echo
cd echo
```
Menginisialisasi proyek .NET
```
dotnet new web
```

Menginstal SDK Agen

dotnet add package Microsoft.Agents.Hosting.AspNetCore

Buka folder menggunakan Visual Studio Code menggunakan perintah ini:
```
code .
```

Mengimpor pustaka yang diperlukan

Di Program.cs, ganti konten yang ada dan tambahkan pernyataan berikut using untuk mengimpor paket SDK ke dalam kode aplikasi Anda:

// 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;

Menerapkan EchoAgent sebagai AgentApplication

Di Program.cs, setelah using pernyataan, tambahkan kode berikut untuk membuat EchoAgentAgentApplication yang diperluas, dan terapkan rute untuk menanggapi peristiwa:

Pembaruan Percakapan
Aktivitas lainnya

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

Menyiapkan server web dan mendaftarkan aplikasi agen

Di Program.cs, setelah pernyataan-pernyataan using, tambahkan kode berikut untuk mengonfigurasi host web, mendaftarkan agen, dan memetakan endpoint /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();

Atur server web untuk mendengarkan di localhost:3978

Di launchSettings.json, perbarui applicationURL ke http://localhost:3978 sehingga aplikasi mendengarkan pada port yang benar.

Menjalankan agen secara lokal dalam mode anonim

Dari terminal Anda, jalankan perintah ini:

dotnet run

Terminal harus mengembalikan sesuatu seperti:

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

Menguji agen di lingkungan lokal

Dari terminal lain (untuk menjaga agen tetap berjalan) instal Microsoft 365 Agents Playground dengan perintah berikut:
```
npm install -g @microsoft/teams-app-test-tool
```
Nota

Perintah ini menggunakan npm karena Microsoft 365 Agents Playground didistribusikan sebagai paket npm.

Terminal harus mengembalikan sesuatu seperti:
```
added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities
```

Jalankan alat pengujian untuk berinteraksi dengan agen Anda menggunakan perintah ini:

teamsapptester

Terminal harus mengembalikan sesuatu seperti:

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

Perintah teamsapptester membuka browser default Anda dan terhubung ke agen Anda.

Agen Anda di playground agen

Di input teks, masukkan dan kirim pesan apa pun untuk melihat balasan echo.

Langkah selanjutnya

Agents Playground tersedia secara default jika Anda sudah menggunakan Toolkit Agen Microsoft 365. Anda dapat menggunakan salah satu panduan berikut jika Anda ingin mulai menggunakan toolkit:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-14

Bagikan melalui

Mulai cepat: Membuat dan menguji agen dasar

Prasyarat

Menginisialisasi proyek dan menginstal SDK

Membuat aplikasi server dan mengimpor pustaka yang diperlukan

Membuat instans agen sebagai AgentApplication

Mulai server web untuk mendengarkan di localhost:3978

Menjalankan agen secara lokal dalam mode anonim

Menguji agen di lingkungan lokal

Prasyarat

Menginisialisasi proyek dan menginstal SDK

Mengimpor pustaka yang diperlukan

Menerapkan EchoAgent sebagai AgentApplication

Mulai server web untuk mendengarkan di localhost:3978

Menjalankan agen secara lokal dalam mode anonim

Menguji agen di lingkungan lokal

Prasyarat

Menginisialisasi proyek dan menginstal SDK

Mengimpor pustaka yang diperlukan

Menerapkan EchoAgent sebagai AgentApplication

Menyiapkan server web dan mendaftarkan aplikasi agen

Atur server web untuk mendengarkan di localhost:3978

Menjalankan agen secara lokal dalam mode anonim

Menguji agen di lingkungan lokal

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: