CrewAI - Narzędzia i Kontekst

📚 Podstawowe Informacje

Rozszerza projekt debaty o dwa kluczowe elementy:

1. Narzędzia (Tools) - agenci mogą używać zewnętrznych API
2. Kontekst (Context) - automatyczne przekazywanie wyników między zadaniami

Projekt: Badacz Finansowy - zespół, który bada firmę i tworzy raport

---

🔄 Porównanie: Projekt Debaty vs Projekt z Narzędziami

| Aspekt | Projekt Debaty | Projekt z Narzędziami | |--------|----------------|----------------------| | Agenty | debater, judge | researcher, analyst | | Zadania | propose, oppose, decide | research_task, analysis_task | | Narzędzia | ❌ Brak | ✅ SerperDevTool (wyszukiwanie) | | Kontekst | ❌ Brak | ✅ context: [research_task] | | Cel | Debatowanie | Badanie i raportowanie |

---

🛠️ Narzędzia (Tools) w CrewAI

Co to są Narzędzia?

Narzędzia to zewnętrzne funkcje, które agenci mogą wywoływać podczas wykonywania zadań. To jak dawać pracownikowi dodatkowe narzędzia do pracy.

Przykłady narzędzi:

• Wyszukiwanie w internecie (SerperDevTool)
• Kalkulacje
• Dostęp do baz danych
• Wywołania API

SerperDevTool - Wyszukiwanie w Internecie

Dlaczego Serper zamiast OpenAI Web Search Tool?

• ✅ Koszty: 2500 darmowych kredytów (vs płatne OpenAI)
• ✅ Jakość: Ustrukturyzowane wyniki Google Search
• ✅ Prostota: Łatwa integracja z CrewAI

Konfiguracja:

1. Rejestracja: Utwórz konto na Serper Dev
2. Klucz API: Uzyskaj klucz API
3. Dodaj do .env:

SERPER_API_KEY=twój_klucz_tutaj

1. Instalacja:

pip install crewai-tools

Użycie Narzędzia w Projekcie

1. Import i Inicjalizacja w crew.py

from crewai_tools import SerperDevTool

# Inicjalizacja narzędzia
search_tool = SerperDevTool()

2. Przypisanie do Agenta w crew.py

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

3. Konfiguracja w agents.yaml (Opcjonalnie)

researcher:
  role: >
    Starszy Badacz Finansowy dla {company}
  goal: >
    Badaj firmę, newsy i potencjalne możliwości dla {company} na rok {year}
  backstory: >
    Jesteś doświadczonym badaczem finansowym...
  llm: openai/gpt-4o-mini
  tools:
    - search_tool: search_tool  # Referencja do narzędzia

Uwaga: Narzędzie można dodać zarówno w crew.py (bezpośrednio) jak i w agents.yaml (przez referencję).

---

🔗 Kontekst (Context) w CrewAI

Co to jest Kontekst?

Kontekst to sposób automatycznego przekazywania wyników z jednego zadania do drugiego. To jak sztafeta - jeden agent przekazuje pałeczkę (wynik) następnemu.

W Tygodniu 2 (OpenAI Agents SDK):

• Kontekst był zarządzany ręcznie przez Runner
• Trzeba było zbierać wyniki i przekazywać je kolejnemu agentowi

W CrewAI:

• Kontekst jest zarządzany automatycznie przez Task
• Wystarczy zdefiniować context: [nazwa_zadania] w YAML

Mechanizm Działania

research_task:
  description: >
    Przeprowadź dokładne badanie firmy {company}...
  expected_output: >
    Kompleksowy dokument badawczy...
  agent: researcher

analysis_task:
  description: >
    Analizuj wyniki badań i stwórz kompleksowy raport...
  expected_output: >
    Dojrzały, profesjonalny raport...
  agent: analyst
  context:
    - research_task  # ⭐ Wynik research_task zostanie automatycznie przekazany!

Co się dzieje:

1. research_task jest wykonywane jako pierwsze (sekwencyjnie)
2. Wynik research_task jest automatycznie dodawany do promptu systemowego dla analysis_task
3. Agent analyst otrzymuje wyniki badań jako kontekst i może je wykorzystać

To jak automatyczna sztafeta! 🏃‍♂️➡️🏃‍♀️

---

📋 Pełna Konfiguracja Projektu

1. Agenty (agents.yaml)

researcher:
  role: >
    Starszy Badacz Finansowy dla {company}
  goal: >
    Badaj firmę, newsy i potencjalne możliwości dla {company} na rok {year}
  backstory: >
    Jesteś doświadczonym badaczem finansowym z talentem do znalezienia
    najbardziej istotnych informacji o {company} na rok {year}.
    Jesteś znany ze zdolności do znalezienia najbardziej istotnych
    informacji i prezentacji ich w jasny i zwięzły sposób. Zawsze odpowiadaj po polsku.
  llm: openai/gpt-4o-mini
  tools:
    - search_tool: search_tool

analyst:
  role: >
    Analityk Rynku i Pisarz Raportów skupiony na {company} na rok {year}
  goal: >
    Analizuj firmę {company} na rok {year} i stwórz kompleksowy, dobrze zorganizowany raport
    który prezentuje wyniki w jasny i angażujący sposób. Zawsze odpowiadaj po polsku.
  backstory: >
    Jesteś precyzyjnym, doświadczonym analitykiem z backgroundem w analizie finansowej
    i badaniu firm. Masz talent do identyfikowania wzorów i wyciągania
    istotnych wniosków z danych badawczych, a następnie komunikowania
    tych wniosków przez dobrze zorganizowane raporty na rok {year}.
  llm: openai/gpt-4o-mini

Kluczowe różnice od projektu debaty:

• ✅ researcher ma tools (narzędzie wyszukiwania)
• ✅ Używają szablonów {company} i {year}
• ✅ Specjalizacja: jeden bada, drugi analizuje

2. Zadania (tasks.yaml)

research_task:
  description: >
    Przeprowadź dokładne badanie firmy {company}. Skup się na:
    1. Aktualnym stanie i zdrowiu firmy
    2. Historycznych wynikach firmy
    3. Głównych wyzwaniach i możliwościach
    4. Ostatnich newsów i wydarzeń
    5. Przyszłymi perspektywach i potencjalnych rozwojach

    Upewnij się, że organizujesz swoje wyniki w strukturalnym formacie z jasnymi sekcjami.
  expected_output: >
    Kompleksowy dokument badawczy z dobrze zorganizowanymi sekcjami obejmującymi
    wszystkie żądane aspekty firmy {company}. Dołącz konkretne fakty, dane i przykłady, gdzie odpowiednie.
  agent: researcher

analysis_task:
  description: >
    Analizuj wyniki badań i stwórz kompleksowy raport na temat {company}.
    Twój raport powinien:
    1. Zaczynać się od podsumowania wykonawczego
    2. Zawierać wszystkie kluczowe informacje z badań
    3. Zapewniać przemyślane analizę trendów i wzorów
    4. Oferować perspektywę rynkową dla firmy, zwracając uwagę, że ta nie powinna być używana do decyzji handlowych
    5. Być sformatowany w profesjonalnym, łatwym do odczytania stylu z jasnymi nagłówkami
  expected_output: >
    Dojrzały, profesjonalny raport na temat {company}, który prezentuje wyniki badań z dodatkową analizą i wnioskami. Raport powinien być dobrze zorganizowany
    z podsumowaniem wykonawczym, głównymi sekcjami i wnioskiem.
  agent: analyst
  context:
    - research_task  # ⭐ KLUCZOWE: Wynik research_task jest przekazywany!
  output_file: output/report.md

Kluczowe elementy:

• ✅ research_task - bez kontekstu (pierwsze zadanie)
• ✅ analysis_task - z kontekstem [research_task]
• ✅ output_file - automatyczne zapisanie raportu

3. Orkiestracja (crew.py)

from typing import List
from crewai import Agent, Crew, Process, Task
from crewai.agents.agent_builder.base_agent import BaseAgent
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool

# Inicjalizacja narzędzia
search_tool = SerperDevTool()

@CrewBase
class AiAgentsCrewaiToolWebRaport:
    """AiAgentsCrewaiToolWebRaport crew"""
    
    agents: List[BaseAgent]
    tasks: List[Task]
    
    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config["researcher"],
            verbose=True,
            tools=[search_tool],  # ⭐ Narzędzie dodane tutaj!
        )
    
    @agent
    def analyst(self) -> Agent:
        return Agent(
            config=self.agents_config["analyst"],
            verbose=True,
            # Brak narzędzi - analyst nie potrzebuje wyszukiwać
        )
    
    @task
    def research_task(self) -> Task:
        return Task(
            config=self.tasks_config["research_task"],
        )
    
    @task
    def analysis_task(self) -> Task:
        return Task(
            config=self.tasks_config["analysis_task"],
            output_file="/output/report.md",  # Opcjonalnie można też tutaj
        )
    
    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,  # Zadania jedno po drugim
            verbose=True,
        )

Kluczowe różnice od projektu debaty:

• ✅ Import SerperDevTool
• ✅ Inicjalizacja search_tool
• ✅ researcher ma tools=[search_tool]
• ✅ analysis_task ma output_file (opcjonalnie w kodzie)

4. Uruchomienie (main.py)

from datetime import datetime
from ai_agents_crewai_tool_web_raport.crew import AiAgentsCrewaiToolWebRaport

def run():
    year = datetime.now().year
    inputs = {
        "company": "Orange",  # Szablon {company}
        "year": year          # Szablon {year}
    }
    
    AiAgentsCrewaiToolWebRaport().crew().kickoff(inputs=inputs)

Kluczowe:

• ✅ Dwa szablony: {company} i {year}
• ✅ Automatyczne wypełnianie przez inputs

---

🔄 Przepływ Pracy (Workflow)

1. Uruchomienie
   ↓
2. Wypełnienie szablonów ({company}, {year})
   ↓
3. Wykonanie research_task
   ├─ Agent: researcher
   ├─ Narzędzie: search_tool (wyszukiwanie w internecie)
   └─ Wynik: Dokument badawczy
   ↓
4. Automatyczne przekazanie kontekstu
   ↓
5. Wykonanie analysis_task
   ├─ Agent: analyst
   ├─ Kontekst: Wynik z research_task (automatycznie!)
   └─ Wynik: Profesjonalny raport
   ↓
6. Zapis do output/report.md

To jak automatyczna linia produkcyjna! 🏭

---

🎯 Kluczowe Różnice: Debaty vs Narzędzia

Projekt Debaty

• ❌ Brak narzędzi zewnętrznych
• ❌ Brak kontekstu między zadaniami
• ✅ Prosty przepływ: propose → oppose → decide
• ✅ Jeden agent wykonuje wiele zadań

Projekt z Narzędziami

• ✅ Narzędzie wyszukiwania (SerperDevTool)
• ✅ Kontekst między zadaniami (context: [research_task])
• ✅ Specjalizacja agentów (jeden bada, drugi analizuje)
• ✅ Zależności między zadaniami (analysis_task potrzebuje research_task)

---

💡 Najważniejsze Koncepcje

1. Narzędzia (Tools)

Definicja: Zewnętrzne funkcje, które agenci mogą wywoływać

Kiedy używać:

• Wyszukiwanie w internecie
• Dostęp do baz danych
• Kalkulacje
• Wywołania API

Jak dodać:

# W crew.py
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

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

2. Kontekst (Context)

Definicja: Automatyczne przekazywanie wyników między zadaniami

Kiedy używać:

• Gdy zadanie zależy od wyniku poprzedniego zadania
• Gdy chcesz przekazać dane między agentami

Jak dodać:

# W tasks.yaml
analysis_task:
  description: >
    Analizuj wyniki badań...
  agent: analyst
  context:
    - research_task  # Wynik research_task jest przekazywany!

Mechanizm:

1. Zadanie z context czeka na wykonanie zadań z listy
2. Wyniki są automatycznie dodawane do promptu systemowego
3. Agent otrzymuje kontekst jako część instrukcji

---

🛠️ Inne Dostępne Narzędzia CrewAI

CrewAI ma wiele wbudowanych narzędzi w pakiecie crewai-tools:

Popularne Narzędzia

1. SerperDevTool - Wyszukiwanie Google
2. WebsiteSearchTool - Wyszukiwanie na stronie
3. FileReadTool - Czytanie plików
4. DirectoryReadTool - Czytanie katalogów
5. YoutubeVideoSearchTool - Wyszukiwanie wideo YouTube
6. ExaSearchTool - Wyszukiwanie Exa

Instalacja

pip install crewai-tools

Użycie

from crewai_tools import (
    SerperDevTool,
    WebsiteSearchTool,
    FileReadTool
)

# Inicjalizacja
search_tool = SerperDevTool()
website_tool = WebsiteSearchTool()
file_tool = FileReadTool()

# Przypisanie do agenta
@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        tools=[search_tool, website_tool, file_tool],  # Wiele narzędzi!
    )

---

📝 Tworzenie Własnych Narzędzi (Custom Tools)

Możesz tworzyć własne narzędzia dziedzicząc z BaseTool:

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

class MyCustomToolInput(BaseModel):
    """Input schema for MyCustomTool."""
    query: str = Field(..., description="Zapytanie do przetworzenia")

class MyCustomTool(BaseTool):
    name: str = "my_custom_tool"
    description: str = "Dokładny opis zastosowania narzędzia. Agent będzie potrzebował tej informacji, aby z niego korzystać."
    args_schema: Type[BaseModel] = MyCustomToolInput
    
    def _run(self, query: str) -> str:
        # Twoja logika tutaj
        result = f"Przetworzono: {query}"
        return result

Użycie:

from tools.custom_tool import MyCustomTool

custom_tool = MyCustomTool()

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        tools=[custom_tool],
    )

---

⚙️ Zaawansowane: Różne Modele dla Różnych Agentów

Możesz przypisać różne modele LLM do różnych agentów:

researcher:
  llm: deepseek/deepseek-chat  # Tańszy, dobry do wyszukiwania

analyst:
  llm: openai/gpt-4o  # Droższy, lepszy do analizy i pisania

Zalety:

• ✅ Optymalizacja kosztów (tańszy model do prostszych zadań)
• ✅ Optymalizacja jakości (lepszy model do złożonych zadań)
• ✅ Elastyczność (każdy agent ma najlepszy model dla swojej roli)

Przykład z projektu:

• researcher - deepseek/deepseek-chat (wyszukiwanie wymaga skrupulatności)
• analyst - grok/mixtral-8x22b-instruct (synteza wymaga zdolności narracyjnych)

---

🔍 Debugowanie i Troubleshooting

Problem 1: "Tool not found"

Przyczyna: Narzędzie nie jest zainstalowane lub nie jest zaimportowane

Rozwiązanie:

pip install crewai-tools

from crewai_tools import SerperDevTool  # Sprawdź import

Problem 2: "Context task not found"

Przyczyna: W context używasz nazwy zadania, której nie ma

Rozwiązanie:

# ❌ Źle
context:
  - research  # Nie istnieje

# ✅ Dobrze
context:
  - research_task  # Zgodne z nazwą w tasks.yaml

Problem 3: "API Key not found"

Przyczyna: Brak klucza API w .env

Rozwiązanie:

# .env
SERPER_API_KEY=twój_klucz_tutaj
OPENAI_API_KEY=twój_klucz_tutaj

Problem 4: Narzędzie nie jest używane przez agenta

Przyczyna: Agent nie rozumie, kiedy użyć narzędzia

Rozwiązanie:

• Upewnij się, że description w zadaniu jasno wskazuje na potrzebę użycia narzędzia
• Sprawdź description narzędzia - musi być jasne, kiedy go użyć
• Użyj verbose=True aby zobaczyć, co agent robi

---

📊 Porównanie: Zarządzanie Kontekstem

| Aspekt | OpenAI Agents SDK (Tydzień 2) | CrewAI (Tydzień 3) | |--------|-------------------------------|-------------------| | Zarządzanie | Ręczne przez Runner | Automatyczne przez Task | | Przekazywanie | Trzeba zbierać wyniki i przekazywać | context: [task_name] w YAML | | Złożoność | Wysoka (kod Pythona) | Niska (deklaratywne YAML) | | Błędy | Łatwo zapomnieć o przekazaniu | Automatyczne, mniej błędów |

Zaleta CrewAI: Mniej kodu, mniej błędów, bardziej deklaratywne podejście!

---

🎯 Najważniejsze Do Zapamiętania

1. Narzędzia = zewnętrzne funkcje dla agentów (tools=[search_tool])
2. Kontekst = automatyczne przekazywanie wyników (context: [task_name])
3. SerperDevTool = wyszukiwanie Google (2500 darmowych kredytów)
4. Różne modele = optymalizacja kosztów i jakości
5. Zależności zadań = context automatycznie zarządza kolejnością
6. Output files = automatyczne zapisywanie wyników

---

🔄 Pełny Cykl Projektu z Narzędziami

| Etap | Akcja | Kluczowa Koncepcja | |------|-------|-------------------| | 1. Instalacja | pip install crewai-tools | Narzędzia zewnętrzne | | 2. Konfiguracja API | Dodaj SERPER_API_KEY do .env | Klucze API | | 3. Import narzędzia | from crewai_tools import SerperDevTool | Inicjalizacja | | 4. Przypisanie | tools=[search_tool] w agencie | Użycie narzędzia | | 5. Konfiguracja zadań | context: [research_task] | Przekazywanie kontekstu | | 6. Uruchomienie | crew().kickoff(inputs=inputs) | Automatyczna orkiestracja |

---

💻 Przykład: Pełny Kod Projektu

Struktura plików

ai_agents_crewai_tool_web_raport/
├── .env                    # SERPER_API_KEY, OPENAI_API_KEY
├── src/
│   └── ai_agents_crewai_tool_web_raport/
│       ├── config/
│       │   ├── agents.yaml  # Definicja agentów z tools
│       │   └── tasks.yaml   # Definicja zadań z context
│       ├── tools/
│       │   └── custom_tool.py  # Przykład custom tool
│       ├── crew.py         # Import i przypisanie narzędzi
│       └── main.py         # Inputs i kickoff
└── output/
    └── report.md           # Wynik analysis_task

Minimalny przykład działania

# crew.py
from crewai_tools import SerperDevTool
search_tool = SerperDevTool()

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        tools=[search_tool],  # Narzędzie
    )

# tasks.yaml
analysis_task:
  agent: analyst
  context:
    - research_task  # Kontekst

---

🚀 Następne Kroki

Po opanowaniu narzędzi i kontekstu możesz:

1. Dodać więcej narzędzi - kombinuj różne narzędzia
2. Złożone zależności - wiele zadań w context
3. Custom tools - stwórz własne narzędzia
4. Optymalizacja modeli - różne modele dla różnych zadań
5. Knowledge sources - dodaj źródła wiedzy do załogi

---

Podsumowanie: Narzędzia i kontekst to dwa kluczowe elementy, które sprawiają, że CrewAI jest potężnym narzędziem do budowania złożonych systemów agentowych. Narzędzia dają agentom możliwości, a kontekst zapewnia płynną współpracę między zadaniami! 🎉