Cómo construir un sistema multiagente con CrewAI en 2026
TL;DR
Un sistema útil de CrewAI comienza con los límites de las tareas, no con las personalidades de los agentes. Da a cada agente entradas, herramientas, resultados esperados y condiciones de fallo distintas.
Usa un Crew para colaboración abierta y un Flow para control de aplicación determinista. La mayoría de los sistemas de producción necesitan un Flow alrededor de uno o más pequeños Crews.
El patrón de trabajo mínimo es Agente → Tarea → Crew → inicio. Comienza con una ejecución secuencial para que las salidas y fallos sean fáciles de inspeccionar.
No le des a cada agente todas las herramientas. El acceso a herramientas con el menor privilegio reduce el costo, la exposición a inyecciones de mensajes y los efectos secundarios difíciles de depurar.
Agrega salidas estructuradas, barreras de seguridad, rastros y aprobación humana antes de escalar el equipo. Más agentes aumentan la sobrecarga de coordinación y no garantizan una mejor respuesta.
Para crews de investigación web, separa la adquisición de datos del razonamiento. Nstproxy Crawl puede preparar contenido de sitios delimitados mientras los agentes de CrewAI lo analizan e informan sobre él.
¿Qué estás construyendo con CrewAI?
Un sistema multi-agente CrewAI es un conjunto de agentes con roles asignados a tareas bajo un proceso definido. El Crew coordina esos agentes y tareas; un Flow puede envolver al crew cuando la aplicación circundante necesita un estado explícito, ramificación, persistencia o recuperación. Si los agentes necesitan evidencia de sitios web aprobada, Nstproxy Crawl puede proporcionar la capa de adquisición en lugar de permitir que cada agente navegue sin límites.
La guía de conceptos de CrewAI distingue entre Crews autónomos y Flows impulsados por eventos. Esto es importante porque muchos tutoriales modelan un proceso empresarial fijo como una conversación entre agentes. En la práctica, el código determinista debería decidir cuándo comienza un trabajo, qué estado es válido y si se requiere una aprobación; los agentes deberían manejar las partes que realmente necesitan interpretación.
Este tutorial construye un pequeño crew de investigación secuencial con dos agentes:
Un investigador convierte el material fuente proporcionado en un informe de evidencia.
Un editor convierte ese informe en un memorando de decisión y debe preservar las incertidumbres.
El ejemplo evita deliberadamente herramientas de navegación en vivo. Una herramienta web se puede agregar más tarde, después de que su política de dominio, contrato de salida y comportamiento de error se hayan probado.
Por qué el diseño de tareas importa más que el número de agentes
Un agente debería existir solo cuando tiene una responsabilidad, contexto o límite de herramienta diferente. Dividir "investigación", "análisis" y "escritura" en tres agentes es útil si cada uno produce un artefacto inspectable. Es un desperdicio si los tres reciben el mismo gran mensaje y repiten la misma búsqueda.
Antes de escribir código, define este contrato:
Componente
Investigador
Editor
Entrada
Tema y paquete de fuentes aprobadas
Informe de evidencia del investigador
Herramientas permitidas
Recuperación solo sobre datos aprobados
Sin herramienta de recuperación en el ejemplo mínimo
Salida
Afirmaciones, evidencia de apoyo, conflictos, incertidumbres
Memorando conciso con afirmaciones citadas y preguntas abiertas
Condición de fallo
Falta de apoyo o fuente inaccesible
Afirmación no soportada o incertidumbre oculta
Puerta humana
Política de fuente
Publicación final o acción empresarial
Este diseño se asemeja a un arnés de agente confiable: los roles son menos importantes que los permisos, el estado, los rastros y las comprobaciones de aceptación.
Requisitos previos y creación del proyecto
Usa una versión de Python compatible con CrewAI, unas credenciales de proveedor de modelos almacenadas fuera del control de fuente y la ruta de instalación actual basada en uv. La página de documentación de CrewAI enlaza a las páginas de instalación y inicio rápido mantenidas; sigue esas páginas para el rango de compatibilidad actual de Python y comando de CLI en lugar de confiar en un tutorial antiguo de pip.
Después de la instalación, esboza un proyecto con la CLI de CrewAI e inspecciona la estructura generada. Un proyecto estándar separa la configuración YAML para agentes y tareas del código de ensamblaje en Python. Mantén secretos en variables de entorno o en un administrador de secretos aprobado, nunca en YAML comprometido en Git.
El diseño generado es útil porque hace que los cambios en los mensajes sean revisables:
La implementación más pequeña e instructiva mantiene definiciones en un solo archivo. Hace que el flujo de datos sea visible antes de que un equipo introduzca decoradores, YAML, herramientas personalizadas o Flows.
Paso 1: definir dos agentes
Crea crew_demo.py con el siguiente código. El nombre del modelo se pasa a través de una variable de entorno para que el ejemplo no congele un identificador que puede ser retirado.
import os
from crewai import Agent, Crew, Process, Task
model_name = os.environ["CREWAI_MODEL"]researcher = Agent( role="Investigador de evidencia",```python
goal="Construir un resumen de evidencia rastreable para el tema solicitado", backstory="Se separan afirmaciones respaldadas, conflictos y desconocidos.", llm=model_name, allow_delegation=False, verbose=True,)editor = Agent( role="Editor de memorándum de decisiones", goal="Convertir un resumen de evidencia en una recomendación concisa y calificada", backstory="Se preservan las citas y nunca se oculta la incertidumbre.", llm=model_name, allow_delegation=False, verbose=True,)
role, goal y backstory influyen en el comportamiento, pero los controles importantes son el modelo, las herramientas disponibles y la configuración de delegación. Comience con la delegación deshabilitada. La delegación no restringida de agente a agente hace que el uso de tokens y la terminación sean más difíciles de predecir.
Paso 2: definir salidas antes de las instrucciones
Agregue dos tareas. La segunda tarea se refiere a la primera a través de context, lo que hace que la dependencia sea explícita.
research_task = Task( description=("Investigar {topic} utilizando solo el paquete fuente suministrado en {source_path}. ""Enumere las afirmaciones respaldadas, citas, contradicciones y desconocidos."), expected_output=("Un resumen de evidencia en Markdown con secciones para afirmaciones, fuentes, ""conflictos y preguntas sin respuesta."), agent=researcher,)memo_task = Task( description=("Crear un memorándum de decisión a partir del resumen de evidencia. Preserve las ""referencias de la fuente, califique la incertidumbre y recomiende una próxima prueba."), expected_output=("Un memorándum en Markdown que contenga una recomendación, evidencia, riesgos, ""desconocidos y la próxima acción."), agent=editor, context=[research_task],)
Una expected_output es un objetivo de aceptación, no una garantía. El código de producción debe validar secciones requeridas o utilizar un resultado estructurado de Pydantic donde la tarea lo soporte.
Paso 3: ensamblar y ejecutar la tripulación
Agregue la tripulación y la llamada de inicio:
crew = Crew( agents=[researcher, editor], tasks=[research_task, memo_task], process=Process.sequential, verbose=True,)result = crew.kickoff( inputs={"topic":"Si adoptar un nuevo modelo de recuperación","source_path":"data/approved-sources.md",})print(result.raw)
Ejecute esto solo después de establecer el selector de modelo y las credenciales requeridas por ese proveedor. El código de este artículo fue verificado sintácticamente, pero un inicio en vivo requiere un entorno Python compatible, el paquete CrewAI, una cuenta de proveedor y un paquete fuente real. Esos requisitos externos no pueden ser validados por un artículo estático.
Método 2: mover una tripulación estable a YAML y anotaciones
Una vez que el prototipo funcione, mueva las descripciones largas de roles y tareas a config/agents.yaml y config/tasks.yaml. Luego, ensámblelos en crew.py con @CrewBase, @agent, @task y @crew. La guía de anotaciones de CrewAI explica que las claves de configuración y los nombres de métodos decorados deben corresponder.
Esta estructura es mejor para la revisión porque los cambios de aviso no se mezclan con los cambios de orquestación. También facilita la selección de modelos específicos del entorno. Mantenga tres reglas:
Proporcione nombres estables a las claves de configuración; renombrar solo un lado rompe el mapeo.
Mantenga la construcción de herramientas en Python, donde se pueden hacer cumplir las credenciales y listas de permitidos.
Pruebe el orden final de las tareas ensambladas; el orden de declaración y las dependencias de contexto pueden producir un comportamiento diferente.
Proporciona a tu equipo una capa de evidencia controlada
Utiliza Nstproxy Crawl para preparar contenido limitado del sitio web mientras los agentes de CrewAI se enfocan en análisis, validación e informes.
Agrega datos web sin otorgar a los agentes un navegador sin restricciones
Un equipo de investigación necesita evidencia nueva, pero navegar directamente no es la única arquitectura. Un patrón más seguro es adquirir primero páginas aprobadas, almacenar la procedencia y exponer la recuperación en solo lectura al investigador. Nstproxy Crawl puede limitar la recolección por profundidad de sitio, cantidad de páginas y reglas de ruta, renderizar JavaScript y devolver salidas seleccionadas como Markdown, HTML, JSON, enlaces o PDF.
Un trabajo determinista valida los dominios objetivo contra la política.
El rastreador recoge páginas autorizadas y registra la URL más el tiempo de recuperación.
Un analizador almacena contenido limpio y metadatos en el repositorio de evidencia.
El agente de investigación recibe recuperación en solo lectura sobre ese repositorio.
El editor ve el resumen de evidencia, no instrucciones de navegación en bruto.
Este es el mismo límite utilizado en muchos proyectos de agentes de IA: las herramientas adquieren o transforman datos, mientras que el agente decide cómo utilizarlos. Revisa la guía del índice web antes de añadir embeddings para que la identidad del documento, frescura y deduplicación se definan primero.
Cuándo envolver al equipo en un Flujo
Utiliza un Flujo cuando la ejecución deba ramificarse, pausarse, reanudarse o actualizarse un estado duradero. Ejemplos incluyen enrutar memorandos de baja confianza para su revisión, reintentar un paso de adquisición fallido y detener un trabajo después de una violación de política. La documentación de Flows de CrewAI describe pasos impulsados por eventos, estado, enrutamiento y persistencia.
Un límite de producción sensato es:
Flow valida la solicitud y la política de origen.
Flow inicia el trabajo de adquisición y maneja fallos recuperables.
Un pequeño equipo analiza la evidencia recuperada.
La validación determinista verifica la salida del equipo.
Flow solicita aprobación humana antes de publicar o tomar una acción externa.
No utilices un agente para decidir si su propia salida pasó la validación. Las verificaciones estructurales, las reglas de dominio permitido, las citas requeridas y los presupuestos máximos de ejecución pertenecen al código determinista.
Prueba el sistema antes de agregar más agentes
La evaluación debe medir toda la tarea, no cuán convincente suena la transcripción. Crea un pequeño conjunto de pruebas con evidencia esperada y casos de fallo conocidos, y luego rastrea:
tasa de apoyo a la reclamación y validez de la cita;
evidencia faltante o contradictoria emergida;
validez de la salida estructurada;
llamadas a herramientas fuera del alcance previsto;
uso total del modelo y de herramientas por cada memo completado;
reintentos, tiempos de espera y razones de rechazo humano.
Prueba texto fuente adversarial que indique al agente que ignore su tarea, respuestas de herramientas mal formadas, recuperación vacía y documentos duplicados. Si la versión de dos agentes no puede superar estos casos de manera consistente, un agente gerente o un equipo más grande añadirán más rutas de fallo en lugar de resolver el defecto de diseño.
Una política de recopilación de datos automatizada también debe definir la retención, intervalos de actualización, derechos de acceso y eliminación. El acceso técnico a una página no establece por sí mismo el permiso para recopilar o reutilizarla.
Veredicto final: comienza con una transferencia explícita
Para construir un sistema multi-agente con CrewAI, comienza con dos agentes, dos salidas de tareas observables y un proceso secuencial. Mueve la validación determinista y el control del ciclo de vida a un Flow, otorga a cada agente solo las herramientas que necesita, y añade agentes solo cuando un nuevo rol crea un contexto o límite de permiso real.
El siguiente paso es ejecutar el equipo mínimo contra un pequeño paquete de evidencia aprobado, guardar su traza y escribir afirmaciones de fallo antes de conectar herramientas en vivo. Para investigaciones respaldadas por sitios web, Nstproxy Crawl puede suministrar material fuente limitado y reutilizable mientras el equipo se mantiene enfocado en el análisis.
Prepara evidencia web trazable para tu sistema CrewAI
Utiliza Nstproxy Crawl para convertir sitios autorizados en artefactos fuente controlados para recuperación, evaluación y cita en lugar de dar a cada agente acceso independiente de navegación.
CrewAI es un marco de trabajo de Python para construir agentes basados en roles, tareas, equipos y Flows impulsados por eventos. Los equipos apoyan la colaboración autónoma, mientras que los Flows proporcionan un control de aplicación más explícito.
P: ¿Cuántos agentes debería usar un primer proyecto de CrewAI?
Dos agentes suelen ser suficientes para un primer proyecto cuando tienen una transferencia significativa, como investigador a revisor. Agrega otro agente solo si necesita un contexto, herramientas, permisos o criterios de evaluación distintos.
P: ¿Debería un proceso de CrewAI ser secuencial o jerárquico?
Empieza de manera secuencial cuando el orden de la tarea es conocido porque es más fácil de rastrear y probar. Considera la coordinación jerárquica solo cuando la delegación dinámica produzca ganancias medibles que justifiquen las llamadas al modelo adicionales y los modos de fallo.
P: ¿Puede CrewAI navegar por la web?
Los agentes de CrewAI pueden usar herramientas web cuando esas herramientas están configuradas, pero el acceso debe ser limitado al dominio, de solo lectura donde sea posible y protegido contra instrucciones no confiables. Una capa de adquisición separada puede ofrecer un control más estricto.
Los productos de investigación profunda no resuelven todos la misma capa. Esta guía separa la adquisición controlada de la web de la síntesis autónoma y selecciona cinco opciones según el caso de uso de producción.
Lena Zhou
Sep. 2nd 2026
110M+ IP reales con 99.9% de acceso exitoso
Respuesta media ultrarrapida ~0.5s para tareas de alta concurrencia
Desde solo $0.1/GB
Acceso inmediato a pools premium de proxies residenciales, datacenter, IPv6 e ISP.
