Snabbstart: Skapa och testa en grundläggande agent

Den här snabbstarten vägleder dig genom att skapa en anpassad motoragent som svarar med det meddelande du skickar till den.

Förutsättningar

• Python 3.9 eller senare.

  • Om du vill installera Python går du till https://www.python.org/downloads/och följer anvisningarna för operativsystemet.
  • För att verifiera versionen skriver du i ett terminalfönster python --version.

• En valfri kodredigerare. Dessa instruktioner använder Visual Studio Code.

  Om du använder Visual Studio Code installerar du Python-tillägget

Initiera projektet och installera SDK

Skapa ett Python-projekt och installera nödvändiga beroenden.

1. Öppna en terminal och skapa en ny mapp

   mkdir echo
   cd echo
   

2. Öppna mappen med hjälp av Visual Studio Code med det här kommandot:

   code .
   

3. Skapa en virtuell miljö med valfri metod och aktivera den antingen via Visual Studio Code eller i en terminal.

   När du använder Visual Studio Code kan du använda de här stegen med Python-tillägget installerat.

   1. Tryck på F1, skriv Python: Create environmentoch tryck på Retur.

      1. Välj Venv för att skapa en .venv virtuell miljö på den aktuella arbetsytan.

      2. Välj en Python-installation för att skapa den virtuella miljön.

         Värdet kan se ut så här:

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

4. Installera Agents-SDK

   Använd pip för att installera paketet microsoft-agents-hosting-aiohttp med det här kommandot:

   pip install microsoft-agents-hosting-aiohttp
   

Skapa serverprogrammet och importera de bibliotek som krävs

1. Skapa en fil med namnet start_server.py, kopiera följande kod och klistra in den i:

   # 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
   

   Den här koden definierar en start_server funktion som vi ska använda i nästa fil.

2. Skapa en fil med namnet app.py med följande kod i samma katalog.

   # 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
   

Skapa en instans av agenten som en AgentApplication

I app.pylägger du till följande kod för att skapa AGENT_APP som en instans av AgentApplication, och implementera tre vägar för att svara på tre händelser:

• Konversationsuppdatering
• meddelandet /help
• annan aktivitet

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

Starta webbservern för att lyssna i localhost:3978

I slutet av app.pystartar du webbservern med .start_server

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

Kör agenten lokalt i anonymt läge

Kör det här kommandot från terminalen:

python app.py

Terminalen ska returnera följande:

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

Testa agenten lokalt

1. Från en annan terminal (för att hålla agenten igång) installerar du Microsoft 365 Agents Playground med det här kommandot:

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

   Anmärkning

   Det här kommandot använder npm eftersom Microsoft 365 Agents Playground inte är tillgängligt med pip.

   Terminalen bör returnera något i stil med:

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

2. Kör testverktyget för att interagera med din agent med det här kommandot:

   teamsapptester
   

   Terminalen bör returnera något i stil med:

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

Kommandot teamsapptester öppnar din standardwebbläsare och ansluter till din agent.

Nu kan du skicka valfritt meddelande för att se ekosvaret eller skicka meddelandet /help för att se hur meddelandet dirigeras till _help hanteraren.

Nästa steg

Etablera Azure Bot-resurser som ska användas med Agents SDK

Den här snabbstarten vägleder dig genom att skapa en anpassad motoragent som bara svarar med vad du än skickar till den.

Förutsättningar

• Node.js v22 eller senare

  • Om du vill installera Node.js går du till nodejs.org och följer anvisningarna för operativsystemet.
  • För att verifiera versionen skriver du i ett terminalfönster node --version.

• En valfri kodredigerare. Dessa instruktioner använder Visual Studio Code.

Initiera projektet och installera SDK

Använd npm för att initiera ett node.js projekt genom att skapa en package.json och installera nödvändiga beroenden

1. Öppna en terminal och skapa en ny mapp

   mkdir echo
   cd echo
   

2. Initiera projektet node.js

   npm init -y
   

3. Installera Agents-SDK

   npm install @microsoft/agents-hosting-express
   

4. Öppna mappen med hjälp av Visual Studio Code med hjälp av det här kommandot:

   code .
   

Importera nödvändiga bibliotek

Skapa filen index.mjs och importera följande NPM-paket till programkoden:

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

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

Implementera EchoAgent som en AgentApplication

I index.mjslägger du till följande kod för att skapa förlängningen EchoAgent av AgentApplication och implementera tre vägar för att svara på tre händelser:

• Konversationsuppdatering
• meddelandet /help
• annan aktivitet

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

Starta webbservern för att lyssna i localhost:3978

I slutet av index.mjs startar du webbservern med startServer, baserat på express, med MemoryStorage som tillståndslagring.

startServer(new EchoAgent(new MemoryStorage()))

Kör agenten lokalt i anonymt läge

Kör det här kommandot från terminalen:

node index.mjs

Terminalen bör returnera följande:

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

Testa agenten lokalt

1. Från en annan terminal (för att hålla agenten igång) installerar du Microsoft 365 Agents Playground med det här kommandot:

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

   Terminalen bör returnera något i stil med:

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

2. Kör testverktyget för att interagera med din agent med det här kommandot:

   node_modules/.bin/teamsapptester
   

   Terminalen bör returnera något i stil med:

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

Kommandot teamsapptester öppnar din standardwebbläsare och ansluter till din agent.

Nu kan du skicka valfritt meddelande för att se ekosvaret eller skicka meddelandet /help för att se hur meddelandet dirigeras till _help hanteraren.

Nästa steg

Etablera Azure Bot-resurser som ska användas med Agents SDK

Denna quickstart visar hur du laddar ner och kör QuickStart/Empty Agent-exemplet från GitHub.

Det finns två huvudsakliga sätt att komma igång med Microsoft 365 Agents SDK:

• Klona och kör exemplet med QuickStart/Empty Agent-agenten som är tillgängligt på GitHub

• Använd Microsoft 365 Agents Toolkit. Agents Toolkit har två inbyggda mallar för Visual Studio och Visual Studio Code som använder Microsoft 365 Agents SDK för att börja med en Snabbstart/Tom agent och en väderagent som använder Azure Foundry eller OpenAI-tjänster med antingen semantisk kernel eller LangChain.

Förutsättningar

Du behöver några saker innan du kommer igång. I de här stegen används exemplet QuickStart/Empty Agent i .NET-snabbstarten, men du kan också använda alla Agents SDK-exempel.

• .NET 8.0 SDK
• Visual Studio eller Visual Studio Code
• Kunskap om ASP.NET Core och asynkron programmering i C#
• quickstart Ladda ned exemplet från GitHub

Öppna lösningen

1. Öppna lösningsfilen QuickStart.csproj i Visual Studio.

2. Kör projektet.

Nu körs agenten lokalt via port 3978.

Testa din agent lokalt

1. Installera Agents Playground om du inte redan har gjort det.

   winget install agentsplayground
   

2. Starta agenten i Visual Studio eller Visual Studio Code

3. Starta apptestaren för Teams. I en kommandotolk: agentsplayground

   • Verktyget öppnar en webbläsare som visar Teams App Test Tool, redo att skicka meddelanden till din agent.

4. Din agent som körs på port 3978 bör ansluta automatiskt till agentens lekplats i webbläsaren och du bör kunna interagera med din agent som körs lokalt

Hur fungerar agenten?

Med Agents SDK skapas en agent med hjälp av klasserna AgentApplication och AgentApplicationOptions . Det här är inbyggt i Program.cs exemplets fil.

Skapa en agent

Du kan se i exemplet att när agenten byggs, läses AgentApplicationOptions in och din anpassade agentklass MyAgent.cs, som ärver från AgentApplication, laddas.

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

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

Sedan läses lagringen in som standard med klassen MemoryStorage. Detta möjliggör att kontext kan spåras över olika dialogväxlingar när TurnState används, men bör i produktionsmiljö ersättas med mer varaktig lagring såsom BlobsStorage eller CosmosDbPartitionedStorage.

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

Resten av agentapplikationen använder standardmönster för .NET-hosting och lägger till rutter för att acceptera meddelanden vid en specifik slutpunkt. Dessa vägar använder IAgent-gränssnittet för att acceptera agentaktiviteten och ger utvecklare AgentApplication objektet för att arbeta med den aktivitetsnyttolast som skickades till den från kanalen/klienten. Läs mer om aktiviteter och arbete med aktiviteter

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

Lägga till ny anpassad logik i en metod

Utvecklare lägger till anpassad logik i klassen MyAgent.cs som implementerar AgentApplication. Den här klassen använder AgentApplicationOptions för att konfigurera specifika inställningar från din konfiguration och Program.cs registrerar händelselyssnare från Agents SDK, som är tillgänglig i klassen AgentApplication som refererar till din respektive anpassade metod när dessa händelser utlöses från klienten.

I följande exempel utlöser WelcomeMessageAsync metoden och OnActivity utlöser metoden OnMessageAsync.

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

Dessa händelser dirigeras via slutpunkten som konfigurerats i din MyProgram.cs och det finns många händelser som du kan använda. Den vanligaste är OnActivity. Mer information om de händelser som SDK implementerar finns i mer information om hur du arbetar med aktiviteter och specifikationen för aktivitetsprotokoll.

När din metod har utlösts, till exempel OnMessageAsync för att avsluta svängen, kan du i din anpassade logik välja att svara för att skicka ett meddelande tillbaka till klienten med hjälp av de metoder som är tillgängliga på och instansen av Klassen TurnContext som ska vara en parameter i din metod enligt följande exempel:

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

Tips/Råd

Granska de andra TurnContext-metoderna som är tillgängliga för att återgå till klienten.

Nu vet du grunderna, kolla in nästa steg och arbeta för att lägga till anpassad hanteringslogik i din agent och skicka tillbaka olika händelser.

Nästa steg

• Läs mer om aktiviteter och arbete med aktiviteter
• Granska de AgentApplication-händelser som du kan svara på från klienten
• Granska De TurnContext-händelser som du kan skicka tillbaka till klienten
• Etablera Azure Bot-resurser som ska användas med Agents SDK
• Konfigurera .NET-agenten så att den använder OAuth

Agents Playground är tillgängligt som standard om du redan använder Microsoft 365 Agents Toolkit. Du kan använda någon av följande guider om du vill komma igång med verktygslådan:

• Skapa .NET-agenter i Visual Studio med hjälp av Microsoft 365 Agents Toolkit
• Skapa JavaScript-agenter i Visual Studio Code med Microsoft 365 Agents Toolkit