Rychlý start: Vytvoření a testování základního agenta

Tato úvodní příručka vás provede vytvořením vlastního agenta enginu, který odpoví libovolnou zprávou, kterou mu pošlete.

Požadavky

Python 3.9 nebo novější
- Pokud chcete nainstalovat Python, přejděte na https://www.python.org/downloads/stránku a postupujte podle pokynů pro váš operační systém.
- Chcete-li ověřit verzi, zadejte python --versionv okně terminálu .
Editor kódu podle vašeho výběru. Tyto pokyny používají Visual Studio Code.

Pokud používáte Visual Studio Code, nainstalujte rozšíření Pythonu.

Inicializace projektu a instalace sady SDK

Vytvořte projekt Pythonu a nainstalujte požadované závislosti.

Otevření terminálu a vytvoření nové složky
```
mkdir echo
cd echo
```
Pomocí tohoto příkazu otevřete složku pomocí editoru Visual Studio Code:
```
code .
```
Vytvořte virtuální prostředí pomocí metody podle vašeho výběru a aktivujte ho prostřednictvím editoru Visual Studio Code nebo v terminálu.

Při použití editoru Visual Studio Code můžete použít tyto kroky s nainstalovaným rozšířením Pythonu .
1. Stiskněte klávesu F1, zadejte Python: Create environmenta stiskněte Enter.
  1. Vyberte Venv a vytvořte .venv virtuální prostředí v aktuálním pracovním prostoru.
  2. Vyberte instalaci Pythonu a vytvořte virtuální prostředí.
    
    Hodnota může vypadat takto:
    
    Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
Instalace sady Agents SDK

Pomocí nástroje pip nainstalujte balíček microsoft-agents-hosting-aiohttp pomocí tohoto příkazu:
```
pip install microsoft-agents-hosting-aiohttp
```

Vytvoření serverové aplikace a import požadovaných knihoven

Vytvořte soubor s názvem start_server.py, zkopírujte následující kód a vložte ho do:

# 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

Tento kód definuje start_server funkci, která použijeme v dalším souboru.

Ve stejném adresáři vytvořte soubor s názvem app.py s následujícím kódem.

# 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

Vytvořte instanci agenta jako AgentApplication

Do app.pypole přidejte následující kód, který vytvoří AGENT_APP jako instanci objektu AgentApplicationa implementuje tři trasy pro reakci na tři události:

Aktualizace konverzace
zpráva /help
jakákoli jiná aktivita

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

Spuštění webového serveru pro naslouchání v localhost:3978

Na konci app.py, spusťte webový server pomocí start_server.

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

Místní spuštění agenta v anonymním režimu

V terminálu spusťte tento příkaz:

python app.py

Terminál by měl vrátit následující:

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

Otestujte agenta lokálně

Z jiného terminálu (aby byl agent spuštěný) nainstalujte Microsoft 365 Agents Playground tímto příkazem:
```
npm install -g @microsoft/teams-app-test-tool
```
Poznámka:

Tento příkaz používá npm, protože Microsoft 365 Agents Playground není k dispozici pomocí pip.

Terminál by měl vrátit něco podobného:
```
added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities
```

Pomocí tohoto příkazu spusťte testovací nástroj pro interakci s vaším agentem:

teamsapptester

Terminál by měl vrátit něco podobného:

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

Příkaz teamsapptester otevře výchozí prohlížeč a připojí se k vašemu agentu.

Váš agent v prostředí agentů

Teď můžete odeslat libovolnou zprávu, abyste viděli odezvu echo, nebo odeslat zprávu /help, abyste viděli, jak se tato zpráva směruje do obslužné rutiny _help.

Další kroky

Zřízení prostředků Azure Bot pro použití se sadou Agents SDK

Tento úvod vás provede vytvořením vlastního agenta stroje, který odpoví přesně tím, co mu pošlete.

Požadavky

Node.js v22 nebo novější
- Pokud chcete nainstalovat Node.js přejděte na nodejs.org a postupujte podle pokynů pro váš operační systém.
- Chcete-li ověřit verzi, zadejte node --versionv okně terminálu .
Editor kódu podle vašeho výběru. Tyto pokyny používají Visual Studio Code.

Inicializace projektu a instalace sady SDK

Slouží npm k inicializaci projektu node.js vytvořením package.json a instalací požadovaných závislostí.

Otevření terminálu a vytvoření nové složky
```
mkdir echo
cd echo
```
Inicializace projektu node.js
```
npm init -y
```

Instalace sady Agents SDK

npm install @microsoft/agents-hosting-express

Pomocí tohoto příkazu otevřete složku pomocí editoru Visual Studio Code:
```
code .
```

Import potřebných knihoven

Vytvořte soubor index.mjs a naimportujte do kódu aplikace následující balíčky NPM:

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

Implementovat EchoAgent jako AgentApplication

Do index.mjspole přidejte následující kód pro vytvoření EchoAgent rozšíření AgentApplication a implementujte tři trasy pro reakci na tři události:

Aktualizace konverzace
zpráva /help
jakákoli jiná aktivita

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

Spuštění webového serveru pro naslouchání v localhost:3978

Na konci index.mjs spusťte webový server pomocí startServer na základě expresu s použitím MemoryStorage jako úložiště stavu přepnutí.

startServer(new EchoAgent(new MemoryStorage()))

Místní spuštění agenta v anonymním režimu

V terminálu spusťte tento příkaz:

node index.mjs

Terminál by měl vrátit toto:

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

Otestujte agenta lokálně

Z jiného terminálu (aby byl agent spuštěný) nainstalujte Microsoft 365 Agents Playground tímto příkazem:

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

Terminál by měl vrátit něco podobného:

added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

Pomocí tohoto příkazu spusťte testovací nástroj pro interakci s vaším agentem:

node_modules/.bin/teamsapptester

Terminál by měl vrátit něco podobného:

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

Příkaz teamsapptester otevře výchozí prohlížeč a připojí se k vašemu agentu.

Váš agent v prostředí agentů

Teď můžete odeslat libovolnou zprávu, abyste viděli odezvu echo, nebo odeslat zprávu /help, abyste viděli, jak se tato zpráva směruje do obslužné rutiny _help.

Další kroky

Zřízení prostředků Azure Bot pro použití se sadou Agents SDK

Tento rychlý start vám ukáže, jak si stáhnout a spustit vzorek QuickStart/Empty Agent z GitHubu.

Existují dva hlavní způsoby, jak začít se sadou Microsoft 365 Agents SDK:

Naklonujte a spusťte ukázkový projekt agenta QuickStart/Empty Agent dostupný na GitHubu.
Použijte sadu nástrojů Microsoft 365 Agents Toolkit. Sada Agents Toolkit obsahuje dvě vestavěné šablony pro Visual Studio a Visual Studio Code, které používají sadu Microsoft 365 Agents SDK pro začátek s QuickStart/Prázdným Agentem a Agentem počasí, který využívá služby Azure Foundry nebo OpenAI se sémantickým jádrem nebo s frameworkem LangChain.

Požadavky

Než začnete, potřebujete pár věcí. Tyto kroky používají ukázku rychlého startu nebo prázdného agenta v rychlém startu .NET, ale můžete také použít libovolnou ukázku sady Agents SDK.

Otevřete řešení

Otevřete soubor řešení QuickStart.csproj ve Visual Studiu.
Spusťte projekt.

V tomto okamžiku váš agent běží lokálně pomocí portu 3978.

Otestujte svého agenta lokálně

Pokud jste to ještě neudělali, nainstalujte službu Agents Playground .
```
winget install agentsplayground
```
Spusťte agenta v aplikaci Visual Studio nebo Visual Studio Code
Spusťte tester aplikace Teams. Na příkazovém řádku: agentsplayground
- Nástroj otevře webový prohlížeč zobrazující nástroj Teams App Test Tool připravený k odesílání zpráv vašemu agentu.
Spuštěný agent na portu 3978 by se měl automaticky připojit k testovacímu prostředí agenta v prohlížeči a měli byste být schopni interagovat s vaším agentem běžícím lokálně.

Jak agent funguje?

Se sadou Agents SDK se agent sestaví pomocí tříd AgentApplication a AgentApplicationOptions . Toto je součástí Program.cs souboru ukázky.

Vytvořte svého agenta

V ukázce vidíte, že během sestavování agenta AgentApplicationOptions se načítá a vaše vlastní třída agenta MyAgent.cs, která je podtřídou AgentApplication.

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

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

Úložiště se pak ve výchozím nastavení načte pomocí třídy MemoryStorage. To umožňuje sledovat kontext při použití TurnState, avšak v produkčním prostředí by se to mělo nahradit trvalejším úložištěm, jako je BlobStorage nebo CosmosDbPartitionedStorage.

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

Zbytek aplikace agenta používá standardní vzory hostování .NET a přidává trasy pro příjem zpráv v určitém koncovém bodu. Tyto trasy používají rozhraní IAgent k přijetí aktivity agenta a poskytují vývojářům AgentApplication objekt pro práci s payloadem Aktivity, který byl předán z kanálu nebo klienta. Další informace o aktivitách a práci s aktivitami

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

Přidání nové vlastní logiky do metody

Vývojáři přidávají vlastní logiku do MyAgent.cs třídy, která implementuje AgentApplication. Tato třída používá AgentApplicationOptions ke konfiguraci konkrétního nastavení z vaší konfigurace a Program.cs registruje posluchače událostí z Agents SDK, které jsou k dispozici ve třídě AgentApplication, jež odkazuje na vaši příslušnou vlastní metodu při aktivaci těchto událostí z klienta.

V následujícím příkladu OnConversationUpdate aktivuje metodu WelcomeMessageAsync a OnActivity aktivuje metodu OnMessageAsync.

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

Tyto události se směrují přes koncový bod nakonfigurovaný ve vašem MyProgram.cs a můžete využít mnoho různých událostí. Nejběžnější je OnActivity. Další informace o událostech, které sada SDK implementuje, naleznete u práce s aktivitami a specifikaci protokolu aktivit.

Jakmile se vaše metoda aktivuje, například OnMessageAsync pro ukončení tahu, můžete zvolit vlastní logiku pro odeslání zprávy zpět klientovi pomocí metod dostupných v třídě TurnContext, která by měla být parametrem ve vaší metodě, jak je znázorněno v následujícím příkladu.

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

Návod

Projděte si další metody TurnContext , které jsou k dispozici pro návrat do klienta.

Teď znáte základy, projděte si další kroky a pracujte na přidání vlastní logiky obslužné rutiny do vašeho agenta a odesílání různých událostí.

Další kroky

Pokud už používáte sadu Microsoft 365 Agents Toolkit, je dětské hřiště agentů k dispozici ve výchozím nastavení. Pokud chcete začít se sadou nástrojů, můžete použít jeden z následujících průvodců:

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-18

Sdílet prostřednictvím

Rychlý start: Vytvoření a testování základního agenta

Požadavky

Inicializace projektu a instalace sady SDK

Vytvoření serverové aplikace a import požadovaných knihoven

Vytvořte instanci agenta jako AgentApplication

Spuštění webového serveru pro naslouchání v localhost:3978

Místní spuštění agenta v anonymním režimu

Otestujte agenta lokálně

Další kroky

Požadavky

Inicializace projektu a instalace sady SDK

Import potřebných knihoven

Implementovat EchoAgent jako AgentApplication

Spuštění webového serveru pro naslouchání v localhost:3978

Místní spuštění agenta v anonymním režimu

Otestujte agenta lokálně

Další kroky

Požadavky

Otevřete řešení

Otestujte svého agenta lokálně

Jak agent funguje?

Vytvořte svého agenta

Přidání nové vlastní logiky do metody

Další kroky

Váš názor

Další materiály