Tema & Suscripción (Topic & Subscription)
Existen dos formas en que el entorno de ejecución (runtime) entrega mensajes:
Mensajería directa (direct messaging): de uno a uno, el remitente debe especificar el ID del agente receptor.
Difusión (broadcast): de uno a muchos, el remitente no especifica los ID de los agentes receptores.
Muchos escenarios son adecuados para la difusión, especialmente en flujos de trabajo orientados a eventos, donde los agentes no siempre saben quién manejará sus mensajes.
Esta sección se enfoca en los conceptos clave de la difusión: tema (topic) y suscripción (subscription).
Tema (Topic)
Un tema define el alcance de un mensaje difundido.
El runtime implementa un modelo de publicación-suscripción (publish-subscribe) mediante su API de difusión. Al publicar un mensaje, se debe especificar un tema, el cual actúa como una abstracción sobre los ID de agentes.
📌 Un tema se compone de dos partes:
💡 Tema = (Tipo de Tema, Fuente del Tema)
El tipo de tema suele definirse en el código de la aplicación para representar el tipo de mensaje. Ejemplo: un agente de GitHub puede usar
"GitHub_Issues"para mensajes sobre nuevos issues.La fuente del tema es un identificador único dentro de un tipo de tema. Suele definirse con base en los datos de la aplicación. Ejemplo:
"github.com/{repo_name}/issues/{issue_number}"
🧠 Esto permite limitar el alcance de los mensajes y crear espacios aislados (silos).
Los Topic IDs se pueden convertir a cadenas y viceversa. Formato:
💡 Formato del Topic ID:
Tipo_Tema/Fuente_Tema
Los tipos se consideran válidos si están en UTF8 y solo contienen letras alfanuméricas (a-z) y (0-9), o guiones bajos (_). Un identificador válido no puede empezar con un número ni contener espacios. Las fuentes se consideran válidas si están en UTF8 y solo contienen caracteres entre ASCII 32 (espacio) y 126 (~) (inclusive).
Suscripción (Subscription)
Una suscripción mapea un tema a uno o más ID de agentes.
📌 El runtime mantiene un registro de las suscripciones y las usa para entregar mensajes a los agentes.
Si un tema no tiene suscripciones, los mensajes no se entregan a ningún agente.
Si un tema tiene varias suscripciones, el mensaje se entregará una sola vez a cada agente suscrito.
Puedes agregar o eliminar suscripciones usando la API del runtime.
Suscripción Basada en Tipo (Type-based Subscription)
Una type-based subscription mapea un tipo de tema a un tipo de agente. No necesita conocer las fuentes del tema ni las claves de los agentes.
💡 Fórmula de la Suscripción Basada en Tipo:
Tipo de Tema –> Tipo de Agente
✅ Es la forma más recomendada, ya que es portable y no depende de los datos.
📦 En Python, se representa con TypeSubscription.
Escenarios para Type-based Subscription
Se puede aplicar en muchos contextos donde los temas o agentes dependen de los datos. Los escenarios se dividen en:
Un solo inquilino (single-tenant) vs multi-inquilino (multi-tenant)
Un solo tema vs múltiples temas por inquilino
Un tenant se refiere a un conjunto de agentes que manejan una sesión de usuario o solicitud específica.
Escenario: Single-Tenant, Single Topic
Este es el caso más simple:
Un solo tenant
Un solo tema para toda la aplicación
🔧 ¿Cómo aplicarlo?
Crea una TypeSubscription por cada tipo de agente
Usa el mismo tipo y fuente de tema para todos los mensajes
Ejemplo:
Entonces, todos los mensajes usan el tema:
➡️ Este tema entregará el mensaje a los siguientes agentes:
La siguiente figura mostraría visualmente cómo funciona esta suscripción.
Si el agente con el ID especificado no existe, el entorno de ejecución lo creará.
Inquilino Único, Múltiples Temas (Single-Tenant, Multiple Topics)
En este escenario, hay un solo tenant, pero deseas controlar qué agente maneja qué tema. Esto es útil cuando quieres crear espacios aislados (silos) y tener agentes especializados en distintos temas.
📌 Para aplicar una suscripción basada en tipo en este caso:
Crea una suscripción basada en tipo por cada tipo de agente, pero usando diferentes tipos de tema.
Puedes mapear el mismo tipo de tema a múltiples tipos de agentes si deseas que compartan ese tema.
Para la fuente del tema, usa el mismo valor en todos los mensajes que publiques.
📌 Continuando con el ejemplo anterior y los mismos tipos de agentes, las suscripciones serían:
🔁 Con estas suscripciones:
Un mensaje publicado al tema
("triage", "default")será entregado al agente del tipo"triage_agent".Un mensaje publicado al tema
("coding", "default")será entregado a los agentes con tipo"coder_agent"y"reviewer_agent".
🖼️ La figura siguiente muestra cómo funciona esta suscripción basada en tipo en este ejemplo.
Escenarios Multi-Inquilino (Multi-Tenant Scenarios)
En los escenarios de inquilino único, la fuente del tema (topic source) siempre es la misma (por ejemplo, "default") – está codificada directamente en el código de la aplicación.
Sin embargo, al pasar a escenarios multi-inquilino, la fuente del tema depende de los datos.
💡 Una buena señal de que estás en un escenario multi-inquilino es que necesitas múltiples instancias del mismo tipo de agente. Por ejemplo:
Quieres que diferentes sesiones de usuario sean manejadas por instancias separadas para mantener sus datos privados aislados.
O quieres distribuir una carga de trabajo pesada entre múltiples instancias del mismo tipo de agente para que trabajen en paralelo.
📌 Continuando con el ejemplo anterior:
Si deseas tener instancias dedicadas de agentes para manejar un issue específico de GitHub, necesitas configurar la fuente del tema (topic source) como un identificador único del issue.
Por ejemplo, supongamos que tienes una suscripción basada en tipo para el tipo de agente "triage_agent":
Entonces:
Cuando se publique un mensaje al tema
("github_issues", "github.com/microsoft/autogen/issues/1"), el entorno de ejecución entregará el mensaje al agente con ID("triage_agent", "github.com/microsoft/autogen/issues/1").Si se publica un mensaje al tema
("github_issues", "github.com/microsoft/autogen/issues/9"), se entregará al agente con ID("triage_agent", "github.com/microsoft/autogen/issues/9").
🖼️ La figura correspondiente muestra cómo funciona esta suscripción basada en tipo en este ejemplo.
Nota que el ID del agente depende de los datos, y el entorno de ejecución creará una nueva instancia del agente si no existe.
Para admitir múltiples temas por inquilino, puedes usar diferentes tipos de temas, al igual que en el escenario de inquilino único con múltiples temas.
Última actualización
