CrewAI: guía de agentes, tareas, flows y despliegue

CrewAI es un framework que permite asignar tareas a agentes especializados, reunirlos en equipos y organizar su trabajo mediante flows. Usted define las responsabilidades, las herramientas disponibles, los resultados esperados y las transiciones del programa; la fiabilidad depende después de los modelos, los controles y los permisos elegidos.

Entender los componentes antes de crear un equipo

En CrewAI, un agente combina un rol, un objetivo, unas instrucciones y un modelo de lenguaje. Una tarea describe el trabajo solicitado y el resultado que debe entregar. Una crew reúne los agentes y las tareas conforme a un proceso de ejecución.

El flow actúa en otro nivel: organiza las etapas de la aplicación. Puede incluir una validación de datos, la ejecución de una crew, una comprobación en Python y una solicitud de aprobación. Esta separación ayuda a distinguir las decisiones que se dejan al modelo de las reglas que impone el software.

Componente	Responsabilidad	Ejemplo de diseño
Agente	Realizar un trabajo con un rol y unas herramientas	Extraer los hechos presentes en un expediente
Tarea	Definir una petición y su resultado esperado	Elaborar una lista de hechos con sus fuentes
Crew	Organizar el trabajo de los agentes	Encadenar la extracción y la redacción
Flow	Dirigir las etapas y el estado del programa	Validar el expediente antes de iniciar el equipo
Herramienta	Dar acceso a una función externa	Leer un documento autorizado

Estos componentes no equivalen a colaboradores humanos. Asignar a un agente el rol de revisor no demuestra que vaya a detectar los errores del redactor. Ambos pueden compartir las mismas limitaciones o aceptar una afirmación sin pruebas.

Empiece por concretar qué justifica utilizar varios agentes. Si una extracción seguida de una comprobación programada cubre la necesidad, añadir un equipo puede limitarse a multiplicar los intercambios. La guía de sistemas multiagente desarrolla esta decisión de arquitectura.

Definir roles y tareas que se puedan verificar

Los principales campos de un agente incluyen role, goal, backstory, llm y tools. Ajustes como allow_delegation, max_iter y max_execution_time delimitan su comportamiento. La documentación de agentes, consultada el 24 de octubre de 2026, explica su alcance.

Utilice el rol para concretar una responsabilidad, el objetivo para definir cuándo se considera logrado el trabajo y las instrucciones para fijar los límites. Evite las biografías ficticias que pretenden dar autoridad al modelo. Es preferible una instrucción operativa: extraer únicamente la información presente, conservar su procedencia e indicar qué datos faltan.

Una tarea debe describir sus datos de entrada, el trabajo que debe realizar y su salida. CrewAI utiliza, entre otros, description y expected_output; el campo context permite señalar los resultados de tareas anteriores. La documentación de tareas también explica las salidas estructuradas y los mecanismos de control.

Para un expediente documental, puede solicitar una lista de afirmaciones acompañadas de sus referencias y, después, una síntesis basada en esa lista. Especifique que la ausencia de una fuente debe quedar visible. Una instrucción general sobre la calidad no basta para definir un resultado verificable.

Separe las comprobaciones de formato de las comprobaciones de contenido. Su código puede verificar que exista un campo o que un identificador sea válido. Comprobar que una afirmación se corresponde con el documento exige compararla con la fuente. Una salida estructurada facilita los intercambios entre etapas, pero no garantiza la veracidad del contenido.

Elegir el proceso de ejecución

CrewAI documenta un proceso secuencial y otro jerárquico. El primero sigue el orden de las tareas; el segundo deja la organización en manos de un coordinador, configurado mediante manager_llm o manager_agent. Estos mecanismos se detallan en la documentación de procesos.

Criterio	Secuencial	Jerárquico
Organización	Orden definido en la configuración	Asignación dirigida por un coordinador
Responsabilidades	Asignaciones explícitas	Distribución según las capacidades de los agentes
Diagnóstico	Revisar cada etapa por orden	Revisar también las decisiones de coordinación
Uso que conviene considerar	Cadena de procesamiento conocida	Distribución que varía según el expediente

Para empezar, elija el proceso secuencial. Le resultará más fácil identificar la tarea que pierde información o produce una respuesta inutilizable. Introduzca un coordinador solo si la asignación dinámica resuelve una dificultad que haya observado.

La delegación requiere la misma prudencia. Puede ser útil cuando un agente necesita la aportación de un especialista, pero cada intercambio añade contexto y trabajo que revisar. Defina las responsabilidades y las condiciones de parada antes de activarla.

La elección del framework viene después de la arquitectura. La comparativa de CrewAI y LangGraph ayuda a examinar sus diferencias; el artículo sobre frameworks de agentes de IA sitúa estos enfoques en un panorama más amplio.

Preparar el entorno y el primer ejercicio

La documentación de instalación consultada el 24 de octubre de 2026 requiere Python a partir de 3.10 y anterior a 3.14. Utiliza uv para instalar la CLI y gestionar el proyecto. Estos requisitos y los comandos que aparecen a continuación proceden de la guía oficial de instalación.

Prepare también el acceso al proveedor del modelo elegido y las credenciales de los servicios externos que vaya a utilizar. Compruebe sus condiciones de uso, sus límites y el destino de los datos. Debe elegir al proveedor antes de enviar documentos confidenciales.

Para el primer ejercicio, utilice un expediente breve que no contenga información sensible. El objetivo propuesto es convertir una nota en una síntesis con referencias, sin navegación web, sin mensajería y sin escribir en aplicaciones de gestión. Este alcance permite examinar el trabajo de los agentes sin depender desde el principio de varias integraciones.

Defina el resultado esperado antes de instalar: una síntesis fiel, las referencias al expediente y una lista de la información ausente. Conserve también una respuesta de referencia redactada manualmente para comparar las omisiones y los añadidos.

Por último, distinga la CLI instalada de forma global de la biblioteca que utiliza el proyecto. Actualizar la primera no actualiza automáticamente la segunda. Conserve los archivos de dependencias del proyecto para poder reconstruir el entorno que produjo un resultado.

Instalar y configurar la primera crew

1. Comprobar Python e instalar la CLI

Compruebe su intérprete:

python3 --version

Si no tiene uv, la documentación propone esta instalación para macOS y Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Para Windows, indica:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

A continuación, instale la CLI y compruebe que esté disponible:

uv tool install crewai
uv tool list

Si la instalación señala un problema con el PATH, el comando documentado es:

uv tool update-shell

2. Generar el proyecto

La sintaxis oficial para crear el proyecto es:

crewai create crew <your_project_name>

Sustituya el nombre entre los signos de menor y mayor por el de su proyecto. Después, abra la carpeta generada en su editor.

La documentación actual da preferencia a JSONC: los agentes se definen en agents/ y el equipo en crew.jsonc. Los tutoriales que utilizan crew.py, config/agents.yaml y config/tasks.yaml corresponden al modo clásico, que sigue siendo compatible mediante la opción --classic.

3. Adaptar los archivos generados

Para el ejercicio, defina un agente de extracción y otro de síntesis. El primero debe recoger los hechos y sus referencias; el segundo debe redactar únicamente a partir de esa recopilación. Empiece sin delegación.

En crew.jsonc, sitúe la extracción antes de la redacción e indique de forma explícita la dependencia entre ambas. Mantenga la coherencia de los identificadores entre archivos. Complete las variables de entrada necesarias y la configuración del modelo elegido.

Guarde las claves en .env y compruebe que el archivo esté excluido del repositorio. Una clave no debe aparecer en las instrucciones de los agentes ni en un ejemplo compartido.

4. Instalar las dependencias y ejecutar

Desde la raíz del proyecto:

crewai install
crewai run

Examine el resultado entregado y las etapas intermedias. El primer objetivo es lograr una ejecución que pueda entenderse: entradas conocidas, tareas identificables, salida conservada y errores visibles. Una respuesta bien redactada no basta para validar el equipo.

Conectar herramientas con permisos limitados

Una herramienta convierte una decisión del modelo en una llamada a una función de software. Su descripción debe especificar qué hace, qué argumentos acepta y qué devuelve. La documentación de herramientas de CrewAI presenta las herramientas disponibles y su uso con los agentes.

Añada las herramientas de forma gradual. Empiece con una lectura limitada a un directorio e incorpore después las búsquedas o los servicios de gestión necesarios. Cada conexión adicional introduce otra posible causa de error: autenticación, datos desactualizados, falta de disponibilidad o resultados demasiado voluminosos.

Si crea una herramienta propia, valide los argumentos en el código. Una instrucción que pida respetar un ámbito de acceso no sustituye la comprobación efectiva de la ruta, la cuenta o la operación autorizada. Devuelva errores que permitan actuar, en lugar de un resultado ambiguo que el agente pueda interpretar como un éxito.

La llamada a herramientas también debe tener un contrato de salida: distinga entre un resultado vacío, un acceso denegado y un fallo del servicio. Cada situación requiere una respuesta diferente.

Si opta por una conexión MCP, examine las herramientas expuestas y los permisos del servidor antes de integrarla. Compartir un protocolo no supone disponer de una autorización general de acceso.

Reserve las acciones sensibles para una etapa controlada. Si se va a enviar un mensaje, muestre el destinatario y el contenido exactos para su aprobación. Si se va a escribir en una aplicación de gestión, compruebe el estado actual e impida los duplicados. Una aprobación que solo se refiera al objetivo sigue siendo demasiado imprecisa.

Utilizar flows para controlar la aplicación

Los flows disponen de un estado y de métodos conectados mediante eventos. @start() define un punto de entrada, @listen() una reacción a una etapa y @router() una bifurcación condicional. La persistencia está disponible con @persist, según la documentación de flows.

El siguiente ejemplo didáctico está adaptado de estos mecanismos. Muestra la separación entre preparación y comprobación, sin llamar a ningún modelo:

from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel


class EtatDossier(BaseModel):
    texte: str = ""
    statut: str = "nouveau"


class DossierFlow(Flow[EtatDossier]):
    @start()
    def preparer(self):
        self.state.texte = "Document de démonstration"
        self.state.statut = "prepare"
        return self.state.texte

    @listen(preparer)
    def verifier(self, texte):
        if not texte.strip():
            raise ValueError("Document vide")
        self.state.statut = "verifie"
        return self.state.statut


resultat = DossierFlow().kickoff()
print(resultat)

En una aplicación, podría insertar la crew después de validar el documento y comprobar su salida antes de transmitirla. Mantenga en el código las reglas que puedan verificarse de forma determinista: la presencia de una entrada, el formato de un identificador, el derecho de acceso o el destino autorizado.

Defina también un estado de negocio explícito: expediente recibido, análisis terminado, validación pendiente, publicación realizada. Evite almacenar únicamente un historial de texto que resulte difícil de interpretar al reanudar el proceso.

La persistencia debe probarse junto con sus efectos externos. Restaurar el estado de un flow no basta para impedir que se repita un envío o una escritura. Prevea un identificador de operación y compruebe si la acción ya se completó antes de volver a ejecutarla.

Gestionar el contexto, los conocimientos y la memoria

El contexto útil para una tarea no tiene por qué incluir todo el historial disponible. Transmita los elementos necesarios para su trabajo junto con su procedencia. Una síntesis demasiado comprimida puede eliminar una salvedad; un expediente completo puede ocultar los pasajes decisivos entre información menos relevante.

Separe tres categorías en el diseño: los datos de la solicitud, los documentos de referencia y la información conservada entre ejecuciones. No tienen el mismo periodo de utilidad ni las mismas reglas de acceso.

Para una síntesis documental, conserve la correspondencia entre cada afirmación y el pasaje del que procede. Si un agente intermedio reformula los hechos, transmita también las referencias: el redactor debe poder localizar las pruebas.

Active una memoria persistente solo después de identificar qué debe conservar y para qué. Defina un plazo de conservación, un procedimiento de eliminación y una separación entre usuarios. Una preferencia útil en un expediente puede convertirse en una instrucción inadecuada en otro.

La inyección de prompts también afecta a los documentos consultados. Un texto externo puede pedir que se cambien las reglas o que se utilice una herramienta. Trátelo como un dato que debe analizarse y mantenga las autorizaciones en la aplicación. La guía Proteger un agente de IA detalla estas medidas.

Medir la calidad y el coste por expediente

Evalúe el proceso completo con expedientes representativos: documentos incompletos, contradicciones, fuentes ausentes y herramientas no disponibles. Incluya casos en los que la respuesta correcta sea pedir una aclaración o rechazar una acción.

Mida por separado la fidelidad a las fuentes, las omisiones, el cumplimiento del formato y el éxito de las operaciones. Un resultado puede ser correcto en cuanto al contenido y, aun así, resultar inutilizable para el siguiente programa. También puede respetar perfectamente el formato y contener una afirmación falsa.

Compare el equipo con una solución más sencilla utilizando las mismas entradas. Mantenga varios agentes si su aportación mejora los resultados observados o facilita un control necesario. Una distribución de funciones atractiva sobre el papel no constituye una medición.

Para calcular el presupuesto, sume las llamadas a modelos, los servicios externos, el alojamiento y el tiempo de revisión. Relacione ese gasto con los expedientes aceptados e incluya los fallos y las reanudaciones. La calculadora de precios de modelos ayuda a estimar la parte correspondiente a los tokens.

Establezca límites de iteraciones, duración y reintentos. Conserve un registro de los cambios de configuración y de sus resultados. Modifique un solo elemento cada vez cuando busque el origen de un empeoramiento.

Desplegar y supervisar el proceso

Puede ejecutar la aplicación en su propia infraestructura o valorar CrewAI AMP. Esta plataforma ofrece, entre otras funciones, despliegue gestionado, acceso API y trazas de ejecución, según la presentación oficial de CrewAI AMP.

Criterio	Infraestructura gestionada por su equipo	CrewAI AMP
Entorno	Usted prepara y mantiene el entorno de ejecución	Infraestructura gestionada por la plataforma
Integración	Usted construye el servicio de acceso	Acceso API disponible
Supervisión	Usted organiza los registros y las alertas	Trazas y registros integrados
Presupuesto	Hay que estimar el alojamiento y la operación	Hay que consultar las condiciones de la oferta

Antes de cualquier despliegue, reproduzca el entorno local, separe los secretos y defina quién se encargará de los incidentes. Una aplicación desplegada debe poder rechazar una solicitud, detenerse de forma controlada y conservar información suficiente para explicar un fallo.

Para AMP, la guía oficial de despliegue documenta esta secuencia desde el proyecto preparado:

crewai login
crewai deploy create
crewai deploy status
crewai deploy logs

Durante la creación se detectan, entre otros elementos, la información del repositorio y las variables del archivo .env destinadas a la plataforma. Por tanto, revise su contenido y su destino antes de realizar esta operación.

Una vez en funcionamiento, supervise los errores, la duración, las reanudaciones y el coste por proceso. Proteja los registros: pueden contener documentos o resultados sensibles. Por último, pruebe la vuelta a una configuración anterior. Nuestro directorio de agentes y frameworks permite seguir comparando soluciones.

Problemas frecuentes

No se encuentra el comando. Compruebe que la CLI aparezca en la lista de herramientas de uv y aplique después la corrección del PATH indicada en la instalación. Vuelva a abrir la terminal antes de continuar.

Los archivos no coinciden con el tutorial. Identifique el formato del proyecto: JSONC o el clásico Python/YAML. Utilice la documentación correspondiente y evite mezclar las estructuras durante el primer ejercicio.

No se encuentra un agente o una tarea. Compare los identificadores declarados en crew.jsonc y en los archivos de agentes. Compruebe también que las dependencias de contexto hagan referencia a tareas anteriores.

El modelo responde, pero las herramientas fallan. Pruebe por separado la autenticación del servicio, los argumentos y el formato devuelto. Una respuesta de texto correcta no valida toda la integración.

La síntesis inventa información. Examine primero la recopilación de hechos que recibe el redactor. Si el error ya aparece en esa etapa, refuerce la comparación con los documentos y permita expresamente que se señale la información ausente.

Al reanudar se repite una acción. Compruebe la distinción entre el estado guardado y la operación externa completada. Añada una protección contra duplicados antes de volver a activar el proceso.

Lista de comprobación antes de la puesta en servicio

Páginas relacionadas

Preguntas frecuentes

¿Hay que saber programar para utilizar CrewAI?

La configuración JSONC permite describir un equipo sin escribir toda su orquestación en Python. Aun así, debe comprender las dependencias, las claves API y los errores de ejecución. Crear herramientas específicas y mantener la aplicación en funcionamiento por cuenta propia requiere conocimientos de desarrollo.

¿CrewAI funciona con un modelo local?

Depende del proveedor, de su interfaz y de las capacidades del modelo elegido. Compruebe la compatibilidad en la documentación de la versión instalada y pruebe después las llamadas a herramientas y las salidas esperadas. Un modelo capaz de conversar puede fallar dentro de un ciclo de ejecución de un agente.

¿Qué diferencia hay entre una crew y un flow?

Una crew reúne agentes que trabajan en tareas comunes. Un flow describe la ejecución del programa, con su estado y sus transiciones. Una aplicación puede utilizar un flow para coordinar varias crews.

¿CrewAI es gratuito?

El framework se distribuye con licencia MIT según la revisión del sitio de octubre de 2026. Sin embargo, su uso puede generar gastos de modelos, herramientas externas y alojamiento. La plataforma CrewAI AMP es una oferta independiente cuyas condiciones debe consultar.

¿Se puede reanudar un proceso de CrewAI tras una interrupción?

Los flows disponen de mecanismos para conservar su estado. También debe prever qué ocurrirá con las herramientas ya ejecutadas: restaurar un estado no garantiza que una escritura en un sistema externo no se repita. Pruebe las interrupciones antes de pasar a producción.

CrewAI, guía de referencia: equipos de agentes, tareas, herramientas, flows y despliegue