Avvio rapido: creare e testare un agente di base

Questa guida introduttiva illustra la creazione di un agente del motore personalizzato che risponde con qualsiasi messaggio inviato.

Prerequisiti

Python 3.9 o versione successiva.
- Per installare Python, passare a https://www.python.org/downloads/e seguire le istruzioni per il sistema operativo.
- Per verificare la versione, in una finestra del terminale digitare python --version.
Editor di codice di propria scelta. Queste istruzioni usano Visual Studio Code.

Se si usa Visual Studio Code, installare l'estensione Python

Inizializzare il progetto e installare l'SDK

Creare un progetto Python e installare le dipendenze necessarie.

Aprire un terminale e creare una nuova cartella
```
mkdir echo
cd echo
```
Aprire la cartella usando Visual Studio Code usando questo comando:
```
code .
```
Creare un ambiente virtuale con il metodo scelto e attivarlo tramite Visual Studio Code o in un terminale.

Quando si usa Visual Studio Code, è possibile usare questi passaggi con l'estensione Python installata.
1. Premere F1, digitare Python: Create environmente premere INVIO.
  1. Selezionare Venv per creare un .venv ambiente virtuale nell'area di lavoro corrente.
  2. Selezionare un'installazione python per creare l'ambiente virtuale.
    
    Il valore potrebbe essere simile al seguente:
    
    Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
Installa l'SDK degli Agenti

Usare pip per installare il pacchetto microsoft-agents-hosting-aiohttp con questo comando:
```
pip install microsoft-agents-hosting-aiohttp
```

Creare l'applicazione server e importare le librerie necessarie

Creare un file denominato start_server.py, copiare il codice seguente e incollarlo in:

# 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

Questo codice definisce una start_server funzione che verrà usata nel file successivo.

Nella stessa directory creare un file denominato app.py con il codice seguente.

# 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

Creare un'istanza dell'agente come AgentApplication

In app.pyaggiungere il codice seguente per creare come AGENT_APP istanza di AgentApplicatione implementare tre route per rispondere a tre eventi:

Aggiornamento conversazione
messaggio /help
qualsiasi altra attività

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

Avviare il server Web per l'ascolto in localhost:3978

Alla fine di app.pyavviare il server Web usando start_server.

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

Eseguire l'agente in locale in modalità anonima

Dal terminale eseguire questo comando:

python app.py

Il terminale deve restituire quanto segue:

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

Testare l'agente localmente

Da un altro terminale (per mantenere l'agente in esecuzione) installare Microsoft 365 Agents Playground con questo comando:
```
npm install -g @microsoft/teams-app-test-tool
```
Annotazioni

Questo comando usa npm perché Microsoft 365 Agents Playground non è disponibile tramite pip.

Il terminale dovrebbe restituire un risultato simile al seguente:
```
added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities
```

Eseguire lo strumento di test per interagire con l'agente usando questo comando:

teamsapptester

Il terminale dovrebbe restituire un risultato simile al seguente:

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

Il teamsapptester comando apre il browser predefinito e si connette all'agente.

Il tuo agente nell'ambiente degli agenti

È ora possibile inviare qualsiasi messaggio per visualizzare la risposta echo o inviare il messaggio /help per vedere come viene instradato il messaggio al _help gestore.

Passaggi successivi

Effettuare il provisioning delle risorse di Azure Bot da usare con Agents SDK

Questa guida introduttiva illustra la creazione di un agente motore personalizzato che risponde esattamente con ciò che gli invii.

Prerequisiti

Node.js v22 o versione successiva
- Per installare Node.js passare a nodejs.org e seguire le istruzioni per il sistema operativo.
- Per verificare la versione, in una finestra del terminale digitare node --version.
Editor di codice di propria scelta. Queste istruzioni usano Visual Studio Code.

Inizializzare il progetto e installare l'SDK

Usare npm per inizializzare un progetto node.js creando un package.json e installando le dipendenze necessarie

Aprire un terminale e creare una nuova cartella
```
mkdir echo
cd echo
```
Inizializzare il progetto di node.js
```
npm init -y
```

Installa l'SDK degli Agenti

npm install @microsoft/agents-hosting-express

Aprire la cartella usando Visual Studio Code usando il comando seguente:
```
code .
```

Importare le librerie necessarie

Creare il file index.mjs e importare i pacchetti NPM seguenti nel codice dell'applicazione:

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

Implementare EchoAgent come AgentApplication

In index.mjsaggiungere il codice seguente per creare l'estensione EchoAgentdi AgentApplication e implementare tre route per rispondere a tre eventi:

Aggiornamento conversazione
messaggio /help
qualsiasi altra attività

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

Avviare il server Web per l'ascolto in localhost:3978

Alla fine di index.mjs, avvia il server web utilizzando startServer basato su Express, usando MemoryStorage come sistema di archiviazione dello stato del turno.

startServer(new EchoAgent(new MemoryStorage()))

Eseguire l'agente in locale in modalità anonima

Dal terminale eseguire questo comando:

node index.mjs

Il terminale deve restituire quanto segue:

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

Testare l'agente localmente

Da un altro terminale (per mantenere l'agente in esecuzione) installare Microsoft 365 Agents Playground con questo comando:
```
npm install -D @microsoft/teams-app-test-tool
```
Il terminale dovrebbe restituire un risultato simile al seguente:
```
added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities
```

Eseguire lo strumento di test per interagire con l'agente usando questo comando:

node_modules/.bin/teamsapptester

Il terminale dovrebbe restituire un risultato simile al seguente:

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

Il teamsapptester comando apre il browser predefinito e si connette all'agente.

Il tuo agente nell'ambiente degli agenti

È ora possibile inviare qualsiasi messaggio per visualizzare la risposta echo o inviare il messaggio /help per vedere come viene instradato il messaggio al _help gestore.

Passaggi successivi

Effettuare il provisioning delle risorse di Azure Bot da usare con Agents SDK

Questo quickstart ti mostra come scaricare ed eseguire l'esempio QuickStart/Empty Agent da GitHub.

Esistono due modi principali per iniziare a usare Microsoft 365 Agents SDK:

Clonare ed eseguire l'esempio di agente di avvio rapido/vuoto disponibile in GitHub
Usa il toolkit degli agenti di Microsoft 365. Agents Toolkit include due modelli predefiniti per Visual Studio e Visual Studio Code che usano Microsoft 365 Agents SDK per iniziare con un agente di avvio rapido/vuoto e un agente meteo che usa Azure Foundry o OpenAI Services con kernel semantico o LangChain.

Prerequisiti

Prima di iniziare, sono necessari alcuni aspetti. Questi passaggi usano l'esempio di Avvio rapido/Agente vuoto nella guida introduttiva a .NET, ma è anche possibile usare qualsiasi esempio di Agents SDK.

.NET 8.0 SDK
Visual Studio o Visual Studio Code
Conoscenza di programmazione ASP.NET Core e asincrona in C#
Scaricare l'esempio quickstart da GitHub

Aprire la soluzione

Aprire il file QuickStart.csproj della soluzione in Visual Studio.
Esegui il progetto.

A questo punto, l'agente viene eseguito localmente usando la porta 3.978.

Testare l'agente in locale

Installare Agents Playground se non è già stato fatto.
```
winget install agentsplayground
```
Avvia l'agente in Visual Studio o Visual Studio Code
Avviare il tester delle app di Teams. Al prompt dei comandi: agentsplayground
- Lo strumento apre un Web browser che mostra lo strumento di test delle app di Teams, pronto per l'invio di messaggi all'agente.
L'agente in esecuzione sulla porta 3978 dovrebbe connettersi automaticamente all'agent playground nel browser e potrai interagire con il tuo agente in esecuzione locale.

Come funziona l'agente?

Con Agents SDK, un agente viene compilato usando le classi AgentApplication e AgentApplicationOptions . Viene compilato nel Program.cs file dell'esempio.

Genera il tuo agente

Nell'esempio è possibile osservare che, man mano che l'agente è in fase di compilazione AgentApplicationOptions , viene caricata e la classe MyAgent.cs dell'agente personalizzato che eredita da AgentApplication

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

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

La risorsa di archiviazione viene quindi caricata per impostazione predefinita usando la classe MemoryStorage. Ciò consente di tenere traccia del contesto tra turni quando si usa TurnState , ma deve essere disattivato nell'ambiente di produzione per un'archiviazione più persistente, ad esempio BlobsStorage o CosmosDbPartitionedStorage.

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

Il resto dell'applicazione agente usa modelli di hosting .NET standard e aggiunge route per accettare messaggi in un endpoint specifico. Queste route usano l'interfaccia IAgent per accettare l'attività dell'agente e forniscono agli sviluppatori l'oggetto AgentApplication per lavorare con il payload attività passato dal canale o dal client. Altre informazioni sulle attività e sull'uso delle attività

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

Aggiungere una nuova logica personalizzata in un metodo

Gli sviluppatori aggiungono logica personalizzata nella MyAgent.cs classe che implementa AgentApplication. Questa classe utilizza il AgentApplicationOptions per configurare le impostazioni specifiche dalla tua configurazione e Program.cs registra i listener di eventi dall'Agents SDK, disponibile nella classe AgentApplication che fa riferimento al rispettivo metodo personalizzato quando quegli eventi vengono attivati dal client.

Nell'esempio seguente OnConversationUpdate attiva il WelcomeMessageAsync metodo e OnActivity attiva il metodo OnMessageAsync.

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

Quegli eventi vengono indirizzati tramite l'endpoint configurato nel tuo MyProgram.cs e sono disponibili numerosi eventi utilizzabili. Il più comune è OnActivity. Per altre informazioni sugli eventi implementati dall'SDK, vedere altre informazioni sull'uso delle attività e sulla specifica del protocollo activity.

Dopo l'attivazione del metodo, ad esempio OnMessageAsync per terminare il turno, è possibile scegliere nella logica personalizzata di rispondere per inviare un messaggio al client usando i metodi disponibili in e l'istanza della classe TurnContext che deve essere un parametro nel metodo, come illustrato nell'esempio seguente:

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

Suggerimento

Esaminare gli altri metodi TurnContext disponibili per tornare al client.

Ora che conosci le nozioni di base, dai un'occhiata ai passaggi successivi e lavora all'aggiunta di logiche personalizzate per i gestori nel tuo agente e a inviare eventi differenti.

Passaggi successivi

Agents Playground è disponibile per impostazione predefinita se si usa già Microsoft 365 Agents Toolkit. Se si vuole iniziare a usare il toolkit, è possibile usare una delle guide seguenti:

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-18

Condividi tramite

Avvio rapido: creare e testare un agente di base

Prerequisiti

Inizializzare il progetto e installare l'SDK

Creare l'applicazione server e importare le librerie necessarie

Creare un'istanza dell'agente come AgentApplication

Avviare il server Web per l'ascolto in localhost:3978

Eseguire l'agente in locale in modalità anonima

Testare l'agente localmente

Passaggi successivi

Prerequisiti

Inizializzare il progetto e installare l'SDK

Importare le librerie necessarie

Implementare EchoAgent come AgentApplication

Avviare il server Web per l'ascolto in localhost:3978

Eseguire l'agente in locale in modalità anonima

Testare l'agente localmente

Passaggi successivi

Prerequisiti

Aprire la soluzione

Testare l'agente in locale

Come funziona l'agente?

Genera il tuo agente

Aggiungere una nuova logica personalizzata in un metodo

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive