Saltar al contenido principal

Guía de desarrollo y API del Agente de IA

Esta guía es la referencia técnica para integrar el Agente de IA de plugNmeet. Abarca la API de creación de salas para la comunicación entre servidores, los endpoints protobuf a los que accede el cliente de navegador dentro de la sala y el flujo de webhooks que permite mantener la continuidad entre sesiones.

En Desarrollo Activo

El motor del Agente de IA y sus API están en desarrollo activo. Los nombres de los campos, las reglas de validación y el comportamiento de los endpoints pueden cambiar antes de la publicación general. La integración con un solo clic en los plugins de Moodle, WordPress y Joomla está prevista una vez que la función se finalice y se publique. Mientras tanto, realice la integración mediante la API que se describe a continuación.

Dónde se ubica la configuración​

El Agente de IA se configura en el objeto insights_features de la sala, dentro de ai_agent_features. Este objeto se encuentra dentro de metadata.room_features cuando llama a /auth/room/create.

metadata
└── room_features
└── insights_features
├── is_allow
└── ai_agent_features ← this guide
├── auto_session_config
├── mcp_servers
└── custom_provider (BYOK)

Antes de que una sala pueda utilizar el agente, su servidor debe incluir una entrada insights.services.ai_agent en config.yaml, salvo que la sala proporcione su propio custom_provider. Consulte Configuración del servidor y del proveedor.

Referencia de campos de ai_agent_features​

La tabla enumera los 32 campos de InsightsAIAgentFeatures en plugnmeet_create_room_insights.proto, además de los mensajes anidados AIAgentAutoSessionConfig, ExternalMCPServerConfig e InsightsAIAgentCustomProvider.

CampoTipoObligatorioDescripción
is_allowboolSíInterruptor general del Agente de IA en esta sala.
session_modeenumSíAI_AGENT_SESSION_MODE_NORMAL_ROOM (0), AI_AGENT_SESSION_MODE_CONTROLLED_USERS (1) o AI_AGENT_SESSION_MODE_OPEN_PER_USER (2).
auto_session_configobjectSegún el modoAjustes de enrutamiento para las sesiones 1 a 1 automáticas. Consulte auto_session_config.
agent_display_namestringNoNombre con el que se muestra el agente. Predeterminado: AI Assistant.
system_promptstringSí, cuando is_allow está activoInstrucciones del anfitrión sobre la personalidad y el comportamiento del agente.
previous_session_contextstringNoContexto de una sesión anterior, normalmente el JSON del resumen o su valor previous_session_context_prompt.
topicstringSí, cuando is_allow está activoLa lección, demostración o formación sobre la que debe mantenerse el agente.
allowed_subtopicsstring[]NoHasta 64 subtemas que quedan dentro del alcance.
forbidden_topicsstring[]NoHasta 32 temas que el agente debe rechazar.
strict_topic_enforcementboolNoRechazar las solicitudes fuera del tema. Predeterminado: true.
topic_anchor_interval_turnsuint32NoVuelve a insertar el anclaje del tema cada N turnos. Predeterminado 6, rango de 3 a 12.
spoken_langstring (BCP-47)NoIdioma del alumno o del visitante, por ejemplo en-US.
target_langstring (BCP-47)NoIdioma que se está aprendiendo. Déjelo vacío para temas que no sean de idiomas.
instruction_langstring (BCP-47)NoIdioma en el que el agente explica. Si está vacío, se usa spoken_lang.
voicestringNoIdentificador de voz del proveedor. Debe figurar en la lista de voces permitidas del servidor.
speaking_ratefloatNoVelocidad del habla, de 0.5 a 2.0. Predeterminado 1.0.
allow_whiteboard_writeboolNoPermite que el agente dibuje en la pizarra. Predeterminado true.
allow_vision_captureboolNoPermite que el agente reciba instantáneas de la pizarra y del bloc de notas. Predeterminado true.
vision_debounce_msuint32NoTiempo de espera entre instantáneas. Predeterminado 1200, máximo 5000.
vision_max_edge_pxuint32NoArista más larga de la instantánea. Predeterminado 1024, rango de 512 a 1600.
allow_pollsboolNoPermite cuestionarios y encuestas. Predeterminado true.
allow_chat_messageboolNoPermite que el agente publique en el chat de IA. Predeterminado true.
allow_notepad_writeboolNoPermite que el agente escriba en el bloc de notas compartido. Predeterminado true.
allow_web_fetchboolNoPermite que el agente consulte páginas HTTPS aprobadas. Predeterminado false.
allowed_knowledge_urlsstring[]Recomendado cuando allow_web_fetch es trueHasta 32 prefijos de URL HTTPS que el agente puede consultar.
knowledge_cache_ttl_secondsuint32NoTiempo de caché de las páginas consultadas. Predeterminado 3600, rango de 60 a 86400.
mcp_serversmap<string, ExternalMCPServerConfig>NoHasta 2 servidores MCP externos. Consulte Servidores MCP externos.
max_session_secondsuint32NoLímite de duración de la sesión, de 60 a 7200. Si no se indica, el valor predeterminado es 1800.
max_audio_minutesuint32NoPresupuesto de audio por sesión, hasta 240. Con 0 se usa el valor predeterminado del servidor, 120.
is_enabledboolDebe ser falseIndicador interno de ejecución. El anfitrión no puede establecerlo.
active_session_idstringDebe estar vacíoCampo interno de ejecución. El anfitrión no puede establecerlo.
custom_providerobjectNoProveedor BYOK propio de la sala. Consulte custom_provider (BYOK).

auto_session_config​

CampoTipoDescripción
allowed_participant_idsstring[]Hasta 32 identificadores de participante. Se usa en CONTROLLED_USERS.
max_concurrent_sessionsuint32Se usa en OPEN_PER_USER. El servidor limita este valor a 16.
auto_start_agentboolOpcional. Controla si el agente se inicia automáticamente en las sesiones enrutadas.

ExternalMCPServerConfig​

CampoTipoDescripción
urlstringEndpoint HTTPS, con un máximo de 1024 caracteres.
headersmap<string, string>Encabezados de solicitud opcionales, hasta 16 pares. La clave admite 128 caracteres como máximo y el valor 2048.
allowed_toolsstring[]Hasta 8 nombres de herramienta. Solo estas herramientas se ofrecen al agente.
scopestringIndicación opcional de propietario: shared, text_chat o ai_agent.

custom_provider (BYOK)​

CampoTipoObligatorioDescripción
providerstringSígoogle u openai.
api_keystringSíClave de API del proveedor, de 1 a 512 caracteres. Nunca se difunde.
endpointstringNoURL base HTTPS de una puerta de enlace o de un servidor autoalojado, hasta 512 caracteres.
auth_headerstringNoNombre del encabezado que transporta la clave, hasta 128 caracteres.
realtime_modelstringNoSustituye el modelo en tiempo real.
delegation_modelstringNoSustituye el modelo de delegación.
summarize_modelstringNoSustituye el modelo de resumen.

Modos de sesión​

ModoQuién inicia la sesiónEnrutamientoCámaras web y compartición de pantallaUso habitual
NORMAL_ROOMUn moderador, desde el panel de salas de gruposSalas de grupos 1 a 1 manualesSin cambiosPráctica dirigida por el docente, demostraciones guiadas por ventas
CONTROLLED_USERSAutomático, para los participantes indicadosCada participante autorizado recibe <Name> (AI Session)Desactivadas en toda la salaListas de alumnos asignados, grupos de incorporación
OPEN_PER_USERAutomático, para cualquier visitanteCada visitante recibe una sesión aislada, hasta max_concurrent_sessionsDesactivadas en toda la salaSalas de estudio 24/7, enlaces de demostración de producto

En los modos automáticos, la sala principal funciona como sala de espera. Los participantes que no están autorizados permanecen en ella.

Ejemplos de solicitudes​

Todos los ejemplos se envían a /auth/room/create. Utilizan los encabezados de autenticación estándar de la API que se describen en la API para crear una sala. Solo se muestran las partes relevantes; el resto de campos de metadatos son opcionales.

1. NORMAL_ROOM: sesiones de grupo dirigidas por el docente​

{
"room_id": "class-algebra-01",
"metadata": {
"room_title": "Algebra Class",
"room_features": {
"allow_webcams": true,
"allow_screen_share": true,
"breakout_room_features": {
"is_allow": true
},
"insights_features": {
"is_allow": true,
"ai_features": {
"is_allow": true
},
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_NORMAL_ROOM",
"agent_display_name": "Math Tutor",
"system_prompt": "You are a patient algebra tutor. Work step by step on the whiteboard and ask the student to predict each step.",
"topic": "Linear equations",
"allowed_subtopics": ["one-variable equations", "word problems"],
"forbidden_topics": ["homework answers for graded tests"],
"strict_topic_enforcement": true,
"topic_anchor_interval_turns": 6,
"spoken_lang": "en-US",
"instruction_lang": "en-US",
"speaking_rate": 1.0,
"allow_whiteboard_write": true,
"allow_polls": true,
"allow_notepad_write": true,
"allow_web_fetch": false,
"max_session_seconds": 1800,
"max_audio_minutes": 60
}
}
}
}
}

2. CONTROLLED_USERS: lista de alumnos asignados​

{
"room_id": "tutoring-group-7",
"metadata": {
"room_title": "Tutoring Group 7",
"room_features": {
"insights_features": {
"is_allow": true,
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_CONTROLLED_USERS",
"auto_session_config": {
"allowed_participant_ids": ["student-101", "student-102", "student-103"],
"auto_start_agent": true
},
"agent_display_name": "Study Coach",
"system_prompt": "You are a study coach for high-school chemistry. Ask one question at a time and check each answer with a short quiz.",
"topic": "Chemical bonding",
"allowed_subtopics": ["ionic bonds", "covalent bonds", "electronegativity"],
"forbidden_topics": ["exam cheating", "personal advice"],
"strict_topic_enforcement": true,
"topic_anchor_interval_turns": 6,
"allow_polls": true,
"max_session_seconds": 1800
}
}
}
}
}

allowed_participant_ids admite hasta 32 identificadores. Cada uno debe coincidir con el user_id que utiliza su aplicación cuando un participante se une a la sala.

3. OPEN_PER_USER: sala de estudio o demostración de autoservicio 24/7​

{
"room_id": "study-room-spanish",
"metadata": {
"room_title": "Spanish Practice Room",
"room_features": {
"allow_webcams": false,
"allow_screen_share": false,
"insights_features": {
"is_allow": true,
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_OPEN_PER_USER",
"auto_session_config": {
"max_concurrent_sessions": 8,
"auto_start_agent": true
},
"agent_display_name": "Lucía",
"system_prompt": "You are a friendly Spanish speaking coach for adult beginners. Speak mostly in simple Spanish and explain grammar in English when needed.",
"topic": "Everyday Spanish conversation",
"allowed_subtopics": ["greetings", "ordering food", "travel vocabulary"],
"forbidden_topics": ["politics", "medical advice"],
"spoken_lang": "en-US",
"target_lang": "es-ES",
"instruction_lang": "en-US",
"speaking_rate": 0.9,
"voice": "YOUR_PROVIDER_VOICE_ID",
"max_session_seconds": 1200,
"max_audio_minutes": 30
}
}
}
}
}

Aunque envíe un número mayor, el servidor limita max_concurrent_sessions a 16. Establezca voice con un identificador de la lista de voces permitidas de su proveedor, u omítalo para usar la voz default_voice del servidor.

4. Con BYOK (custom_provider)​

Este ejemplo utiliza la puerta de enlace compatible con OpenAI del propio anfitrión para una sola sala. La clave se elimina de los metadatos de la sala antes de difundirlos y se almacena únicamente en Redis.

{
"room_id": "demo-acme-visitor-room",
"metadata": {
"room_title": "Acme Product Demo",
"room_features": {
"insights_features": {
"is_allow": true,
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_OPEN_PER_USER",
"auto_session_config": {
"max_concurrent_sessions": 4
},
"system_prompt": "You are a visual sales engineer for Acme Analytics. Use the uploaded deck and keep answers short.",
"topic": "Acme Analytics product demo",
"forbidden_topics": ["pricing negotiation"],
"max_session_seconds": 1800,
"custom_provider": {
"provider": "openai",
"api_key": "sk-YOUR-ROOM-SCOPED-KEY",
"endpoint": "https://gateway.example.com/v1",
"auth_header": "Authorization",
"realtime_model": "gpt-realtime-2.1-mini",
"delegation_model": "gpt-5.4-mini",
"summarize_model": "gpt-5.4-mini"
}
}
}
}
}
}

Si se establece custom_provider, el servidor no necesita una entrada de servicio ai_agent en config.yaml. Los modelos que omita utilizan los valores predeterminados del servidor para el proveedor elegido.

5. Con servidores MCP externos (mcp_servers)​

{
"room_id": "onboarding-acme-001",
"metadata": {
"room_title": "Acme API Onboarding",
"room_features": {
"insights_features": {
"is_allow": true,
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_NORMAL_ROOM",
"system_prompt": "You are a technical onboarding assistant for the Acme API. Check the checklist before each step.",
"topic": "Acme API authentication and webhooks",
"allow_web_fetch": true,
"allowed_knowledge_urls": ["https://docs.acme.example/api/"],
"knowledge_cache_ttl_seconds": 3600,
"mcp_servers": {
"acme-docs": {
"url": "https://mcp.acme.example/mcp",
"allowed_tools": ["search_docs", "read_doc"],
"scope": "ai_agent"
}
}
}
}
}
}
}

Sesiones de IA en salas de grupos​

Un moderador puede iniciar una sesión de IA 1 a 1 dentro de una sala de grupos. Utilice /api/breakoutRoom/create con estos campos de CreateBreakoutRoomsReq:

CampoTipoDescripción
enable_ai_agentboolCrea las salas de grupos con una sesión del Agente de IA asociada.
ai_agent_contextstringContexto opcional a nivel de sala para el agente, de hasta 2000 caracteres.

Cada sala de grupos también contiene sus propios indicadores enable_ai_agent, ai_agent_context (hasta 2000 caracteres) y ai_agent_joined. El indicador ai_agent_joined informa al panel de Sesiones de IA del moderador de si un agente se ha unido a esa sala.

{
"room_id": "class-algebra-01",
"requested_user_id": "teacher-1",
"duration": 15,
"enable_ai_agent": true,
"ai_agent_context": "Student is practising two-step equations. Start with the warm-up from last session.",
"allow_return_to_main_room": true,
"rooms": [
{ "title": "Ana", "users": [{ "id": "student-ana" }] },
{ "title": "Ben", "users": [{ "id": "student-ben" }] }
]
}

Las salas de grupos heredan la configuración del proveedor BYOK de la sala principal, de modo que la misma clave y los mismos modelos se aplican a todas las sesiones.

Seguridad del conocimiento externo y de los servidores MCP externos​

El acceso externo es la parte de mayor riesgo en la configuración del agente. El servidor aplica las reglas que se indican a continuación.

Conocimiento externo (allow_web_fetch)​

  • Desactivado de forma predeterminada. Establezca allow_web_fetch: true solo cuando lo necesite.
  • Solo HTTPS. Las URL con http:// sin cifrar se rechazan.
  • Lista de permitidos obligatoria. El agente solo puede consultar las URL que empiecen por alguna entrada de allowed_knowledge_urls (hasta 32 prefijos). Utilice una ruta final, como https://docs.example.com/api/, para limitar el alcance.
  • Con caché. Las páginas consultadas se almacenan en caché durante knowledge_cache_ttl_seconds, lo que limita las solicitudes repetidas.
  • El contenido no es de confianza. El texto consultado se encapsula como datos. No puede modificar las reglas del agente.

Servidores MCP externos (mcp_servers)​

  • Máximo 2 servidores por sala. El límite se aplica a los ámbitos shared, ai_agent y text_chat.
  • Máximo 8 herramientas permitidas por servidor. Las herramientas que no figuran en allowed_tools nunca se ofrecen al agente.
  • Política de solo lectura. El servidor aplica una política de herramientas estrictamente de solo lectura. Las herramientas que escriben, eliminan o envían datos no se exponen, aunque se indiquen en la lista. Diseñe su servidor MCP de forma que sus herramientas de lectura sean las únicas que exponga.
  • Solo HTTPS en el puerto 443. Se rechazan otros esquemas y puertos.
  • Protección SSRF. Las conexiones se comprueban en el momento de establecerlas. Solo se permiten direcciones enrutables globalmente, por lo que se rechazan las conexiones a direcciones privadas, de bucle local, de enlace local o que no sean globales.
  • Los encabezados son secretos. Incluya los tokens de API en headers. Se almacenan en el servidor y no se difunden a los participantes.
No apunte los servidores MCP a servicios internos

Aunque exista protección SSRF, conecte los servidores MCP únicamente a servicios que tenga previsto exponer al Agente de IA y a sus visitantes. Utilice un endpoint MCP dedicado de solo lectura, no su API interna de administración.

Flujo de continuidad entre sesiones​

La continuidad permite que un alumno o un prospecto que regresa retome la conversación donde la dejó. El flujo consta de cuatro pasos:

  1. La sesión termina. El servidor escribe un artefacto AI_AGENT_SESSION_SUMMARY para la sala principal y envía un webhook artifact_created. Consulte Webhooks.
  2. Su backend obtiene el artefacto. Llame a /auth/artifact/fetch con type: "AI_AGENT_SESSION_SUMMARY" (o 11) y el identificador de la sala.
  3. Su backend prepara el contexto. Puede pasar el JSON del resumen o utilizar su valor continuation.previous_session_context_prompt, que es un prompt breve redactado precisamente para este fin.
  4. Comienza la siguiente sesión. Envíe previous_session_context en la siguiente solicitud a /auth/room/create o en la solicitud a /api/aiAgent/start.
{
"room_id": "study-room-spanish",
"metadata": {
"room_features": {
"insights_features": {
"is_allow": true,
"ai_agent_features": {
"is_allow": true,
"session_mode": "AI_AGENT_SESSION_MODE_OPEN_PER_USER",
"previous_session_context": "Last session: the learner practised greetings and ordering food. Struggled with the subjunctive. Next focus: travel vocabulary.",
"topic": "Everyday Spanish conversation"
}
}
}
}
}

La continuidad por usuario funciona mejor con OPEN_PER_USER y CONTROLLED_USERS, modos en los que su backend conoce la identidad del alumno. Utilice el campo user_info.ex_user_id del resumen para asociar al alumno con sus propios registros.

Endpoints dentro de la sala (/api/aiAgent/*)​

El cliente de navegador controla el agente a través de estos endpoints. La autenticación se realiza con el JWT de sala del participante, no con la clave de API del servidor. Las solicitudes y las respuestas usan protobuf (application/x-protobuf), no JSON.

EndpointMétodoMensaje de solicitudQuién puede llamarloFinalidad
/api/aiAgent/startPOSTAIAgentStartReqSolo el administrador de la salaInicia el agente. Opcionalmente sustituye system_prompt y previous_session_context.
/api/aiAgent/stopPOSTAIAgentStopReqAdministrador, delegado actual o participante preautorizadoDetiene la sesión. Admite un reason opcional, por ejemplo host_stopped.
/api/aiAgent/statusGET o POSTAIAgentStatusReqCualquier participante de la salaDevuelve AIAgentStatusRes con el AIAgentStateMsg actual.
/api/aiAgent/pausePOSTAIAgentPauseReqAdministrador, delegado o participante preautorizadoPausa el agente.
/api/aiAgent/resumePOSTAIAgentResumeReqAdministrador, delegado o participante preautorizadoReanuda un agente en pausa.
/api/aiAgent/sendContextPOSTAIAgentSendContextReqAdministrador, delegado o participante preautorizadoInyecta contexto externo, como un evento de temporizador o datos del LMS. source puede ser lms o timer.
/api/aiAgent/redelegatePOSTAIAgentRedelegateReqAdministrador, delegado o participante preautorizadoTraslada el control a otro participante. Si target_user_id está vacío, el servidor elige.

Las respuestas de inicio, parada, estado y del resto de endpoints de control utilizan el mensaje protobuf AIAgentStatusRes, que contiene status, msg y un state opcional.

Estados de ejecución​

AIAgentStateMsg.state indica uno de estos estados de ejecución: CONNECTING, LISTENING, THINKING, SPEAKING, DRAWING, PAUSED, RECONNECTING y STOPPED.

Ejemplo: enviar contexto desde un evento del LMS​

Cree un AIAgentSendContextReq con su biblioteca de protobuf (por ejemplo protobufjs o plugnmeet-protocol-js):

AIAgentSendContextReq {
text: "The student has just submitted quiz 3 with a score of 4 out of 5. Review the missed question."
source: "lms"
}

Envíe los bytes codificados a /api/aiAgent/sendContext con el JWT de sala del participante en el encabezado Authorization.

Páginas relacionadas​