Agentes de IA

Un agente de IA es un asistente de varios pasos. Lee la conversación, planifica, llama a herramientas (sus herramientas de IA, herramientas MCP y una búsqueda en la base de conocimiento), analiza los resultados y vuelve a llamar al modelo hasta tener una respuesta. El nodo Crear respuesta de chat de IA hace una única llamada al modelo y responde; el nodo Agente de IA puede seguir trabajando a lo largo de varias llamadas al modelo y a herramientas, dentro de los límites que usted defina, antes de responder.

Use un agente cuando una solicitud requiera varios pasos, por ejemplo "buscar el pedido del cliente, comprobar su estado de entrega y ofrecer una nueva fecha". Para una respuesta directa a partir de instrucciones y una base de conocimiento, el nodo de IA es más sencillo y económico.

Los componentes

Parte	Qué es	Dónde se configura
Harness de IA	El motor que ejecuta el bucle del agente: el propio de MonoChat, un SDK de agentes o un servicio de agentes alojado.	Configuración › Automatización › AI harnesses
Modelos	Los modelos de IA con los que piensa el agente: un modelo principal, un modelo alternativo opcional y un modelo rápido opcional. Los harnesses alojados utilizan en su lugar los modelos de su propio proveedor.	El nodo Agente de IA
Herramientas	Ámbitos de IA, funciones de tipo Herramienta de IA y herramientas MCP.	El nodo Agente de IA
Presupuesto de ejecución	Límites de llamadas al modelo, llamadas a herramientas, tokens, duración y reintentos para cada ejecución.	El nodo Agente de IA
Ejecución	Una ejecución del agente. Cada ejecución se registra en Ejecuciones del agente de IA.	La crea el nodo o la API

AI harnesses

Configuración › Automatización › AI harnesses enumera los harnesses en los que pueden ejecutarse sus agentes: los que MonoChat ofrece a todos los espacios de trabajo y los que usted añade con sus propias credenciales.

Harness	Dónde se ejecuta	Modelos que utiliza	Quién lo añade
MonoChat Native	Dentro de MonoChat	Sus modelos de IA	MonoChat
OpenAI Agents SDK	Dentro de MonoChat	Sus modelos de IA	MonoChat
Claude Agent SDK	En el agent runner de MonoChat	Sus modelos de IA	MonoChat
pi	En el agent runner de MonoChat	Sus modelos de IA	MonoChat
OpenAI Agents API	En la nube de OpenAI	Los modelos permitidos del harness	Usted, con su clave de API de OpenAI (MonoChat también puede ofrecer una)
Claude Managed Agents	En la nube de Anthropic	Los modelos permitidos del harness	Usted, con su clave de API de Anthropic (MonoChat también puede ofrecer una)
Custom Endpoint	En su propio servidor	Sus modelos de IA (opcional)	Usted, con su endpoint y su secreto

Los harnesses que se ejecutan en MonoChat los ofrece MonoChat; su espacio de trabajo solo puede añadir harnesses que utilicen sus propias credenciales. Claude Agent SDK y pi necesitan el agent runner de MonoChat: donde no esté configurado, una ejecución en ellos falla con "This harness is not available on this server."

Sea cual sea el harness, MonoChat mantiene el control: cada llamada al modelo de un harness que utiliza sus modelos de IA pasa por MonoChat (por lo que se aplican la facturación y el presupuesto), cada llamada a herramientas ejecuta sus funciones, herramientas MCP y ámbitos de IA en su espacio de trabajo, y el presupuesto se aplica en todos los harnesses.

Añadir un harness

Vaya a Configuración › Automatización › AI harnesses y haga clic en + (Crear).
Introduzca un Nombre y, opcionalmente, una Descripción.
Elija el Harness. Cada opción indica dónde se ejecuta.
En Credenciales, introduzca lo que necesita el harness:
- OpenAI Agents API, Claude Managed Agents: Clave de API.
- Custom Endpoint: Endpoint y Clave de API.
Para un harness alojado, complete Modelos permitidos: introduzca los nombres de modelo del proveedor (por ejemplo, el ID de modelo de OpenAI o Anthropic). Use Añadir modelo para añadir hasta 10 modelos. Los agentes de este harness solo pueden elegir de esta lista.
Haga clic en Guardar.

Al editar un harness, el tipo de Harness no se puede cambiar, y el campo de la clave indica Clave de API (déjela vacía para conservar la clave guardada).

Claude Managed Agents

La primera vez que se usa un harness de este tipo, MonoChat crea un agente y un entorno en esa cuenta de Anthropic y los reutiliza después.

Custom Endpoint

Un harness Custom Endpoint envía las ejecuciones a su propio servicio, por ejemplo un agente autoalojado. En cada ejecución, MonoChat envía un POST a <Endpoint>/runs con Authorization: Bearer <API Key>. El cuerpo contiene el ID de la ejecución, las instrucciones, la entrada, los mensajes de la conversación, el presupuesto, los alias de modelo (agent-main, agent-fallback, agent-fast) y tres URL con un token para esta ejecución:

una pasarela de modelos (URL base compatibles con OpenAI …/v1 y con Anthropic) que llama a los modelos de IA del nodo y aplica el presupuesto,
un servidor MCP que expone las herramientas de la ejecución,
una URL de eventos donde su servicio informa del resultado (completed con result, o failed con error).

El token de la ejecución deja de funcionar cuando esta termina.

El nodo Agente de IA

Añada un agente a un flujo con el nodo Agente de IA, dentro de los nodos híbridos del diseñador de flujos. Consulte Flujos para saber cómo añadir y conectar nodos.

Campos

Sección	Campo	Descripción
	Nombre	El nombre del nodo que se muestra en el lienzo.
	Harness de IA	Obligatorio. El harness que ejecuta el agente.
	Instrucciones	Las instrucciones de sistema del agente: su rol, tono, reglas y lo que puede o no puede hacer.
	Tarea (se añade a las instrucciones del agente; se pueden usar etiquetas)	Lo que este nodo le pide al agente. Se añade después de las instrucciones y puede usar las mismas etiquetas que el prompt del nodo de IA, por ejemplo para incluir datos del cliente.
Modelos	Modelo principal	El modelo que utiliza el agente. Obligatorio para todos los harnesses excepto Custom Endpoint.
	Modelo alternativo (tras el límite flexible)	El modelo al que cambia el agente al alcanzar el límite flexible de llamadas al modelo, normalmente un modelo más económico o más rápido.
	Modelo rápido (tareas ligeras en segundo plano)	Un modelo que un harness puede utilizar para sus llamadas ligeras en segundo plano.
	Modelo (uno de los modelos permitidos del harness)	Se muestra en lugar de los tres campos anteriores para un harness alojado.
Sesión del agente	Conversación	Continuar la sesión de agente existente (predeterminado) o Iniciar una nueva sesión de agente. Consulte Sesiones de agente.
	Clave de tarea (sesiones de agente separadas por tarea)	Opcional. Mantiene una sesión de agente distinta por cada clave en la misma conversación, por ejemplo `booking` y `support`.
	Límite del historial de mensajes	Cuántos mensajes de la conversación recibe el agente.
	Modelos de AI de voz a texto	Un modelo con Transcripción. Los mensajes de voz de la conversación llegan al agente como texto.
Ajustes de herramientas	Ámbitos de AI	Bases de conocimiento en las que puede buscar el agente. Se ofrecen al agente como una herramienta de búsqueda en la base de conocimiento.
	Herramienta de AI	Funciones de tipo Herramienta de AI a las que puede llamar el agente.
	Configurar herramientas de contenido del cliente MCP de IA	Abre el panel donde se añaden las herramientas MCP. Consulte Clientes MCP.
Mensajes	Reenviar mensajes intermedios al cliente	Desactivado de forma predeterminada. Lo que el agente escribe mientras sigue trabajando (por ejemplo "Voy a revisar su pedido") se envía al cliente cuando está activado; cuando está desactivado se añade a la conversación solo como un mensaje susurro que ve únicamente su equipo.
	Enviar respuesta	Activado de forma predeterminada. Envía la respuesta final del agente al cliente. Desactívelo para usar la respuesta solo dentro del flujo.
Presupuesto de ejecución	Máx. de llamadas al modelo	Predeterminado: 4.
	Límite flexible: llamadas al modelo	Opcional. Tras este número de llamadas al modelo, el agente cambia al modelo alternativo. Debe ser inferior a Máx. de llamadas al modelo y requiere un modelo alternativo.
	Máx. de llamadas a herramientas	Predeterminado: 6. Con `0`, la ejecución termina como Presupuesto superado en cuanto el agente intenta llamar a una herramienta.
	Máx. de tokens totales	Predeterminado: 20000. Tokens de entrada y salida de todas las llamadas al modelo de la ejecución.
	Duración máxima (segundos)	Predeterminado: 30.
	Máx. de reintentos	Predeterminado: 2. Cuántas veces se reintenta una llamada al modelo fallida.

consejo

Escriba las reglas estables en Instrucciones y el trabajo concreto de este paso en Tarea. Así, varios nodos Agente de IA de un flujo pueden compartir las mismas instrucciones y diferir solo en su tarea.

aviso

Los harnesses alojados no admiten un límite flexible, porque no pueden cambiar a un modelo alternativo. Deje vacío Límite flexible: llamadas al modelo en ellos.

Qué ocurre cuando el flujo llega al nodo

MonoChat comprueba su saldo y los ajustes del nodo, e inicia una ejecución. La ejecución queda En cola y después En ejecución. La instancia de flujo espera en el nodo.
El agente recibe las instrucciones y la tarea y, cuando el flujo pertenece a una conversación, los mensajes de la conversación hasta el Límite del historial de mensajes, con los mensajes de voz transcritos.
El agente llama a modelos y herramientas hasta que tiene una respuesta o alcanza un límite. El texto que escribe entre llamadas a herramientas se trata como un mensaje intermedio.
Cuando termina la ejecución:
- si quedó Completado y Enviar respuesta está activado, la respuesta se envía al cliente. Las respuestas largas se dividen en varios mensajes cuando superan el límite del canal (4096 caracteres en WhatsApp);
- si terminó de cualquier otra forma, se añade a la conversación un mensaje susurro "AI agent run ended: estado. error" para su equipo.
El flujo continúa por la salida que corresponde a cómo terminó la ejecución.

Las ejecuciones de una misma sesión de agente se procesan de una en una, en orden.

Salidas

Salida	Cuándo
Completado	El agente terminó con una respuesta.
Presupuesto superado	La ejecución agotó Máx. de llamadas al modelo, Máx. de llamadas a herramientas o Máx. de tokens totales.
Tiempo agotado	La ejecución alcanzó la Duración máxima (segundos).
Odio, Jailbreak, Autolesión, Sexual, Violencia	El filtro de contenido del proveedor del modelo detuvo la ejecución por esta categoría. Son las mismas salidas que tiene el nodo de IA.
En caso de fallo	La ejecución falló por cualquier otro motivo o se canceló. Una detención por el filtro de contenido también llega aquí en los nodos guardados antes de que existieran estas salidas; abra y guarde ese nodo para obtenerlas.

Conecte al menos Completado y En caso de fallo. Un patrón habitual es enviar Presupuesto superado, Tiempo agotado y En caso de fallo a un nodo Asignar conversación para que un compañero tome el relevo.

Sesiones de agente

Una sesión de agente es la memoria del agente entre ejecuciones. MonoChat mantiene una sesión de agente activa por conversación, harness y clave de tarea.

Continuar la sesión de agente existente la reutiliza, de modo que el agente retoma lo que estaba haciendo. En los harnesses alojados, también continúa la sesión propia del proveedor.
Iniciar una nueva sesión de agente cierra la activa y empieza de cero, por ejemplo al comenzar un tema nuevo.
Una Clave de tarea mantiene sesiones independientes en paralelo dentro de la misma conversación.

Facturación

Las llamadas al modelo en modelos de IA proporcionados por MonoChat se facturan de su saldo como de costumbre. Las llamadas en sus propios modelos las factura su proveedor.
Un harness proporcionado por MonoChat puede añadir sus propias tarifas por ejecución, por minuto y por llamada a herramientas y, en un harness alojado, los tokens que informe su proveedor. Aparecen en Transacciones como Ejecución del agente de IA, Duración del agente de IA, Llamada a herramienta del agente de IA y categorías de tokens de IA.
Un harness que usted añade con sus propias credenciales no tiene tarifa de MonoChat; su proveedor le factura.
Una ejecución no se inicia cuando su saldo es insuficiente.

Evento Ejecución del agente de IA finalizada

Ejecución del agente de IA finalizada es un nodo de evento. Se dispara cuando termina una ejecución asociada a un cliente, tanto si la inició un flujo como si se inició a través de la API con una conversación. Como otros nodos de evento, tiene ajustes opcionales de Condición y Tiempo agotado. Úselo para iniciar un flujo independiente tras las ejecuciones de agentes, por ejemplo para registrar resultados o avisar a un equipo.

Iniciar un agente desde código

Las funciones personalizadas y los clientes de la API pueden ejecutar agentes con estos métodos (permiso Iniciar / Leer / Cancelar ejecuciones de agentes de IA en la automatización):

Método	Qué hace
`business.tenants.automation.ai.aiAgentRuns.create`	Inicia una ejecución. Devuelve `aiAgentRunId` y `aiAgentSessionId`.
`business.tenants.automation.ai.aiAgentRuns.show`	Devuelve una ejecución (`_id`) con su estado, uso, pasos y resultado.
`business.tenants.automation.ai.aiAgentRuns.cancel`	Cancela una ejecución en cola o en curso (`_id`).

create recibe aiHarnessClientId, input (la tarea), opcionalmente sessionId (para trabajar en una conversación), aiAgentSessionId, taskKey e isNewSession, y options con los mismos ajustes que el nodo: instructions, aiModelClientId, fallbackAiModelClientId, fastAiModelClientId, harnessModel, toolCustomFunctionIds, aiScopeIds, aiMcpClientDatas, messageHistoryLimit, speechToTextAiModelClientId, forwardIntermediateMessages, willSendAnswer y un budget obligatorio. A través de la API, forwardIntermediateMessages y willSendAnswer son false de forma predeterminada.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

La ejecución es asíncrona: léala más tarde con show, o reaccione a ella con el evento Ejecución del agente de IA finalizada. Sin un sessionId, cada llamada inicia una nueva sesión de agente, salvo que pase el aiAgentSessionId que devolvió una llamada anterior; el agente verá entonces las ejecuciones completadas anteriores de esa sesión de agente como su historial. Consulte Método para saber cómo llamar a métodos desde una función.

Permisos

Permiso	Permite
Leer / Crear / Actualizar / Eliminar harnesses de IA en la automatización	Gestionar AI harnesses
Leer ejecuciones de agentes de IA en la automatización	Ver Ejecuciones del agente de IA
Iniciar ejecuciones de agentes de IA en la automatización	Llamar a `aiAgentRuns.create`
Cancelar ejecuciones de agentes de IA en la automatización	Llamar a `aiAgentRuns.cancel`

Consulte Roles.

Ejecuciones del agente de IA: vea qué hizo cada ejecución
Modelos de IA
Clientes MCP
Ámbitos de IA
Flujos

Los componentes​

AI harnesses​

Añadir un harness​

Custom Endpoint​

El nodo Agente de IA​

Campos​

Qué ocurre cuando el flujo llega al nodo​

Salidas​

Sesiones de agente​

Facturación​

Evento Ejecución del agente de IA finalizada​

Iniciar un agente desde código​

Permisos​

Relacionado​