Conceptos básicos

HeartBeatAgents se organiza en torno a un puñado de conceptos básicos. Entenderlos te ayudará a diseñar agentes eficaces y a sacar el máximo partido de la plataforma.

Agentes

Un agente es una entidad de IA autónoma con un rol, una personalidad y un conjunto de capacidades definidos. Cada agente tiene un proveedor y modelo de LLM principal, órdenes permanentes que rigen su comportamiento, acceso a herramientas y canales específicos, y su propio almacén de memoria. Los agentes funcionan de forma independiente, y puedes ejecutar varios, cada uno especializado en una función distinta (soporte, ventas, ingeniería, etc.).

Propiedades clave: nombre, descripción, proveedor, modelo, órdenes permanentes, nivel de autonomía (supervisado, semiautónomo, totalmente autónomo), estado (activo, en pausa, archivado).

Conversaciones

Una conversación es un hilo de mensajes entre un usuario y un agente. Las conversaciones mantienen su estado a lo largo de varios turnos y pueden extenderse durante horas, días o semanas. Cada conversación pertenece a un agente concreto y está asociada a un canal concreto: la unidad principal de interacción, y la fuente de la memoria episódica.

Propiedades clave: ID de conversación, ID de agente, canal, identidades de los participantes, historial de mensajes, estado (activa, resuelta, escalada), metadatos.

Herramientas

Las herramientas son capacidades discretas que un agente puede invocar durante una conversación. Cada herramienta tiene un nombre, una descripción (que el LLM lee para saber cuándo usarla), parámetros de entrada y un manejador de ejecución. Las herramientas las proporcionan las integraciones: conecta una integración de Stripe, y herramientas como stripe_get_customer y stripe_create_refund quedan disponibles.

Propiedades clave: nombre de la herramienta, descripción, esquema de parámetros, origen de la integración, permisos requeridos, límites de tasa.

Planificación

Un objetivo expresado en lenguaje natural se descompone en una secuencia de pasos ordenados por dependencias, que se te muestra para aprobación, edición o rechazo antes de que se ejecute nada. Ver Planificación.

Vista previa en vivo

Un agente puede ejecutar un servidor de desarrollo real o un proceso de larga duración dentro de su espacio de trabajo aislado y devolverte una vista previa en vivo y funcional, no una descripción de una. Ver Vista previa en vivo.

Delegación

Un agente puede entregar una subtarea a otro agente al que se le ha concedido acceso y recibir el resultado de vuelta, de la misma manera que una persona delega en un compañero de equipo. Ver Delegación.

Memoria

La memoria da a los agentes continuidad entre conversaciones, implementada como tres tipos:

• Episódica: almacena el historial de conversaciones. Permite a los agentes recordar interacciones previas.
• Semántica: almacena hechos y conocimiento extraídos: preferencias, información de cuenta, decisiones.
• Procedimental: almacena patrones de comportamiento aprendidos, para que los agentes reutilicen procesos multipaso exitosos ante tipos de tareas recurrentes.

Todos los tipos de memoria usan embeddings vectoriales para la recuperación, así que los agentes encuentran memorias relevantes por similitud semántica, no solo por coincidencia de palabras clave.

Canales

Los canales son las plataformas de comunicación donde los agentes interactúan con los usuarios: más de 20 compatibles, incluyendo Slack, Discord, Microsoft Teams, Telegram, WhatsApp, SMS, correo electrónico y chat web. Cada canal tiene su propio adaptador que normaliza los mensajes a un formato estándar; un agente puede conectarse a varios canales simultáneamente, y las conversaciones mantienen su contexto sin importar en qué canal ocurran. Ver la Guía de canales para la lista completa y los pasos de configuración.

Voz

La voz es una conversación hablada en tiempo real con un agente en el navegador, independiente de los canales de texto anteriores. Necesita un proyecto de LiveKit (transporte) y un proveedor de voz (Deepgram o ElevenLabs) conectados antes de funcionar. Ver Voz y Configuración de voz.

Integraciones

Las integraciones conectan un agente con servicios externos, normalmente autenticándose mediante OAuth 2.0. Conectar una integración descubre y expone automáticamente sus herramientas a tus agentes: Google Workspace, Microsoft 365, GitHub, Jira, HubSpot, Salesforce, Stripe, Notion, y más. Ver la Guía de integraciones para el catálogo completo y el modelo de seguridad.

Órdenes permanentes

Las órdenes permanentes son instrucciones persistentes que definen el comportamiento de un agente en todas sus conversaciones. A diferencia de una simple instrucción de sistema, están estructuradas (definiciones de rol, reglas de comportamiento, límites de conocimiento, políticas de escalado, límites operativos) y versionadas, lo que permite revertir un cambio que produzca un comportamiento indeseado. Es el factor individual más determinante para la calidad de un agente.

Propiedades clave: texto de la orden, número de versión, fecha de creación, estado activo, agente asociado, historial de cambios.

Relacionado

• Referencia de la API: invocar agentes y consultar memoria mediante programación
• Configuración inicial: crear tu primer agente