Usa Beeuni como backend de agentes para tu producto

Usa la API de Beeuni o el SDK de TypeScript para crear sesiones de agentes desde tu aplicación. Tu producto se encarga de la interfaz y de sus usuarios; Beeuni ejecuta las herramientas del agente y devuelve mensajes y archivos.

Imagina una herramienta de compras que compara proveedores. Un usuario selecciona productos y proveedores aprobados; el agente visita las páginas públicas de sus catálogos, consulta listas de precios de un servicio de documentos conectado y crea una hoja comparativa. Tu aplicación gestiona el inicio de sesión y la revisión, mientras la sesión de Beeuni recopila la información y realiza la comparación.

Define la tarea que enviará tu interfaz

Enumera las entradas, las acciones permitidas, el formato de salida y los posibles casos de error. Para el ejemplo del catálogo, proporciona las páginas de los proveedores aprobados, referencias a los documentos de catálogo conectados y los campos que se deben comparar. Solicita una fila por producto, con el precio cotizado y la moneda, además de una referencia a la fuente. Los datos de dimensiones que falten deben marcarse como desconocidos. La tarea no debe realizar pedidos.

• Responsabilidades de la aplicación: autenticar a las personas, decidir quién puede acceder a cada tarea, validar las entradas y presentar el resultado.
• Configuración del proyecto: elegir el agente, el modelo, las habilidades y las herramientas autorizadas que requiere este tipo de trabajo.
• Trabajo de la sesión: enviar la solicitud, seguir el progreso e inspeccionar los mensajes recibidos y los archivos de salida.

Da a la sesión acceso a las fuentes que necesita

Configura el proyecto con las herramientas de navegador y de conexión que requiere la tarea. Para un servicio privado de documentos, conecta una cuenta y concede al agente acceso al conector pertinente. Un enlace incluido en una solicitud no concede acceso por sí solo. Mantén la cuenta seleccionada y las fuentes permitidas en consonancia con el cliente que envió la tarea; la guía de conectores explica el acceso a las cuentas.

El agente podrá entonces consultar los documentos seleccionados mediante esas herramientas, visitar páginas públicas de productos y escribir un script para conciliar códigos de producto y tamaños de paquete. Pídele que guarde los valores obtenidos, las ubicaciones de las fuentes y las horas de consulta junto con el resultado. Si no se puede leer un catálogo o una página requiere otro inicio de sesión, devuelve esa incidencia a la interfaz en vez de inventar un precio.

Mantén las credenciales en tu servidor

La guía del SDK muestra cómo instalar @beeuni/sdk, crear un cliente y autenticar solicitudes. Mantén la clave de API en tu servidor, fuera del código del navegador.

Decide a qué proyectos de Beeuni puede acceder cada cliente. Mantén separados sus archivos y cuentas conectadas cuando sea necesario, y comprueba el acceso en tu servidor antes de reenviar solicitudes. La guía de autenticación explica los métodos de inicio de sesión disponibles.

Muestra el progreso y gestiona las reconexiones

El SDK permite crear sesiones, esperar a que estén listas y enviar solicitudes. El ejemplo completo explica cómo recibir eventos y leer la respuesta. Usa esos eventos para mostrar el progreso real. «Abriendo páginas de proveedores», «Comparando productos» y «Resultado listo» deben corresponder a un trabajo o estado que puedas observar.

Asigna a cada comparación un registro de tarea en tu aplicación. Guarda las referencias a las fuentes seleccionadas, las columnas solicitadas y los identificadores del proyecto y de la sesión de Beeuni, así como la ubicación de salida cuando esté disponible. Este registro conecta la pantalla de revisión con el trabajo que ya está en curso.

Application task record — illustrative fields, not an SDK payload
app_task_id
approved_source_references
requested_columns
beeuni_project_id
beeuni_session_id
output_reference
review_status

Imagina que un usuario selecciona tres catálogos de proveedores y luego actualiza la página. La interfaz actualizada busca la tarea de la aplicación y la sesión de Beeuni existente. Consulta el progreso guardado y reanuda el seguimiento de ese trabajo. Crear una sesión nueva cada vez que se carga la página duplicaría la tarea.

La conexión también puede interrumpirse antes de que tu servidor reciba la confirmación del envío. Es un resultado incierto, no una prueba de que no haya ocurrido nada. Comprueba la sesión antes de enviar la solicitud de nuevo. Si aún no puedes determinar si se aceptó, muestra esa incertidumbre en lugar de iniciar automáticamente otra comparación.

Verifica el resultado en tu aplicación

Para la comparación de catálogos, comprueba que estén las columnas obligatorias, que los archivos se puedan leer, que haya referencias a las fuentes y que se indiquen los productos que no se pudieron asociar. Las diferencias en el tamaño de los paquetes son una trampa habitual: no se puede comparar directamente un precio por caja de doce unidades con un precio por unidad. Conserva el importe y la unidad cotizados, y añade un precio normalizado solo cuando la fuente respalde la conversión.

La pantalla de revisión debe permitir que el usuario abra la fuente de cada precio y vea las asociaciones sin resolver. El archivo puede estar listo aunque algunas filas aún requieran revisión; mantén esos estados separados en tu aplicación.

Permite que las personas corrijan un resultado sin perder el contexto

Supongamos que dos proveedores usan nombres distintos para la misma silla. El agente los deja como productos separados, pero quien revisa reconoce que coinciden. Una corrección útil incluye las dos filas de origen y la relación deseada: «Compara estos productos como si fueran el mismo, pero mantén separados el acabado cotizado y el tamaño del paquete». Enviar solo «inténtalo de nuevo» deja que el agente adivine qué estaba mal.

Registra esa corrección junto a la tarea y conserva disponible el resultado anterior. El siguiente resultado puede corregir la asociación de productos y, a la vez, cambiar otra fila. Muestra la comparación revisada y su versión anterior para que quien revisa pueda comprobar ambas. Decide qué versión ofrecerá el botón de descarga y registra cuál fue aprobada.

La aprobación podría publicar la comparación en una pantalla interna de compras. Enviar un pedido a un proveedor es una acción aparte, con sus propios permisos y confirmación. Define ese límite en la aplicación antes de dar al agente acceso a herramientas de compra. La finalización de una hoja de cálculo no debe activar automáticamente un pedido.

Decide cuánto trabajo puede iniciar una solicitud

Establece límites prácticos para los envíos, como la cantidad de catálogos y el trabajo permitido en cada solicitud. Comparar tres listas de precios breves no es lo mismo que conciliar todo un archivo de productos. Muestra el alcance aceptado antes de empezar para que la persona pueda reducir la solicitud o elegir un trabajo en segundo plano.

Consulta los datos de uso y cargos en la plataforma cuando estén disponibles, en lugar de calcular la factura final a partir de la longitud de los mensajes. Si tu producto necesita un límite estricto de gasto o una garantía de cancelación, verifica cómo los aplica la integración. Un temporizador o un botón de «Detener» no bastan para demostrar que el trabajo y los cargos se han detenido.

Prueba la integración con casos que puedas verificar manualmente

Conserva un pequeño conjunto de catálogos con interpretaciones esperadas: una lista de precios clara, un escaneo ilegible, dos monedas, tamaños de paquete contradictorios y un producto sin una asociación clara. Úsalos cuando cambies el modelo, las instrucciones o la configuración del proyecto. Compara las filas resultantes y sus referencias a las fuentes, incluido aquello que el agente deje sin resolver.

Sal también de la página durante una ejecución, vuelve después y envía una corrección cuando aparezca el resultado. Comprueba qué resultado se descarga y si otra persona que haya iniciado sesión puede acceder a la tarea. El catálogo puede interpretarse correctamente mientras tu aplicación muestra una versión equivocada o la expone a la cuenta incorrecta. Prueba tanto el resultado del agente como la interfaz que lo rodea.