Com utilitzar CrewAI: Una guia pràctica per a fluxos de treball multi-agent
Promesa audaç: Si mai has desitjat poder clonar el teu millor company d'equip per abordar un projecte més ràpidament, CrewAI t'hi apropa—orquestrant múltiples agents d'IA que planifiquen, col·laboren i lliuren el treball junts.
En aquesta guia pràctica i orientada a solucions, aprendràs exactament com utilitzar CrewAI: des d'instal·lar el marc de treball i definir agents, fins a construir rols, eines, tasques i fluxos de treball multi-agent estructurats que ofereixen resultats reals. Cobrirem patrons per a la investigació, contingut, anàlisi de dades i generació de codi—i com evitar problemes comuns com ara els carrerons sense sortida dels agents, la inflació de prompts i l'excés d'abast de les eines.
El nostre objectiu: oferir-te un camí pas a pas de "prova-ho avui" amb codi de copiar i enganxar, millors pràctiques provades en batalla i uns quants plans de flux de treball que pots adaptar. Tant si estàs automatitzant la investigació de mercat com construint una especificació de producte a partir de tiquets, aquest és el teu punt d'entrada per utilitzar CrewAI de manera efectiva.
Què és CrewAI (i per què és diferent)
- CrewAI és un marc de treball per construir sistemes multi-agent on cada agent té un rol, objectiu, eines i regles. Llavors, el marc de treball coordina aquests agents—lliurant tasques, compartint context i iterant cap a una sortida.
- A diferència d'un únic prompt d'un LLM, CrewAI imposa estructura: els agents són explícits, les tasques són modulars, les eines tenen permisos i els resultats són auditables.
- La recompensa: fluxos de treball descomposats (investigació → síntesi → escriptura → QA) que reflecteixen com treballen els equips reals—només que més ràpid, escalable i reproduïble.
Inici ràpid: Com utilitzar CrewAI en 10 minuts
A continuació, hi ha un patró mínim per portar-te de zero a un equip multi-agent en funcionament. Assumim que utilitzes Python.
1) Instal·lar i configurar
pip install crewai langchain-openai python-dotenv
Crea un fitxer .env amb les teves claus de proveïdor de LLM:
OPENAI_API_KEY=sk-your-key
# o altres proveïdors compatibles amb la teva pila
2) Defineix els teus agents (rols + objectius + eines)
from crewai import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
researcher = Agent(
role="Investigador de mercat",
goal="Trobar coneixements actuals i creïbles sobre el mercat objectiu i els competidors.",
backstory=(
"Ets un analista diligent que verifica les afirmacions, cita les fonts i resumeix "
"senyals de publicacions de renom."
),
tools=[], # afegeix eines web/de cerca/scraper més tard
llm=llm
)
strategist = Agent(
role="Estratega de producte",
goal="Sintetitzar la investigació en un posicionament nítid i opcions de full de ruta.",
backstory="Prioritzes la claredat, la viabilitat i els resultats mesurables.",
tools=[],
llm=llm
)
writer = Agent(
role="Escriptor de contingut",
goal="Produir un resum ben estructurat amb exemples i passos següents.",
backstory="Escrius en anglès concís i persuasiu i segueixes les guies d'estil.",
tools=[],
llm=llm
)
3) Crea tasques (entrades, sortides i criteris d'acceptació)
from crewai import Task
research_task = Task(
description=(
"Investigar el mercat de programari de gestió de projectes per a les PIME als EUA el 2025. "
"Identificar els principals competidors, nivells de preus, ICPs i tres necessitats no satisfetes. "
"Retornar punts amb 3–5 citacions."
),
expected_output=(
"Un resum en markdown amb seccions: Mida del mercat, actors clau, preus, ICPs, "
"Necessitats no satisfetes, fonts (amb enllaços)."
),
agent=researcher
)
synthesis_task = Task(
description=(
"Utilitzant el resum de la investigació, produir una declaració de posicionament, 2–3 diferenciadors, "
"i un full de ruta de 90 dies amb fites."
),
expected_output="Una nota estratègica concisa (<= 400 paraules).",
agent=strategist
)
writing_task = Task(
description=(
"Convertir la nota estratègica en un document d'una pàgina orientat al públic. Incloure un titular, "
"proposta de valor, punts de característiques i una CTA."
),
expected_output="Un document d'una pàgina en markdown adequat per a una pàgina de destí.",
agent=writer
)
4) Orquestrar l'equip (flux + memòria)
from crewai import Crew
crew = Crew(
agents=[researcher, strategist, writer],
tasks=[research_task, synthesis_task, writing_task],
process="sequential", # lliurar sortides en ordre
verbose=True
)
result = crew.kickoff
print(result)
Aquesta és la teva primera pipeline en funcionament. Has definit agents, has connectat tasques i has executat un flux seqüencial. Per ampliar-lo, afegeix eines (cerca, scraping, execució de codi), passos de validació i etapes paral·leles.
Un model mental per a projectes de CrewAI
Pensa com un gestor de projectes:
- Rols: Qui fa què? Investigador, analista, enginyer, revisor.
- Regles: Quins estàndards s'han de complir? Guia d'estil, citacions, proves.
- Eines: Quines capacitats estan permeses? Cerca web, base de dades vectorial, Python, APIs.
- Tasques: Com desglossem el problema? Entrades, sortides, criteris d'acceptació.
- Traspassos: Què es passa? Artefactes, metadades, restriccions.
- Feedback: Qui valida? Un agent de control de qualitat, un humà en el bucle o proves.
Amb CrewAI, el teu codi codifica aquest model operatiu.
Com utilitzar CrewAI per a treball real: 5 patrons provats
1) Investigació → Síntesi → Redacció (Contingut i informes)
- Agents: Investigador, editor, escriptor, verificador de fets.
- Eines: Cerca web, verificador de fonts, guia d'estil.
- Consell: Força les citacions i una "taula de reclamacions" per evitar les al·lucinacions.
fact_checker = Agent(
role="Verificador de fets",
goal="Validar totes les afirmacions amb fonts primàries; marcar les citacions febles.",
backstory="Escèptic, meticulós, imparcial.",
llm=llm
)
qa_task = Task(
description="Validar totes les declaracions factuals; afegir correccions en línia amb etiquetes [FIX].",
expected_output="Un esborrany corregit amb un resum de les correccions.",
agent=fact_checker
)
2) Especificació del producte a partir de tiquets (Enginyeria)
- Agents: Agrupador de tiquets, autor d'especificacions, revisor, autor de proves.
- Eines: API de seguiment d'incidències, context de la base de codi mitjançant embeddings, generador de proves unitàries.
- Consell: Afegeix una llista de verificació automatitzada de "Definició de fet".
3) Dades → Coneixement → Narrativa (Analítica)
- Agents: Manipulador de dades (Python), analista, narrador.
- Eines: Pandas, SQL, gràfics, execució de notebook.
- Consell: Utilitza un agent habilitat per a eines amb execució de
python per a analítiques verificables.
4) Generació de codi amb proteccions
- Agents: Planificador, codificador, linter, provador, revisor.
- Eines: Lectura de repositori, executor de proves unitàries, formatador, escàner de seguretat.
- Consell: Requereix que el revisor faci referència a les proves que demostren la correcció.
5) Seqüències de correu electrònic de clients a escala
- Agents: Segmentador, redactor, personalitzador, control de qualitat.
- Eines: API de CRM, plantilles, guia de to de marca.
- Consell: Afegeix una eina de verificació de rebot/spam i força variants A/B.
Afegir eines: Dona als agents capacitats reals
CrewAI brilla quan els agents poden utilitzar eines. Exemple: dona a l'investigador cerca web i un lector d'URL.
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_community.document_loaders import WebBaseLoader
search = DuckDuckGoSearchRun
def web_search_tool(query: str):
return search.run(query)
def read_url_tool(url: str):
loader = WebBaseLoader(url)
docs = loader.load
return "\n\n".join([d.page_content[:2000] for d in docs])
researcher.tools = [web_search_tool, read_url_tool]
Millors pràctiques:
- Privilegi mínim: Només adjunta les eines que l'agent realment necessita.
- Disciplina d'esquema: Les eines han de ser deterministes i tipades; retornar text concís i estructurat (JSON/Markdown) quan sigui possible.
- Control de costos: Mantingues les sortides de les eines curtes; resumeix abans de lliurar.
Dissenyar tasques que tinguin èxit
Les tasques ben dissenyades fan o desfan els sistemes multi-agent.
- Sigues explícit: "Retorna una taula en markdown amb columnes X, Y, Z."
- Defineix criteris d'acceptació: "Conté 3 citacions que enllacen a fonts primàries."
- Estableix límits: Els recomptes de paraules, els límits de temps o els límits de pas redueixen la deriva.
- Inclou exemples: Proporciona una mini-especificació del format de sortida desitjat.
- Afegeix etiquetes de memòria: Utilitza encapçalaments/claus consistents entre tasques per facilitar els traspassos.
Exemple d'esquelet de tasca:
Task(
description=(
"Resumir 5 estudis recents sobre la productivitat del treball remot (2023–2025) amb "
"metodologia, mida de la mostra i conclusions clau."
),
expected_output=(
"Markdown amb seccions H2 per estudi, una taula de comparació final i enllaços."
),
agent=researcher
)
Modes d'orquestració: Seqüencial vs. Paral·lel vs. Híbrid
- Seqüencial: Traspassos fiables; més lent però més fàcil de raonar.
- Paral·lel: Múltiples agents treballen alhora (per exemple, 3 investigadors); fusionar més tard.
- Híbrid: Investigació de sortida en paral·lel → síntesi i QA d'entrada.
Exemple híbrid:
r1 = Agent(role="Investigador A", goal="Centrar-se en els preus", backstory="", llm=llm)
r2 = Agent(role="Investigador B", goal="Centrar-se en les característiques", backstory="", llm=llm)
# Tasques paral·leles per a r1, r2; una tasca de síntesi de seguiment fusiona les seves sortides.
Consell: Quan fusionis, indica al sintetitzador que desdupliqui, resolgui conflictes i citi la font més forta.
Proteccions i QA: Mantingues els agents honestos
- Àrbitres: Afegeix un revisor o verificador de fets amb poder de veto explícit.
- Llistes de verificació: Codifica el compliment (privadesa, seguretat, to de marca) com una llista de verificació que l'agent de control de qualitat ha de marcar.
- Autocrítica: Demana als agents que incloguin una breu secció de "Què podria haver perdut".
- Determinisme: Utilitza una temperatura més baixa per als agents de control de qualitat.
qa = Agent(
role="Revisor de control de qualitat",
goal="Assegurar-se que les sortides compleixen els criteris d'acceptació i la guia d'estil.",
backstory="Ets estricte i pedant.",
llm=llm
)
Enginyeria de prompts per a agents de CrewAI
Els prompts del teu agent són mini descripcions de treball. Mantingues-los ajustats.
- Prompt de rol: Qui ets, per a què optimitzes.
- Prompt d'objectiu: L'estat final desitjat.
- Restriccions: Recompte de paraules, format, to, referències.
- Eines: Noms, quan utilitzar-les, què retornar.
- Exemples: 1–2 mostres curtes i realistes.
Fragment:
researcher = Agent(
role="Investigador analític",
goal=(
"Lliurar resums compactes i precisos amb 3–5 citacions creïbles i una nota de risc."
),
backstory=(
"Verifiques les afirmacions, prefereixes les fonts primàries i marques la incertesa."
),
llm=llm
)
Observabilitat: Veure què van fer els agents (i per què)
Activa els registres verbosos i conserva els artefactes:
- Emmagatzema el prompt, la sortida i les trucades d'eines de cada tasca.
- Desa un manifest d'execució amb metadades (model, temp, eines).
- Mantingues un bloc de notes per a notes provisionals; ajuda a la depuració i a les auditories.
Patró:
crew = Crew(..., verbose=True, output_log_file="runs/2025-crew.log")
Consells de cost, latència i fiabilitat
- Processament per lots: Paral·lelitzar tasques independents; limitar la concurrència per evitar els límits de taxa.
- Resumir: Comprimir els artefactes intermedis per reduir la rotació de tokens.
- Emmagatzematge en memòria cau: Memoritzar passos estables (per exemple, definicions de mercat) amb magatzems vectorials.
- Alternatives: Proporcionar un model de còpia de seguretat o una política de reintent per a trucades inestables.
- Humà en el bucle: Inserir portes d'aprovació opcionals en passos d'alt risc.
Problemes comuns (i com solucionar-los)
- Problema: Tasques vagues → sortides serpentejants.
- Solució: Afegeix criteris d'acceptació i exemples explícits.
- Problema: Massa eines → distracció i cost.
- Solució: Privilegi mínim, eines específiques de la tasca només.
- Problema: Bucles infinits o sobre-iteració.
- Solució: Afegeix límits de pas/temps i una clàusula de "parar si es compleixen els criteris".
- Problema: Pèrdua de context entre agents.
- Solució: Utilitza objectes de trasllat estructurats (JSON) i encapçalaments consistents.
- Problema: Reflexió posterior de control de qualitat.
- Solució: Tracta el control de qualitat com un agent de primera classe amb poder de veto.
Exemple d'extrem a extrem: Generador de resums competitius
Objectiu: Generar un resum competitiu comparant tres eines per a una persona objectiu.
Agents:
- Analista de persona → defineix els punts de dolor i els treballs per fer.
- Investigador → recopila dades i citacions.
- Sintetitzador → construeix una taula de comparació i coneixements.
- Escriptor → produeix el resum final.
- QA → verifica les fonts i la claredat.
Esquelet:
persona = Agent(role="Analista de persona", goal="Defineix ICP i JTBD.", llm=llm)
researcher = Agent(role="Investigador", goal="Recopila dades creïbles.", llm=llm)
synth = Agent(role="Sintetitzador", goal="Comparar i interpretar.", llm=llm)
writer = Agent(role="Escriptor", goal="Crea un resum llest per a executius.", llm=llm)
qa = Agent(role="QA", goal="Valida les afirmacions i la claredat.", llm=llm)
persona_task = Task(description="Defineix ICP & JTBD per als líders de RevOps en SaaS.", agent=persona,
expected_output="Punts + punts de dolor + mètriques d'èxit.")
research_task = Task(description="Recopila preus, característiques i ressenyes per a 3 eines.", agent=researcher,
expected_output="Taula + 5 citacions.")
synth_task = Task(description="Construeix una matriu de comparació i els 3 principals coneixements.", agent=synth,
expected_output="Taula de markdown + coneixements.")
write_task = Task(description="Redacta un resum d'1 pàgina amb recomanacions.", agent=writer,
expected_output="Resum executiu en markdown.")
qa_task = Task(description="Comprova la precisió i la llegibilitat; soluciona els problemes.", agent=qa,
expected_output="Resum net i validat.")
crew = Crew(agents=[persona, researcher, synth, writer, qa],
tasks=[persona_task, research_task, synth_task, write_task, qa_task],
process="sequential", verbose=True)
print(crew.kickoff)
Quan utilitzar CrewAI en comparació amb un sol prompt
Utilitza CrewAI quan:
- La tasca es descompon naturalment en rols o etapes.
- Necessites traçabilitat, control de qualitat o ús d'eines.
- Estàs construint una pipeline reutilitzable, no una única.
Afegeix-te a un sol prompt quan:
- És una tasca curta i subjectiva sense eines externes.
- La velocitat importa més que l'estructura.
Per cert: Redacta més ràpid amb un panell lateral d'IA
Si estàs utilitzant fluxos de treball multi-agent per investigar, perfilar i redactar contingut, val la pena assenyalar que un panell lateral d'IA com Sider.ai es pot situar al costat del teu navegador i documents per resumir pàgines, generar perfils i refinar esborranys en temps real. No substituirà l'orquestració de CrewAI, però pot accelerar les parts manuals—recollir fragments, reescriure seccions o comprovar el to—abans de tornar a connectar el contingut al teu equip. Propers passos accionables
- Instal·la CrewAI i executa l'exemple d'inici ràpid.
- Tria un flux de treball real (investigació → esborrany → QA) i codifica'l.
- Afegeix una eina a la vegada; mesura l'impacte en la qualitat de la sortida i el cost.
- Introdueix un agent de control de qualitat amb criteris d'acceptació explícits.
- Mou-te a un model d'orquestració híbrid per a la velocitat.
Conclusions clau
- CrewAI converteix projectes complexos en fluxos de treball modulars i multi-agent.
- L'èxit depèn de rols nítids, tasques clares i un ús disciplinat de les eines.
- Les proteccions (QA, llistes de verificació, límits) mantenen els costos baixos i la qualitat alta.
- Comença petit, després escala amb investigació paral·lela i fluxos híbrids.
Mini-llista de verificació: Com utilitzar CrewAI de manera efectiva
- Defineix rols, objectius i eines explícitament.
- Escriu tasques amb criteris d'acceptació i exemples.
- Utilitza seqüencial per a la fiabilitat, híbrid per a la velocitat.
- Afegeix un agent de control de qualitat aviat; dóna-li poder de veto.
- Registra-ho tot; emmagatzema artefactes per a auditories.
- Optimitza el cost amb resums, emmagatzematge en memòria cau i processament per lots.
FAQ
Q1: Què és CrewAI i com puc utilitzar-lo per a fluxos de treball multi-agent?
CrewAI és un marc de treball per orquestrar múltiples agents d'IA amb rols, tasques i eines. L'utilitzes definint agents, creant tasques amb criteris d'acceptació i executant un equip que coordina els traspassos per produir una sortida final.
P2: Com puc afegir eines com ara la cerca web als agents de CrewAI?
Adjunta funcions d'eines a un agent i indica-li quan ha d'utilitzar-les. Mantingues les sortides estructurades i breus (p. ex., JSON o markdown) per controlar els costos i millorar les transferències.
P3: Quan hauria d'utilitzar CrewAI en comptes d'un únic prompt d'un LLM?
Utilitza CrewAI quan una tasca es descompon en etapes, requereix l'ús d'eines o control de qualitat, o necessita conductes repetibles. Utilitza un únic prompt per a tasques ràpides i subjectives que no necessiten estructura.
P4: Com puc evitar les al·lucinacions en les sortides de CrewAI?
Afegeix un agent de verificació de fets o de control de qualitat amb poder de veto, exigeix citacions a fonts primàries, estableix una temperatura baixa per al control de qualitat i especifica criteris d'acceptació com ara una taula de reclamacions.
P5: Pot CrewAI executar tasques en paral·lel per accelerar les coses?
Sí. Utilitza agents paral·lels per a tasques independents (p. ex., diversos investigadors) i després una tasca de síntesi per fusionar els resultats. L'orquestració híbrida equilibra la velocitat i la fiabilitat.