Przewodnik badacza

Dla kogo jest ten przewodnik

Dla badaczy AI i programistów, którzy chcą eksplorować, odtwarzać i rozszerzać eksperymenty w Agent-Lab. Jeśli piszesz w Pythonie, używasz Jupyter i myślisz kategoriami eksperymentów, agentów i pipeline'ów, poczujesz się tu jak w domu. Znajomość LLM, RAG i podstaw kontenerów jest pomocna, ale niewymagana.

Agent-Lab dostarcza komponenty wielokrotnego użytku (typy agentów, narzędzia, integracje) oraz zbiór notatników Jupyter z przykładami krok po kroku, dzięki czemu szybko zaczniesz efektywnie pracować.

Szybki start — uruchom przykłady

Wymagania: Python 3.12+, działające środowisko Jupyter (JupyterLab lub Notebook) oraz opcjonalnie lokalny Docker do kompleksowych integracji. Praca w klonie repozytorium:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

Otwórz notebooks/ i zacznij od 01_…, a potem przechodź przez te, które cię interesują.

Uwagi:

• Notatniki są w większości samodzielne; nagłówek każdego z nich określa wymagane zmienne środowiskowe i usługi zewnętrzne (klucze API, endpointy).
• Wymagane klucze znajdują się w .env — skopiuj .env.example i uzupełnij go (zobacz Dokumentację konfiguracji).
• Aby eksperymentować z Agent-Lab z poziomu własnego projektu zamiast repozytorium, wykonaj pip install btech-agent-lab i złóż aplikację za pomocą create_app() — zobacz sekcję Rozszerzanie frameworka w Przewodniku programisty.

Struktura projektu — krótki przegląd

• notebooks/ — interaktywne przykłady typów agentów, ewaluacji i integracji. Zacznij tutaj.
• agent_lab/ — pakiet frameworka:
  • app_factory.py — korzeń kompozycji: create_app().
  • core/ — źródła konfiguracji, kontener DI, rozwiązywanie extra_deps.
  • domain/ — modele, interfejsy repozytoriów, wyjątki (Model domeny encji).
  • services/ — logika biznesowa i implementacje w agent_types/.
  • interface/ — api/ (routery HTTP) i mcp/ (serwer MCP).
  • infrastructure/ — adaptery bazy danych, uwierzytelniania, metryk i śledzenia.
• tests/ — zestawy unit/, integration/, template/ i simulation/ (zobacz Testy i symulacje).
• doc/ — dokumentacja, którą właśnie czytasz.

Zrozumienie tych warstw pokazuje, gdzie znajduje się dane zachowanie: przykłady w notebooks, podstawowe kontrakty w core/ i domain/, a adaptery w infrastructure/.

Notatniki — główna ścieżka nauki

Typowa kolejność:

Każdy notatnik zawiera: krótki opis celu eksperymentu, wymagane zmienne środowiskowe i sekrety, funkcje pomocnicze oraz wyniki tekstowe i wizualne pozwalające przeanalizować decyzje i metryki agenta.

Wskazówka: uruchamiaj notatniki po kolei, aby stopniowo poszerzać wiedzę. Podczas iteracji używaj mniejszych zbiorów danych i prób, aby uruchomienia były szybkie.

Podstawowe pojęcia

• Agent — zarejestrowana implementacja w agent_lab/services/agent_types/ (@discoverable_agent). Rejestr rozwiązuje ją leniwie przez kontener DI, wstrzykując zadeklarowane extra_deps.
• Narzędzia — odrębne umiejętności, które agent może wywołać (wyszukiwanie, przeglądanie stron, TTS/ASR), zaimplementowane jako adaptery w agent_lab/infrastructure/ lub agent_lab/interface/.
• Container — obiekt kompozycji DI (agent_lab/core/container.py); utwórz jego podklasę, aby dodać providerów na potrzeby swoich eksperymentów.
• Repozytoria — interfejsy dostępu do danych w agent_lab/domain/repositories/.
• ConfigSource — źródło konfiguracji; w eksperymentach używaj źródeł YAML, a w środowisku produkcyjnym Vault.

Gdy chcesz zmodyfikować zachowanie, zdecyduj, czy zmiana jest: eksperymentalna (tylko notatnik), architektoniczna (core/domain/services) czy integracyjna (adapter w infrastructure). Preferuj małe, testowalne zmiany — i dodaj lub zaktualizuj notatnik, który pokazuje nowe zachowanie.

Prowadzenie eksperymentów i zapisywanie wyników

Notatniki wyświetlają kroki pośrednie; w przypadku solidniejszych eksperymentów:

• Używaj deterministycznych ziaren tam, gdzie losowość ma znaczenie.

• Zapisuj metryki istotne dla twojego pytania badawczego — opóźnienie, zużycie tokenów, liczbę wywołań narzędzi, oceny sędziego. Warstwa obserwowalności eksportuje wszystko jako OpenTelemetry (zobacz Obserwowalność); środowisko symulacji zapisuje oceny sędziego w Langfuse/LangWatch (zobacz Testy i symulacje).

• Aby uruchomienia były powtarzalne, eksportuj komórki notatnika do skryptów i uruchamiaj je w CI lub na węzłach obliczeniowych:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• docker/app/Dockerfile buduje obraz środowiska uruchomieniowego z przypiętymi wersjami, zapewniający powtarzalne wykonanie.

Prototypowanie nowych zachowań

1. Dodaj nowy typ agenta: utwórz klasę w agent_lab/services/agent_types/, oznacz ją dekoratorem @discoverable_agent("your_type") i dodaj notatnik, który podłącza ją przez kontener DI i sprawdza na małym scenariuszu. Pełny opis znajdziesz w sekcji Budowanie agentowych workflow.
2. Zmień dostawcę embeddingów: zaimplementuj zgodny adapter w agent_lab/infrastructure/ i zweryfikuj go notatnikiem 01.
3. Dodaj magazyn wyszukiwania lub wektorową bazę danych: zaimplementuj metody repozytorium w agent_lab/domain/repositories/ i adapter w agent_lab/infrastructure/database/; zasil go danymi za pomocą małego notatnika ładującego i zademonstruj wyszukiwanie w notatniku z zapytaniami.

Wskazówka projektowa: utrzymuj wąskie interfejsy adapterów i testuj je w izolacji małymi testami jednostkowymi.

Testowanie i ewaluacja

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

Gdy zmieniasz podstawowe zachowanie, dodaj test jednostkowy i krótki notatnik demonstrujący zmianę — to właśnie to połączenie sprawia, że badania są tu powtarzalne. Pełne środowisko testowe, konfigurację sędziego i platformy ewaluacyjne opisuje strona Testy i symulacje.

Lista kontrolna powtarzalności

• Przypnij wersje środowiska (uv + pyproject.toml / uv.lock).
• Zapisz ziarna i pliki konfiguracyjne (config-dev.yml, config-test.yml).
• Zachowaj checkpoint notatnika i wszelkie artefakty wyjściowe (CSV/JSON) razem z eksperymentem.
• Zanotuj endpointy śledzenia, do których eksportowano dane — ślady są dziennikiem twojego eksperymentu.