Saltar al contenido principal

Configurar

La página Configurar (/configure/:agentId) es el espacio de trabajo administrativo para un agente individual. Solo es accesible para usuarios con el rol de administrador. La página carga el registro del agente por ID, muestra una barra de identidad en la parte superior y renderiza una tira de pestañas debajo. Las pestañas visibles dependen del execution_mode del agente y de si este ha declarado variables de plantilla.

Barra de Identidad del Agente​

La barra en la parte superior de la página muestra:

  • Avatar — un icono de un solo carácter derivado de la primera letra del nombre del agente
  • Nombre del agente — obtenido del registro del agente (name o el campo configurable type==agent/name)
  • Insignia de tipo — el valor de agent_type
  • Insignia de ID — el agentId sin procesar de la URL
  • Insignia de importado — mostrada para agentes cuyo execution_mode no es local (por ejemplo, passthrough, proxy). Esta insignia indica que la orquestación está controlada por el sistema de origen y no puede modificarse en Runtime. El texto emergente dice: "Orchestration (skills, knowledge, MCP) is controlled by the source system and cannot be modified here."

Disponibilidad de Pestañas​

Las pestañas visibles se determinan en el momento de carga a partir de dos factores:

Tipo de agentePestañas mostradas
Agente local, sin variables de plantillaSkills, Knowledge, MCP Servers, Channels, Notifications
Agente local, con variables de plantillaVariables, Skills, Knowledge, MCP Servers, Channels, Notifications
Agente importado / passthrough, sin variablesChannels, Notifications
Agente importado / passthrough, con variablesVariables, Channels, Notifications

Pestaña Variables​

La pestaña Variables está disponible cuando el agente tiene al menos una variable de plantilla declarada (prompt_variables). Cada variable se muestra como un campo de texto editable. La etiqueta del campo proviene de pv.label si está definida; de lo contrario, de pv.name. La referencia de plantilla Jinja2 (por ejemplo, {{customer_name}}) se muestra junto a la etiqueta. Un botón de restablecimiento restaura el campo a su valor predeterminado declarado. Una sugerencia Default: muestra el valor predeterminado actual debajo de cada campo.

Los cambios se agrupan — ninguno se guarda hasta que se hace clic en el botón Save variables. El botón está deshabilitado cuando no hay cambios sin guardar. Tras el éxito, el registro del agente se vuelve a obtener para que la pestaña refleje el estado guardado de inmediato.

Pestaña Skills​

La pestaña Skills enumera todas las habilidades asignadas a este agente. Cada fila de habilidad muestra:

  • Nombre de visualización (recurre a name si no se ha definido display_name)
  • Insignia de tipo — Custom, Inbuilt o System, con código de color
  • Descripción — mostrada debajo del nombre cuando está presente
  • Referencia de herramienta — el identificador de herramienta subyacente, mostrado en texto pequeño y atenuado
  • Selector de conexión — aparece en línea cuando la habilidad tiene authentication_required: true; permite al administrador vincular una credencial almacenada a esta habilidad para este agente

Las habilidades son de solo lectura en esta vista — agregar o eliminar habilidades se realiza en el constructor de agentes. La pestaña no está disponible para agentes importados.

Pestaña Knowledge​

La pestaña Knowledge muestra todas las fuentes de datos del inquilino, divididas en dos grupos:

  • Linked to Agent — fuentes de datos ya adjuntas a este agente (coincidentes por datasourceid)
  • Other Available Sources — fuentes de datos del inquilino que no están vinculadas actualmente a este agente

Cada tarjeta de fuente de datos muestra el nombre, la insignia de datasource_type (database, file, common o system), una insignia Active cuando is_active es verdadero, y una descripción cuando está presente. Para las fuentes de datos que requieren autenticación, se muestra un ConnectionSelector en línea.

Las fuentes de datos de tipo file son expandibles. Al expandir una fuente de datos de archivo, se revelan sus archivos cargados con nombre y tamaño. Desde la vista expandida, un administrador puede:

  • Cargar un archivo — activa un selector de archivos; el archivo se carga en la fuente de datos de inmediato
  • Eliminar un archivo — elimina el archivo seleccionado; la lista se actualiza automáticamente

La pestaña no está disponible para agentes importados.

Pestaña MCP Servers​

La pestaña MCP Servers enumera todos los servidores Model Context Protocol adjuntos a este agente. Cada tarjeta de servidor muestra:

  • Nombre del servidor y una insignia de transporte (por ejemplo, stdio, sse)
  • Insignia de estado Activo / Inactivo
  • Descripción cuando se proporciona
  • Selector de conexión — mostrado cuando authentication_required es verdadero
  • Divulgación de herramientas — al hacer clic en el recuento de herramientas se expande una lista de todos los nombres de herramientas expuestos por este servidor; al pasar el cursor sobre un nombre de herramienta se muestra su descripción

La pestaña no está disponible para agentes importados.

Pestaña Channels​

La pestaña Channels expone tres tarjetas de canal de entrega para enrutar las interacciones del agente a través de sistemas externos. Cada tarjeta tiene un interruptor de alternancia (On / Off) y un botón Save. La configuración de esta pestaña no altera la orquestación del agente — solo controla cómo se expone el agente externamente.

Microsoft Teams — conecta el agente a un bot de Teams mediante un registro de aplicación de Azure Bot. Campos:

  • Client ID (App ID) — el ID de aplicación (cliente) de Azure
  • Tenant ID — el ID de inquilino de Azure Active Directory
  • Client Secret — el valor del secreto de cliente; se muestra como puntos enmascarados cuando ya se ha guardado un secreto; déjelo en blanco en guardados posteriores para conservar el secreto existente

Nota: La tarjeta de Teams solía tener sus propios campos Greeting response y Welcome message, y la tarjeta Embed su propio Welcome message. Esos campos se han trasladado a la pestaña Conversation, donde se configuran una vez para el agente y se aplican en todos los canales. El texto configurado antes del cambio fue migrado automáticamente — no es necesario volver a introducirlo.

Webhook — expone el agente como un endpoint HTTP al que los sistemas externos pueden enviar solicitudes POST. El proceso del worker de webhook se ejecuta de forma asíncrona. Campos:

  • Authentication — None (endpoint público), API key (basada en encabezado) o HMAC (cuerpo firmado con sha256)
  • API key header name — el nombre del encabezado utilizado cuando se selecciona la autenticación api_key (predeterminado: X-Beak-Webhook-Key)
  • API key / HMAC shared secret — el valor del secreto; enmascarado cuando ya está guardado
  • Trigger message — un prefijo de indicación opcional que se antepone a cada carga útil entrante

Una vez que el webhook está habilitado y guardado, aparece un panel Trigger URL debajo del botón de guardar. Muestra la URL del endpoint en vivo con un botón de copia y muestras de integración en pestañas para cURL, Python y Node.js.

Mail — conecta uno o más buzones de Microsoft 365 al agente. Cada nuevo correo electrónico en un buzón conectado activa una ejecución del agente. Agregue un buzón con un Registro de Aplicación de Azure que tenga el permiso Mail.Read (Aplicación) y el consentimiento del administrador; consulte Settings para los requisitos previos del canal de correo. Por buzón, los campos son:

  • Label — un nombre para el buzón, mostrado en la lista de buzones
  • Mailbox email — la dirección a monitorear, por ejemplo, support@acme.com
  • Microsoft Tenant ID / Application (Client) ID / Client Secret — las credenciales del Registro de Aplicación de Azure; el secreto se enmascara una vez guardado, y se deja en blanco en guardados posteriores para conservar el valor existente
  • Test Connection — valida las credenciales y el acceso al buzón sin guardar

En What the agent receives, dos interruptores controlan cuánto del contenido de cada correo electrónico llega al agente. Ambos están desactivados de forma predeterminada, incluso para buzones conectados antes de que existieran estas configuraciones, por lo que habilitarlos siempre es una elección deliberada:

  • Send the whole conversation — de forma predeterminada, el agente solo ve el mensaje más reciente, porque cada correo electrónico inicia un nuevo hilo de conversación. Active esto para incluir también los mensajes anteriores del hilo de correo electrónico. Los hilos largos se recortan a los mensajes más recientes que caben en un presupuesto de caracteres, y el agente recibe información sobre cuántos mensajes anteriores quedaron fuera. Use esto para buzones donde las respuestas dependen de lo que ya se acordó — un buzón de soporte o disputas — en lugar de buzones de solicitud de un solo uso.
  • Analyse attachments — extrae el texto de los archivos adjuntos del mensaje y lo pasa al agente, para que pueda responder preguntas sobre el contenido del archivo en lugar de ver solo los nombres de archivo. Compatible con PDF, Word, PowerPoint, Excel, CSV, texto sin formato e imágenes (mediante OCR). Las imágenes en línea, como logotipos de firma, se omiten, y los archivos muy grandes se enumeran pero no se extraen.

Nota: El análisis de archivos adjuntos se factura por página. Utiliza Azure Document Intelligence para documentos y Azure AI Vision para imágenes, y se ejecuta en cada correo electrónico entrante a ese buzón que lleva un archivo adjunto. Actívelo en los buzones donde los archivos adjuntos son importantes, no de forma generalizada.

Nota: El análisis de archivos adjuntos depende de las credenciales de extracción de documentos de la plataforma, que son aprovisionadas por entorno por el equipo de operaciones de Beak — no son un campo de Ajustes de autoservicio. Si no están presentes, el agente igualmente recibe el correo electrónico y la lista de archivos adjuntos, con una nota de que la extracción no está disponible, en lugar de fallar la ejecución. Comuníquese con el soporte de Beak para habilitarlos en su entorno.

Ambas configuraciones pueden modificarse en cualquier momento desde Edit en la fila del buzón; cambiarlas no interrumpe la entrega de correo ni requiere volver a dar consentimiento a la aplicación de Azure.

Pestaña Conversation​

La pestaña Conversation establece qué dice el agente antes de que se le formule alguna pregunta, y qué responde sin consultar al modelo. Ambos son propiedades del agente, por lo que se aplican de forma idéntica independientemente de cómo se acceda a él — chat web, Microsoft Teams, el widget integrado, la aplicación de escritorio y el correo. La pestaña también está disponible para agentes importados.

Mensajes de apertura​

Dos campos, con duraciones deliberadamente diferentes:

  • Welcome message — mostrado al inicio de cada conversación nueva.
  • First-time message — mostrado una sola vez por persona, siempre. Se rastrea por usuario y por agente en lugar de por canal, por lo que alguien que lo vea en Teams no lo verá de nuevo en el chat web.

Ambos aceptan {first_name} y {agent_name}, y el editor muestra una vista previa en vivo con un nombre de ejemplo. Deje un campo vacío para no mostrar nada — un agente sin ninguno de los dos configurados se comporta exactamente como antes.

Respuestas estándar​

Una lista de respuestas fijas para preguntas cuya respuesta ya conoce. Cada entrada empareja un conjunto de reglas de coincidencia con el texto exacto a enviar. No hay un límite práctico en cuántas se pueden agregar.

Cuando una entrada coincide, el agente devuelve su texto literalmente y no llama al modelo — por lo que la respuesta es exactamente lo que escribió, no tiene coste alguno y se devuelve de inmediato.

Cada entrada tiene:

  • Name — solo para su referencia; nunca se muestra a la persona que conversa.
  • When the message… — cómo se compara el mensaje:
    • Any of these keywords — coincide con palabras completas, por lo que una palabra clave hi no se activará en "this".
    • Message contains — la frase aparece en cualquier parte del mensaje.
    • Message is exactly — el mensaje completo, ignorando la puntuación y las mayúsculas.
    • Regular expression — para patrones que los otros modos no pueden expresar.
  • Only match short messages — un límite de palabras para el mensaje completo. Configúrelo en 3 para un saludo de modo que "hi there" coincida, pero "hi can you create a ticket" siga llegando al agente.
  • Also match similar wording — formulaciones de ejemplo opcionales. Cuando ninguno de los patrones coincide, el agente compara el mensaje con estas por significado, de modo que "I forgot my login" puede llegar a una entrada escrita para "reset my password". Déjelo vacío y la entrada permanece puramente literal.
  • Answer — la respuesta. Admite los mismos marcadores de posición que los mensajes de apertura.
  • Let the agent phrase this answer — desactivado de forma predeterminada. Actívelo cuando la respuesta necesite adaptarse a la conversación; el agente entonces usa su texto como contenido requerido en lugar de enviarlo literalmente, lo cual es más lento y usa tokens.

El orden importa. La lista se verifica de arriba hacia abajo y la primera coincidencia gana, por lo que coloque las reglas más específicas por encima de las más amplias — una entrada contains: ticket por encima de una is exactly: ticket status responderá a ambas. Use las flechas en cada fila para reordenar.

Nota: Use el cuadro Try a question antes de confiar en una nueva regla. Escriba un mensaje de ejemplo e informará qué entrada lo respondería, o que ninguna lo haría. Esta es la única forma de ver si una regla eclipsa a otra antes de que un usuario real lo descubra.

Dónde editar​

Las mismas configuraciones aparecen en el editor de agentes de Beak AI Studio, en Conversation, junto al prompt del agente. Ambas consolas leen y escriben los mismos valores, por lo que no importa cuál utilice.

Nota: Las respuestas estándar reemplazan el uso de respuestas predefinidas en el prompt del sistema. Una instrucción en el prompt es una sugerencia que el modelo puede reformular; una entrada aquí se devuelve exactamente como se escribió, siempre.

Pestaña Notifications​

La pestaña Notifications proporciona anulaciones por agente para las tres plantillas de correo electrónico transaccional utilizadas por el sistema de aprobaciones. Las plantillas usan la sintaxis Jinja2 y admiten los siguientes marcadores de posición: {{ agent_name }}, {{ requester_name }}, {{ approver_email }}, {{ prompt_summary }}, {{ magic_link }}, {{ expires_relative }} y {{ tenant_name }}.

Tres sub-pestañas seleccionan la plantilla que se está editando:

  • Request — enviada al aprobador cuando llega una nueva solicitud de aprobación; debe incluir {{ magic_link }} para que el aprobador pueda actuar
  • Resolved elsewhere — enviada cuando la aprobación fue decidida a través de otro canal (chat o Teams) para que el destinatario del correo electrónico sepa que el enlace ya no está activo
  • Expired — enviada cuando la ventana de aprobación se cerró sin ninguna decisión

Cada sub-pestaña expone tres campos: Subject, HTML body y Plain-text body. Dejar un campo en blanco hace que el agente use el valor predeterminado de la plataforma para ese campo. Los cambios se guardan con el botón Save; el botón Discard revierte al último estado guardado.

Mejores Prácticas​

  • Siempre guarde el Client Secret la primera vez que configure Teams — una vez que se navega fuera de la página, el secreto no puede recuperarse desde la interfaz de usuario y debe rotarse en Azure AD si se pierde.
  • Para integraciones de webhook, prefiera la autenticación HMAC sobre API key en entornos de producción; verifica la integridad de la carga útil además de la identidad del llamante.
  • Active el Analyse attachments del correo por buzón en lugar de en todos — llama a un servicio de Azure por página en cada correo electrónico entrante con un archivo adjunto, por lo que un buzón de alto volumen cuyos archivos adjuntos el agente nunca analiza es un coste puro.
  • Si un agente responde a un hilo de correo como si los mensajes anteriores nunca hubieran ocurrido, verifique Send the whole conversation en ese buzón: sin ello, el agente solo ve el mensaje más reciente.
  • Al cargar archivos en una fuente de datos de tipo file, mantenga los archivos individuales por debajo de unos pocos megabytes; los archivos grandes ralentizan el pipeline de recuperación y pueden ser truncados por la ventana de contexto del agente.
  • Coloque las respuestas fijas frecuentemente solicitadas en Conversation → respuestas estándar en lugar de en el prompt: la respuesta quedará garantizada palabra por palabra, se devuelve de inmediato y no consume tokens.
  • Use la pestaña Variables para personalizar el texto de marca blanca (nombre de empresa, saludo) por implementación en lugar de crear agentes separados para cada cliente.
  • La pestaña Notifications solo necesita modificarse cuando las plantillas de correo electrónico predeterminadas de la plataforma no coinciden con la marca del inquilino; dejar todos los campos en blanco es una configuración válida y de bajo mantenimiento.

Páginas Relacionadas​

  • Overview — panel de control de runtime
  • Agents — cuadrícula de agentes y vista de chat
  • Suites — paquetes de instalación que aprovisionan agentes y sus recursos automáticamente
  • Approvals — revisar solicitudes de aprobación generadas por agentes
  • Connections — gestionar credenciales almacenadas referenciadas por habilidades y fuentes de datos
  • Providers — configurar credenciales de proveedor LLM
  • Settings — configuración a nivel de inquilino, incluidos los requisitos previos del canal de correo