Compartir a través de

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

En este inicio rápido, le guía a través de la configuración de un agente de Python Agent Framework en funcionamiento mediante herramientas, notificaciones, observabilidad y prueba de Agent 365 mediante el área de juegos de Agents y Teams.

Requisitos previos

  • Si tiene previsto usar Visual Studio Code, debe tener instalado .NET. (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 aplicar scaffolding al ejemplo, o bien puede instalar el paquete manualmente mediante este comando:

    uv pip install -e . --find-links ../dist --pre

  • Acceso a GitHub

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

  • A365 CLI

  • Autenticación de identidad del agente

Configurar el marco de trabajo del agente y el ejemplo de Python desde el Kit de herramientas de agentes de Microsoft 365

Para prepararlo todo, instale el Kit de herramientas de Microsoft 365 Agents en VS Code, abra la galería de ejemplos y aplique scaffolding a Agent Framework + Python ejemplo localmente para que pueda 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, después abra Extensiones, un panel Ctrl+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 de Marketplace 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ónelo.

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

  10. Seleccione Crear.

    Captura de pantalla de Agent Framework Agent con el SDK de A365 con 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 kit de herramientas aplica scaffolding al ejemplo Agent Framework + Python en una subcarpeta (como sample_agent) y después lo abre automáticamente en VS Code.

    Una vez completado el scaffolding, ahora tiene un proyecto de agente Agent Framework + Python totalmente funcional en la máquina

  12. Instalar los paquetes de Agent 365 necesarios

    Antes de ejecutar el ejemplo, abra el package.json 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 haya revisado el package.json, instale todo mediante la ejecución de este comando:

    uv pip install -e

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

Observabilidad

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 encapsula cada invocación de agente en un para InferenceScope que las entradas, salidas y metadatos se puedan capturar 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 + Agent. Obtenga más información sobre la observabilidad

Pruebe 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 u 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 agentica mediante valores creados a partir del plano técnico del agente.
  • Inicie el agente localmente, que lo expone a herramientas como el área de juegos de agentes.
  • Use Agents Playground para probar mensajes, herramientas y notificaciones sin configurar un inquilino ni implementar nada.
  • Cuando esté listo para el comportamiento real, publique un inquilino de Microsoft 365 y pruebe el agente dentro de Teams, Outlook u otras superficies de Microsoft 365.

Más información sobre pruebas

Publicar su agente

Cuando el agente está listo para experiencias reales de Microsoft 365, como chats de Teams, mensajes de Outlook, Word @mentions, se publica en un inquilino de Microsoft 365. El comando Agent 365 CLI publish es un comando que controla el empaquetado: actualiza el manifiesto, agrupa todo y carga el agente en el 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 detectar 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. Consulta Configurar el plano 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