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

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

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.

Pasos siguientes

Aprovisionamiento de recursos de Azure Bot para usarlos con el SDK de agentes

Esta guía rápida le guía para crear un agente de motor personalizado que solo responde con todo lo que le 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:

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

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

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.

Pasos siguientes

Aprovisionamiento de recursos de Azure Bot para usarlos con el SDK de agentes

Este inicio rápido te muestra cómo descargar y ejecutar el ejemplo de QuickStart/Empty Agent desde GitHub.

Hay dos formas principales de empezar a trabajar con el SDK de agentes de Microsoft 365:

• Clona y ejecuta el agente de muestra QuickStart/Empty Agent disponible en GitHub

• Use el Kit de herramientas de Agentes de Microsoft 365. El Kit de herramientas de agentes tiene dos plantillas integradas para Visual Studio y Visual Studio Code que utilizan el SDK de agentes de Microsoft 365 para comenzar con un Agente de inicio rápido o un Agente vacío y un Agente meteorológico que utiliza Azure Functions o los servicios de OpenAI con Semantic Kernel o LangChain.

Prerrequisitos

Necesita algunas cosas antes de empezar. En estos pasos se usa el ejemplo QuickStart/Empty Agent en el inicio rápido de .NET, pero también puede usar cualquier ejemplo de SDK de agentes.

• SDK de .NET 8.0
• Visual Studio o Visual Studio Code
• Conocimientos de ASP.Net Core y programación asincrónica en C#
• Descarga del quickstart ejemplo de GitHub

Abra la solución

1. Abra el archivo QuickStart.csproj de solución en Visual Studio.

2. Ejecute el proyecto.

En este momento, el agente se ejecuta localmente mediante el puerto 3978.

Prueba tu agente localmente

1. Instale el Agents Playground si aún no lo ha hecho.

   winget install agentsplayground
   

2. Inicio del agente en Visual Studio o Visual Studio Code

3. Inicie el evaluador de aplicaciones de Teams. En un símbolo del sistema: agentsplayground

   • La herramienta abre un explorador web que muestra la herramienta de prueba de aplicaciones de Teams, lista para enviar mensajes al agente.

4. El agente en ejecución en el puerto 3978 debe conectarse automáticamente al área de juegos del agente en el explorador y debería poder interactuar con el agente que se ejecuta localmente.

¿Cómo funciona el agente?

Con el SDK de agentes, un agente se compila mediante las clases AgentApplication y AgentApplicationOptions . Esto se construye en el archivo Program.cs del ejemplo.

Compilar el agente

Puede ver en el ejemplo que, a medida que se construye AgentApplicationOptions, el agente se carga y la clase personalizada de agente MyAgent.cs que hereda de AgentApplication

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

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

A continuación, el almacenamiento se carga de forma predeterminada mediante la clase MemoryStorage. Esto permite realizar un seguimiento del contexto entre turnos cuando se usa TurnState , pero se debe desactivar en producción para un almacenamiento más persistente, como BlobsStorage o CosmosDbPartitionedStorage.

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

El resto de la aplicación del agente usa patrones de hospedaje estándar de .NET y agrega rutas para aceptar mensajes en un punto de conexión específico. Estas rutas usan la interfaz IAgent para aceptar la actividad del agente y proporcionan a los desarrolladores el AgentApplication objeto para trabajar con la carga de actividad que se le ha pasado desde el canal o cliente. Más información sobre las actividades y cómo trabajar con ellas

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

Adición de una nueva lógica personalizada en un método

Los desarrolladores agregan lógica personalizada en la MyAgent.cs clase que implementa AgentApplication. Esta clase utiliza AgentApplicationOptions para configurar cualquier ajuste específico de su configuración y Program.cs registra oyentes de eventos desde el SDK de Agentes, disponible en la clase AgentApplication, que hace referencia al método personalizado correspondiente cuando se desencadenan esos eventos desde el cliente.

En el ejemplo siguiente, OnConversationUpdate desencadena el WelcomeMessageAsync método y OnActivity desencadena el método OnMessageAsync.

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

Esos eventos se enrutan a través del punto de conexión configurado en MyProgram.cs y hay numerosos eventos que puede usar. La más común es OnActivity. Para obtener más información sobre los eventos que implementa el SDK, consulte más información sobre cómo trabajar con actividades y la especificación del protocolo de actividad.

Una vez que se desencadene el método, por ejemplo OnMessageAsync para finalizar el turno, puede optar en su lógica personalizada por enviar un mensaje de vuelta al cliente utilizando los métodos disponibles en una instancia de la clase TurnContext, que debería ser un parámetro en su método tal como se muestra en el ejemplo siguiente.

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

Sugerencia

Revise los otros métodos TurnContext disponibles para volver al cliente.

Ahora que conoce los conceptos básicos, consulte los pasos siguientes y trabaje para agregar lógica de controlador personalizada al agente y enviar eventos diferentes.

Pasos siguientes

• Más información sobre las actividades y cómo trabajar con ellas
• Revise los eventos AgentApplication a los que puede responder desde el cliente.
• Revise los eventos TurnContext que puede devolver al cliente.
• Aprovisionamiento de recursos de Azure Bot para usarlos con el SDK de agentes
• Configuración del agente de .NET para usar OAuth

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:

• Creación de agentes de .NET en Visual Studio mediante el Kit de herramientas de agentes de Microsoft 365
• Creación de agentes de JavaScript en Visual Studio Code con el Kit de herramientas de agentes de Microsoft 365