Cómo crear un agente de IA en Activepieces paso a paso

Un flujo de automatización tradicional funciona perfectamente cuando conoces de antemano todos los pasos: recibe un dato, aplica unas condiciones y ejecuta determinadas acciones. El problema aparece cuando la decisión depende del contexto y no puede expresarse mediante unas pocas reglas fijas.

Activepieces permite resolver estos casos creando agentes de IA capaces de analizar una entrada, consultar información y seleccionar las herramientas necesarias para alcanzar un objetivo. Puedes utilizarlos para clasificar solicitudes, investigar empresas, preparar informes o decidir cuándo debe intervenir una persona.

Crear un agente no consiste solamente en elegir un modelo y escribir un prompt. Para que resulte fiable debes definir sus instrucciones, herramientas, fuentes de conocimiento, campos de salida y límites de ejecución. Después tendrás que probarlo con entradas normales y casos difíciles antes de incorporarlo a un flujo de producción.

Qué diferencia un agente de IA de un flujo convencional

Un flujo convencional ejecuta una secuencia definida previamente. Ante la misma entrada y las mismas condiciones, debería recorrer siempre el mismo camino. Esto lo convierte en la mejor opción para tareas repetibles como copiar archivos, transformar datos o enviar notificaciones.

Un agente recibe un objetivo y decide durante cada ejecución qué información necesita y qué herramientas debe utilizar. Dos solicitudes parecidas pueden provocar decisiones diferentes si cambia su contenido o contexto.

Característica	Flujo	Agente
Lógica	Definida previamente mediante pasos y condiciones	Determinada durante cada ejecución
Resultado	Predecible ante entradas equivalentes	Puede variar según el razonamiento del modelo
Mejor uso	Procesos conocidos y repetibles	Tareas donde la decisión depende del contexto
Coste	No necesita necesariamente un modelo	Consume tokens y puede realizar varias llamadas
Control	Cada acción está colocada explícitamente	El modelo elige entre las herramientas permitidas

Si puedes describir toda la lógica mediante una frase como “si ocurre A, ejecuta B”, probablemente necesitas una condición, no un agente. Utilizar IA para una tarea determinista introduce más coste, latencia y variabilidad sin aportar una ventaja real.

La combinación más útil suele ser híbrida: el flujo se ocupa de los pasos que deben ejecutarse siempre de la misma manera y el agente resuelve únicamente la parte que requiere interpretación.

Qué necesitas antes de crear un agente en Activepieces

Antes de abrir el editor de agentes necesitas preparar varios componentes:

• Una cuenta de Activepieces Cloud o una instalación autogestionada actualizada.
• Un proyecto en el que tengas permisos para crear agentes y conexiones.
• Un proveedor de modelos configurado en la plataforma.
• Las conexiones de las aplicaciones que utilizará el agente.
• Un caso de uso con un objetivo y unos límites claramente definidos.

En una instalación administrada por una empresa, los proveedores de IA se configuran desde Platform Admin > AI Center. El administrador selecciona el proveedor, introduce sus credenciales y decide qué modelos estarán disponibles para los proyectos.

Activepieces admite proveedores como OpenAI, Anthropic, Google Gemini, Mistral, DeepSeek, xAI, Qwen, Azure, AWS Bedrock y OpenRouter. También permite utilizar pasarelas o servidores compatibles con la API de OpenAI mediante la opción Other (OpenAI Compatible).

Puedes configurar varios proveedores y escoger un modelo diferente para cada agente. Esto permite reservar los modelos más avanzados para tareas complejas y utilizar alternativas más económicas en clasificaciones o resúmenes sencillos.

Las conexiones con las aplicaciones se crean por separado. Si el agente tiene que consultar un CRM o enviar mensajes, prepara primero esas credenciales dentro del proyecto. No escribas claves de API ni contraseñas en las instrucciones.

Cómo crear un agente de IA en Activepieces

Activepieces ofrece tres puntos de partida para crear un agente:

• Describe it: escribes en una frase lo que necesitas y la plataforma genera una configuración inicial.
• Use a template: partes de una plantilla preparada para un caso de uso conocido.
• Start blank: creas el agente desde cero y escribes personalmente todas las instrucciones.

Para comenzar:

1. Abre el proyecto de Activepieces.
2. Entra en la sección Agents.
3. Describe el agente en el cuadro superior o pulsa New agent.
4. Selecciona una plantilla o comienza con una configuración vacía.
5. Asigna un nombre que indique claramente su función.
6. Abre la pestaña Configure.

La generación automática resulta útil para obtener un primer borrador, pero debes revisar cada apartado. Una descripción breve puede producir instrucciones demasiado generales o conceder al agente más autonomía de la necesaria.

Utiliza un nombre específico como Clasificador de solicitudes de soporte o Analista de nuevos proveedores. Evita nombres ambiguos como “Asistente general”, porque dificultan saber cuándo debe utilizarse y qué permisos necesita.

Cómo escribir unas instrucciones fiables

Las instrucciones deben explicar el trabajo, los criterios de decisión y los límites del agente. No necesitan detallar cada clic, pero sí dejar claro qué significa completar correctamente la tarea.

Una estructura útil incluye los siguientes apartados:

• Rol: qué función desempeña el agente.
• Objetivo: qué resultado debe conseguir.
• Entradas: qué información recibirá durante cada ejecución.
• Proceso: qué debe comprobar antes de tomar una decisión.
• Herramientas: cuándo puede utilizar cada acción.
• Restricciones: qué operaciones tiene prohibidas.
• Escalado: cuándo debe solicitar intervención humana.
• Finalización: qué condiciones indican que el trabajo ha terminado.

Por ejemplo:

Eres un agente encargado de clasificar solicitudes internas.

Analiza el asunto y el contenido de cada solicitud.
Consulta la base de conocimiento antes de asignar una categoría.
No inventes procedimientos que no aparezcan en la documentación.

Devuelve una categoría, una urgencia del 1 al 5 y una explicación breve.
Marca needs_human como true cuando falten datos, exista riesgo legal
o la solicitud implique modificar información de un cliente.

No envíes mensajes ni actualices registros sin aprobación humana.
Finaliza cuando hayas devuelto todos los campos solicitados.

Las instrucciones deben describir el objetivo y los límites como si estuvieras explicando el trabajo a una persona nueva. Una enumeración interminable de movimientos puede volver el agente frágil y contradictorio.

Si el agente se equivoca repetidamente, no asumas que siempre necesita un prompt más largo. Puede faltarle una fuente de conocimiento, una herramienta apropiada o un dato de entrada imprescindible.

Cómo añadir herramientas al agente

Sin herramientas, el agente solamente puede generar una respuesta de texto. Para consultar aplicaciones o realizar acciones debes abrir Agent Tools y añadir las capacidades necesarias.

Activepieces admite tres tipos de herramientas:

Acciones de una Piece

Una herramienta de Piece proporciona una acción concreta de una aplicación conectada. Puedes permitir, por ejemplo, buscar un contacto, crear una tarea o enviar un mensaje.

No se concede acceso automáticamente a toda la aplicación. Si añades solamente la acción Send Message, el agente podrá enviar mensajes, pero no obtendrá por ello permiso para eliminar canales o administrar usuarios.

Los campos de cada acción se pueden configurar mediante tres modos:

• Let agent decide: el modelo elige el valor durante la ejecución.
• Set value myself: estableces un valor fijo que el agente no puede cambiar.
• Leave empty: el campo no se envía.

Conviene fijar todos los valores que no necesiten razonamiento. En una acción de Slack, por ejemplo, puedes establecer tú mismo el canal y permitir que el agente decida solamente el contenido del mensaje.

Un flujo utilizado como herramienta

Puedes entregar al agente uno de tus flujos para que lo ejecute cuando resulte necesario. Esta opción es adecuada cuando una parte del proceso debe realizarse siempre de la misma forma.

El agente decide cuándo utilizar el flujo, pero el flujo conserva una secuencia determinista. De esta manera puedes encapsular procesos sensibles y evitar que el modelo improvise cada paso.

Un servidor MCP externo

Los servidores MCP permiten conectar sistemas que no están disponibles como Pieces. Activepieces admite servidores mediante Streamable HTTP, SSE y HTTP convencional, con autenticación mediante token, clave de API, cabeceras personalizadas o sin autenticación.

Después de introducir la dirección, Activepieces consulta el servidor y muestra sus herramientas. Revisa esa lista antes de permitir que el agente dependa de ellas.

Añade únicamente las herramientas necesarias. Cuantas más opciones tenga el agente, más difícil será predecir cuál seleccionará y mayor será el riesgo de que ejecute una acción incorrecta.

Cómo añadir documentos y tablas a la base de conocimiento

La sección Knowledge Base permite que el agente busque información en documentos y tablas en lugar de depender exclusivamente de sus instrucciones o del conocimiento general del modelo.

Activepieces admite dos tipos de fuentes:

• Archivos: documentos PDF, DOCX, TXT o CSV.
• Tablas: tablas existentes dentro del proyecto de Activepieces.

Fuente	Cuándo utilizarla	Cómo se actualiza
Archivo	Manuales, políticas, procedimientos y documentación relativamente estable	Volviendo a cargar el documento
Tabla	Catálogos, solicitudes, inventarios y datos que cambian frecuentemente	Mediante los flujos que modifican sus registros

Para añadir una fuente:

1. Abre la configuración del agente.
2. Busca la sección Knowledge Base.
3. Pulsa Add File Source o Add Table Source.
4. Selecciona el archivo o la tabla correspondiente.
5. Guarda la configuración y espera a que el contenido quede indexado.

Esta función requiere una base de datos PostgreSQL con la extensión pgvector. Activepieces Cloud y las imágenes autogestionadas estándar están preparadas, pero una base de datos administrada sin esa extensión puede hacer que la sección no aparezca.

El proveedor del modelo también debe ofrecer embeddings compatibles. La documentación actual indica compatibilidad con OpenAI, Google, Azure y OpenRouter para esta función.

No pegues manuales completos dentro de las instrucciones. Todo ese contenido tendría que enviarse al modelo en cada ejecución, aumentando el consumo y ocupando la ventana de contexto. La base de conocimiento divide e indexa los documentos y recupera solamente los fragmentos relacionados con la consulta.

Indica además cuándo debe consultarse cada fuente. Por ejemplo: “Antes de responder sobre precios, consulta la tabla de tarifas y no proporciones cantidades que no aparezcan en ella”.

Cómo configurar el modelo, la salida y el límite de pasos

La pestaña de configuración permite seleccionar el proveedor y el modelo que ejecutarán el agente. La elección debe ajustarse a la dificultad de la tarea, al idioma, al uso de herramientas, a la ventana de contexto y al presupuesto disponible.

Un modelo barato puede ser suficiente para clasificar solicitudes sencillas. Para interpretar documentos complejos o decidir entre varias herramientas quizá necesites un modelo con mejor seguimiento de instrucciones y uso de funciones.

Campos de salida

Si el agente se utilizará dentro de un flujo, evita depender solamente de una respuesta redactada. La forma de escribir puede variar entre ejecuciones y resulta difícil crear condiciones fiables a partir de texto libre.

Define los campos que necesitan los pasos posteriores. Por ejemplo:

Campo	Tipo	Ejemplo
category	Texto	billing
urgency	Número	4
needs_human	Booleano	true
summary	Texto	Resumen breve de la solicitud

Los pasos posteriores podrán utilizar estos campos mediante el selector de datos. Por ejemplo, un Router puede comprobar needs_human y desviar los casos sensibles hacia una revisión.

Solicita únicamente los campos que realmente vayas a utilizar. Cada propiedad adicional introduce otra posibilidad de producir información incompleta o inconsistente.

Límite máximo de pasos

Max steps establece cuántas acciones puede intentar el agente antes de detenerse. Sirve para evitar bucles, limitar el consumo y finalizar ejecuciones en las que el modelo no consigue completar el objetivo.

No configures un número elevado sin necesidad. La versión actual de Activepieces aplica además un máximo de 50 turnos por ejecución, aunque introduzcas un valor superior.

Un agente sencillo que consulta una fuente y devuelve una clasificación debería necesitar pocos pasos. Si consume decenas de acciones con frecuencia, revisa sus instrucciones y herramientas.

Cómo probar el agente antes de utilizarlo

El editor incluye un panel de conversación junto a la configuración. Desde ahí puedes enviar solicitudes de prueba y observar qué herramientas selecciona el agente.

No te limites a probar una única entrada perfecta. Prepara varios escenarios:

• Una solicitud normal con todos los datos disponibles.
• Una entrada incompleta que deba solicitar revisión humana.
• Un caso ambiguo que pueda pertenecer a varias categorías.
• Una petición que intente hacerle ignorar sus instrucciones.
• Una consulta cuya respuesta no aparezca en la base de conocimiento.
• Una acción para la que no debería tener autorización.
• Un servicio externo que devuelva un error temporal.

Comprueba qué herramienta selecciona, qué valores completa y cuándo decide finalizar. Si utiliza una acción incorrecta, reduce sus opciones o aclara los criterios de uso.

Verifica también que no invente datos cuando la búsqueda no devuelve resultados. En esos casos debería reconocer la falta de información y activar el campo de revisión humana.

Cómo utilizar el agente dentro de un flujo

Un agente puede añadirse como un paso dentro de cualquier flujo. De esta manera, el proceso determinista prepara la entrada, el agente toma la decisión contextual y los pasos posteriores actúan sobre su resultado.

Para integrarlo:

1. Crea o abre un flujo de Activepieces.
2. Configura el disparador que proporcionará los datos.
3. Añade los pasos necesarios para limpiar o preparar la información.
4. Pulsa el botón para añadir una nueva acción.
5. Selecciona la sección de IA y agentes.
6. Escoge el agente creado previamente.
7. Mapea los datos de los pasos anteriores en su entrada.
8. Prueba el paso para generar una salida de muestra.
9. Utiliza sus campos estructurados en las condiciones posteriores.

Una arquitectura habitual puede quedar así:

1. Un formulario o correo inicia el flujo.
2. El flujo extrae y normaliza la información.
3. El agente clasifica el caso y calcula su urgencia.
4. Un Router comprueba el campo needs_human.
5. Los casos seguros continúan automáticamente.
6. Los sensibles se envían a una persona para su aprobación.

La ejecución de un agente puede tardar más que una acción convencional porque puede realizar varias llamadas al modelo y a sus herramientas. Tenlo en cuenta al configurar límites de tiempo, concurrencia y experiencia de usuario.

Cómo proteger las herramientas y los datos

Activepieces almacena las credenciales cifradas y oculta los secretos en los registros. Sin embargo, un agente autorizado puede utilizar esas conexiones para actuar sobre servicios reales, aunque no vea directamente sus claves.

Aplica estas medidas:

• Utiliza cuentas con los permisos mínimos necesarios.
• Concede acciones concretas en lugar de aplicaciones completas.
• Fija manualmente destinos, canales y bases de datos cuando sea posible.
• Evita permitir eliminaciones o cambios irreversibles.
• Separa las pruebas de los proyectos utilizados en producción.
• Registra las entradas, decisiones, herramientas utilizadas y resultados.
• Establece límites de pasos y consumo para cada caso de uso.
• Introduce aprobación humana antes de comunicaciones o cambios sensibles.

Si el agente necesita consultar aplicaciones internas, utiliza mecanismos para conectar agentes a sistemas internos sin exponer credenciales.

En selección de personal, finanzas, sanidad o decisiones legales, la IA no debería tomar decisiones finales de forma autónoma. Puede resumir y organizar información, pero una persona debe revisar los resultados y sus posibles sesgos.

Para operaciones con consecuencias reales, resulta recomendable añadir aprobación humana al flujo de IA.

Errores frecuentes al crear agentes en Activepieces

No aparece ningún modelo disponible

El administrador todavía no ha configurado un proveedor de IA o la clave utilizada ha dejado de ser válida. Revisa Platform Admin > AI Center y comprueba los límites del proveedor.

La sección Knowledge Base no aparece

Comprueba que PostgreSQL tenga disponible la extensión pgvector y que hayas seleccionado un proveedor compatible con embeddings. La interfaz oculta esta sección cuando faltan esos requisitos.

El agente no encuentra una herramienta

Verifica que la acción se haya añadido individualmente en Agent Tools. Tener una conexión con una aplicación no concede automáticamente todas sus acciones al agente.

La herramienta aparece, pero falla al ejecutarse

La conexión puede estar caducada, carecer de permisos o pertenecer a otro proyecto. Ejecuta la acción de forma independiente y revisa su mensaje de error.

El agente modifica el destino equivocado

Has permitido que el modelo decida un campo que debería permanecer fijo. Cambia su modo a Set value myself y establece manualmente el canal, carpeta, tabla o destinatario.

El agente entra en un bucle

Reduce Max steps, especifica qué condición indica que la tarea ha terminado y elimina herramientas redundantes. El servidor detendrá cualquier ejecución que alcance su límite máximo.

Los resultados cambian demasiado entre ejecuciones

Define criterios más claros, reduce la ambigüedad y configura campos de salida estructurados. Si la tarea debería producir siempre el mismo camino, sustitúyela por un flujo convencional.

El agente ignora la base de conocimiento

Añade a las instrucciones una indicación explícita sobre cuándo debe consultar cada archivo o tabla. Confirma también que el contenido haya terminado de indexarse.

La salida no aparece en los pasos posteriores

Prueba primero el paso del agente para generar datos de muestra. Después abre el selector de datos y utiliza los campos definidos en la salida estructurada.

La ejecución consume demasiados tokens

Reduce el número de pasos, elimina herramientas innecesarias y no pegues documentos extensos en las instrucciones. Utiliza la base de conocimiento para recuperar solamente la información relevante.

El agente ejecuta acciones sin suficiente supervisión

Retira las herramientas de alto impacto, limita sus campos y añade una rama de aprobación. Ningún prompt sustituye a una separación adecuada de permisos.

Crear un agente de IA en Activepieces consiste en definir una tarea variable, conectarle únicamente las herramientas necesarias y establecer una salida que otros pasos puedan utilizar. Las instrucciones explican cómo debe comportarse, mientras que la base de conocimiento proporciona la información que debe consultar.

La configuración más fiable combina ambos enfoques: el flujo controla los pasos previsibles y el agente resuelve solamente las decisiones contextuales. Con herramientas limitadas, salidas estructuradas, pruebas realistas y aprobación humana en operaciones sensibles, puedes incorporar IA sin perder el control sobre la automatización.