Przewodnik programisty

Dwa sposoby rozwoju

Agent-Lab to framework, którego używasz jako biblioteki, a jednocześnie repozytorium, w którym możesz pracować bezpośrednio. Obie opcje są obsługiwane:

• Jako biblioteka (zalecane dla produktów). Dodaj btech-agent-lab do własnego projektu, zdefiniuj agentów, rozszerzając klasy bazowe, i złóż aplikację za pomocą create_app(). Framework rozszerzasz przez jego publiczne API — dziedziczenie, dekoratory i konfigurację — i nigdy nie edytujesz kodu frameworka. Zacznij od Samouczka lub Szybkiego startu, a następnie przeczytaj Rozszerzanie frameworka. Aby pominąć kod szablonowy, wygeneruj gotowy projekt konsumencki poleceniem uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (zobacz cookiecutter/README.md).
• W repozytorium (dla współtwórców i implementacji referencyjnej). Sklonuj repozytorium i dodawaj agentów w agent_lab/services/agent_types/, uruchamiaj dołączoną aplikację referencyjną oraz korzystaj z notatników i testów integracyjnych. W ten sposób rozwijane są wbudowani agenci. Zobacz Budowanie agentowych workflow.

Obie ścieżki korzystają z tych samych elementów składowych; różnica dotyczy wyłącznie tego, gdzie znajduje się twój kod. Wybierz tę, która pasuje do twojego projektu.

Konfiguracja środowiska

Instalacja

Agent-Lab jest przeznaczony dla Pythona 3.12+ i do zarządzania zależnościami używa uv.

Używanie Agent-Lab jako biblioteki — zainstaluj go we własnym projekcie:

pip install btech-agent-lab
# or
uv add btech-agent-lab

Praca w repozytorium — sklonuj je i zsynchronizuj środowisko:

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Upewnij się, że Docker lub inne środowisko uruchomieniowe kontenerów jest zainstalowane i uruchomione — korzystają z niego testy integracyjne (przez testcontainers), a dołączone pliki Docker Compose dostarczają zależności aplikacji.

Skopiuj przykładowy plik środowiskowy

cp .env.example .env

Ten plik zawiera klucze API dostawców AI oraz endpointy używane przez symulacje agentów. Każda zmienna jest opisana w Dokumentacji konfiguracji.

Implementacja referencyjna

Repozytorium zawiera kompletną aplikację referencyjną (agent_lab.main), która rejestruje wszystkich wbudowanych agentów — RAG, automatyzację przeglądarki, notatki głosowe, wizję i wieloagentowych nadzorców. Jest to zarówno produkt gotowy do wdrożenia, jak i kanoniczny przykład korzystania z frameworka: to nic więcej niż wywołanie create_app() na wbudowanych pakietach agentów.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

Używaj jej jako działającego wzorca podczas budowania własnej aplikacji oraz jako najszybszego sposobu na wypróbowanie Agent-Lab od początku do końca. Przygotowanie jej infrastruktury (trzech baz danych PostgreSQL, Redis, Keycloak, Vault) w środowisku deweloperskim lub produkcyjnym opisuje Przewodnik wdrażania. Następna sekcja pokazuje, jak uruchomić ją lokalnie.

Uruchamianie aplikacji

Uruchamianie aplikacji za pomocą Uvicorn

Na potrzeby programowania i debugowania w IDE uruchom aplikację referencyjną bezpośrednio:

uvicorn agent_lab.main:app --reload

Interaktywna dokumentacja OpenAPI jest dostępna pod adresem http://localhost:8000/docs.

Gdy używasz Agent-Lab jako biblioteki, swoją aplikację uruchamiasz w ten sam sposób — wskaż uvicorn moduł, który wywołuje create_app():

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Uruchamianie aplikacji za pomocą Docker Compose

Dwa wstępnie skonfigurowane pliki Docker Compose uruchamiają aplikację referencyjną razem ze stosem obserwowalności:

• compose-grafana.yml: aplikacja oraz Grafana, Prometheus, Tempo i Loki.
• compose-opensearch.yml: aplikacja oraz OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

Po uruchomieniu aplikacji API jest dostępne pod adresem http://localhost:18000/docs. Dashboardy obserwowalności:

• Grafana: http://localhost:3000 (domyślne dane logowania: admin/admin). Zobacz przykład z Grafana.
• OpenSearch Dashboards: http://localhost:5601. Zobacz przykład z OpenSearch.

Praktyki programistyczne

Wstrzykiwanie zależności

Aplikacja używa Dependency Injector do wstrzykiwania zależności, co pozwala rozdzielić odpowiedzialności i ułatwia testowanie.

Kontener jest zdefiniowany w agent_lab/core/container.py. Gdy używasz Agent-Lab jako biblioteki, utwórz podklasę Container, aby dodać własnych providerów, i przekaż jej instancję do create_app(container=...). Pracując w repozytorium, rejestruj dodatkowe usługi frameworka bezpośrednio w kontenerze.

Konfiguracja aplikacji

Konfiguracja jest ładowana przez ConfigSource (zobacz agent_lab/core/config.py) i wiązana z kontenerem DI. Framework zawiera trzy źródła YAML do programowania i testowania, wybierane automatycznie na podstawie zmiennej środowiskowej:

• config-dev.yml: środowisko deweloperskie, aktywowane, gdy ustawiono DEVELOPING — przeznaczone do debugowania w IDE.
• config-test.yml: środowisko testowe, aktywowane, gdy ustawiono TESTING — używane przez konfigurację testów integracyjnych.
• config-docker.yml: środowisko Docker Compose, aktywowane, gdy ustawiono DOCKER.

Te pliki definiują ustawienia takie jak połączenia z bazą danych i uwierzytelnianie i są przeznaczone wyłącznie do programowania i testowania. W środowisku produkcyjnym używaj Vault przez VaultConfigSource (domyślne, gdy nie ustawiono żadnej flagi środowiskowej). Aby dostarczać konfigurację z innego backendu, zaimplementuj własny ConfigSource i przekaż go do create_app(config_source=...). Każdy klucz konfiguracji i każda zmienna środowiskowa są opisane w Dokumentacji konfiguracji.

Model domeny encji

Model danych — encje i relacje między nimi używane w całej aplikacji — opisuje Model domeny encji.

Logowanie i obserwowalność

Aplikacja używa OpenTelemetry do logowania i obserwowalności; konfiguracja znajduje się w agent_lab/infrastructure/metrics/tracer.py. Wywołania FastAPI, HTTPX, LangChain, SQLAlchemy i OpenAI są instrumentowane od razu, z wymiennymi backendami dla Langfuse i LangWatch. Szczegóły znajdziesz w Przewodniku po obserwowalności.

Testowanie

Projekt używa pytest z naciskiem na testy integracyjne (próg pokrycia: 90%), wspieranego przez Testcontainers, dzięki czemu testy działają na prawdziwych usługach w kontenerach Docker. Osobny zestaw symulacji ocenia zachowanie agentów od początku do końca z LLM w roli sędziego.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

Pierwsze uruchomienie może potrwać kilka minut, ponieważ pobierane są obrazy Docker i modele embeddingów. Pełny obraz znajdziesz w przewodniku po testowaniu.

Inicjalizacja pre-commit

Jeśli planujesz współtworzyć kod lub budować nowych agentów na bazie Agent-Lab, zainstaluj hooki pre-commit:

pre-commit install

Dzięki temu twój kod będzie zgodny ze standardami kodowania projektu przed każdym commitem.

Budowanie agentowych workflow

Agent-Lab jest zbudowany na LangGraph, który zapewnia wydajny sposób budowania agentowych workflow z użyciem LLM. Dzięki modułowej architekturze i klasom bazowym agentów zbudowanie takiego workflow jest prostym procesem.

Zdefiniuj nową implementację agenta

Agent to kluczowe pojęcie w Agent-Lab, oznaczające autonomiczny byt, który potrafi wykonywać zadania, podejmować decyzje i wchodzić w interakcje z innymi agentami lub systemami zewnętrznymi. Agent jest konkretną implementacją jednej z klas bazowych:

Klasa rozszerzająca WorkflowAgentBase definiuje:

• workflow reprezentujący zachowanie agenta — zadania, podejmowanie decyzji oraz interakcje z innymi agentami lub systemami zewnętrznymi.
• parametry inicjalizacji, takie jak prompty (szablony Jinja2) i inne ustawienia dostosowujące zachowanie agenta (kolekcje magazynu wektorów, temperatura itd.).

Oto przykład utrwalonych parametrów inicjalizacji agenta, który wykonuje transkrypcję i analizę głosu, po utworzeniu agenta i zapisaniu go w bazie danych:

Przez REST API można tworzyć i dopracowywać wielu agentów opartych na tej samej implementacji.

Zarejestruj agenta za pomocą @discoverable_agent

Oznacz swoją podklasę AgentBase dekoratorem @discoverable_agent("<agent_type>"). Ten jeden dekorator to cała rejestracja, jakiej potrzebuje agent — sprawia, że agent jest:

• wykrywalny przez rejestr agentów (agent_lab/services/agent_types/registry.py),
• rozwiązywalny przez kontener DI, który leniwie tworzy jego instancję i wstrzykuje wszelkie zadeklarowane extra_deps,
• prawidłowy z punktu widzenia API, ponieważ schemat tworzenia agenta dynamicznie waliduje agent_type względem rejestru.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

Uwaga (migracja): wcześniejsze wersje wymagały ręcznego podpinania każdego agenta w container.py, dodawania go do registry.py i rozszerzania schematu Pydantic w agents/schema.py. Te kroki są przestarzałe — @discoverable_agent obsługuje je wszystkie. Wszelkie zadeklarowane extra_deps są rozwiązywane po nazwie z kontenera (być może podklasy) w momencie tworzenia instancji.

Jeśli agent potrzebuje współpracowników poza AgentUtils, udostępnij ich jako providerów w kontenerze (utwórz podklasę Container, gdy używasz biblioteki) i wymień ich nazwy w extra_deps.

Uczyń agenta wykrywalnym

Framework importuje tylko te moduły agentów, o których został poinformowany — dzięki temu dekorator zostaje wykonany:

• W repozytorium: umieść agenta w agent_lab/services/agent_types/ — aplikacja referencyjna skanuje ten pakiet w ramach DEFAULT_SCAN_PACKAGES (create_app()).

• Jako biblioteka: przekaż swój pakiet do create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — jawna lista zastępuje wartości domyślne (w ten sposób wykluczasz też wbudowane możliwości) — albo opublikuj go z zainstalowanego pakietu przez grupę entry pointów agent_lab.agents, aby konsumenci wykrywali go automatycznie:

  # pyproject.toml of the package that ships the agents
  [project.entry-points."agent_lab.agents"]
  my_agents = "my_agents"

Eksperymentowanie z implementacją agenta

Przykłady interaktywnego testowania agenta w Jupyter, z użyciem tego samego mechanizmu wstrzykiwania zależności, znajdziesz w notatnikach. To wygodny sposób na prototypowanie i walidację zachowania w kontrolowanym środowisku — zobacz Przewodnik badacza.

Interfejs agenta w REST API

Po zarejestrowaniu agenta tworzysz jego instancje i zarządzasz nimi przez REST API — możesz uruchomić kilka skonfigurowanych instancji tej samej implementacji, każdą z własnymi promptami i ustawieniami. Katalog endpointów i przykładowe żądania znajdziesz w Dokumentacji REST API.

Testowanie agenta

• Testy integracyjne (tests/integration/) walidują agenta na prawdziwej infrastrukturze za pomocą pytest i testcontainers.
• Symulacje (tests/simulation/) oceniają zachowanie od początku do końca z LLM w roli sędziego. Zobacz przewodnik po testowaniu.

Serwer MCP

Przewodnik po serwerze MCP opisuje, jak udostępniać agentów (i dodatkowe narzędzia) klientom MCP, takim jak Claude Desktop, na potrzeby wykrywania agentów, historii dialogów i komunikacji między agentami.

Rozszerzanie frameworka

Gdy używasz Agent-Lab jako biblioteki, kształtujesz aplikację wyłącznie przez create_app() i publiczne API eksportowane z pakietu najwyższego poziomu agent_lab — nigdy przez edycję kodu frameworka:

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

Wszystko powyżej jest eksportowane z agent_lab (zobacz agent_lab/__init__.py); pełna lista kluczy konfiguracji, z których korzystają te ustawienia, znajduje się w Dokumentacji konfiguracji.

Współtworzenie projektu

Wsparcie społeczności jest dla nas bardzo cenne. Jeśli napotkasz problem lub masz propozycje ulepszeń, zgłoś je, tworząc zgłoszenie na naszej stronie GitHub Issues.

Aby wnieść wkład w projekt, wykonaj następujące kroki:

1. Utwórz fork repozytorium.
2. Utwórz nową gałąź dla swojej funkcji lub poprawki błędu.
3. Aktywuj hooki pre-commit, uruchamiając pre-commit install, wprowadź zmiany i zatwierdź je z jasnymi i zwięzłymi komunikatami.
4. Upewnij się, że twoje zmiany przechodzą hooki pre-commit i próg pokrycia 90% (make test).
5. Wypchnij zmiany do swojego forka repozytorium.
6. Utwórz Pull Request (PR) do gałęzi main oryginalnego repozytorium.

Przejrzymy twój PR i przekażemy informację zwrotną. Dziękujemy za twój wkład i wsparcie!

Wdrożenie produkcyjne

Przewodnik wdrażania opisuje wdrażanie aplikacji referencyjnej w środowisku produkcyjnym za pomocą dołączonych chartów Helm i skryptów Terraform.