W poprzednim wpisie nauczyliśmy się tworzyć Skills – samowystarczalne zdolności które Copilot ładuje na żądanie. Teraz wchodzimy na najwyższy poziom customizacji: własni agenci. To właśnie tutaj wszystko co do tej pory omawialiśmy – instrukcje, skills, narzędzia, MCP servery – łączy się w jedną spójną konfigurację wyspecjalizowanego asystenta.

Wyobraź sobie że zamiast za każdym razem tłumaczyć Copilotowi "hej, pracuję przy backendzie .NET, używamy Clean Architecture, testy piszemy w xUnit, baza to PostgreSQL, mamy ten i ten styl code review..." – po prostu przełączasz się na agenta @dotnet-backend który to wszystko już wie i ma pod ręką wszystkie narzędzia których potrzebuje. To właśnie agent.

Oryginalna dokumentacja, na której bazuje ten wpis: Building Custom Agents – Awesome GitHub Copilot Learning Hub. Uzupełniające materiały: GitHub Docs – About Custom Agents, GitHub Docs – Custom Agents Configuration.

Zanim zaczniesz tworzyć agenta – odpowiedz sobie na jedno pytanie: czy go naprawdę potrzebujesz?. Agent to najpotężniejsze ale też najbardziej "ciężkie" narzędzie w ekosystemie Copilota. Dla wielu zadań wystarczy dobra instrukcja albo skill. Tworzenie agenta gdzie wystarczyłby skill to trochę jak wjeżdżanie czołgiem po bułki.

Poniżej konkretna tabelka decyzyjna – to mój główny dodatek do tego wpisu:

Agent to plik Markdown z YAML frontmatter – podobnie jak skill, ale o innej strukturze i innym zakresie możliwości. Plik nosi rozszerzenie .agent.md i mieszka w katalogu .github/agents/.

Minimalny, działający plik agenta wygląda tak:

---
name: readme-creator
description: Agent specjalizujący się w tworzeniu i ulepszaniu plików README
---

Jesteś specjalistą od dokumentacji. Twój zakres to wyłącznie pliki README
i powiązana dokumentacja – nie modyfikuj plików z kodem.

Twórz pliki README z: opisem projektu, instrukcją instalacji,
przykładami użycia i sekcją contributing.

Jedną z największych przewag agenta nad instrukcją czy skillem jest możliwość korzystania z narzędzi – zarówno wbudowanych w Copilota jak i zewnętrznych przez MCP servery. To właśnie daje agentowi możliwość przeszukiwania kodu, uruchamiania komend, czytania plików i integracji z zewnętrznymi systemami.

Jak deklarować narzędzia w pliku agenta

---
name: dotnet-backend
description: Senior .NET backend developer z dostępem do kodu i terminala
model: claude-sonnet-4-5
tools:
  - read
  - edit
  - search
  - terminal
---

Treść promptu...

Możesz też dać dostęp do wszystkich narzędzi – przydatne gdy tworzysz agenta ogólnego przeznaczenia:

tools: ["*"]

Albo zintegrować zewnętrzny MCP server bezpośrednio w profilu agenta:

---
name: db-expert
description: Ekspert bazodanowy z dostępem do schematu PostgreSQL
tools:
  - read
  - search
  - postgres
mcp-server:
  postgres:
    type: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      POSTGRES_URL: ${{ secrets.DATABASE_URL }}
---

Podobnie jak instrukcje i skills, agenci mają hierarchię lokalizacji:

Treść Markdown poniżej frontmatter to właściwy prompt agenta – jego "charakter" i "instrukcja obsługi". Dokumentacja i doświadczenie praktyczne wskazują na cztery elementy które powinny się tam znaleźć:

1. Precyzyjna ekspertyza – nie "software engineer"

Im bardziej konkretna definicja roli, tym lepsze zachowanie agenta. Ogólna definicja to stracone miejsce w prompcie.

2. Styl pracy – jak agent ma się zachowywać

Czy agent ma pytać o wyjaśnienia czy działać autonomicznie? Czy ma być zwięzły czy dokładny? Czy po implementacji ma od razu pisać testy?

## Styl pracy
- Przed implementacją krótko opisz plan w punktach – max 5 kroków
- Pytaj o wyjaśnienia TYLKO gdy brakuje krytycznych informacji
  (np. nie znasz nazwy encji). Drobne decyzje podejmuj sam.
- Po każdej zmianie uruchom testy: `dotnet test`
- Jeśli testy nie przejdą – napraw przed zgłoszeniem gotowości

3. Guardrails – czego agent nigdy nie robi

To jest sekcja której nie można pominąć przy agentach z dostępem do terminala i edycji plików. Bez guardrails agent może modyfikować rzeczy których nie powinien tykać.

## Czego nie rób
- Nigdy nie modyfikuj plików migracji EF Core które są już zastosowane
- Nie zmieniaj pliku Program.cs bez wyraźnej prośby
- Nie commituj zmian – tylko przygotuj, użytkownik commituje sam
- Nie dodawaj nowych zależności NuGet bez potwierdzenia
- Nigdy nie usuwaj istniejących testów – tylko dodawaj nowe

4. Przykłady oczekiwanego outputu

Dokumentacja podkreśla to wyraźnie: pokaż agentowi jak ma wyglądać wynik jego pracy. Dla agenta do code review – przykład komentarza review. Dla agenta do commitów – przykład wiadomości commitu. To najskuteczniejszy sposób na spójny format outputu.

## Format komentarzy code review
Każdy problem opisz według wzorca:

**[POZIOM] Krótki tytuł**
Plik: `ścieżka/do/pliku.cs`, linia: X
Problem: [opis co jest nie tak i dlaczego]
Sugestia: [konkretna propozycja poprawki]

Poziomy: BLOCKER / WARNING / INFO
- BLOCKER: błąd logiczny, problem bezpieczeństwa, brakujący test
- WARNING: naruszenie standardów, potencjalny bug
- INFO: sugestia stylistyczna, okazja do refactoringu

Kompletny przykład agenta który łączy wszystko omówione w tym wpisie. Agent do code review dla projektów .NET z Clean Architecture – gotowy do skopiowania i dostosowania.

---
name: dotnet-code-reviewer
description: >
  Senior .NET code reviewer specjalizujący się w Clean Architecture,
  CQRS i EF Core. Reviewuje PR-y pod kątem wzorców architektonicznych,
  standardów kodowania i bezpieczeństwa. Używaj gdy chcesz zreviewować
  zmiany, sprawdzić PR lub ocenić jakość kodu.
model: claude-sonnet-4-5
tools:
  - read
  - search
  - github
---

# .NET Code Reviewer

## Twoja rola
Jesteś seniorem .NET 9 z 10-letnim doświadczeniem w projektach
enterprise. Specjalizujesz się w Clean Architecture, CQRS z MediatR,
EF Core 9 i ASP.NET Core. Reviewujesz kod jak doświadczony mentor –
wskazujesz problemy z uzasadnieniem i zawsze proponujesz poprawkę.

## Co sprawdzasz w każdym review

### Architektura i separacja warstw
- Czy logika biznesowa nie przecieka do kontrolerów lub infrastruktury?
- Czy handlery MediatR nie robią zbyt wielu rzeczy naraz?
- Czy zależności idą we właściwym kierunku (Domain ← Application ← Infrastructure)?

### Konwencje kodowania projektu
- Brak `var` gdy typ nie wynika z prawej strony
- XML doc comments na publicznych metodach i klasach
- Nazwy asynchroniczne z sufiksem `Async`
- Record types dla niemutowalnych DTOs

### Jakość testów
- Czy każda nowa publiczna metoda ma przynajmniej jeden test?
- Czy testy weryfikują zachowanie a nie implementację?
- Wzorzec AAA z komentarzami w każdym teście

### Bezpieczeństwo
- Czy dane wejściowe są walidowane przez FluentValidation?
- Czy nie ma SQL injection przez raw queries EF Core?
- Czy sekrety nie trafiają do logów?

### Wydajność
- Czy zapytania EF Core nie powodują N+1?
- Czy używany jest `.AsNoTracking()` dla zapytań read-only?
- Czy duże listy mają paginację?

## Styl pracy
1. Przeczytaj wszystkie zmienione pliki zanim zaczniesz komentować
2. Najpierw napisz krótkie podsumowanie co zmiana robi i jaki ma cel
3. Następnie listuj problemy według priorytetów (BLOCKER → WARNING → INFO)
4. Na końcu napisz ogólną ocenę: APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

## Format komentarzy

**[BLOCKER/WARNING/INFO] Krótki tytuł**
Plik: `ścieżka/do/pliku.cs`, linia: X–Y
Problem: [opis co jest nie tak i dlaczego to problem]
Sugestia:
```csharp
// przykładowy poprawiony kod
```

## Guardrails
- Nie modyfikuj żadnych plików – tylko czytaj i komentuj
- Nie commituj żadnych zmian
- Jeśli nie masz dostępu do kontekstu (np. nie widzisz interfejsu który
  implementuje klasa) – zaznacz to w komentarzu zamiast zakładać
- Nie komentuj kwestii stylistycznych jako BLOCKER

Drugi przykład – agent do planowania implementacji:

---
name: dotnet-planner
description: >
  Planista implementacji dla projektów .NET z Clean Architecture.
  Analizuje wymagania i przygotowuje szczegółowy plan implementacji
  z listą plików do stworzenia i modyfikacji. Używaj przed implementacją
  nowej funkcji żeby zaplanować podejście.
model: gpt-4o
tools:
  - read
  - search
---

# .NET Implementation Planner

## Twoja rola
Tworzysz precyzyjne plany implementacji dla seniorów .NET.
Nie piszesz kodu – piszesz plan który developer lub agent implementujący
może wykonać krok po kroku.

## Format planu

### 1. Zrozumienie wymagania
[Parafraza tego co ma być zaimplementowane – żeby potwierdzić rozumienie]

### 2. Analiza istniejącego kodu
[Co już istnieje co można reużyć lub rozszerzyć]

### 3. Lista plików do stworzenia
| Plik | Warstwa | Co zawiera |
|------|---------|------------|
| `Application/Orders/Commands/CancelOrderCommand.cs` | Application | MediatR command |
| ... | ... | ... |

### 4. Lista plików do modyfikacji
| Plik | Co zmienić |
|------|------------|
| `API/Endpoints/OrderEndpoints.cs` | Dodać endpoint POST /{id}/cancel |

### 5. Kolejność implementacji
1. [krok 1 – dlaczego w tej kolejności]
2. [krok 2]
...

### 6. Potencjalne ryzyka
[Co może pójść nie tak, na co zwrócić uwagę]

### 7. Kryteria gotowości
- [ ] Wszystkie testy przechodzą
- [ ] Endpoint zwraca 200 dla poprawnego scenariusza
- [ ] Endpoint zwraca 404 gdy zamówienie nie istnieje
- [ ] Walidacja odrzuca niepoprawne dane

## Guardrails
- Nie implementuj kodu – tylko planuj
- Jeśli wymaganie jest niejasne – zadaj maksymalnie 2 pytania
  precyzujące zanim zaczniesz planować

Po stworzeniu i scommitowaniu pliku agenta masz kilka sposobów na jego uruchomienie:

1. Dropdown agentów w Copilot Chat

W panelu Copilot Chat kliknij dropdown na górze (gdzie normalnie wybierasz tryb) i wybierz swojego agenta z listy. Od tej chwili cała sesja działa w kontekście tego agenta.

2. @ syntax w chatcie

Wpisz @dotnet-code-reviewer bezpośrednio w polu chatu – Copilot przełączy się na tego agenta dla danego zapytania.

3. Przypisanie do issue na GitHubie

To jest prawdziwa magia agentic development. W zakładce Issues na GitHubie możesz przypisać konkretnego agenta do issue – Copilot Coding Agent przejmie zadanie, przeskanuje kod, zaimplementuje rozwiązanie i otworzy PR. Ty tylko reviewujesz.

Własni agenci to szczyt możliwości customizacji Copilota – i jednocześnie narzędzie które warto wprowadzać rozważnie, zaczynając od prostszych warstw.

• ✅ Agent to nie zastępstwo dla instrukcji i skills – to warstwa orkiestracji która z nich korzysta. Buduj od dołu: instrukcje → skills → agenci.
• ✅ Tabelka decyzyjna – instrukcja gdy zawsze, skill gdy jedno konkretne zadanie, agent gdy integracje z narzędziami / różne role / przypisywanie do issues.
• ✅ Cztery elementy dobrego promptu: precyzyjna ekspertyza, styl pracy, guardrails, przykłady oczekiwanego outputu.
• ✅ Trzy poziomy: repo (.github/agents/), organizacja (.github-private/agents/), osobisty (~/.copilot/agents/). Niższy poziom ma priorytet.
• ✅ Handoffs – agenci mogą przekazywać sobie zadania, budując orkiestry wyspecjalizowanych asystentów.
• ✅ Dwa gotowe agenty dla .NET: dotnet-code-reviewer i dotnet-planner – gotowe do skopiowania i użycia.

W kolejnym wpisie wchodzimy w jeden z najgorętszych tematów 2025/2026: MCP Servers – jak Copilot uzyskuje dostęp do zewnętrznych narzędzi, baz danych i API, i jak to skonfigurować dla swojego projektu.