Zbuduj AI PR Reviewer z 3 rownoleglymi subagentami w Pythonie

Code review to jedna z najcenniejszych — i najdrozszych — czynnosci w inzynierii oprogramowania.

Starszy programista spedza 2-4 godziny dziennie na przegladaniu pull requestow. To 10-20 godzin tygodniowo. Nie pisze kodu. Nie projektuje systemow. Nie mentoruje. Po prostu czyta diffy, sprawdza SQL injection, wypatruje zapytan N+1 i zostawia komentarze o brakujacych type hintach.

Pomnoz to przez zespol pieciu seniorow. To 50-100 godzin ludzkiego potencjalu tygodniowo, z czego spora czesc idzie na kontrole, ktore podazaja za wyraznymi, powtarzalnymi wzorcami.

Co by bylo, gdybys mogl zautomatyzowac powtarzalne czesci? Nie zastepowac seniora — wspierac go. Wylapywac oczywiste problemy zanim w ogole spojrzy na PR, zeby mogl skupic sie na architekturze, logice i designie.

Dokladnie to zbudowalismy. AI PR reviewer, ktory uruchamia trzech wyspecjalizowanych subagentow rownolegle — bezpieczenstwo, styl i wydajnosc — i zwraca ustrukturyzowany, posortowany wg priorytetu przeglad w okolo 30 sekund.

Oto jak to dziala i pelny dzialajacy kod, ktory mozesz uruchomic juz dzis.

Architektura: 3 specjalistow, 1 koordynator

Glowna idea jest prosta: zamiast jednego monolitycznego promptu “przejrzyj ten kod”, dzielimy przeglad na trzy domeny, kazda obslugiwana przez wyspecjalizowanego subagenta.

Security Reviewer — sprawdza:

Podatnosci na SQL injection
Cross-site scripting (XSS)
Zakodowane na sztywno sekrety i klucze API
Niebezpieczna deserializacja
Command injection
Niebezpieczne operacje na plikach

Style Reviewer — sprawdza:

Naruszenia konwencji nazewnictwa
Duplikacja kodu
Nadmierna zlozonosc cyklomatyczna
Brakujace type hinty
Pokrycie docstringami
Martwy kod i nieuzywane importy

Performance Reviewer — sprawdza:

Wzorce zapytan N+1
Niepotrzebne alokacje pamieci
Blokujace I/O w kontekstach async
Brakujace indeksy bazodanowe
Mozliwosci cachowania
Niezoptymalizowane petle i struktury danych

Kazdy subagent otrzymuje ten sam git diff, przeglada go przez swoja wyspecjalizowana optyka i zwraca ustrukturyzowane wyniki. Agent nadrzedny koordynuje ich — wysylajac wszystkich trzech rownolegle, a nastepnie agregujac wyniki w zunifikowany przeglad posortowany wg waznosci.

To jest wzorzec deep agent: koordynator, ktory planuje, deleguje do specjalistow i syntetyzuje wyniki. To ta sama architektura uzywana przez Claude Code, Codex i inne produkcyjne agenty kodujace — ale open-source i zbudowana na Pydantic AI.

Kod: ~40 linii, w pelni dzialajacy

Oto kompletna implementacja uzywajaca pydantic-deepagents:

import asyncio
from pydantic import BaseModel
from pydantic_deep import create_deep_agent, DeepAgentDeps, LocalBackend
from pydantic_deep.types import SubAgentConfig


class ReviewFinding(BaseModel):
    """A single finding from the code review."""
    file: str
    line: int
    severity: str   # critical, warning, info
    category: str   # security, style, performance
    description: str
    suggestion: str


# --- Define 3 specialist subagents ---

security_agent = SubAgentConfig(
    name="security-reviewer",
    description="Reviews code for security vulnerabilities",
    instructions=(
        "You are a security-focused code reviewer. "
        "Check for: SQL injection, XSS, hardcoded secrets, "
        "unsafe deserialization, command injection, insecure file ops. "
        "Return structured findings with file path, line number, "
        "severity (critical/warning/info), and a concrete fix suggestion."
    ),
)

style_agent = SubAgentConfig(
    name="style-reviewer",
    description="Reviews code style and conventions",
    instructions=(
        "You are a code style reviewer. "
        "Check for: naming convention violations, code duplication, "
        "excessive complexity, missing type hints, missing docstrings, "
        "dead code, unused imports. "
        "Return structured findings with file path, line number, "
        "severity, and a concrete improvement suggestion."
    ),
)

perf_agent = SubAgentConfig(
    name="performance-reviewer",
    description="Reviews code for performance issues",
    instructions=(
        "You are a performance-focused code reviewer. "
        "Check for: N+1 queries, unnecessary allocations, "
        "blocking I/O in async code, missing indexes, cache opportunities, "
        "unoptimized loops. "
        "Return structured findings with file path, line number, "
        "severity, and a concrete optimization suggestion."
    ),
)


# --- Create the coordinator agent ---

agent = create_deep_agent(
    "claude-sonnet-4-5",
    instructions=(
        "You are a senior code reviewer. "
        "Delegate to your 3 specialist subagents in parallel, "
        "then aggregate their findings into a unified review "
        "sorted by severity (critical first). "
        "Remove duplicates and add an overall summary."
    ),
    subagents=[security_agent, style_agent, perf_agent],
)


# --- Run the review ---

async def main():
    deps = DeepAgentDeps(backend=LocalBackend(root_dir="."))
    result = await agent.run(
        "Review the current git diff and provide a comprehensive code review. "
        "Focus on security vulnerabilities, style issues, and performance problems.",
        deps=deps,
    )
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

To wszystko. Ponizej 40 linii wlasciwej logiki. Rozlozmy to na czesci.

Jak to dziala, krok po kroku

1. Ustrukturyzowane wyjscie z Pydantic

Model ReviewFinding definiuje dokladnie, jak wyglada kazde znalezisko. Sciezka pliku, numer linii, poziom waznosci, kategoria, opis i konkretna sugestia. Zadnego tekstu swobodnego. Zadnego “moze warto rozwazyc…”. Ustrukturyzowane, parseowalne, mozliwe do dzialania dane.

To jedna z zalet budowania na Pydantic AI — wyjscie modelu jest walidowane w runtime. Jesli LLM zwroci znalezisko bez poziomu waznosci, zostanie to natychmiast wychwycone.

2. Trzy SubAgentConfig

Kazdy SubAgentConfig definiuje specjaliste:

name — unikalny identyfikator, ktorego agent nadrzedny uzywa do delegowania
description — mowi agentowi nadrzednemu kiedy uzywac tego subagenta (logika routingu)
instructions — system prompt dla subagenta, skupiony na jego domenie

Instrukcje sa konkretne. Nie mowimy “przejrzyj ten kod”. Mowimy “sprawdz SQL injection, XSS, zakodowane sekrety…” Ta konkretnosc sprawia, ze przeglady sa faktycznie uzyteczne. Kazdy subagent jest ekspertem w swojej domenie, nie generalist probujacy ogarnac wszystko.

3. Rownolegle wykonanie przez subagentow

Kiedy przekazujesz subagents=[security_agent, style_agent, perf_agent] do create_deep_agent(), agent nadrzedny dostaje narzedzia do delegowania zadan do kazdego subagenta. Agent nadrzedny decyduje jak ich orkiestrowac — a poniewaz instrukcje mowia “deleguj rownolegle”, wszystkie trzy uruchamiaja sie jednoczesnie.

To jest fundamentalnie rozne od lancuchow sekwencyjnych. Zamiast czekac az przeglad bezpieczenstwa sie zakonczy przed rozpoczeciem przegladu stylu, wszystkie trzy dzialaja rownolegle. Dlatego dostajesz wyniki w ~30 sekund zamiast ~90 sekund.

4. LocalBackend do dostepu do plikow

LocalBackend(root_dir=".") daje agentowi (i jego subagentom) dostep do odczytu twojego lokalnego systemu plikow. Subagenty moga czytac git diff, sprawdzac konkretne pliki dla kontekstu i rozumiec strukture codebase’u.

Jesli chcesz zamiast tego sandboxowane wykonanie, zamien LocalBackend na StateBackend() (w pamieci) lub DockerSandbox() (w kontenerze). Kod agenta pozostaje ten sam — zmienia sie tylko backend.

5. Agregacja przez agenta nadrzednego

Instrukcje agenta nadrzednego mowia mu, zeby agregowal, deduplikowal i sortowal wg waznosci. Jesli wiec przeglad bezpieczenstwa i przeglad stylu oba flaguja ta sama linie (np. zakodowany klucz API to zarowno problem bezpieczenstwa jak i stylu), agent nadrzedny laczy je w jedno znalezisko z najwyzszym priorytetem.

Wyjscie to czysty, priorytetyzowany przeglad — krytyczne problemy najpierw, ostrzezenia nastepnie, informacyjne notatki na koncu.

Jak wyglada wyjscie

Oto przyklad tego, co reviewer produkuje uruchomiony na prawdziwym PR:

## Code Review Summary

**Files reviewed:** 4
**Total findings:** 7 (2 critical, 3 warning, 2 info)

### Critical

1. **[SECURITY]** `api/auth.py:42` — SQL query built with f-string interpolation.
   Vulnerable to SQL injection.
   → Use parameterized queries: `cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))`

2. **[SECURITY]** `config.py:15` — AWS secret key hardcoded in source.
   → Move to environment variable: `os.environ["AWS_SECRET_KEY"]`

### Warning

3. **[PERFORMANCE]** `api/users.py:78` — Querying user.posts inside a loop (N+1 pattern).
   → Use `selectinload(User.posts)` in the initial query.

4. **[STYLE]** `api/users.py:23-45` — Function `process_user_data` is 67 lines with 8 branches.
   Cyclomatic complexity too high.
   → Extract validation logic into separate function.

5. **[PERFORMANCE]** `api/export.py:31` — Building CSV by string concatenation in loop.
   → Use `io.StringIO` or `csv.writer` for O(n) instead of O(n^2).

### Info

6. **[STYLE]** `models/user.py:12` — Missing type hints on `calculate_score` parameters.
   → Add: `def calculate_score(self, weights: list[float], threshold: float = 0.5) -> float:`

7. **[STYLE]** `api/auth.py:1-5` — `import os, sys, json` — unused imports `sys` and `json`.
   → Remove unused imports.

Kazde znalezisko ma plik, numer linii, kategorie i konkretna poprawke. Senior moze przeskanowac to w 30 sekund i zdecydowac, ktore znaleziska zaakceptowac, ktore zmodyfikowac, a ktore odrzucic.

Uruchamianie: jako skrypt lub slash command

Samodzielny skrypt

Zapisz powyzszy kod jako review.py i uruchom:

pip install pydantic-deep
python review.py

Agent czyta biezacy katalog, pobiera git diff i wypisuje przeglad.

Jako slash command pydantic-deep

Jesli uzywasz pydantic-deepagents jako CLI (jak Claude Code), mozesz zarejestrowac to jako slash command:

# Uruchom wbudowana komende review
pydantic-deep review

Agent dziala w twoim terminalu, czyta twoj katalog roboczy i wypisuje przeglad inline.

W CI/CD (GitHub Actions)

- name: AI Code Review
  run: |
    pip install pydantic-deep
    python review.py > review.md

- name: Post Review Comment
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const review = fs.readFileSync('review.md', 'utf8');
      github.rest.issues.createComment({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        body: review
      });

Teraz kazdy PR automatycznie dostaje AI review zanim czlowiek w ogole na niego spojrzy.

Dlaczego 3 subagenty zamiast 1 promptu?

Mozesz sie zastanawiac: dlaczego nie dac jednemu agentowi jednego promptu, ktory mowi “przejrzyj ten kod pod katem bezpieczenstwa, stylu i wydajnosci”?

Trzy powody:

1. Specjalizacja wygrywa z generalizacja. Kiedy prosisz jeden LLM o robienie wszystkiego, ma tendencje do bycia szerokim i plytkim. Prompt skupiony na bezpieczenstwie z konkretnymi wzorcami podatnosci produkuje bardziej dokladne znaleziska niz generyczny prompt “przejrzyj ten kod”.

2. Rownolegle wykonanie. Trzy subagenty dzialaja jednoczesnie. Jeden agent robiacy trzy przejscia dziala sekwencyjnie. W skali to roznica miedzy 30-sekundowymi a 2-minutowymi przegladami.

3. Niezalezne skalowanie. Chcesz dodac czwartego subagenta do kontroli dostepnosci? Albo piatego do walidacji kontraktow API? Po prostu dodaj kolejny SubAgentConfig. Agent nadrzedny automatycznie obsluguje koordynacje. Mozesz tez zmieniac modele per subagent — szybszy model do kontroli stylu, mocniejszy do analizy bezpieczenstwa.

Szerszy obraz: wzorzec Deep Agent

Ten PR reviewer to jeden przyklad wzorca deep agent — tej samej architektury zasilajcej Claude Code, OpenAI Codex i Cursor za kulisami.

Wzorzec:

Planuj — rozbij zlezone zadanie na podzadania
Deleguj — wyslij podzadania do specjalistow (subagentow)
Wykonaj — kazdy specjalista pracuje niezaleznie ze swoimi narzediami
Syntetyzuj — agent nadrzedny agreguje wyniki w spojne wyjscie

pydantic-deepagents to open-source implementacja tego wzorca, zbudowana na Pydantic AI. To framework, ktorego uzywamy w Vstorm do wysylania produkcyjnych agentow AI — a PR reviewer to jedna z najprostszych rzeczy, ktore mozesz z nim zbudowac.

Wyprobuj

Repozytorium: pydantic-deepagents na GitHub
Instalacja: pip install pydantic-deep
Pakiet subagentow: subagents-pydantic-ai
Dokumentacja: pydantic-deep.vstorm.co

Kod PR reviewera z tego artykulu jest w katalogu examples/. Sklonuj go, wskazan na swoje repo i zobacz, co znajdzie.

Jesli juz robisz code review recznie, sprobuj uruchomic to obok istniejacego procesu przez tydzien. Porownaj znaleziska. Mozesz byc zaskoczony ile problemow AI wylapuje, ktore ludzie pomijaja — szczegolnie te nudne, opartych na dopasowywaniu wzorcow jak zapytania N+1 i brakujace type hinty.

Ludzie w twoim zespole powinni przegladac architekture, logike i design. Niech subagenty zajma sie checklista.

Jestem Kacper, AI Engineer w Vstorm — Applied Agentic AI Engineering Consultancy. Budujemy i udostepniamy na open-source produkcyjne narzedzia do agentow AI w Pythonie. Daj gwiazdke pydantic-deepagents na GitHub, jesli uznasz to za przydatne.