AG-UI: otwarty kontrakt między agentem a ekranem

Temat: Open Source AI

AG-UI (Agent–User Interaction Protocol) to otwarty protokół zdarzeń między agentem a aplikacją, w której pracuje człowiek: przenosi odpowiedź, kroki, wywołania narzędzi, wspólny stan i prośby o zatwierdzenie. Nie jest biblioteką przycisków ani formatem danych biznesowych. Stan na 6.10.2026 referencyjny pakiet TypeScript @ag-ui/core ma wersję 1.0.2 z 5.10.2026, a pierwsze wydanie 1.0 pochodzi z 17.09.2026 (rejestr npm); projekt ma licencję MIT (repozytorium AG-UI). Dokumentacja nie podaje osobnego numeru wersji samego protokołu. Ten wpis jest dla zespołu, który buduje ekran dla agenta i chce wiedzieć, jakie zdarzenia obsłużyć i co przetestować.

Jak AG-UI dzieli pracę z MCP i A2A, pokazuje poradnik o MCP i protokołach agentów. Gdzie ta warstwa leży w całej aplikacji z agentem, od ekranu po modele, pokazuje poradnik o stosie AI native.

Jakie zdarzenia definiuje AG-UI

Dokumentacja zdarzeń dzieli je na kategorie. Klient nie musi obsłużyć wszystkich od razu, ale powinien wiedzieć, które pomija.

KategoriaZdarzeniaCo pokazuje użytkownikowi
Cykl życiaRunStarted, RunFinished, RunError, StepStarted, StepFinishedże agent pracuje, skończył albo przerwał z błędem
WiadomościTextMessageStart, TextMessageContent, TextMessageEnd, TextMessageChunkodpowiedź pisaną na bieżąco
NarzędziaToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult, ToolCallChunkktóre narzędzie agent wywołuje i z jakimi argumentami
StanStateSnapshot, StateDelta, MessagesSnapshotwspólny stan ekranu i agenta, pełny albo przyrostowy
AktywnośćActivitySnapshot, ActivityDeltapostęp dłuższej pracy
RozumowanieReasoningStart, ReasoningMessageStart/Content/End/Chunk, ReasoningEnd, ReasoningEncryptedValuetok rozumowania, jeśli aplikacja go pokazuje
SubagenciSubagentStarted, SubagentFinished, SubagentErrorpracę agentów pomocniczych
SpecjalneRaw, Customzdarzenia spoza standardu

Zdarzenia THINKING_* są oznaczone jako przestarzałe; nowe aplikacje używają zdarzeń rozumowania. MetaEvent ma status szkicu.

Przerwania: zatwierdzenie przed skutkiem

Najważniejsza dla firmy jest obsługa przerwań. Według dokumentacji przebieg może zakończyć się zdarzeniem RunFinished z wynikiem zawierającym listę przerwań (interrupts). Agent czeka wtedy na decyzję człowieka, a klient wznawia pracę nowym przebiegiem z odpowiedzią (resume).

Dzięki temu ekran może pokazać propozycję, na przykład zmianę statusu zamówienia, i poczekać na „zatwierdź” albo „odrzuć”. Protokół transportuje jednak tylko zdarzenia. Nie rozstrzyga, czy agent ma prawo wykonać operację. Serwer musi sprawdzić tożsamość użytkownika, kontekst i zakres działania niezależnie od tego, co pokazał ekran.

Transport, SDK i integracje

AG-UI działa z dowolnym transportem zdarzeń: SSE, WebSocket albo webhookami; repozytorium zawiera referencyjną implementację HTTP. Stan na 6.10.2026 według repozytorium:

  • Pakiety referencyjne: TypeScript (@ag-ui/core) i Python (ag-ui-protocol, wersja 1.0.0 w PyPI).
  • SDK społeczności: Kotlin, Go, Dart, Java, Rust, Ruby, C++ i .NET.
  • Integracje z frameworkami agentów: m.in. Microsoft Agent Framework, Google ADK, AWS Strands Agents, Mastra, Pydantic AI, LlamaIndex, LangGraph i CrewAI; Claude Agent SDK przez integrację społeczności; OpenAI Agents SDK w przygotowaniu.

Nie myl AG-UI z A2UI. Według dokumentacji A2UI to specyfikacja generatywnego interfejsu, przez którą agent dostarcza gotowe widżety, a AG-UI to protokół interakcji między agentem a użytkownikiem. Oba mogą działać razem.

Kiedy AG-UI pasuje do suwerennego systemu

Własny strumień SSE lub WebSocket też zadziała, ale wtedy zespół sam utrzymuje format zdarzeń i kod klienta. AG-UI daje wspólny kontrakt, więc można wymienić framework agenta bez przepisywania ekranu. Otwarty protokół nie czyni jednak całego systemu suwerennym. Potrzebny jest jeszcze własny hosting, autoryzacja, retencja zdarzeń i sprawdzona zgodność implementacji.

Co daje agentom kodującym w AI SDLC

Agent kodujący może wygenerować klienta albo adapter zgodny z typami zdarzeń. Zgodność typów nie dowodzi jednak spójności stanu. Testy muszą objąć kolejność zdarzeń, utratę połączenia, ponowienie i odtworzenie stanu po powrocie (StateSnapshot po ponownym połączeniu). Zaplanuj też, co ekran pokaże, gdy przyjdzie zdarzenie, którego klient nie zna. Agent z entuzjazmem wygeneruje obsługę wszystkich typów zdarzeń, zanim ktoś zapyta, które naprawdę są potrzebne.

Próba przed wyborem

  1. Odłącz sieć w połowie wywołania narzędzia i połącz ponownie. Ekran nie może pokazać propozycji jako wykonanego działania.
  2. Wywołaj przerwanie do zatwierdzenia i odrzuć propozycję. Sprawdź w systemie docelowym, że nic się nie zmieniło.
  3. Zatwierdź propozycję jako użytkownik bez uprawnień do operacji. Serwer musi odmówić, nawet jeśli ekran pokazał przycisk.

Jeżeli wynik próby jest pozytywny, zapisz decyzję architektoniczną: zastosowanie, wersje pakietów, alternatywy, właściciela utrzymania i warunek wymiany. Gotowe komponenty interfejsu zbudowane na AG-UI opisuje wpis CopilotKit.

Portret Krzysztofa Majchrzyckiego

O autorze

Krzysztof Majchrzycki jest architektem systemów i AI Business Partnerem. Od wielu lat łączy technologię z biznesem i zarządzaniem. Współtworzył firmy technologiczne i kierował polskim oddziałem międzynarodowej grupy. Dziś projektuje modele firm i inteligentne systemy operacyjne, które z nich wynikają. Ukończył Executive MBA i ma certyfikat Prosci® Certified Change Practitioner.

Buduj interfejs agenta z odbiorem, nie na wiarę

Forward Deployed AI Engineer to kurs w Akademii dla inżyniera, który buduje aplikacje i agentów w systemach firmy: projektuje integracje, uprawnienia i zatwierdzenia, pisze testy i prowadzi odbiór. Kurs jest w przygotowaniu — zapisz się na listę oczekujących.