Microsoft Teams: chat empresarial

Piensa en conectar Hermes Agent a Microsoft Teams como darle a tu asistente de IA una credencial de empresa: una vez que está en el equipo, puede unirse a reuniones, responder preguntas en canales y echar una mano en los mensajes directos, todo sin salir de la aplicación que tus compañeros ya usan a diario.

Por qué Teams es diferente de Slack

Si has usado el Socket Mode de Slack antes, Teams funciona un poco distinto. En lugar de mantener una conexión abierta, Teams llama al webhook público de tu bot cada vez que alguien envía un mensaje. Eso significa que tu instancia de Hermes necesita una URL HTTPS pública — no localhost. Para probar, puedes usar un túnel; para producción, la apuntarás a tu dominio real del servidor.

Cómo se comporta el bot

Aquí tienes la regla simple:

Dónde le hablas	Qué pasa
Chat personal (mensaje directo)	El bot responde a todos los mensajes — no hace falta mencionarlo con @
Chat grupal	El bot solo responde cuando lo mencionas con @
Canal	El bot solo responde cuando lo mencionas con @

Teams envía las menciones como etiquetas <at>NombreDelBot</at>, pero Hermes las elimina automáticamente antes de procesarlas — así que no tienes que preocuparte por eso.

Paso 1: Instala la CLI de Teams

Primero, instala la herramienta de línea de comandos de Microsoft que automatiza el registro del bot — no necesitas el portal de Azure:

npm install -g @microsoft/teams.cli@preview
teams login

Para verificar tu inicio de sesión y encontrar tu ID de objeto de AAD (lo necesitarás más adelante para restringir el acceso), ejecuta:

teams status --verbose

Paso 2: Expón el puerto del webhook

Teams no puede entregar mensajes a localhost. Para desarrollo local, usa un túnel para obtener una URL HTTPS pública. El puerto por defecto es 3978 (cámbialo con TEAMS_PORT si es necesario).

Aquí tienes tres opciones sencillas:

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot

# ngrok
ngrok http 3978

# cloudflared
cloudflared tunnel --url http://localhost:3978

Copia la URL https:// de la salida — la necesitarás en el siguiente paso. Deja el túnel corriendo mientras desarrollas.

Paso 3: Crea el bot

Ahora registra tu bot con Teams:

teams app create \
  --name "Hermes" \
  --endpoint "https://<tu-url-del-tunel>/api/messages"

La CLI te dará tu CLIENT_ID, CLIENT_SECRET y TENANT_ID, además de un enlace de instalación. Guarda el secreto del cliente inmediatamente — no se mostrará de nuevo.

Paso 4: Configura las variables de entorno

Añade estas a tu archivo ~/.hermes/.env:

# Requeridas
TEAMS_CLIENT_ID=<tu-client-id>
TEAMS_CLIENT_SECRET=<tu-client-secret>
TEAMS_TENANT_ID=<tu-tenant-id>

# Restringe el acceso a usuarios específicos (recomendado)
# Usa los IDs de objeto de AAD de `teams status --verbose`
TEAMS_ALLOWED_USERS=<tu-id-de-objeto-aad>

Paso 5: Inicia la puerta de enlace

Si usas Docker, ejecuta desde el directorio que contiene docker-compose.yml (normalmente tu repositorio clonado de hermes-agent, no ~):

cd /ruta/a/hermes-agent
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up

Para instalaciones desde el código fuente, asegúrate de incluir primero el extra de Teams:

uv sync --extra teams
# o, para instalaciones editables:
uv pip install -e ".[teams]"

Para terminar

Conectar Hermes a Teams es un baile de cuatro pasos: instala la CLI, expón una URL pública, crea el bot y configura tus variables de entorno. Una vez que esté en marcha, tu asistente de IA se convierte en un miembro más del equipo — respondiendo automáticamente en los mensajes directos y uniéndose a los chats grupales cuando lo invocas.

Consejo práctico: Empieza con TEAMS_ALLOWED_USERS configurado solo con tu propio ID de objeto de AAD. Así podrás probar con seguridad sin preocuparte de que compañeros al azar activen tu bot — y luego amplía el acceso cuando estés seguro de que todo funciona.

---