Saltar al contenido principal

Resúmenes y artefactos de uso del Agente de IA

Cada sesión del Agente de IA genera dos artefactos que se almacenan asociados a la sala principal:

ArtefactoValor de tipoFinalidad
AI_AGENT_SESSION_SUMMARY11Informe JSON estructurado de la sesión: qué se aprendió, qué se practicó, los resultados de los cuestionarios, la actividad en el espacio de trabajo y el contexto de continuación para la siguiente sesión.
AI_AGENT_USAGE10Uso de tokens y de audio, desglosado por rol y modalidad, con los costos estimados.

Esta página describe ambos artefactos, con los nombres de campo exactos que se utilizan en plugnmeet_room_artifacts.proto.

En Desarrollo Activo

El motor del Agente de IA y sus formatos de artefacto están en desarrollo activo. Los nombres de los campos y los campos que aún no se documentan 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.

Cómo recibe los artefactos​

  1. La sesión finaliza y el servidor escribe ambos artefactos en la sala principal.
  2. Su servidor recibe un webhook artifact_created por cada artefacto.
  3. Su servidor obtiene el JSON con /auth/artifact/fetch, filtrando por type (AI_AGENT_SESSION_SUMMARY o AI_AGENT_USAGE).
Use el webhook como disparador

No consulte los artefactos de forma periódica. Escuche artifact_created, compruebe room_artifact.type y obtenga después únicamente el artefacto que necesite.

AI_AGENT_SESSION_SUMMARY​

El archivo de resumen es JSON y se genera con los nombres de campo del proto (snake_case). Se incluyen las cadenas vacías, las listas vacías y los valores cero, de modo que todos los campos siempre están presentes. Los campos opcionales se omiten cuando no están definidos.

Campos de nivel superior​

CampoTipo JSONDescripción
summary_sourcestringllm cuando un modelo de texto ha refinado el resumen. local_fallback cuando el resumen se ha construido solo a partir de la telemetría de la sesión.
generated_atstringMarca de tiempo ISO-8601 del momento en que se creó el resumen.
user_infoobjectEl alumno o visitante de esta sesión. Siempre presente. Consulte user_info.
sessionobjectDatos de la sesión: horas, duración, motivo de finalización, tema y recuentos.
evaluationobjectValoración del dominio y de la participación.
quiz_evaluationobjectResultados de cuestionarios y encuestas.
progress_logarrayEstado de cada concepto a lo largo de la sesión.
workspace_activityobjectQué herramientas y espacios de trabajo se han utilizado.
continuationobjectContexto y enfoque para la siguiente sesión.
narrative_summarystringUn párrafo breve y legible para docentes, comerciales o notas del CRM.
usagemapUso de tokens por rol: session, delegation y summary. Consulte Uso por rol.
Versión del esquema

El resumen no incluye un campo schema_version. Detecte los cambios por los nombres de campo de la tabla anterior y por el metadata del registro del artefacto.

user_info​

CampoTipo JSONDescripción
user_idstringIdentificador interno del participante utilizado en la sesión.
namestringNombre visible, si se conoce. Opcional.
ex_user_idstringIdentificador de usuario de su sistema, enviado al unirse el participante. Utilícelo para asociar registros. Opcional.
extra_datastringMetadatos personalizados del participante, como cadena de objeto JSON. Opcional.

session​

CampoTipo JSONDescripción
room_idstringIdentificador de la sala principal.
room_sidstringEl SID de LiveKit de la sala principal.
session_idstringIdentificador único de esta sesión de IA.
agent_display_namestringNombre que utilizó el agente, por ejemplo Math Tutor.
topicstringEl tema configurado.
allowed_subtopicsstring[]Los subtemas configurados.
started_atstring (int64)Hora de inicio, en milisegundos Unix. Protobuf codifica los enteros de 64 bits como cadenas JSON.
ended_atstring (int64)Hora de finalización, en milisegundos Unix.
duration_secondsstring (int64)Duración de la sesión en segundos.
end_reasonstringMotivo por el que terminó la sesión, como host_stopped, empty_room o budget.
off_topic_redirects_countnumberRecuento acumulado de redirecciones por salirse del tema durante la sesión.
turns_countnumberNúmero de turnos de conversación.

evaluation​

CampoTipo JSONDescripción
overall_scorenumberPuntuación global de la sesión, según la establezca el paso de evaluación.
mastery_levelstringDescriptor breve, como developing, proficient o mastered.
participation_levelstringDescriptor breve de la intensidad con la que participó la persona.
concepts_masteredstring[]Conceptos que la persona ha demostrado dominar.
concepts_practicedstring[]Conceptos trabajados pero aún no consolidados.
struggled_withstring[]Conceptos que resultaron difíciles a la persona.
vocabulary_or_key_termsstring[]Términos clave o vocabulario utilizado en la sesión.
rubric_notesstringExplicación de cómo se llegó a la evaluación.

Los valores de mastery_level y participation_level son texto libre generado por el paso de resumen. Cree los filtros a partir de overall_score y de los arreglos de conceptos, no de las etiquetas exactas.

quiz_evaluation​

CampoTipo JSONDescripción
total_quizzesnumberNúmero de cuestionarios o encuestas con respuestas correctas en la sesión.
total_responsesnumberNúmero de respuestas enviadas.
correct_responsesnumberNúmero de respuestas correctas.
accuracy_percentnumbercorrect_responses / total_responses expresado en porcentaje.
questionsarrayUna entrada por pregunta.

Cada entrada de questions contiene:

CampoTipo JSONDescripción
poll_idstringIdentificador de la encuesta o del cuestionario.
questionstringEl texto de la pregunta.
correct_optionstringEl texto de la respuesta correcta.
total_votesstring (uint64)Total de votos recibidos.
correct_votesstring (uint64)Votos emitidos para la respuesta correcta.
passedbooleanSi la pregunta cumplió la regla de aprobado del cuestionario.

progress_log​

Cada entrada describe un concepto:

CampoTipo JSONDescripción
conceptstringNombre del concepto.
statusstringEstado al finalizar la sesión, como practiced o mastered.
notesstringNota opcional sobre el concepto.

workspace_activity​

CampoTipo JSONDescripción
tools_usedmap<string, number>Número de veces que se llamó a cada herramienta, por ejemplo whiteboard_draw_diagram: 3.
whiteboard_usedbooleanSi se utilizó la pizarra.
notepad_usedbooleanSi se utilizó el bloc de notas compartido.

continuation​

CampoTipo JSONDescripción
next_session_focusstringEnfoque recomendado para la siguiente sesión.
recommended_warm_upstringActividad breve de apertura para la siguiente sesión.
unfinished_subtopicsstring[]Subtemas que aún no se han tratado.
previous_session_context_promptstringPrompt de contexto ya preparado. Páselo a la siguiente sesión como previous_session_context.

Uso por rol​

El mapa usage tiene una entrada por rol:

ClaveQué abarca
sessionEl modelo de voz en tiempo real: la conversación en directo, incluido el audio.
delegationEl modelo de texto que gestiona las llamadas a herramientas y los turnos delegados. Presente en los proveedores que usan un modelo de delegación independiente.
summaryEl modelo de texto que redactó el resumen al finalizar la sesión.

Cada entrada es un objeto de uso de tokens, descrito en la sección siguiente.

Resumen de ejemplo​

El ejemplo siguiente es un resumen realista de una sesión de estudio de 20 minutos. Los valores son ilustrativos.

{
"summary_source": "llm",
"generated_at": "2026-03-14T10:42:19Z",
"user_info": {
"user_id": "pnm_user-7f3a",
"name": "Ana Rivera",
"ex_user_id": "student-204",
"extra_data": "{\"class\":\"Grade 9B\"}"
},
"session": {
"room_id": "study-room-spanish",
"room_sid": "RM_kR8w2sXq1ZbA",
"session_id": "ai-7c1e9b40",
"agent_display_name": "Lucía",
"topic": "Everyday Spanish conversation",
"allowed_subtopics": ["greetings", "ordering food", "travel vocabulary"],
"started_at": "1773484800000",
"ended_at": "1773486000000",
"duration_seconds": "1200",
"end_reason": "host_stopped",
"off_topic_redirects_count": 1,
"turns_count": 34
},
"evaluation": {
"overall_score": 72,
"mastery_level": "developing",
"participation_level": "high",
"concepts_mastered": ["greetings", "ordering with 'quisiera'"],
"concepts_practiced": ["travel vocabulary"],
"struggled_with": ["subjunctive after 'quiero que'"],
"vocabulary_or_key_terms": ["la cuenta", "el menú", "por favor"],
"rubric_notes": "Confident in greetings and food vocabulary. Needs more practice with the subjunctive."
},
"quiz_evaluation": {
"total_quizzes": 2,
"total_responses": 6,
"correct_responses": 4,
"accuracy_percent": 67,
"questions": [
{
"poll_id": "poll-1a2b",
"question": "Which phrase politely asks for the bill?",
"correct_option": "La cuenta, por favor",
"total_votes": "1",
"correct_votes": "1",
"passed": true
},
{
"poll_id": "poll-3c4d",
"question": "Choose the correct form: Quiero que tú ___ conmigo.",
"correct_option": "vengas",
"total_votes": "1",
"correct_votes": "0",
"passed": false
}
]
},
"progress_log": [
{ "concept": "greetings", "status": "mastered", "notes": "Used formal and informal forms correctly." },
{ "concept": "subjunctive after 'quiero que'", "status": "struggling", "notes": "Needed two corrections." }
],
"workspace_activity": {
"tools_used": {
"whiteboard_draw_shapes": 2,
"whiteboard_write_content": 5,
"notepad_write": 3,
"create_quiz": 2
},
"whiteboard_used": true,
"notepad_used": true
},
"continuation": {
"next_session_focus": "Subjunctive after expressions of desire",
"recommended_warm_up": "Order a meal using a role-play with three menu items",
"unfinished_subtopics": ["travel vocabulary"],
"previous_session_context_prompt": "Previous session (Everyday Spanish): mastered greetings and ordering; struggled with the subjunctive after 'quiero que'. Start with a short warm-up, then practise the subjunctive."
},
"narrative_summary": "Ana practised greetings and ordering food with confidence. She answered most quiz questions correctly, but the subjunctive after 'quiero que' needs more practice. Start the next session with a meal role-play, then focus on the subjunctive.",
"usage": {
"session": {
"prompt_tokens": 18420,
"completion_tokens": 3110,
"total_tokens": 21530,
"breakdown": {
"session_prompt_tokens": "18420",
"session_audio_prompt_tokens": "9800",
"session_completion_tokens": "3110",
"session_audio_completion_tokens": "2600",
"audio_millis": "1200000"
}
},
"delegation": {
"prompt_tokens": 2950,
"completion_tokens": 640,
"total_tokens": 3590,
"breakdown": {
"delegation_prompt_tokens": "2950",
"delegation_completion_tokens": "640"
}
},
"summary": {
"prompt_tokens": 4100,
"completion_tokens": 520,
"total_tokens": 4620,
"breakdown": {
"summary_prompt_tokens": "4100",
"summary_completion_tokens": "520"
}
}
}
}

Los valores del desglose son cadenas en el JSON porque protobuf codifica int64 como cadenas. Conviértalos a enteros en su código.

Nombres de campo en el ejemplo

El ejemplo utiliza los nombres de campo que se enumeran en esta página. Algunos campos, como las claves de breakdown dentro de usage, pueden variar según el proveedor. Lea los valores que necesite e ignore las claves que no reconozca.

AI_AGENT_USAGE​

El artefacto de uso se almacena como RoomArtifactMetadata con una carga token_usage. Sus campos de metadatos son:

Campo de metadatosDescripción
token_usage.prompt_tokensTotal de tokens de entrada de todos los roles.
token_usage.completion_tokensTotal de tokens de salida de todos los roles.
token_usage.total_tokensTokens de entrada más tokens de salida.
token_usage.breakdownRecuentos por rol y por modalidad, descritos a continuación.
token_usage.prompt_tokens_estimated_costCosto estimado de la entrada. Opcional. Se omite en las sesiones BYOK.
token_usage.completion_tokens_estimated_costCosto estimado de la salida. Opcional. Se omite en las sesiones BYOK.
token_usage.total_tokens_estimated_costCosto total estimado. Opcional. Se omite en las sesiones BYOK.
reference_artifact_idIdentificador del artefacto AI_AGENT_SESSION_SUMMARY correspondiente. Úselo para vincular ambos.
user_infoLa misma identidad de alumno que en el resumen. Se incluye cuando el resumen la contiene.
occurred_in_breakout_roomtrue cuando la sesión se ejecutó en una sala de grupos.
source_room_table_idIdentificador de la tabla de la base de datos de la sala en la que se ejecutó la sesión.

Claves del desglose​

El mapa breakdown utiliza un prefijo por rol: session_, delegation_ o summary_. Por ejemplo, session_prompt_tokens y delegation_prompt_tokens.

Cada rol puede informar de estas claves cuando el valor es mayor que cero:

Sufijo de claveSignificado
_prompt_tokensTokens de entrada.
_completion_tokensTokens de salida.
_cached_prompt_tokensTokens de entrada servidos desde la caché.
_cache_write_prompt_tokensTokens de entrada escritos en la caché.
_text_prompt_tokensTokens de entrada de texto.
_audio_prompt_tokensTokens de entrada de audio.
_image_prompt_tokensTokens de entrada de imagen.
_cached_text_prompt_tokens, _cached_audio_prompt_tokens, _cached_image_prompt_tokensEntrada en caché, por modalidad.
_cache_write_text_prompt_tokens, _cache_write_audio_prompt_tokens, _cache_write_image_prompt_tokensEscrituras en caché, por modalidad.
_text_completion_tokensTokens de salida de texto.
_audio_completion_tokensTokens de salida de audio.
_thinking_completion_tokensTokens de salida de razonamiento, cuando el modelo los informa.

Claves de toda la sesión:

ClaveSignificado
audio_millisDuración del habla en milisegundos, utilizada en las sesiones con precio por audio y por minuto.
summary_prompt_tokensTokens de entrada empleados en redactar el resumen.
summary_completion_tokensTokens de salida empleados en redactar el resumen.
custom_provider_<provider>Se establece en 1 en las sesiones BYOK. Por ejemplo, custom_provider_openai.

Cálculo de costos por modalidad​

Los costos se estiman a partir de la tabla pricing del archivo config.yaml de su servidor. Cada modalidad tiene su propia tarifa:

  • La entrada y la salida de texto usan las tarifas de texto.
  • La entrada y la salida de audio usan las tarifas de audio, que suelen ser más altas.
  • La entrada de imagen usa la tarifa de imagen.
  • La entrada en caché usa la tarifa de caché cuando está definida. Si no hay tarifa de caché, los tokens en caché se facturan como entrada no cacheada.
  • Las escrituras en caché usan la tarifa de escritura en caché cuando está definida.
  • El habla en directo con precio por minuto (OpenAI Live) se estima a partir de audio_millis y de la tarifa price_per_minute.

La estimación es una ayuda contable. No sustituye a la factura de su proveedor. Mantenga los valores de pricing alineados con su contrato con el proveedor.

Atribución a la sala principal​

Ambos artefactos se almacenan en la sala principal, incluso cuando la sesión se ejecutó en una sala de grupos 1 a 1. Utilice estos campos para distinguirlos:

  • occurred_in_breakout_room: true identifica una sesión que se ejecutó en una sala de grupos.
  • source_room_table_id identifica la sala en la que se prestó la sesión.
  • reference_artifact_id vincula el uso con su resumen.

Por ejemplo, un centro educativo puede informar del uso por clase agrupando por el identificador de la sala principal y, aun así, ver qué sesiones fueron salas de grupos por alumno.

Supresión de la facturación con BYOK​

Cuando una sala utiliza su propio proveedor mediante custom_provider (BYOK), el servidor considera la sesión fuera de la facturación de la plataforma:

  • Los tres campos *_estimated_cost no se incluyen en el artefacto de uso.
  • El desglose incluye custom_provider_<provider>: 1. Su código de facturación o de webhook puede leer este indicador para omitir los cargos de la plataforma.
  • Los recuentos de tokens se siguen registrando, de modo que puede hacer seguimiento del uso aunque pague directamente al proveedor.

Utilice este indicador en su lógica de facturación:

const usage = artifact.metadata.token_usage;
const isBYOK = Object.keys(usage.breakdown || {}).some(k => k.startsWith('custom_provider_'));

if (!isBYOK) {
// Charge the platform cost for this room, using usage.total_tokens_estimated_cost
}

Uso de los artefactos en sus sistemas​

ObjetivoCampos que debe utilizar
Mostrar un informe del alumno a un docenteevaluation, quiz_evaluation, continuation, narrative_summary
Alimentar un CRMuser_info.ex_user_id, session.duration_seconds, quiz_evaluation.accuracy_percent, narrative_summary
Continuar la siguiente sesióncontinuation.previous_session_context_prompt
Hacer seguimiento del costo de la plataformaAI_AGENT_USAGE, total_tokens_estimated_cost y la ausencia de custom_provider_*
Saber qué herramientas se utilizaronworkspace_activity.tools_used

Para conocer el flujo de continuidad, consulte Continuidad entre sesiones. Para configurar los precios, consulte Tablas de precios.

Notas sobre privacidad​

  • El resumen contiene información de alumnos y visitantes, además de respuestas de cuestionarios. Trátelo como datos personales conforme a su política de privacidad.
  • El resumen es una evaluación, no una transcripción. Las transcripciones son un tipo de artefacto distinto.
  • Su servidor decide durante cuánto tiempo se conservan los artefactos.

Consulte el Resumen de seguridad para saber cómo se almacenan y se conservan los artefactos del servicio de IA.

Páginas relacionadas​