CrewAI:n käyttö: Käytännön opas moniagenttityönkulkuihin
Rohkea lupaus: Jos olet koskaan toivonut voivasi kloonata parhaan tiimikaverisi, jotta voisit viedä projektin läpi nopeammin, CrewAI pääsee lähelle – orkestroimalla useita tekoälyagentteja, jotka suunnittelevat, tekevät yhteistyötä ja toimittavat työt yhdessä.
Tässä käytännöllisessä, ratkaisukeskeisessä oppaassa opit tarkalleen, miten CrewAI:ta käytetään: kehyksen asentamisesta ja agenttien määrittelystä aina roolien, työkalujen, tehtävien ja jäsenneltyjen moniagenttityönkulkujen rakentamiseen, jotka tuottavat todellisia tuloksia. Käsittelemme tutkimuksen, sisällön, data-analyysin ja koodin generoinnin malleja – ja miten vältetään yleisiä sudenkuoppia, kuten agenttien umpikuja, kehotteiden paisuminen ja työkalujen ylikäyttö.
Painopisteemme: tarjota sinulle vaiheittainen "kokeile tänään" -polku kopioi-liitä-koodilla, taisteluissa testatuilla parhailla käytännöillä ja muutamilla työnkulkujen suunnitelmilla, joita voit mukauttaa. Olitpa automatisoimassa markkinatutkimusta tai rakentamassa tuotespesifikaatiota tiketeistä, tämä on on sinun reittisi CrewAI:n tehokkaaseen käyttöön.
Mikä on CrewAI (ja miksi se on erilainen)
- CrewAI on kehys moniagenttijärjestelmien rakentamiseen, jossa jokaisella agentilla on rooli, tavoite, työkalut ja säännöt. Kehys koordinoi sitten näitä agentteja – siirtää tehtäviä, jakaa kontekstia ja iterioi kohti tulosta.
- Toisin kuin yksittäinen LLM-kehotus, CrewAI pakottaa rakenteen: agentit ovat eksplisiittisiä, tehtävät ovat modulaarisia, työkalut ovat luvallisia ja tulokset ovat auditoitavissa.
- Hyöty: hajotetut työnkulut (tutkimus → synteesi → kirjoittaminen → laadunvarmistus), jotka heijastavat todellisten tiimien työskentelytapaa – vain nopeammin, skaalautuvammin ja toistettavammin.
Pikaopas: CrewAI:n käyttö 10 minuutissa
Alla on minimaalinen malli, jonka avulla pääset nollasta toimivaan moniagenttiryhmään. Oletetaan, että käytät Pythonia.
1) Asenna ja aseta
pip install crewai langchain-openai python-dotenv
Luo .env -tiedosto LLM-palveluntarjoajasi avaimilla:
OPENAI_API_KEY=sk-your-key
# tai muut pinosi tukemat palveluntarjoajat
2) Määritä agenttisi (roolit + tavoitteet + työkalut)
from crewai import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
researcher = Agent(
role="Market Researcher",
goal="Find credible, current insights on the target market and competitors.",
backstory=(
"You are a diligent analyst who verifies claims, cites sources, and summarizes "
"signals from reputable publications."
),
tools=[], # add web/search/scraper tools later
llm=llm
)
strategist = Agent(
role="Product Strategist",
goal="Synthesize research into a crisp positioning and roadmap options.",
backstory="You prioritize clarity, feasibility, and measurable outcomes.",
tools=[],
llm=llm
)
writer = Agent(
role="Content Writer",
goal="Produce a well-structured brief with examples and next steps.",
backstory="You write in concise, persuasive English and follow style guides.",
tools=[],
llm=llm
)
3) Luo tehtäviä (syötteitä, tulosteita ja hyväksymiskriteereitä)
from crewai import Task
research_task = Task(
description=(
"Research the US SMB project management software market in 2025. "
"Identify top competitors, pricing tiers, ICPs, and three unmet needs. "
"Return bullet points with 3–5 citations."
),
expected_output=(
"A markdown brief with sections: Market Size, Key Players, Pricing, ICPs, "
"Unmet Needs, Sources (with links)."
),
agent=researcher
)
synthesis_task = Task(
description=(
"Using the research brief, produce a positioning statement, 2–3 differentiators, "
"and a 90-day roadmap with milestones."
),
expected_output="A concise strategy memo (<= 400 words).",
agent=strategist
)
writing_task = Task(
description=(
"Turn the strategy memo into a public-facing one-pager. Include a headline, "
"value proposition, feature bullets, and a CTA."
),
expected_output="A markdown one-pager suitable for a landing page.",
agent=writer
)
4) Orkestroi ryhmä (virtaus + muisti)
from crewai import Crew
crew = Crew(
agents=[researcher, strategist, writer],
tasks=[research_task, synthesis_task, writing_task],
process="sequential", # hand off outputs in order
verbose=True
)
result = crew.kickoff
print(result)
Se on ensimmäinen toimiva putkesi. Määritit agentit, kytkit tehtävät ja suoritit peräkkäisen virtauksen. Laajenna sitä lisäämällä työkaluja (haku, raapiminen, koodin suoritus), validointivaiheita ja rinnakkaisia vaiheita.
CrewAI-projektien mentaalimalli
Ajattele kuin projektipäällikkö:
- Roolit: Kuka tekee mitä? Tutkija, analyytikko, insinööri, tarkastaja.
- Säännöt: Mitkä standardit on täytettävä? Tyyliopas, viittaukset, testit.
- Työkalut: Mitkä ominaisuudet ovat sallittuja? Verkkohaku, vektoritietokanta, Python, API:t.
- Tehtävät: Miten jaamme ongelman osiin? Syötteet, tulosteet, hyväksymiskriteerit.
- Siirrot: Mitä siirretään eteenpäin? Artefaktit, metatiedot, rajoitukset.
- Palaute: Kuka validoi? Laadunvarmistusagentti, ihminen silmukassa tai testit.
CrewAI:n avulla koodisi koodaa tämän toimintamallin.
CrewAI:n käyttö oikeaan työhön: 5 todistettua mallia
1) Tutkimus → Synteesi → Luonnostelu (sisältö ja raportit)
- Agentit: Tutkija, toimittaja, kirjoittaja, faktantarkistaja.
- Työkalut: Verkkohaku, lähteen tarkistaja, tyyliopas.
- Vinkki: Pakota viittaukset ja "väitetable", jotta estät hallusinaatiot.
fact_checker = Agent(
role="Fact Checker",
goal="Validate all claims against primary sources; flag weak citations.",
backstory="Skeptical, meticulous, unbiased.",
llm=llm
)
qa_task = Task(
description="Validate all factual statements; add corrections inline with [FIX] tags.",
expected_output="A corrected draft with a summary of fixes.",
agent=fact_checker
)
2) Tuotespesifikaatio tiketeistä (suunnittelu)
- Agentit: Tikettien ryhmittelijä, spesifikaation kirjoittaja, tarkastaja, testin kirjoittaja.
- Työkalut: Ongelmaseuranta-API, koodipohjan konteksti upotusten kautta, yksikkötestin generaattori.
- Vinkki: Lisää automaattinen "Valmiin määritelmä" -tarkistuslista.
3) Data → Oivallus → Kertomus (analyysi)
- Agentit: Datan hallitsija (Python), analyytikko, tarinankertoja.
- Työkalut: Pandas, SQL, kaaviointi, muistikirjan suoritus.
- Vinkki: Käytä työkaluilla varustettua agenttia, jossa on
python-suoritus varmennettavaa analytiikkaa varten.
4) Koodin generointi suojakaiteilla
- Agentit: Suunnittelija, koodaaja, linteri, testaaja, tarkastaja.
- Työkalut: Repojen luku, yksikkötestin suorittaja, muotoilija, tietoturvaskanneri.
- Vinkki: Vaadi tarkastajaa viittaamaan testeihin, jotka todistavat oikeellisuuden.
5) Asiakassähköpostisekvenssit mittakaavassa
- Agentit: Segmentoija, copywriter, personoija, laadunvarmistaja.
- Työkalut: CRM-API, mallit, brändin sävyopas.
- Vinkki: Lisää palautus-/roskapostitarkistustyökalu ja pakota A/B-variantit.
Työkalujen lisääminen: Anna agenteille todellisia ominaisuuksia
CrewAI loistaa, kun agentit voivat käyttää työkaluja. Esimerkki: anna tutkijalle verkkohaku ja URL-lukija.
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]
Parhaat käytännöt:
- Pienin oikeus: Liitä vain työkalut, joita agentti todella tarvitsee.
- Skeeman kurinalaisuus: Työkalujen tulee olla deterministisiä ja tyypitettyjä; palauta ytimekästä, jäsenneltyä tekstiä (JSON/Markdown) mahdollisuuksien mukaan.
- Kustannusten hallinta: Pidä työkalun tulosteet lyhyinä; tee yhteenveto ennen siirtämistä.
Onnistuvien tehtävien suunnittelu
Hyvin suunnitellut tehtävät tekevät tai rikkovat moniagenttijärjestelmiä.
- Ole eksplisiittinen: "Palauta markdown-taulukko, jossa on sarakkeet X, Y, Z."
- Määritä hyväksymiskriteerit: "Sisältää 3 viittausta, jotka linkittävät ensisijaisiin lähteisiin."
- Aseta rajat: Sanamäärät, aikarajat tai vaiherajat vähentävät ajautumista.
- Lisää esimerkkejä: Anna minikokoinen erittely halutusta tulostusmuodosta.
- Lisää muistitagia: Käytä yhdenmukaisia otsikoita/avaimia eri tehtävissä siirtojen helpottamiseksi.
Esimerkki tehtävärunko:
Task(
description=(
"Summarize 5 recent studies on remote work productivity (2023–2025) with "
"methodology, sample size, and key findings."
),
expected_output=(
"Markdown with H2 sections per study, a final comparison table, and links."
),
agent=researcher
)
Orkestrointitilat: Peräkkäinen vs. rinnakkainen vs. hybridi
- Peräkkäinen: Luotettavat siirrot; hitaampi, mutta helpompi perustella.
- Rinnakkainen: Useat agentit työskentelevät samanaikaisesti (esim. 3 tutkijaa); yhdistä myöhemmin.
- Hybridi: Tuuletin ulos -tutkimus rinnakkain → tuuletin sisään -synteesi ja laadunvarmistus.
Hybridi esimerkki:
r1 = Agent(role="Researcher A", goal="Focus on pricing", backstory="", llm=llm)
r2 = Agent(role="Researcher B", goal="Focus on features", backstory="", llm=llm)
# Parallel tasks for r1, r2; a follow-up synthesis task merges their outputs.
Vinkki: Kun yhdistät, ohjaa syntetisaattoria poistamaan päällekkäisyydet, ratkaisemaan ristiriidat ja mainitsemaan vahvemman lähteen.
Suojakaiteet ja laadunvarmistus: Pidä agentit rehellisinä
- Erotuomarit: Lisää tarkastaja tai faktantarkistaja, jolla on nimenomainen veto-oikeus.
- Tarkistuslistat: Koodaa vaatimustenmukaisuus (yksityisyys, turvallisuus, brändin sävy) tarkistuslistaksi, joka laadunvarmistusagentin on valittava.
- Itsekritiikki: Pyydä agentteja sisällyttämään lyhyt "Mitä olen saattanut unohtaa" -osio.
- Determinismi: Käytä alhaisempaa lämpötilaa laadunvarmistusagenteille.
qa = Agent(
role="QA Reviewer",
goal="Ensure outputs meet the acceptance criteria and style guide.",
backstory="You are strict and pedantic.",
llm=llm
)
Kehotteiden suunnittelu CrewAI-agenteille
Agenttikehotteesi ovat minikokoisia työnkuvauksia. Pidä ne tiiviinä.
- Roolikehote: Kuka olet, mitä optimoit.
- Tavoitekehote: Haluttu lopputila.
- Rajoitukset: Sanamäärä, muoto, sävy, viittaukset.
- Työkalut: Nimet, milloin niitä käytetään, mitä palautetaan.
- Esimerkit: 1–2 lyhyttä, realistista näytettä.
Katkelma:
researcher = Agent(
role="Analytical Researcher",
goal=(
"Deliver compact, accurate briefs with 3–5 credible citations and a risk note."
),
backstory=(
"You verify claims, prefer primary sources, and flag uncertainty."
),
llm=llm
)
Havaittavuus: Katso, mitä agentit tekivät (ja miksi)
Ota käyttöön yksityiskohtaiset lokit ja säilytä artefaktit:
- Tallenna jokaisen tehtävän kehote, tuloste ja työkalukutsut.
- Tallenna suoritusmanifesti metatiedoilla (malli, lämpötila, työkalut).
- Pidä luonnoslehtiö väliaikaisille muistiinpanoille; se auttaa virheenkorjauksessa ja auditoinneissa.
Malli:
crew = Crew(..., verbose=True, output_log_file="runs/2025-crew.log")
Kustannus-, latenssi- ja luotettavuusvinkkejä
- Eräkäsittely: Rinnasta itsenäiset tehtävät; rajoita samanaikaisuutta välttääksesi nopeusrajoitukset.
- Tee yhteenveto: Pakkaa välituotteet pienentääksesi tokenien vaihtuvuutta.
- Välimuisti: Muista vakaat vaiheet (esim. markkinamääritelmät) vektorivarastojen avulla.
- Varajärjestelyt: Tarjoa varmistusmalli tai uudelleenyrityskäytäntö epävakaille puheluille.
- Ihminen silmukassa: Lisää valinnaisia hyväksyntäportteja korkean riskin vaiheisiin.
Yleiset sudenkuopat (ja miten ne korjataan)
- Sudenkuoppa: Epämääräiset tehtävät → mutkittelevat tulosteet.
- Korjaus: Lisää eksplisiittiset hyväksymiskriteerit ja esimerkkejä.
- Sudenkuoppa: Liian monta työkalua → häiriötekijä ja kustannukset.
- Korjaus: Vain pienimmän oikeuden mukaiset, tehtäväkohtaiset työkalut.
- Sudenkuoppa: Äärettömät silmukat tai yliterointi.
- Korjaus: Lisää vaihe-/aikarajat ja "lopeta, jos kriteerit täyttyvät" -lauseke.
- Sudenkuoppa: Kontekstin menetys agenttien välillä.
- Korjaus: Käytä jäsenneltyjä siirtoobjekteja (JSON) ja yhdenmukaisia otsikoita.
- Sudenkuoppa: Laadunvarmistus jälkikäteen.
- Korjaus: Käsittele laadunvarmistusta ensiluokkaisena agenttina, jolla on veto-oikeus.
Päästä päähän -esimerkki: Kilpailukykyisen tiivistelmän luoja
Tavoite: Luo kilpailukykyinen tiivistelmä, jossa verrataan kolmea työkalua kohdehenkilölle.
Agentit:
- Persona-analyytikko → määrittelee kipupisteet ja jobs-to-be-done.
- Tutkija → kerää tietoja ja viittauksia.
- Syntetisaattori → rakentaa vertailutaulukon ja oivalluksia.
- Kirjoittaja → tuottaa lopullisen tiivistelmän.
- Laadunvarmistus → tarkistaa lähteet ja selkeyden.
Runko:
persona = Agent(role="Persona Analyst", goal="Define ICP and JTBD.", llm=llm)
researcher = Agent(role="Researcher", goal="Collect credible data.", llm=llm)
synth = Agent(role="Synthesizer", goal="Compare and interpret.", llm=llm)
writer = Agent(role="Writer", goal="Create an executive-ready brief.", llm=llm)
qa = Agent(role="QA", goal="Validate claims and clarity.", llm=llm)
persona_task = Task(description="Define ICP & JTBD for RevOps leaders in SaaS.", agent=persona,
expected_output="Bullets + pain points + success metrics.")
research_task = Task(description="Collect pricing, features, and reviews for 3 tools.", agent=researcher,
expected_output="Table + 5 citations.")
synth_task = Task(description="Build a comparison matrix and top 3 insights.", agent=synth,
expected_output="Markdown table + insights.")
write_task = Task(description="Draft a 1-page brief with recommendations.", agent=writer,
expected_output="Executive brief in markdown.")
qa_task = Task(description="Check accuracy and readability; fix issues.", agent=qa,
expected_output="Clean, validated brief.")
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)
Milloin kannattaa käyttää CrewAI:ta verrattuna yksittäiseen kehotteeseen
Käytä CrewAI:ta, kun:
- Tehtävä hajoaa luonnollisesti rooleihin tai vaiheisiin.
- Tarvitset jäljitettävyyttä, laadunvarmistusta tai työkalujen käyttöä.
- Olet rakentamassa uudelleenkäytettävää putkea, et kertaluonteista.
Pysy yhdessä kehotteessa, kun:
- Se on lyhyt, subjektiivinen tehtävä ilman ulkoisia työkaluja.
- Nopeus on tärkeämpää kuin rakenne.
Muuten: Luonnostele nopeammin tekoälyn sivupaneelilla
Jos käytät moniagenttityönkulkuja sisällön tutkimiseen, hahmotteluun ja luonnosteluun, on syytä huomata, että tekoälyn sivupaneeli, kuten Sider.ai, voi olla selaimesi ja dokumenttiesi rinnalla tiivistämässä sivuja, luomassa hahmotelmia ja hienosäätämässä luonnoksia reaaliajassa. Se ei korvaa CrewAI:n orkestrointia, mutta se voi nopeuttaa manuaalisia osia – katkelmien keräämistä, osioiden uudelleenkirjoittamista tai sävyn järkevyystarkistusta – ennen kuin kytket sisällön takaisin ryhmääsi. Toiminnalliset seuraavat vaiheet
- Asenna CrewAI ja suorita pika-aloitusesimerkki.
- Valitse todellinen työnkulku (tutkimus → luonnos → laadunvarmistus) ja koodaa se.
- Lisää yksi työkalu kerrallaan; mittaa vaikutus tulostuslaatuun ja kustannuksiin.
- Ota käyttöön laadunvarmistusagentti, jolla on nimenomaiset hyväksymiskriteerit.
- Siirry hybridiorkestrointimalliin nopeuttaaksesi.
Tärkeimmät huomiot
- CrewAI muuttaa monimutkaiset projektit modulaarisiksi, moniagenttityönkuluiksi.
- Menestys perustuu selkeisiin rooleihin, selkeisiin tehtäviin ja kurinalaiseen työkalujen käyttöön.
- Suojakaiteet (laadunvarmistus, tarkistuslistat, rajoitukset) pitävät kustannukset alhaalla ja laadun korkealla.
- Aloita pienestä, skaalaa sitten rinnakkaisella tutkimuksella ja hybridivirroilla.
Mini-tarkistuslista: CrewAI:n tehokas käyttö
- Määrittele roolit, tavoitteet ja työkalut eksplisiittisesti.
- Kirjoita tehtävät hyväksymiskriteereillä ja esimerkeillä.
- Käytä peräkkäistä luotettavuutta, hybridiä nopeutta varten.
- Lisää laadunvarmistusagentti aikaisin; anna sille veto-oikeus.
- Lokita kaikki; tallenna artefaktit auditointeja varten.
- Optimoi kustannukset yhteenvedoilla, välimuistilla ja eräkäsittelyllä.
UKK
Q1:What is CrewAI and how do I use it for multi‑agent workflows?
CrewAI is a framework for orchestrating multiple AI agents with roles, tasks, and tools. You use it by defining agents, creating tasks with acceptance criteria, and running a crew that coordinates handoffs to produce a final output.
K2: Miten CrewAI-agentteihin lisätään työkaluja, kuten verkkohaku?
Liitä työkalufunktioita agenttiin ja ohjeista, milloin niitä käytetään. Pidä tulosteet jäsenneltyinä ja lyhyinä (esim. JSON tai markdown) kustannusten hallitsemiseksi ja siirtojen parantamiseksi.
K3: Milloin minun pitäisi käyttää CrewAI:ta yhden LLM-kehotteen sijaan?
Käytä CrewAI:ta, kun tehtävä jakautuu vaiheisiin, vaatii työkalujen käyttöä tai laadunvarmistusta tai tarvitsee toistettavia putkia. Käytä yhtä kehotetta nopeisiin, subjektiivisiin tehtäviin, jotka eivät tarvitse rakennetta.
K4: Miten voin estää hallusinaatioita CrewAI:n tulosteissa?
Lisää Fact‑Checker- tai QA-agentti, jolla on veto-oikeus, vaadi viittauksia ensisijaisiin lähteisiin, aseta alhainen lämpötila laadunvarmistukselle ja määritä hyväksymiskriteerit, kuten väitetaulukko.
K5: Voiko CrewAI suorittaa tehtäviä rinnakkain nopeuttaakseen toimintaa?
Kyllä. Käytä rinnakkaisia agentteja itsenäisiin tehtäviin (esim. useita tutkijoita) ja sitten syntetisaattoritehtävää tulosten yhdistämiseksi. Hybridiorkestrointi tasapainottaa nopeutta ja luotettavuutta.