Mulai cepat: Membuat dan menguji agen dasar

Panduan mulai cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan apa pun yang Anda kirimkan kepadanya.

Prasyarat

• Python 3.9 atau lebih baru.

  • Untuk menginstal Python, buka https://www.python.org/downloads/, dan ikuti petunjuk untuk sistem operasi Anda.
  • Untuk memverifikasi versi, di jendela terminal, ketik python --version.

• Editor kode pilihan Anda. Petunjuk ini menggunakan Visual Studio Code.

  Jika Anda menggunakan Visual Studio Code, Instal ekstensi Python

Inisialisasi proyek dan instal SDK

Buat proyek Python dan instal dependensi yang diperlukan.

1. Buka terminal dan buat folder baru

   mkdir echo
   cd echo
   

2. Buka folder menggunakan Visual Studio Code dengan perintah berikut:

   code .
   

3. Buat lingkungan virtual dengan metode yang Anda pilih dan aktifkan baik melalui Visual Studio Code atau di terminal.

   Saat menggunakan Visual Studio Code, Anda dapat menggunakan langkah-langkah ini dengan ekstensi Python yang terinstal.

   1. Tekan F1, jenis Python: Create environment, lalu tekan Masukkan.

      1. Pilih Venv untuk membuat .venv lingkungan virtual di ruang kerja saat ini.

      2. Pilih instalasi Python untuk membuat lingkungan virtual.

         Nilainya mungkin terlihat seperti ini:

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

4. Menginstal SDK Agen

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

   pip install microsoft-agents-hosting-aiohttp
   

Buat aplikasi server dan impor pustaka yang diperlukan

1. Buat file bernama start_server.py, salin kode berikut, lalu tempelkan ke dalamnya:

   # 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 start_server yang akan kita gunakan di file berikutnya.

2. 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 dari agen sebagai AgentApplication

Di app.py, tambahkan kode berikut untuk membuat AGENT_APP sebagai instans dari AgentApplication, lalu mengimplementasikan 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 menerima koneksi 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 akan menampilkan hal berikut:

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

Uji agen secara lokal

1. Dari terminal lainnya (agar agen tetap berjalan), install Microsoft 365 Agents Playground dengan perintah ini:

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

   Catatan

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

   Terminal akan menampilkan sesuatu seperti berikut:

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

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

   teamsapptester
   

   Terminal akan menampilkan sesuatu seperti berikut:

   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 akan membuka browser default Anda dan akan terhubung ke agen Anda.

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

Panduan mulai cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan apa pun yang Anda kirimkan kepadanya.

Prasyarat

• Node.js v22 atau yang lebih baru

  • Untuk menginstal Node.js, buka nodejs.org dan ikuti petunjuk untuk sistem operasi Anda.
  • Untuk memverifikasi versi, di jendela terminal, ketik node --version.

• Editor kode pilihan Anda. Petunjuk ini menggunakan Visual Studio Code.

Inisialisasi proyek dan instal SDK

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

1. Buka terminal dan buat folder baru

   mkdir echo
   cd echo
   

2. Inisialisasikan proyek Node.js

   npm init -y
   

3. Menginstal SDK Agen

   npm install @microsoft/agents-hosting-express
   

4. Buka folder tersebut di Visual Studio Code dengan perintah berikut:

   code .
   

Impor pustaka yang diperlukan

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

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

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

Mengimplementasikan EchoAgent sebagai AgentApplication

Di index.mjs, tambahkan kode berikut untuk membuat EchoAgent yang memperluas 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 menerima koneksi 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 akan menampilkan hal berikut:

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

Uji agen secara lokal

1. Dari terminal lainnya (agar agen tetap berjalan), install Microsoft 365 Agents Playground dengan perintah ini:

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

   Terminal akan menampilkan sesuatu seperti berikut:

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

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

   node_modules/.bin/teamsapptester
   

   Terminal akan menampilkan sesuatu seperti berikut:

   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 akan membuka browser default Anda dan akan terhubung ke agen Anda.

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

Panduan mulai cepat ini memandu Anda membuat agen mesin kustom yang membalas dengan pesan apa pun yang Anda kirimkan kepadanya.

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, di jendela terminal, ketik dotnet --version.

• Editor kode pilihan Anda. Petunjuk ini menggunakan Visual Studio Code.

Inisialisasi proyek dan instal SDK

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

1. Buka terminal dan buat folder baru

   mkdir echo
   cd echo
   

2. Inisialisasi proyek .NET

   dotnet new web
   

3. Menginstal SDK Agen

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Buka folder menggunakan Visual Studio Code dengan perintah berikut:

   code .
   

Impor pustaka yang diperlukan

Di Program.cs, ganti konten yang ada dan tambahkan pernyataan berikut using untuk mengimpor paket SDK ke 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;

Mengimplementasikan EchoAgent sebagai AgentApplication

Di Program.cs, setelah pernyataan using, tambahkan kode berikut untuk membuat EchoAgent yang memperluas AgentApplication, dan mengimplementasikan rute untuk merespons peristiwa:

• Pembaruan Percakapan
• Aktivitas apa pun 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);
   }
}

Siapkan server web dan daftarkan aplikasi agen

Di Program.cs, setelah pernyataan using, tambahkan kode berikut untuk mengonfigurasi host web, mendaftarkan agen, dan memetakan titik akhir /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 ke localhost:3978

Pada launchSettings.json, perbarui applicationURL ke http://localhost:3978 agar aplikasi bisa mendengarkan pada port yang benar.

Jalankan agen secara lokal dalam mode anonim

Dari terminal Anda, jalankan perintah ini:

dotnet run

Terminal akan menampilkan sesuatu seperti berikut:

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

Uji agen secara lokal

1. Dari terminal lainnya (agar agen tetap berjalan), instal Microsoft 365 Agents Playground dengan perintah berikut:

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

   Catatan

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

   Terminal akan menampilkan sesuatu seperti berikut:

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

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

   teamsapptester
   

   Terminal akan menampilkan sesuatu seperti berikut:

   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 akan membuka browser default Anda dan akan terhubung ke agen Anda.

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

Langkah berikutnya

• Lihat sampel Agents SDK di GitHub
• Pelajari selengkapnya tentang Aktivitas dan cara menggunakan Aktivitas
• Tinjau peristiwa AgentApplication yang dapat Anda tanggapi dari klien
• Tinjau peristiwa TurnContext yang dapat Anda kirim kembali ke klien
• Menyediakan sumber daya Azure Bot untuk digunakan dengan Agen SDK
• Mengonfigurasi Agen .NET Anda untuk menggunakan OAuth

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

• Membuat agen .NET di Visual Studio dengan Toolkit Agen Microsoft 365
• Membuat agen JavaScript di Visual Studio Code dengan Toolkit Agen Microsoft 365