Compartir a través de

Inicio rápido: Crear y probar un agente básico

Este inicio rápido le guía a través de la creación de un agente de motor personalizado que responde con el mensaje que envíe.

Prerrequisitos

  • Python 3.9 o posterior.

    • Para instalar Python, vaya a https://www.python.org/downloads/y siga las instrucciones del sistema operativo.
    • Para comprobar la versión, en una ventana de terminal, escriba python --version.

  • Un editor de código de su elección. Estas instrucciones usan Visual Studio Code.

    Si usa Visual Studio Code, instale la extensión de Python.

Inicialización del proyecto e instalación del SDK

Cree un proyecto de Python e instale las dependencias necesarias.

  1. Abra un terminal y cree una carpeta

    mkdir echo
cd echo

  2. Abra la carpeta mediante Visual Studio Code con este comando:

    code .

  3. Cree un entorno virtual con el método que prefiera y actívelo a través de Visual Studio Code o en un terminal.

    Al usar Visual Studio Code, puede usar estos pasos con la extensión de Python instalada.

    1. Presione F1, escriba Python: Create environmenty presione Entrar.

      1. Seleccione Venv para crear un .venv entorno virtual en el área de trabajo actual.

      2. Seleccione una instalación de Python para crear el entorno virtual.

        El valor podría tener este aspecto:

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

  4. Instala el SDK de agentes

    Use pip para instalar el paquete microsoft-agents-hosting-aiohttp con este comando:

    pip install microsoft-agents-hosting-aiohttp

Creación de la aplicación de servidor e importación de las bibliotecas necesarias

  1. Cree un archivo denominado start_server.py, copie el código siguiente y péguelo en:

    # 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

    Este código define una start_server función que usaremos en el siguiente archivo.

  2. En el mismo directorio, cree un archivo denominado app.py con el código siguiente.

    # 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

Creación de una instancia del agente como AgentApplication

En app.py, agregue el código siguiente para crear como AGENT_APP una instancia de AgentApplicatione implemente tres rutas para responder a tres eventos:

  • Actualización de conversación
  • el mensaje /help
  • cualquier otra actividad
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}")

Iniciar el servidor web para escuchar en localhost:3978

Al final de app.py, inicie el servidor web mediante start_server.

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

Ejecutar el agente localmente en modo anónimo

Desde el terminal, ejecute este comando:

python app.py

El terminal debe devolver lo siguiente:

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

Probar el agente localmente

  1. Desde otro terminal (para mantener el agente en ejecución) instale el área de juegos de agentes de Microsoft 365 con este comando:

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

    Nota:

    Este comando usa npm porque el área de juegos de agentes de Microsoft 365 no está disponible mediante pip.

    El terminal debe devolver algo parecido a:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Ejecute la herramienta de prueba para interactuar con el agente mediante este comando:

    teamsapptester

    El terminal debe devolver algo parecido a:

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

El teamsapptester comando abre el explorador predeterminado y se conecta al agente.

Tu agente en el área de juego para agentes

Ahora puede enviar cualquier mensaje para ver la respuesta de eco, o enviar el mensaje /help para ver cómo ese mensaje se enruta al controlador _help.

Este inicio rápido le guía a través de la creación de un agente de motor personalizado que responde con el mensaje que envíe.

Prerrequisitos

  • Node.js v22 o posterior

    • Para instalar Node.js vaya a nodejs.org y siga las instrucciones del sistema operativo.
    • Para comprobar la versión, en una ventana de terminal, escriba node --version.

  • Un editor de código de su elección. Estas instrucciones usan Visual Studio Code.

Inicialización del proyecto e instalación del SDK

Use npm para inicializar un proyecto de node.js creando un package.json e instalando las dependencias necesarias.

  1. Abra un terminal y cree una carpeta

    mkdir echo
cd echo

  2. Inicialización del proyecto de node.js

    npm init -y

  3. Instala el SDK de agentes

    npm install @microsoft/agents-hosting-express

  4. Abra la carpeta mediante Visual Studio Code mediante el comando siguiente:

    code .

Importación de las bibliotecas necesarias

Cree el archivo index.mjs e importe los siguientes paquetes de NPM en el código de la aplicación:

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

Implementar EchoAgent como AgentApplication

En index.mjs, agregue el código siguiente para crear la EchoAgent extensión de AgentApplication e implemente tres rutas para responder a tres eventos:

  • Actualización de conversación
  • el mensaje /help
  • cualquier otra actividad
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)
  }
}

Iniciar el servidor web para escuchar en localhost:3978

Al final de index.mjs, inicia el servidor web usando startServer basado en express, utilizando MemoryStorage como almacenamiento de estado de turno.

startServer(new EchoAgent(new MemoryStorage()))

Ejecuta el agente localmente en modo anónimo

Desde el terminal, ejecute este comando:

node index.mjs

El terminal debe devolver esto:

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

Probar el agente localmente

  1. Desde otro terminal (para mantener el agente en ejecución) instale el área de juegos de agentes de Microsoft 365 con este comando:

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

    El terminal debe devolver algo parecido a:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Ejecute la herramienta de prueba para interactuar con el agente mediante este comando:

    node_modules/.bin/teamsapptester

    El terminal debe devolver algo parecido a:

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

El teamsapptester comando abre el explorador predeterminado y se conecta al agente.

Tu agente en el área de juego para agentes

Ahora puede enviar cualquier mensaje para ver la respuesta de eco, o enviar el mensaje /help para ver cómo ese mensaje se enruta al controlador _help.

Este inicio rápido le guía a través de la creación de un agente de motor personalizado que responde con el mensaje que envíe.

Prerrequisitos

  • SDK de .NET 8.0 o posterior

    • Para instalar el SDK de .NET, vaya a dotnet.microsoft.com y siga las instrucciones del sistema operativo.
    • Para comprobar la versión, en una ventana de terminal, escriba dotnet --version.

  • Un editor de código de su elección. Estas instrucciones usan Visual Studio Code.

Inicialización del proyecto e instalación del SDK

Use dotnet para crear un nuevo proyecto web e instalar las dependencias necesarias.

  1. Abra un terminal y cree una carpeta

    mkdir echo
cd echo

  2. Inicialización del proyecto de .NET

    dotnet new web

  3. Instala el SDK de agentes

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

  4. Abra la carpeta mediante Visual Studio Code con este comando:

    code .

Importación de las bibliotecas necesarias

En Program.cs, reemplace el contenido existente y agregue las siguientes using instrucciones para importar los paquetes del SDK en el código de la aplicación:

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

Implementar EchoAgent como AgentApplication

En Program.cs, después de las using instrucciones , agregue el código siguiente para crear la EchoAgent extensión AgentApplication e implemente rutas para responder a eventos:

  • Actualización de conversación
  • Cualquier otra actividad
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);
   }
}

Configuración del servidor web y registro de la aplicación del agente

Dentro de Program.cs, después de las using instrucciones, agregue el código siguiente para configurar el servidor web, registrar el agente y mapear el /api/messages punto de conexión:

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();

Establecer el servidor web para que escuche en localhost:3978

En launchSettings.json, actualice el applicationURL a http://localhost:3978 para que la aplicación escuche en el puerto correcto.

Ejecuta el agente localmente en modo anónimo

Desde el terminal, ejecute este comando:

dotnet run

El terminal debe devolver algo parecido a:

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

Probar el agente localmente

  1. Desde otro terminal (para mantener el agente en ejecución) instale el área de juegos de agentes de Microsoft 365 con el siguiente comando:

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

    Nota:

    Este comando usa npm porque el área de juegos de agentes de Microsoft 365 se distribuye como un paquete npm.

    El terminal debe devolver algo parecido a:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Ejecute la herramienta de prueba para interactuar con el agente mediante este comando:

    teamsapptester

    El terminal debe devolver algo parecido a:

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

El teamsapptester comando abre el explorador predeterminado y se conecta al agente.

Tu agente en el área de juego para agentes

En el campo de texto, escriba y envíe cualquier mensaje para ver el eco de respuesta.

Pasos siguientes

El área de juegos de agentes está disponible de forma predeterminada si ya usa el Kit de herramientas de agentes de Microsoft 365. Puede usar una de las siguientes guías si desea empezar a trabajar con el kit de herramientas:

  • Last updated on