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

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

Langkah selanjutnya

Memprovisikan sumber daya Azure Bot untuk digunakan dengan Agen SDK

Panduan memulai cepat ini memandu Anda membuat agen mesin kustom yang hanya membalas dengan apa pun yang Anda kirim kepadanya.

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

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

Langkah selanjutnya

Memprovisikan sumber daya Azure Bot untuk digunakan dengan Agen SDK

Mulai cepat ini menunjukkan kepada Anda cara mengunduh dan menjalankan sampel QuickStart/Empty Agent dari GitHub.

Ada dua cara utama untuk mulai menggunakan Microsoft 365 Agents SDK:

Mengkloning dan menjalankan sampel agen QuickStart/Empty Agent yang tersedia di GitHub
Gunakan Toolkit Agen Microsoft 365. Agents Toolkit memiliki dua templat bawaan untuk Visual Studio dan Visual Studio Code yang menggunakan Microsoft 365 Agents SDK untuk memulai proyek dengan QuickStart/Empty Agent dan Weather Agent, yang keduanya menggunakan layanan Azure atau OpenAI dengan Semantic Kernel atau LangChain.

Prasyarat

Anda memerlukan beberapa hal sebelum memulai. Langkah-langkah ini menggunakan sampel QuickStart/Empty Agent di QuickStart .NET, tetapi Anda juga dapat menggunakan sampel SDK Agen apa pun.

.NET 8.0 SDK
Visual Studio atau Visual Studio Code
Pengetahuan tentang ASP.NET Core dan pemrograman asinkron di C#
quickstart Unduh sampel dari GitHub

Buka solusi

Buka file QuickStart.csproj solusi di Visual Studio.
Jalankan proyek.

Pada titik ini, agen Anda berjalan secara lokal menggunakan port 3978.

Menguji agen Anda secara lokal

Instal Agents Playground jika Anda belum melakukannya.
```
winget install agentsplayground
```
Memulai agen di Visual Studio atau Visual Studio Code
Mulai Penguji Aplikasi Teams. Di prompt perintah: agentsplayground
- Alat ini membuka browser web yang menunjukkan Alat Uji Aplikasi Teams, siap untuk mengirim pesan ke agen Anda.
Agen yang sedang berjalan di port 3978 harus terhubung secara otomatis ke taman bermain agen di browser Anda dan Anda harus dapat berinteraksi dengan agen Anda yang berjalan secara lokal

Bagaimana cara kerja agen?

Dengan Agen SDK, agen dibangun menggunakan kelas AgentApplication dan AgentApplicationOptions . Ini dibangun dalam berkas contoh Program.cs.

Buat agen Anda

Anda dapat melihat dalam sampel bahwa saat agen sedang dibangun, AgentApplicationOptions dimuat dan kelas agen kustom Anda, MyAgent.cs, yang mewarisi dari AgentApplication.

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

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

Kemudian penyimpanan dimuat secara default menggunakan kelas MemoryStorage. Ini memungkinkan konteks dilacak di seluruh giliran saat menggunakan TurnState; namun, dalam produksi, disarankan untuk menggantinya dengan penyimpanan yang lebih persisten seperti BlobsStorage atau CosmosDbPartitionedStorage.

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

Aplikasi agen lainnya menggunakan pola hosting .NET standar, dan menambahkan rute untuk menerima pesan di titik akhir tertentu. Rute ini menggunakan antarmuka IAgent untuk menerima aktivitas agen, dan memberi pengembang objek AgentApplication untuk bekerja dengan muatan Aktivitas yang diteruskan ke antarmuka tersebut dari saluran/klien. Pelajari lebih lanjut tentang Aktivitas dan cara mengelola Aktivitas

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

Menambahkan logika kustom baru dalam metode

Pengembang menambahkan logika kustom di MyAgent.cs kelas yang mengimplementasikan AgentApplication. Kelas ini menggunakan AgentApplicationOptions untuk mengonfigurasi pengaturan spesifik dari konfigurasi Anda dan Program.cs serta mendaftarkan pendengar peristiwa dari Agen SDK, tersedia di kelas AgentApplication yang mereferensikan metode kustom masing-masing saat peristiwa tersebut dipicu dari klien.

Dalam contoh berikut, OnConversationUpdate memicu WelcomeMessageAsync metode dan OnActivity memicu metode OnMessageAsync.

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

Peristiwa-peristiwa tersebut dirutekan melalui titik akhir yang dikonfigurasi dalam MyProgram.cs Anda, dan terdapat banyak peristiwa yang dapat digunakan. Yang paling umum adalah OnActivity. Untuk mempelajari selengkapnya tentang peristiwa yang diterapkan SDK, lihat selengkapnya tentang bekerja dengan aktivitas dan spesifikasi protokol Aktivitas.

Setelah metode Anda dipicu, misalnya OnMessageAsync untuk mengakhiri giliran, Anda dapat memilih dalam logika kustom Anda untuk merespons untuk mengirim pesan kembali ke klien dengan menggunakan metode yang tersedia di dan instans kelas TurnContext yang harus menjadi parameter dalam metode Anda seperti yang ditunjukkan dalam contoh berikut:

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

Petunjuk / Saran

Tinjau metode TurnContext lainnya yang tersedia untuk kembali ke klien.

Sekarang Anda mengetahui dasar-dasarnya, lihat langkah-langkah berikutnya dan bekerja untuk menambahkan logika handler kustom ke agen Anda dan mengirim kembali peristiwa yang berbeda.

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 2025-11-18

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

Jalankan Agen secara lokal dalam mode anonim

Menguji agen di lingkungan lokal

Langkah selanjutnya

Prasyarat

Menginisialisasi proyek dan menginstal SDK

Mengimpor pustaka yang diperlukan

Menerapkan EchoAgent sebagai AgentApplication

Mulai server web untuk mendengarkan di localhost:3978

Jalankan Agen secara lokal dalam mode anonim

Menguji agen di lingkungan lokal

Langkah selanjutnya

Prasyarat

Buka solusi

Menguji agen Anda secara lokal

Bagaimana cara kerja agen?

Buat agen Anda

Menambahkan logika kustom baru dalam metode

Langkah Selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: