Inicio rápido: Configuración y ejecución del agente de ejemplo de Python Agent

En este Quickstart, se le guiará a través de la configuración de un agente de Python utilizando el marco de trabajo Agent 365 para herramientas, notificaciones, observabilidad, y para probar el agente mediante Agents Playground y Teams.

Prerrequisitos

  • Si tiene previsto usar Visual Studio Code, debe tener .NET instalado. (se recomienda .NET 8.0).

  • Python 3.11+ instalado

  • Administrador de paquetes UV instalado. Instale esto en un terminal mediante pip install uv.

  • Dependencias de Microsoft Agents Toolkit/Agent Framework

    El ejemplo usado en el tutorial se basa en las bibliotecas de Agent Framework proporcionadas a través del kit de herramientas de agentes de Microsoft 365 o ATK. Los instalará automáticamente cuando use la extensión Agents Toolkit en VS Code para estructurar el ejemplo proporcionado, o puede instalar el paquete manualmente con este comando:

    uv pip install -e . --prerelease=allow

  • Acceso a GitHub

  • Un proyecto de agente de IA ya existente. En este inicio rápido, se utiliza un agente de ejemplo del Kit de herramientas del Agente 365 de Microsoft 365, también conocido como ATK en VS Code.

  • A365 CLI

  • Autenticación de identidad del agente

Configuración del marco de trabajo del agente + Python ejemplo del kit de herramientas de agentes de Microsoft 365

Para prepararlo todo, instalas el kit de herramientas de agentes de Microsoft 365 en VS Code, abres la galería de ejemplos y creas la estructura inicial del marco de trabajo del agente + ejemplo de Python localmente para que puedas configurarlo y ejecutarlo más adelante. Las capturas de pantalla siguientes muestran lo que debería esperar ver a medida que avanza.

  1. Abra Visual Studio Code, a continuación, abra el panel ExtensionsCtrl+Shift+X.

  2. En la barra de búsqueda, escriba "Agents Toolkit".
    Debería ver el resultado que se muestra en la captura de pantalla aquí:

    Captura de pantalla de la búsqueda en el mercado de Extensiones para Agents Toolkit.

  3. Seleccione Microsoft 365 Agents Toolkit.

  4. Seleccione Instalar.

    VS Code muestra la vista de detalles de la extensión similar a la siguiente:

    Captura de pantalla de la página Detalles de la extensión con los botones Instalar y Habilitar.

  5. Una vez instalado, el icono M365 Agents Toolkit aparece en la barra de navegación izquierda.

  6. Selecciónelo para abrir la experiencia de bienvenida.

    Ahora debería ver opciones como Compilar un agente declarativo, Crear un nuevo agente o aplicación y Ver ejemplos, como se muestra aquí:

    Captura de pantalla de la vista de bienvenida del kit de herramientas con crear un agente declarativo, crear un nuevo agente o aplicación y ver las opciones Ejemplos.

  7. Seleccione Ver ejemplos.

  8. En la lista de ejemplos, desplácese para buscar el ejemplo de agente Agent framework + Python.

  9. Selecciónela.

    Verá dos opciones: Crear (scaffold localmente) o Ver en GitHub.

  10. Seleccione Create.

    Captura de pantalla de Agent Framework Agent con Agent 365 SDK usando el ejemplo de Python.

  11. Cuando se le solicite, seleccione una carpeta en la máquina donde se debe generar el ejemplo. Por ejemplo: C:\A365-python-sample

    El conjunto de herramientas estructura el marco del agente y el ejemplo de Python en una subcarpeta (como sample_agent) y luego lo abre automáticamente en VS Code.

    Una vez completada la estructura, ahora tiene un marco de agente totalmente funcional y un proyecto de agente de Python en su máquina.

  12. Instalar los paquetes de Agent 365 necesarios

    Antes de ejecutar el ejemplo, abra el pyproject.toml en su proyecto y confirme que se muestran todas las dependencias necesarias de Agent 365 y de Agent Framework. El ejemplo generado por Microsoft 365 Agents Toolkit ya incluye estas entradas.

    Una vez que hayas revisado el pyproject.toml, instala todo ejecutando este comando:

    uv pip install -e . --prerelease=allow

    Esto extrae todas las bibliotecas de Agent 365 SDK, las dependencias del marco de agente, los componentes de hospedaje y cualquier otra dependencia definida en el ejemplo.

  13. Después de la instalación, compruebe que el proyecto se compila y se ejecuta iniciando el servidor de desarrollo mediante este comando:

    uv run python start_with_generic_host.py

Agregar herramientas de Microsoft 365 (servidores MCP)

Puede explorar y administrar servidores MCP mediante los comandos de desarrollo de a365 en la CLI.

Al trabajar con servidores MCP, puede hacer lo siguiente:

  • Detectar qué servidores MCP están disponibles para su uso
  • Agregar uno o varios servidores MCP a la configuración del agente
  • Revisión de los servidores MCP configurados actualmente
  • Eliminación de servidores MCP que ya no necesita

Una vez agregados los servidores MCP, el manifiesto de herramientas del agente se expande para incluir entradas similares a:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Aprenda a agregar y administrar herramientas

Suscripción y control de notificaciones

El agente de ejemplo se suscribe a todas las notificaciones del SDK de Agent 365 mediante onAgentNotification("*") y las enruta a un único controlador. Este controlador permite al agente reaccionar a los eventos de fondo o del sistema, no solo a los mensajes directos del usuario.

Obtenga información sobre cómo notificar a los agentes

El código siguiente muestra cómo se configura la notificación en el archivo agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observability

Este fragmento de código muestra los cambios mínimos necesarios para habilitar la observabilidad en el ejemplo. Inicializa el SDK de Observabilidad de Agent 365 y envuelve cada invocación de agente en un InferenceScope de modo que las entradas, salidas y metadatos puedan capturarse automáticamente.

En el código siguiente se muestra un ejemplo de observabilidad simplificada en el agent.py archivo.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Este código es la configuración de observabilidad completa necesaria para el ejemplo de marco de Python + Agente. Obtenga más información sobre la observabilidad

Probar el agente

Establezca las variables de entorno necesarias, seleccione un modo de autenticación e inicie el agente localmente. Puede probar todo de un extremo a otro con Agents Playground sin necesidad de un inquilino de Microsoft 365 a menos que quiera publicar el agente y usarlo en aplicaciones como Teams o Outlook.

Introducción a los pasos de prueba

  • Agregue las claves de API y la configuración del modelo a un archivo .env para que el ejemplo pueda comunicarse con un LLM.
  • Elija su modo de autenticación. Para el desarrollo local, el ejemplo admite la autenticación de agente mediante valores creados a partir del plano técnico del agente.
  • Inicie el agente localmente, lo que lo pone a disposición de herramientas como Agents Playground.
  • Use Agents Playground para probar mensajes, herramientas y notificaciones sin configurar un inquilino ni implementar nada.
  • Cuando esté listo para el comportamiento en el mundo real, publique una instancia de Microsoft 365 y pruebe el agente dentro de Teams, Outlook u otras plataformas de Microsoft 365.

Más información sobre pruebas

Publica tu agente

Cuando el agente esté listo para experiencias reales de Microsoft 365, como chats de Teams, mensajes de Outlook y documentos de Word @mentions, publíquelo en un entorno de cliente de Microsoft 365. El comando CLI publish Agent 365 se encarga del empaquetado: actualiza tu manifiesto, agrupa todo y sube el agente al centro de administración de Microsoft.

Durante la publicación, revise y personalice el nombre, la descripción, los iconos y la versión del agente antes de completar la carga. Una vez publicado, el agente se puede registrar e instalar dentro del inquilino.

Importante

Después de publicar tu agente, debes configurar el blueprint del agente en el Portal de Desarrolladores antes de crear instancias. Aprende cómo configurar el plan del agente en el Portal de Desarrolladores

Puede ver los agentes publicados aquí: https://admin.cloud.microsoft/#/agents/all

Más información sobre el flujo de trabajo completo y las instrucciones paso a paso

  • Last updated on