Semantic Kernel i jego następca w ekosystemie .NET

Semantic Kernel, czyli biblioteka, która doczekała się następcy

Semantic Kernel powstał jako odpowiedź Microsoftu na pytanie, jak wpiąć modele językowe do aplikacji w ekosystemie .NET, nie porzucając rzeczy, których wymaga oprogramowanie firmowe: wstrzykiwania zależności, telemetrii, typowania i warstw pośrednich.

W kwietniu 2026 roku Microsoft wydał Agent Framework w wersji 1.0 i wskazał go jako następcę, łącząc w nim dorobek dwóch własnych projektów. Semantic Kernel nadal dostaje wydania i ma dużą społeczność, ale kierunek jest jasny i przy nowym projekcie trzeba to uwzględnić.

Ten tekst opisuje oba: co daje starsza biblioteka, co zmienia następca i kiedy migracja ma sens.

Model pojęciowy

Podstawą jest jądro, czyli kontener łączący modele, wtyczki i usługi pomocnicze. Wygląda to jak kontener wstrzykiwania zależności, znany z tego ekosystemu, i to nie przypadek.

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(deployment, endpoint, apiKey);
builder.Plugins.AddFromType<ZamowieniaPlugin>();

var kernel = builder.Build();

Wtyczka to klasa z metodami oznaczonymi atrybutem, które model może wywołać. Opis metody i jej parametrów pochodzi z atrybutów, więc schemat powstaje z kodu, a nie z osobnego pliku.

public class ZamowieniaPlugin
{
    [KernelFunction, Description("Zwraca status zamowienia o podanym numerze.")]
    public async Task<string> PobierzStatus(
        [Description("numer zamowienia")] string numer)
        => await _baza.StatusAsync(numer);
}

Opis w atrybucie nie jest komentarzem dla programisty, tylko tekstem, który czyta model. Zdanie mówiące, kiedy wywołać metodę, poprawia trafność mocniej niż jakakolwiek zmiana instrukcji systemowej, i to jest najtańsza optymalizacja dostępna w tej bibliotece.

Co zmienia następca

Nowy framework upraszcza to, co w starszej bibliotece wymagało ceremonii, zachowując rzeczy potrzebne w oprogramowaniu firmowym.

Największa zmiana dotyczy narzędzi. Zamiast klasy wtyczki z atrybutami można przekazać zwykłą metodę, a schemat powstaje z jej sygnatury. Przy trzech narzędziach to różnica między jedną linią a osobnym plikiem.

Druga zmiana to uproszczenie modelu pojęciowego. Jądro jako osobny kontener przestaje być obowiązkowe, bo agenta tworzy się bezpośrednio, a zależności wstrzykuje standardowym mechanizmem tego ekosystemu.

Trzecia to połączenie dorobku dwóch projektów. Wcześniej Microsoft rozwijał równolegle bibliotekę do wpinania modeli i osobny projekt do rozmów wieloagentowych, co zmuszało do wyboru albo do łączenia obu. Teraz jest to jedna rzecz.

Czwarta to wsparcie długoterminowe. Wydanie oznaczone jako produkcyjne z zapowiedzią stabilności interfejsów jest w tym ekosystemie argumentem samym w sobie, bo aplikacje firmowe żyją latami.

Migracja

Przejście nie jest przepisaniem aplikacji, ale też nie jest podmianą zależności.

Kod wywołujący model przenosi się prosto, bo pojęcia są zbliżone: agent z instrukcją, wątek rozmowy, narzędzia. Kod wtyczek wymaga zmiany, choć w kierunku uproszczenia, bo klasa z atrybutami zamienia się w zwykłe metody.

Największej uwagi wymagają rzeczy zbudowane wokół jądra: własne usługi rejestrowane w kontenerze, filtry przechwytujące wywołania i konfiguracja przekazywana przez kontener. Tu trzeba przemyśleć, gdzie te elementy trafią w nowym układzie.

Praktyczna kolejność wygląda tak. Najpierw przenieś jeden agent na nowy framework i uruchom go obok istniejącego, bo obie biblioteki mogą działać w tej samej aplikacji. Potem przenieś resztę, sprawdzając zachowanie na tym samym zestawie przypadków. Na końcu usuń starą zależność.

Microsoft udostępnia przewodnik migracji opisujący odpowiedniki pojęć, więc warto zacząć od niego, zanim zaczniesz zgadywać.

Kiedy zostać przy starym

Nie każdy projekt musi migrować i warto to powiedzieć wprost.

Aplikacja działająca stabilnie, z zamkniętym zakresem zmian, nie zyska nic poza pracą. Starsza biblioteka nadal dostaje wydania i nie zniknie z dnia na dzień, więc odłożenie decyzji na kolejny rok jest uzasadnione.

Migracja ma sens, gdy planujesz rozbudowę, gdy uwiera Cię ceremonia wokół wtyczek albo gdy potrzebujesz rzeczy dostępnych wyłącznie w nowym frameworku. Ma też sens przy projekcie startującym teraz, bo pisanie nowego kodu na bibliotece ze wskazanym następcą to dług zaciągany świadomie.

Trzecim czynnikiem jest zespół. Jeśli nikt w zespole nie zna żadnej z tych bibliotek, wybór następcy jest oczywisty. Jeśli zespół zna starszą i ma na niej działające wdrożenia, koszt uczenia się warto uwzględnić, choć pojęcia są na tyle zbliżone, że to raczej dni niż tygodnie.

Warto też ustalić termin przeglądu decyzji zamiast odkładać ją bezterminowo. Data w kalendarzu za pół roku, przy której sprawdzasz stan obu bibliotek, kosztuje nic, a chroni przed sytuacją, w której migracja staje się pilna dopiero wtedy, gdy przestaje działać zależność.

Wywoływanie narzędzi w praktyce

Niezależnie od wybranej biblioteki obowiązują te same zasady, bo wynikają z tego, jak działa model, a nie z konkretnego rozwiązania.

Opis narzędzia decyduje o trafności bardziej niż wszystko inne. Model widzi wyłącznie nazwę, opis i schemat parametrów, więc zdanie mówiące wprost, kiedy narzędzie wywołać, jest ważniejsze niż opis implementacji.

Liczba narzędzi ma znaczenie. Model wybierający spośród czterech myli się rzadziej niż wybierający spośród dwudziestu, więc podział na kilku wyspecjalizowanych agentów bywa lepszy niż jeden z pełnym zestawem.

Uprawnienia egzekwuj w kodzie narzędzia, nie w instrukcji. Identyfikator użytkownika powinien pochodzić z kontekstu wywołania, a nie z parametru, który model może podać dowolnie. To ta sama zasada, co przy OpenAI Agents SDK i przy każdej innej bibliotece agentowej.

Limity są obowiązkowe. Agent bez ograniczenia liczby kroków potrafi wywoływać to samo narzędzie w pętli, a bez limitu czasu zawiesić się na wywołaniu, które nie wraca.

Warstwy pośrednie i telemetria

To obszar, w którym biblioteki z tego ekosystemu wygrywają z alternatywami, bo odpowiadają na potrzeby, które w oprogramowaniu firmowym pojawiają się od pierwszego dnia.

Warstwa pośrednia pozwala przechwycić wywołanie modelu albo narzędzia i coś z nim zrobić: zapisać, zmierzyć, odrzucić, ponowić. To ten sam wzorzec, co w potoku żądań serwera, więc zespół zna go bez uczenia się.

public class LimitKosztuMiddleware : IFunctionInvocationFilter
{
    public async Task OnFunctionInvocationAsync(
        FunctionInvocationContext context, Func<FunctionInvocationContext, Task> next)
    {
        if (_licznik.PrzekroczonyDzienny())
            throw new InvalidOperationException("Przekroczono dzienny limit");

        await next(context);
        _licznik.Dodaj(context.Result.Metadata?["Usage"]);
    }
}

Trzy zastosowania powtarzają się najczęściej. Pierwsze to limity kosztu, żeby błąd w pętli nie wyczerpał budżetu. Drugie to zatwierdzanie działań nieodwracalnych, gdzie warstwa zatrzymuje wywołanie i pyta o zgodę. Trzecie to zapis do systemu obserwacyjnego.

Telemetria jest tu oparta o standard obowiązujący w całym ekosystemie, więc ślady wywołań modelu trafiają tam, gdzie już zbierasz dane o reszcie aplikacji. To wygodniejsze niż osobne narzędzie, bo diagnozowanie wolnego żądania nie wymaga zestawiania dwóch systemów.

Warto włączyć telemetrię od pierwszego dnia. Zużycie tokenów, czas wywołań i liczba ponowień to trzy liczby, których brak zauważa się dopiero przy pierwszym zaskakującym rachunku.

Wdrożenie w chmurze

Przy wdrożeniu na platformie Microsoftu jest kilka rzeczy, które upraszczają pracę i warto je znać, zanim skonfigurujesz wszystko po swojemu.

Tożsamość zarządzana usuwa klucze z konfiguracji całkowicie. Aplikacja uwierzytelnia się swoją tożsamością przypisaną przez platformę, więc nie ma czego trzymać w pliku ani czego rotować.

builder.AddAzureOpenAIChatCompletion(
    deploymentName: deployment,
    endpoint: endpoint,
    credentials: new DefaultAzureCredential());

Druga rzecz to filtrowanie treści włączone domyślnie po stronie usługi. Bywa pomocne i bywa uciążliwe, gdy Twoja dziedzina zawiera słownictwo uznane za wrażliwe. Warto sprawdzić, jak zachowuje się przy Twoich danych, zanim ogłosisz gotowość.

Trzecia to limity przepustowości przypisane do wdrożenia modelu. Przekroczenie zwraca błąd, a nie kolejkuje, więc ponowienia z narastającym odstępem są tu obowiązkowe, a nie zalecane.

Osobną decyzją jest to, czy agent ma w ogóle działać w Twoim procesie. Foundry Agent Service uruchamia go po stronie dostawcy i daje dwie drogi: agenta opisanego samą konfiguracją, bez kodu do utrzymania, albo Twój obraz kontenera, do którego platforma dokłada adres, skalowanie, tożsamość i zbieranie śladów. Pierwsza droga zdejmuje utrzymanie, ale odbiera możliwość wpięcia własnych warstw pośrednich opisanych wyżej, więc przy jakiejkolwiek nietrywialnej kontroli przebiegu zostaje wariant kontenerowy.

Kontra alternatywy

Dla zespołu pracującego w .NET wybór sprowadza się do dwóch pierwszych wierszy, bo alternatywy oznaczałyby osobną usługę w innym języku. To bywa uzasadnione przy zapleczu i tak podzielonym na usługi, ale przy monolicie dokłada granicę, której nie było.

Warto zauważyć, że te biblioteki rozwiązują ten sam problem podobnie, bo wszystkie opierają się na wywoływaniu narzędzi udostępnianym przez dostawców modeli. Różnice dotyczą wygody i ekosystemu, a nie możliwości.

Praktyczny wniosek jest taki, że wybór biblioteki rzadko przesądza o powodzeniu wdrożenia. Przesądzają opisy narzędzi, granice w instrukcji i to, czy masz zestaw przypadków, na którym mierzysz zmiany. Te trzy rzeczy przenoszą się między bibliotekami niemal bez zmian, więc praca w nie włożona nie przepada przy migracji.

Drugi wniosek dotyczy kolejności prac. Warto zacząć od jednego zadania z trzema narzędziami i doprowadzić je do stanu, w którym działa przewidywalnie, zanim zbudujesz system z pięcioma agentami. Rozbudowa przy niesprawdzonych podstawach mnoży problemy, których źródła potem nie da się wskazać.

Wyszukiwanie po własnych danych

Najczęstsze zastosowanie tych bibliotek w firmach to odpowiadanie na pytania z dokumentacji wewnętrznej, a nie budowanie agentów wykonujących działania.

Biblioteka udostępnia abstrakcję magazynu wektorów, więc kod nie zależy od konkretnej bazy. To wygodne przy prototypie na rozwiązaniu wbudowanym i późniejszym przejściu na coś poważniejszego.

var kolekcja = magazyn.GetCollection<string, Fragment>("dokumentacja");
var wyniki = kolekcja.SearchAsync(wektorPytania, top: 5);

Warto natomiast wiedzieć, że abstrakcja upraszcza wybór bazy, a nie samo zadanie. Jakość odpowiedzi zależy od cięcia dokumentów, doboru modelu osadzeń i filtrowania, czyli od rzeczy, których żadna warstwa pośrednia nie załatwi.

Przy pracy z dokumentami po polsku dobór modelu osadzeń ma znaczenie większe niż wybór bazy. Model trenowany głównie na danych angielskich zwraca fragmenty gorzej dopasowane, a diagnoza tego problemu bywa myląca, bo wygląda jak wina wyszukiwania.

Przy większej skali warto sięgnąć po bazę wyspecjalizowaną, na przykład Qdranta, i mierzyć trafność osobnym narzędziem, zamiast oceniać ją po wrażeniu z kilku pytań.

Typowe błędy

Pierwszy to opisy narzędzi pisane dla programisty. Model czyta ten sam tekst i potrzebuje zdania o tym, kiedy wywołać metodę, a nie opisu implementacji.

Drugi to przekazywanie identyfikatora użytkownika w parametrach narzędzia. Model może podać cudzy, więc tożsamość powinna pochodzić z kontekstu wywołania.

Trzeci to brak limitu kroków. Agent w pętli zużyje tyle tokenów, ile mu pozwolisz, a przy modelu z górnej półki cenowej to bywa kosztowne odkrycie.

Czwarty to zaczynanie nowego projektu na bibliotece ze wskazanym następcą. Działa, ale oznacza migrację zaplanowaną na później zamiast decyzji podjętej teraz.

Piąty to brak zestawu przypadków testowych przed migracją. Bez niego nie da się stwierdzić, czy zachowanie po przeniesieniu jest takie samo, a różnice bywają subtelne.

Szósty to trzymanie kluczy w konfiguracji aplikacji. W tym ekosystemie właściwym miejscem jest magazyn sekretów, a przy wdrożeniu w chmurze tożsamość zarządzana, która usuwa klucze całkowicie.

FAQ

Czy Semantic Kernel jest przestarzały?

Nie w sensie wycofania, ale Microsoft wskazał następcę i to on dostaje główny kierunek rozwoju. Starsza biblioteka nadal ma wydania i dużą społeczność, więc istniejące wdrożenia działają, natomiast nowy projekt lepiej zacząć od następcy.

Czym Agent Framework różni się od Semantic Kernel?

Upraszcza definiowanie narzędzi, bo zamiast klasy wtyczki z atrybutami wystarczy zwykła metoda. Łączy też dorobek dwóch projektów Microsoftu, wcześniej rozwijanych osobno, i został wydany jako wersja produkcyjna ze zobowiązaniem do stabilności interfejsów.

Ile trwa migracja?

Zależy od tego, ile logiki zbudowano wokół jądra. Sam kod wywołujący model i definicje narzędzi przenoszą się szybko, a czasu wymagają własne usługi w kontenerze i filtry przechwytujące wywołania. Obie biblioteki mogą działać obok siebie, więc da się to rozłożyć na etapy.

Czy działa z modelami innymi niż od Microsoftu?

Tak, obsługiwane są modele różnych dostawców, w tym Claude i modele lokalne przez interfejs zgodny z popularnym formatem. Integracja z usługami chmurowymi Microsoftu jest najgłębsza, co przy wdrożeniu w tym ekosystemie bywa argumentem rozstrzygającym.

Czy nadaje się do systemów wieloagentowych?

Tak, i to jeden z powodów połączenia dwóch projektów w jeden. Dostępne są też integracje z protokołami wymiany między agentami budowanymi na różnych platformach, co ma znaczenie przy większych wdrożeniach, gdzie nie wszystko powstaje w jednym zespole.

Dokumentacja następcy stoi w centrum wiedzy Microsoftu, a przewodnik migracji w osobnym opracowaniu.