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.

1. Buka terminal dan buat folder baru

   mkdir echo
   cd echo
   

2. Buka folder menggunakan Visual Studio Code menggunakan perintah ini:

   code .
   

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

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

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

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

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

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

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

1. Buka terminal dan buat folder baru

   mkdir echo
   cd echo
   

2. Menginisialisasi proyek node.js

   npm init -y
   

3. Menginstal SDK Agen

   npm install @microsoft/agents-hosting-express
   

4. 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:

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

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

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

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

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

1. Buka file QuickStart.csproj solusi di Visual Studio.

2. Jalankan proyek.

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

Menguji agen Anda secara lokal

1. Instal Agents Playground jika Anda belum melakukannya.

   winget install agentsplayground
   

2. Memulai agen di Visual Studio atau Visual Studio Code

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

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

• Pelajari lebih lanjut tentang Aktivitas dan cara mengelola Aktivitas
• Tinjau event AgentApplication yang dapat Anda tanggapi dari klien
• Tinjau peristiwa TurnContext yang dapat Anda kirim kembali ke klien
• Memprovisikan 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 Toolkit Agen Microsoft 365. Anda dapat menggunakan salah satu panduan berikut jika Anda ingin mulai menggunakan toolkit:

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