CrewAI - Notatka do Nauki i Powtórzeń

Blog

Wpis na blogu

📚 Podstawowe Informacje

CrewAI - framework open source do organizacji zespołów wysoko wydajnych agentów AI.

Ekosystem CrewAI

• CrewAI Enterprise - platforma hostingowa (monetyzacja)
• CrewAI UI Studio - narzędzie low-code/no-code
• CrewAI Framework - framework open source (nasz fokus)

---

🔄 Dwa Podejścia do Przepływów Pracy

Aspekt	CrewAI Crews	CrewAI Flows
Charakter	Autonomiczne, kreatywna współpraca	Deterministyczne, stałe przepływy
Zastosowanie	Eksploracyjne zadania, burze mózgów	Precyzyjna kontrola, audytowalność
Kontrola	Większa swoboda agentów	Ściśle określony przepływ

Fokus kursu: CrewAI Crews (autonomiczność)

---

🧩 Trzy Główne Koncepcje CrewAI

1. Agent

• Autonomiczna jednostka pracy powiązana z LLM
• Składa się z: Role, Goal, Backstory
• Opcjonalnie: Memory, Tools
• Analogia: Agent z Tygodnia 2, ale bardziej ustrukturyzowany

2. Task (Zadanie)

• Konkretne, jednorazowe zadanie do wykonania
• Ma opis i oczekiwany wynik
• Przypisane do jednego agenta
• Brak bezpośredniej analogii w Tygodniu 2!

3. Crew (Załoga)

• Agregat Agentów i Zadań
• Koordynuje przepływ pracy
• Analogia: Runner/Trace (Orkiestrator) z wbudowaną logiką

---

⚙️ Tryby Procesu (Process Modes)

Tryb	Opis	Zastosowanie
Sequential	Zadania jedno po drugim w określonej kolejności	Determinatywne, audytowalne przepływy
Hierarchical	Manager LLM przydziela zadania innym agentom	Złożone, autonomiczne, eksploracyjne zadania

---

⚖️ Kompromisy: Opiniotwórczość vs Elastyczność

Zalety CrewAI

• ✅ Wymusza dobre praktyki: Role, Goal, Backstory
• ✅ Promuje kompleksowy kontekst dla LLM
• ✅ Separacja konfiguracji (YAML)
• ✅ Automatyzacja orkiestracji

Wady CrewAI

• ❌ Mniej elastyczności niż OpenAI Agents SDK
• ❌ Monit systemowy jest składany z 3 elementów (ukryty)
• ❌ Mniej bezpośredniej kontroli nad promptem

---

🔧 Elastyczność Modeli - LiteLLM

• LiteLLM - biblioteka abstrakcyjna ujednolicająca API wielu dostawców
• Format w YAML: Może być z prefiksem lub bez:
  • Z prefiksem: openai/gpt-4o-mini, anthropic/claude-3-haiku, google/gemini-2.5-flash
  • Bez prefiksu: gpt-4o-mini (domyślnie OpenAI)
• Zaleta: Łatwe przełączanie modeli, integracja z Ollama/OpenRouter
• W projekcie: llm: gpt-4o-mini (bez prefiksu, domyślnie OpenAI)

---

📁 Struktura Projektu CrewAI

Tworzenie projektu

crew create crew my_project_name
# lub
crew create flow my_project_name

Struktura katalogów

my_project/
└── src/
    └── my_project/
        ├── config/
        │   ├── agents.yaml    # Konfiguracja agentów
        │   └── tasks.yaml     # Konfiguracja zadań
        ├── crew.py            # Definicja agentów, zadań, załogi (dekoratory)
        └── main.py            # Punkt wejścia

Uruchomienie

crewai run
# lub przez Python
python -m ai_agents_crewai_debate.main

---

🎯 Dekoratory CrewAI

Używane w crew.py:

• @CrewBase - dekorator dla głównej klasy zarządzającej (dekoruje klasę, nie funkcję)
• @agent - dekorator dla metody tworzącej Agenta (automatycznie dodaje do self.agents)
• @task - dekorator dla metody tworzącej Zadanie (automatycznie dodaje do self.tasks)
• @crew - dekorator dla metody zwracającej Załogę (określa process)

Przykład struktury klasy z dekoratorami

from crewai.project import CrewBase, agent, crew, task
from crewai import Agent, Crew, Process, Task

@CrewBase
class AiAgentsCrewaiDebate:
    """AiAgentsCrewaiDebate crew"""
    
    agents: List[BaseAgent]
    tasks: List[Task]
    
    @agent
    def debater(self) -> Agent:
        return Agent(
            config=self.agents_config["debater"],
            verbose=True,
        )
    
    @agent
    def judge(self) -> Agent:
        return Agent(
            config=self.agents_config["judge"],
            verbose=True,
        )
    
    @task
    def propose_task(self) -> Task:
        return Task(
            config=self.tasks_config["propose"],
        )
    
    @task
    def oppose_task(self) -> Task:
        return Task(
            config=self.tasks_config["oppose"],
        )
    
    @task
    def decide_task(self) -> Task:
        return Task(
            config=self.tasks_config["decide"],
        )
    
    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,  # Automatycznie wypełnione przez @agent
            tasks=self.tasks,    # Automatycznie wypełnione przez @task
            process=Process.sequential,  # Enum, nie string!
            verbose=True,
        )

---

📝 Konfiguracja Agentów (agents.yaml)

Pola Agentów

Pole	Opis	Rola w Prompt Engineering
role	Zawodowa tożsamość agenta	Określa kim jest agent
goal	Główny cel do osiągnięcia	Definiuje intencję
backstory	Historia/kontekst agenta	Wprowadza kontekst i ton
llm	Model LLM (format: dostawca/model)	Określa użyty model

Przykład: Agent Debater (z projektu)

debater:
  role: >
    Przekonujący Debatant
  goal: >
    Przedstaw jasny argument za lub przeciw wnioskowi. Wnioskowanie to: {motion}
  backstory: >
    Jesteś doświadczonym dyskutantem z talentem do podawania zwięzłych, ale przekonujących argumentów.
    Wnioskowanie to: {motion}
  llm: gpt-4o-mini  # Może być bez prefiksu lub z prefiksem: openai/gpt-4o-mini

Przykład: Agent Judge

judge:
  role: >
    Wyłonienie zwycięzcy debaty na podstawie przedstawionych argumentów
  goal: >
    Przedstawione argumenty za i przeciw wnioskowi: {motion}, wyłonienie strony, która jest bardziej przekonująca,
    na podstawie przedstawionych argumentów.
  backstory: >
    Jesteś uczciwym sędzią z reputacją oceniającym argumenty bez uwzględniania własnych poglądów i podejmowania decyzji na podstawie meritów argumentu.
    Wnioskowanie to: {motion}
  llm: gpt-4o-mini

Uwaga: Szablony {motion}, {current_year} są wypełniane przez inputs w main.py

---

📋 Konfiguracja Zadań (tasks.yaml)

Pola Zadania

• description - co ma być wykonane (może zawierać szablony {motion})
• expected_output - oczekiwany wynik
• output_file - plik wyjściowy (opcjonalnie, zapisuje wynik do pliku)
• agent - nazwa agenta przypisanego do zadania (musi odpowiadać kluczowi w agents.yaml)

Przykład: Trzy Zadania z Projektu Debaty

propose:
  description: >
    Jesteś proponującym wnioskowanie: {motion}.
    Przedstaw jasny argument za wnioskowanie.
    Bądź bardzo przekonujący.
  expected_output: >
    Twój jasny argument za wnioskowanie, w zwięzły sposób.
  agent: debater
  output_file: output/propose.md

oppose:
  description: >
    Jesteś przeciwnikiem wnioskowania: {motion}.
    Przedstaw jasny argument przeciw wnioskowaniu.
    Bądź bardzo przekonujący.
  expected_output: >
    Twój jasny argument przeciw wnioskowaniu, w zwięzły sposób.
  agent: debater
  output_file: output/oppose.md

decide:
  description: >
    Przejrzyj przedstawione argumenty przez dyskutantów i wyłonienie strony, która jest bardziej przekonująca.
  expected_output: >
    Twoja decyzja na temat strony, która jest bardziej przekonująca, i dlaczego.
  agent: judge
  output_file: output/decide.md

Uwaga: W projekcie debaty jeden agent (debater) wykonuje dwa zadania (propose i oppose), a judge wykonuje decide.

---

🔄 Pełny Cykl Życia Projektu

Etap	Akcja	Kluczowa Koncepcja
Inicjalizacja	crewai create crew my_project	Scaffolding projektu (UV)
Konfiguracja Agentów	config/agents.yaml	Role, Goal, Backstory, LLM (szablony {motion})
Konfiguracja Zadań	config/tasks.yaml	Description, expected_output, output_file, agent
Orkiestracja	src/project/crew.py	Dekoratory, Process.sequential (enum)
Inputs	main.py	Słownik inputs z wartościami dla szablonów
Uruchomienie	crewai run lub python -m project.main	crew().kickoff(inputs=inputs)

---

💡 Kluczowe Wzorce Projektowe

1. Opiniotwórczość - wymusza dobrą inżynierię podpowiedzi
2. Separacja konfiguracji (YAML) - oddzielenie treści od logiki
3. Sekwencyjny proces - deterministyczne wykonanie zadań (Process.sequential)
4. Dekoratory - automatyczna rejestracja komponentów (self.agents, self.tasks)
5. Szablony w YAML - {motion}, {current_year} wypełniane przez inputs
6. Output files - automatyczne zapisywanie wyników zadań do plików

---

💻 Przykład: main.py z Inputs

from ai_agents_crewai_debate.crew import AiAgentsCrewaiDebate
from datetime import datetime

def run():
    inputs = {
        "motion": "Samoświadomość i AI LLMs",
        "current_year": str(datetime.now().year),
    }
    
    AiAgentsCrewaiDebate().crew().kickoff(inputs=inputs)

Kluczowe:

• inputs to słownik z wartościami dla szablonów w YAML
• kickoff(inputs=inputs) uruchamia załogę
• Szablony {motion} i {current_year} są automatycznie zastępowane

---

🔗 Porównanie z Tydniem 2 (OpenAI Agents SDK)

Aspekt	OpenAI Agents SDK	CrewAI
Struktura	Minimalistyczna	Opiniotwórcza, ustrukturyzowana
Prompt	Bezpośrednia kontrola (instructions)	Składany z Role/Goal/Backstory
Zadania	W kodzie lub w agencie	Osobny byt (Task)
Orkiestracja	Manualna (asyncio)	Automatyczna (Crew)
Modele	Głównie OpenAI	Wiele dostawców (LiteLLM)
Elastyczność	Wysoka	Średnia (kompromis)

---

🛠️ Narzędzia (Tools) dla Agentów

Agenci mogą używać narzędzi do wykonywania akcji. Przykład custom tool:

from typing import Type
from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class MyCustomToolInput(BaseModel):
    """Input schema for MyCustomTool."""
    argument: str = Field(..., description="Description of the argument.")

class MyCustomTool(BaseTool):
    name: str = "Name of my tool"
    description: str = "Dokładny opis zastosowania danego narzędzia."
    args_schema: Type[BaseModel] = MyCustomToolInput
    
    def _run(self, argument: str) -> str:
        # Implementation goes here
        return "Wynik działania narzędzia"

Użycie w agencie:

@agent
def debater(self) -> Agent:
    return Agent(
        config=self.agents_config["debater"],
        tools=[MyCustomTool()],  # Dodanie narzędzia
        verbose=True,
    )

---

🎓 Ćwiczenie: Rozbudowa Załogi Debatującej

Zrealizowane w projekcie:

1. ✅ Dwa zadania dla debatanta: propose (za) i oppose (przeciw)
2. ✅ Trzy zadania sekwencyjne: propose → oppose → decide
3. ⚠️ Różne modele: Można przypisać różne LLM do różnych agentów

Do zrobienia:

• Przypisz różne modele do debater i judge (np. gpt-4o vs gpt-4o-mini)
• Obserwuj wpływ modelu na jakość argumentów i decyzji

---

📌 Kluczowe Różnice Mentalne

• Tydzień 2: asyncio i Function Calling - fundamenty
• Tydzień 3: CrewAI - co robi inaczej (terminologia) i co upraszcza (orkiestracja)

---

🎯 Najważniejsze Do Zapamiętania

1. Agent = Role + Goal + Backstory + LLM (definiowane w agents.yaml)
2. Task = osobny byt (nie w agencie, nie w kodzie) - definiowane w tasks.yaml
3. Crew = agregat Agentów + Zadań z trybem procesu (Process.sequential lub Process.hierarchical)
4. YAML = separacja konfiguracji od logiki (szablony {variable})
5. Dekoratory = automatyczna rejestracja (@CrewBase, @agent, @task, @crew)
6. LiteLLM = elastyczność modeli (format: dostawca/model lub bez prefiksu)
7. Inputs = wypełnianie szablonów (kickoff(inputs={...}))
8. Output files = automatyczne zapisywanie wyników zadań do plików

---

📦 Struktura Projektu (Rzeczywisty Przykład)

ai_agents_crewai_debate/
├── src/
│   └── ai_agents_crewai_debate/
│       ├── config/
│       │   ├── agents.yaml      # 2 agenty: debater, judge
│       │   └── tasks.yaml       # 3 zadania: propose, oppose, decide
│       ├── tools/
│       │   └── custom_tool.py   # Przykład custom tool
│       ├── crew.py              # Klasa z dekoratorami
│       └── main.py              # Inputs i kickoff()
├── output/                      # Wyniki zadań (propose.md, oppose.md, decide.md)
├── pyproject.toml              # Zależności (crewai[tools]==1.5.0)
└── README.md

---

🚀 Komendy CLI

# Tworzenie projektu
crewai create crew my_project

# Instalacja zależności
crewai install

# Uruchomienie
crewai run

# Inne funkcje (z main.py)
python -m ai_agents_crewai_debate.main train <iterations> <filename>
python -m ai_agents_crewai_debate.main replay <task_id>
python -m ai_agents_crewai_debate.main test <iterations> <eval_llm>