Microsoft Agent Framework w praktyce

Microsoft Agent Framework, dwie linie w jednym projekcie

Microsoft przez dwa lata rozwijał równolegle dwie biblioteki do budowania agentów. Jedna wyrosła z badań i stawiała na swobodną rozmowę agentów, druga powstała z myślą o firmach i kładła nacisk na wtyczki, bezpieczeństwo i integrację z resztą oferty.

Utrzymywanie dwóch odpowiedzi na to samo pytanie okazało się nie do obrony. Microsoft Agent Framework jest połączeniem obu linii w jeden projekt, wydanym w wersji stabilnej w kwietniu 2026 roku, z jednakowymi pojęciami i interfejsami w Pythonie i na platformie .NET.

Dla kogoś, kto ma kod na AutoGenie albo na Semantic Kernel, to jest wskazany kierunek migracji. Dla nowego projektu to jedna z kilku sensownych opcji, i poniżej opisuję, kiedy wybór akurat tej ma uzasadnienie.

Dwa poziomy: agent i przepływ

Projekt rozdziela dwie rzeczy, które w innych bibliotekach bywają zlepione, i to rozdzielenie jest tu najlepszym pomysłem.

Agent to model z instrukcją i zestawem narzędzi. Dostaje zadanie, sam decyduje, które narzędzia wywołać i w jakiej kolejności, i zwraca wynik. Swoboda jest tu zaletą, bo przy nieprzewidywalnym zadaniu sztywny plan przeszkadza.

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

def sprawdz_stan(sku: str) -> int:
    """Zwraca liczbe sztuk dostepnych w magazynie."""
    return magazyn.policz(sku)

agent = ChatAgent(
    chat_client=OpenAIChatClient(model="gpt-4o"),
    instructions="Odpowiadasz na pytania o dostepnosc towaru. Zawsze sprawdzasz stan.",
    tools=[sprawdz_stan],
)

wynik = await agent.run("Czy mamy jeszcze buty w rozmiarze 42?")

Przepływ to opis tego, co ma się zdarzyć, zapisany wprost przez Ciebie. Kroki, warunki, rozgałęzienia i punkty kontrolne są tu jawne, więc przebieg jest powtarzalny.

Podział pracy między te dwa poziomy jest praktyczną wskazówką na cały projekt. Proces biznesowy o znanych krokach opisuj przepływem. Pojedynczy krok wymagający oceny sytuacji zostaw agentowi. Odwrotna kolejność, czyli oddanie całego procesu agentowi, daje rozwiązanie, którego nie da się debugować ani powtórzyć.

Wzorce orkiestracji

Do łączenia wielu agentów służy pięć gotowych układów i warto je znać z nazwy, bo pokrywają większość realnych potrzeb.

Układ sekwencyjny przekazuje wynik jednego agenta do następnego. Najprostszy i najczęściej wystarczający.

Układ równoległy uruchamia kilku agentów na tym samym wsadzie i zbiera wyniki. Sensowny, gdy zadania są niezależne, bo skraca czas do najwolniejszego z nich.

Rozmowa grupowa pozwala agentom wymieniać wypowiedzi, jak w pierwotnym AutoGenie. Elastyczna i najtrudniejsza do przewidzenia.

Przekazanie oddaje sterowanie innemu agentowi wraz z całym kontekstem. To układ znany z obsługi zgłoszeń, gdzie sprawa wędruje do specjalisty.

Układ z koordynatorem planuje pracę, rozdziela ją i składa wyniki, wracając do planu, gdy coś się nie powiedzie.

Wybierając między nimi, zacznij od najprostszego, który da się obronić. Sekwencja i równoległość pokrywają większość zastosowań, a rozmowa grupowa wygląda najciekawiej i najczęściej rozczarowuje w produkcji, bo ten sam wsad daje różne przebiegi.

Punkty kontrolne i wznawianie

To funkcja, która przy dłuższych procesach decyduje o tym, czy rozwiązanie nadaje się na produkcję, i której w wielu bibliotekach nadal brakuje.

Przepływ zapisuje stan w wyznaczonych momentach. Jeśli proces przerwie się w połowie, przez błąd usługi zewnętrznej albo restart wdrożenia, wznowienie zaczyna od ostatniego punktu, a nie od początku.

Znaczenie tego widać dopiero przy rachunkach. Proces złożony z dwunastu kroków, który wywala się na dziesiątym, przy braku punktów kontrolnych kosztuje dziesięć wywołań modelu za każdym razem, gdy próbujesz naprawić błąd. Przy punktach kontrolnych kosztuje jedno.

Druga zaleta dotyczy udziału człowieka. Przepływ może zatrzymać się i poczekać na zatwierdzenie, a stan czeka zapisany dowolnie długo. To pozwala budować procesy, w których agent przygotowuje decyzję, a człowiek ją potwierdza, bez trzymania procesu w pamięci przez trzy dni.

Harness, czyli warstwa wykonawcza

Wersja z połowy 2026 roku dołożyła warstwę, która pakuje w gotową całość rzeczy dotąd składane ręcznie przy każdym poważnym agencie.

Chodzi o pętlę rozumowania, dostęp do powłoki i systemu plików, zarządzanie kontekstem przy długich sesjach oraz przepływy z zatwierdzeniem przez człowieka. To jest dokładnie ten zestaw, który każdy zespół budujący agenta do pracy z kodem albo z plikami pisał wcześniej sam, zwykle gorzej.

Osobno pojawiło się podejście, w którym model zamiast wybierać narzędzia po kolei pisze krótki program wywołujący je wszystkie, a program wykonuje się raz w izolowanym środowisku. Zysk jest podwójny: mniej wywołań modelu i mniej tur, bo cała sekwencja idzie w jednym przebiegu.

To rozwiązanie jest na wczesnym etapie i warto traktować je jako eksperyment, a nie fundament. Kierunek natomiast jest wart uwagi, bo pokazuje, dokąd zmierza cała branża: od modelu wybierającego narzędzia do modelu piszącego kod, który je wywołuje.

Warstwa pośrednia, czyli kontrola nad przebiegiem

Mechanizm, który przy poważnym wdrożeniu okazuje się ważniejszy niż same wzorce orkiestracji, a w dokumentacji zajmuje mało miejsca.

Do każdego etapu wykonania da się podpiąć funkcję przechwytującą to, co się dzieje, przed wywołaniem modelu, po nim, przed wywołaniem narzędzia i po jego zakończeniu. Wygląda niepozornie, a rozwiązuje cztery problemy naraz.

Pierwszy to zatwierdzanie działań. Narzędzie modyfikujące dane albo wysyłające wiadomość może wymagać potwierdzenia, a warstwa pośrednia jest miejscem, w którym to sprawdzasz, bez rozsypywania warunków po kodzie narzędzi.

Drugi to zapisywanie przebiegu. Każde wywołanie razem z argumentami, wynikiem, czasem i użyciem tokenów trafia do dziennika w jednym miejscu, więc późniejsza diagnoza nie wymaga powtarzania przebiegu.

Trzeci to obsługa błędów. Narzędzie zwracające wyjątek zwykle powinno oddać modelowi komunikat, a nie wywalić cały przebieg, bo model często potrafi poprawić argumenty i spróbować ponownie.

Czwarty to ograniczanie kosztu. Licznik wywołań i tokenów prowadzony w tej warstwie pozwala przerwać przebieg po przekroczeniu progu, zamiast odkrywać przekroczenie na fakturze.

Warto napisać te cztery rzeczy raz, na początku projektu, i podpiąć do wszystkich agentów. Dopisywanie ich później, gdy agentów jest dwunastu, jest tą samą pracą pomnożoną przez dwanaście.

Obserwowalność i koszty

Agent zawodzi inaczej niż zwykły kod, bo nie rzuca wyjątku, tylko zwraca odpowiedź gorszą od oczekiwanej. To zmienia sposób, w jaki trzeba go pilnować.

Biblioteka wystawia dane telemetryczne w powszechnie przyjętym formacie, więc przebieg wpina się do narzędzi, których zespół już używa, bez osobnego panelu. Jeden przebieg jest widoczny jako drzewo: wywołania modelu, wywołania narzędzi, czasy i zużycie tokenów.

Trzy miary warto obserwować od pierwszego dnia. Liczba tur na zadanie pokazuje, czy agent krąży. Koszt na zadanie mówi, czy rozwiązanie się skaluje. Udział zadań zakończonych powodzeniem, liczony na stałym zestawie przypadków, mówi, czy zmiana w instrukcji poprawiła cokolwiek, czy tylko wyglądała na poprawę.

Ta trzecia miara wymaga zestawu przypadków z oczekiwanym wynikiem i jest jedyną, która pozwala porównać dwie wersje agenta. Bez niej ocena sprowadza się do wrażenia po kilku ręcznych próbach, a wrażenie regularnie myli, zwłaszcza przy zmianach w instrukcji systemowej.

Z czym się łączy

Biblioteka nie wiąże Cię z jednym dostawcą modeli, i to jest istotna zmiana wobec wcześniejszych narzędzi Microsoftu.

Gotowe łączniki obejmują usługi Microsoftu, modele OpenAI, Claude, rozwiązania Google i Amazona oraz modele uruchamiane lokalnie. Zmiana dostawcy to podmiana klienta w konstruktorze agenta, bez ruszania reszty kodu.

Obsługiwane są też dwa protokoły, które w tym roku stały się standardem. Pierwszy pozwala podłączać narzędzia i źródła danych wystawione przez zewnętrzne serwery, więc gotowa integracja z systemem firmowym nie wymaga pisania własnego kodu. Drugi opisuje komunikację między agentami różnych producentów, co ma znaczenie, gdy Twój agent ma rozmawiać z cudzym.

Wsparcie dla obu protokołów warto sprawdzić na własnym przypadku, zanim wpiszesz je do projektu architektury. Standardy są młode, a zgodność bywa częściowa.

Microsoft Agent Framework kontra alternatywy

Pierwsze kryterium jest banalne i decydujące: język. Jeśli zaplecze stoi na .NET, ta biblioteka jest praktycznie jedyną poważną opcją, bo żadna z pozostałych nie ma wariantu dla tej platformy. LangGraph i OpenAI Agents SDK dają Pythona i JavaScript, Google ADK Pythona, Javę i Go, a .NET nie pojawia się w żadnym z nich.

Drugie to zobowiązanie do wsparcia. Wersja stabilna niesie deklarację utrzymania interfejsu, co po historii z dwoma poprzednimi projektami ma realną wartość dla zespołu planującego wdrożenie na lata.

Trzecie, jak zwykle, to pytanie, czy framework jest w ogóle potrzebny. Agent z trzema narzędziami i jednym krokiem to sto linii kodu wywołującego model wprost, bez żadnej biblioteki.

Migracja z poprzednich projektów

Producent dostarcza przewodniki dla obu linii i warto zacząć od nich, bo opisują odpowiedniki pojęć.

Przy przejściu z pierwszej biblioteki największą zmianą jest odejście od rozmowy jako mechanizmu sterowania. To, co było wymianą wypowiedzi między agentami, zapisujesz jako przepływ z jawnymi krokami. Zwykle okazuje się, że kolejność i tak była stała, więc zmiana usuwa niepowtarzalność, nie odbierając niczego.

Przy przejściu z drugiej największą zmianą jest model agenta. Wtyczki i funkcje przenoszą się prosto, natomiast warstwa planowania działa inaczej i wymaga przemyślenia.

W obu przypadkach kolejność prac jest ta sama. Najpierw wydziel narzędzia jako zwykły kod niezależny od biblioteki, bo to najcenniejsza część i przenosi się bez zmian. Potem zbuduj zestaw przypadków testowych z oczekiwanym wynikiem, bo bez niego nie odróżnisz udanej migracji od nieudanej. Dopiero potem przepisuj orkiestrację.

Nie migruj wszystkiego naraz. Jeden proces przeniesiony w całości i uruchomiony obok starego mówi więcej niż plan obejmujący dziesięć procesów, bo dopiero porównanie obu wersji na tym samym ruchu pokazuje różnicę w jakości i koszcie.

Typowe błędy

Pierwszy to oddanie agentowi całego procesu o znanych krokach. Znane kroki opisuj przepływem, bo zyskujesz powtarzalność i tańsze debugowanie.

Drugi to pominięcie punktów kontrolnych przy długich procesach. Każdy restart kosztuje wtedy pełny przebieg od początku, razem z wszystkimi wywołaniami modelu.

Trzeci to rozmowa grupowa wybrana dlatego, że wygląda najciekawiej. W produkcji liczy się powtarzalność, a ten układ jej nie daje.

Czwarty to brak limitu kosztu na przebieg. Agent w pętli potrafi wykonać kilkadziesiąt wywołań, zanim ktokolwiek zauważy problem.

Piąty to wpisanie protokołów do projektu architektury bez sprawdzenia zgodności na własnym przypadku. Standardy są młode, a wsparcie bywa częściowe.

Szósty to migracja bez zestawu testowego. Agenci nie zwracają wartości porównywalnych znakiem równości, więc bez przypadków z oczekiwanym wynikiem ocena zmiany jest zgadywanką.

FAQ

Czy to następca AutoGena i Semantic Kernel?

Tak, producent nazywa go wprost bezpośrednim następcą obu projektów, stworzonym przez te same zespoły. AutoGen jest w trybie utrzymania, Semantic Kernel pozostaje wspierany, a nowy rozwój idzie do jednego repozytorium.

Czy działa poza ekosystemem Microsoftu?

Tak. Gotowe łączniki obejmują modele różnych dostawców, w tym uruchamiane lokalnie, a biblioteka nie wymaga usług chmurowych Microsoftu. Integracja z nimi jest natomiast głębsza niż z resztą, co przy wdrożeniu w tej chmurze bywa argumentem rozstrzygającym.

Python czy .NET?

Oba warianty mają te same pojęcia i porównywalny zakres, więc wybieraj według języka zaplecza. Wariant dla .NET jest tu wyróżnikiem wobec konkurencji, bo większość bibliotek agentowych go nie oferuje.

Czy potrzebuję frameworka do prostego agenta?

Zwykle nie. Agent z kilkoma narzędziami i jednym krokiem to niewiele kodu wywołującego model wprost. Framework zarabia na siebie przy zarządzaniu stanem, punktach kontrolnych, ponawianiu i obserwowalności.

Jak sprawdzić, czy nadaje się do mojego projektu?

Zbuduj w nim jeden realny proces ze swojego systemu, nie przykład z dokumentacji, i zmierz trzy rzeczy: koszt przebiegu, czas odpowiedzi i to, jak szybko ustalasz przyczynę po nieudanym uruchomieniu. Trzecia miara przesądza najczęściej, a sprawdzana jest najrzadziej.

Dokumentacja stoi na stronie projektu, a informacje o wydaniach na blogu zespołu.