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.
| Kategoria | Zdarzenia | Co pokazuje użytkownikowi |
|---|---|---|
| Cykl życia | RunStarted, RunFinished, RunError, StepStarted, StepFinished | że agent pracuje, skończył albo przerwał z błędem |
| Wiadomości | TextMessageStart, TextMessageContent, TextMessageEnd, TextMessageChunk | odpowiedź pisaną na bieżąco |
| Narzędzia | ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult, ToolCallChunk | które narzędzie agent wywołuje i z jakimi argumentami |
| Stan | StateSnapshot, StateDelta, MessagesSnapshot | wspólny stan ekranu i agenta, pełny albo przyrostowy |
| Aktywność | ActivitySnapshot, ActivityDelta | postęp dłuższej pracy |
| Rozumowanie | ReasoningStart, ReasoningMessageStart/Content/End/Chunk, ReasoningEnd, ReasoningEncryptedValue | tok rozumowania, jeśli aplikacja go pokazuje |
| Subagenci | SubagentStarted, SubagentFinished, SubagentError | pracę agentów pomocniczych |
| Specjalne | Raw, Custom | zdarzenia 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
- Odłącz sieć w połowie wywołania narzędzia i połącz ponownie. Ekran nie może pokazać propozycji jako wykonanego działania.
- Wywołaj przerwanie do zatwierdzenia i odrzuć propozycję. Sprawdź w systemie docelowym, że nic się nie zmieniło.
- 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.
- Agenci AI
