EA - 12-Factor Agents - Nowe podejście, które może zmienić Twoje myślenie o AI

Dlaczego 12-Factor Agents to nie tylko kolejny "best practice"?

Pamiętacie 12-Factor App firmy Heroku z 2011 roku? Te zasady które zrewolucjonizowały sposób budowania aplikacji cloud-native i SaaS? Cóż, w świecie AI mamy teraz podobny przełom - 12-Factor Agents od Dexa Horthyego z HumanLayer.

Ale zanim pomyślimy "kolejny framework", zatrzymajmy się na moment. To nie jest frameworka - to metodologia inspirowana sprawdzoną koncepcją 12-Factor App, ale przełożona na specyficzne wyzwania budowania niezawodnych systemów AI.

Analogie między 12-Factor App a 12-Factor Agents

12-Factor App skupiało się na budowaniu aplikacji które są:

• Przenośne między środowiskami wykonania
• Skalowalne bez większych zmian w architekturze
• Utrzymywalne poprzez jasne separacje odpowiedzialności
• Wdrażalne w sposób ciągły dla maksymalnej elastyczności

12-Factor Agents przenosi te same filozoficzne założenia do świata AI:

• Przewidywalne w działaniu mimo niezdeterministycznej natury LLM
• Modularne zamiast monolitycznych frameworków
• Kontrolowalne z pełną własnością nad kluczowymi komponentami
• Produkcyjne gotowe do wdrożenia u klientów biznesowych

Dlaczego tradycyjne frameworki AI zawodzą?

Tak jak 12-Factor App powstało w odpowiedzi na problemy z monolitycznymi aplikacjami, 12-Factor Agents odpowiada na frustracje z obecnymi frameworkami AI:

Klasyczny przepływ problemów:

1. Decyzja o budowie agenta
2. Szybki start z frameworkiem (LangChain, Crew AI, etc.)
3. Osiągnięcie 70-80% jakości
4. Zdanie sobie sprawy że 80% to za mało dla klientów
5. Próba odwrotnej inżynierii frameworka
6. Rozpoczęcie od nowa - wiadomo że trzeba być elastycznym

Kluczowa obserwacja: Najlepsze "agenty AI" w rzeczywistości to głównie dobrze zaprojektowane oprogramowanie z LLM strategicznie wplecionymi w kluczowych punktach.

12 Czynników - szczegółowo 

Factor 1: Natural Language to Tool Calls (Język naturalny do wywołań narzędzi)

Co to znaczy: Konwersja poleceń w języku naturalnym na ustrukturyzowane wywołania narzędzi.

Przykład praktyczny: Polecenie "utwórz link płatności na 750$ dla Terri" zostaje przekształcone w strukturalne wywołanie API:

{ "tool": "create_payment_link", "amount": 750, "currency": "USD", "customer": "Terri" }

Dlaczego to ważne: LLM świetnie rozumie intencje, ale narzędzia potrzebują strukturalnych danych. Ten factor jest mostem między tymi światami.

Factor 2: Own your prompts (Własność promptów)

Co to znaczy: Nie oddawaj inżynierii promptów w ręce frameworka. Traktuj prompty jako kod pierwszej klasy.

Praktyczne zastosowanie:

• Prompty w plikach, nie ukryte w frameworku
• Wersjonowanie promptów w Git
• A/B testing różnych wersji promptów
• Pełna kontrola nad instrukcjami przekazywanymi agentowi

Dlaczego to krytyczne: Prompt to serce Twojego agenta. Framework może mieć swoje priorytety, Ty masz swoje.

Factor 3: Own your context window (Własność okna kontekstu)

Co to znaczy: Zarządzaj kontekstem rozmowy, historią promptów i stanem, optymalizując wydajność i ograniczając zużycie tokenów.

Techniki zarządzania kontekstem:

• Kompresja historii: Podsumowywanie starszych części konwersacji
• Selektywne przechowywanie: Zachowywanie tylko najważniejszych informacji
• Strategie przycinania: Usuwanie najmniej istotnych fragmentów gdy osiągniesz limit tokenów
• Kontekst hierarchiczny: Różne poziomy szczegółowości dla różnych części historii

Praktyczny przykład: Zamiast przechowywać całą historię 20 kroków workflow, zachowujesz podsumowanie: "Agent wykonał kroki 1-18: analiza danych, generowanie raportu, weryfikacja wyników. Teraz wykonuje krok 19: finalizacja dokumentu".

Factor 4: Tools are just structured outputs (Narzędzia to tylko ustrukturyzowane wyniki)

Co to znaczy: Traktowanie narzędzi jako sposobu na otrzymywanie strukturalnych danych z modeli językowych, nie jako magicznych czarnych skrzynek.

Zmiana perspektywy:

• Zamiast: "Agent wywołuje narzędzie X"
• Myśl: "Agent produkuje JSON który wygląda jak wywołanie narzędzia X"

Korzyści: Łatwiejsze testowanie, debugowanie i mockowanie narzędzi.

Factor 5: Unify execution state and business state (Unifikacja stanu wykonania i stanu biznesowego)

Co to znaczy: Integracja stanu agenta z logiką biznesową aplikacji.

Praktyczne podejście:

• Stan agenta nie żyje w odizolowanym bubble
• Jest częścią modelu domenowego aplikacji
• Pozwala na łatwe przechodzenie między trybem "human" i "agent"
• Umożliwia audyt i compliance

Factor 6: Launch/Pause/Resume with simple APIs (Uruchom/Wstrzymaj/Wznów poprzez proste API)

Co to znaczy: Umożliwienie elastycznego zarządzania cyklem życia agenta.

Przypadki użycia:

• Pauzowanie na zatwierdzenie użytkownika
• Wstrzymywanie przy osiągnięciu limitu kosztów
• Wznawianie po poprawie danych wejściowych
• Scheduled execution w określonych godzinach

Factor 7: Contact humans with tool calls (Kontakt z ludźmi poprzez wywołania narzędzi)

Co to znaczy: Strukturyzowane wywołania narzędzi do uzyskiwania wkładu człowieka w kluczowych sytuacjach.

Przykład: Agent nie wie jak interpretować niejednoznaczne dane i "wywołuje" narzędzie:

{ "tool": "ask_human", "question": "Znalazłem dwie faktury z tą samą datą ale różnymi kwotami. Która jest prawidłowa?", "context": {...}, "options": ["Faktura A: 1500€", "Faktura B: 1800€", "Obie są błędne"] }

Factor 8: Own your control flow (Własność przepływu sterowania)

Co to znaczy: Kontrola nad logiką przepływu agenta, umożliwiająca pauzowanie, cache'owanie wyników czy wdrożenie ograniczeń.

Elementy kontroli:

• Warunki stopu (maksymalny czas, koszt, liczba iteracji)
• Punkty kontrolne wymagające zatwierdzenia
• Mechanizmy rollback w przypadku błędu
• Cache'owanie kosztownych operacji

Factor 9: Compact Errors into Context Window (Kompaktowanie błędów w oknie kontekstu)

Co to znaczy: Efektywne zarządzanie błędami poprzez ich kompresję w kontekście.

Techniki:

• Kategoryzacja błędów zamiast pełnych stack trace'ów
• Agregacja podobnych błędów
• Extraktowanie kluczowych informacji diagnostycznych
• Tworzenie "błędów-podsumowań" dla serii niepowodzeń

Factor 10: Small, Focused Agents (Małe, skoncentrowane agenty)

Co to znaczy: Budowanie wyspecjalizowanych agentów o ograniczonym zakresie odpowiedzialności.

Przykłady:

• Agent do analizy dokumentów PDF
• Agent do schedulowania spotkań
• Agent do monitoring systemów
• Agent do generowania raportów

Korzyści: Łatwiejsze utrzymanie, testowanie, debugging i skalowanie.

Factor 11: Trigger from anywhere, meet users where they are (Wyzwalanie z dowolnego miejsca)

Co to znaczy: Możliwość uruchamiania agentów z różnych punktów w aplikacji i różnych kanałów komunikacji.

Kanały integracji:

• Slack boty
• Email workflows
• Web interfaces
• API endpoints
• Mobile apps
• CLI tools

Factor 12: Make your agent a stateless reducer (Agent jako bezstanowy reduktor)

Co to znaczy: Traktowanie agentów jako czystych funkcji przekształcających kontekst wejściowy w działania wyjściowe.

Funkcyjne podejście:

Agent(currentState, userInput) → (newState, actions)

Korzyści:

• Przewidywalność - te same inputy dają te same outputy
• Testowalność - łatwe unit testy
• Debugowalność - jasny przepływ danych
• Skalowalność - możliwość równoległego przetwarzania

Implementacja podobna do Redux reducerów:

def agent_reducer(state, action): if action.type == 'USER_MESSAGE': return process_user_message(state, action.payload) elif action.type == 'TOOL_RESULT': return process_tool_result(state, action.payload) # ...

Porównanie z 12-Factor App

12-Factor App	12-Factor Agents	Wspólne DNA
Jeden codebase	Własność promptów	Kontrola nad kodem
Jawne dependencies	Własność kontekstu	Brak ukrytych zależności
Config w środowisku	Unifikacja stanów	Separacja konfiguracji od logiki
Backing services	Narzędzia jako struktury	Traktowanie zewnętrznych zasobów jako usług
Bezstanowe procesy	Agent jako reduktor	Funkcyjne, przewidywalne zachowanie

Co dalej z tym wszystkim?

12-Factor Agents to nie kolejny hype - to przeniesienie sprawdzonych zasad inżynierii oprogramowania do nowego domeniu.

Tak jak 12-Factor App stało się standardem dla aplikacji cloud-native, 12-Factor Agents może stać się fundamentem dla niezawodnych systemów AI w produkcji.

Kluczowa lekcja: Najszybszym sposobem na dostarczenie wysokiej jakości oprogramowania AI klientom jest włączenie małych, modułowych koncepcji do istniejącego produktu, zamiast zaczynania od zera z frameworkami.

Zanim pójdziesz do kogoś po pomoc przy budowie agentów AI:

• sprawdź czy 12-Factor Agents nie rozwiąże Twojego problemu
• przyjdź z propozycją architektury, nie z oczekiwaniem że ktoś to zrobi za Ciebie
• upewnij się czy zespół ma wiedzę o LLM i production-ready systemach
• pamiętaj że własność kodu jest lepsza niż vendor lock-in

Bo jak powiedział kiedyś pewien mądry człowiek - najlepsza architektura, specyfikacja i design wyłonią się z zespołu deweloperskiego, który wie co robi.

Links:

• 12-Factor Agents GitHub
• 12-Factor App Methodology
• HumanLayer

EA - OWASP ASVS: Configuration Verification Requirements

 W nowoczesnych środowiskach DevSecOps, kontrola nad zależnościami i komponentami firm trzecich to nie tylko kwestia porządku, ale bezpieczeństwa. Dlatego coraz więcej organizacji decyduje się na wprowadzenie wewnętrznych narzędzi typu artifact repository manager (np. JFrog Artifactory, Sonatype Nexus, GitHub Packages), które pełnią funkcję jednego źródła prawdy dla wszystkich zależności.

Dlaczego to ważne?

• Zależności są wektorami ataku. Większość nowoczesnych aplikacji składa się z setek bibliotek zewnętrznych. Jeśli choć jedna z nich ma lukę — system jest podatny.

• Brak centralizacji to chaos. Pobieranie zależności „na żywioł” (z różnych mirrorów, nieautoryzowanych źródeł) to ryzyko.

• Potrzebujemy zgodności z politykami bezpieczeństwa. ASVS jasno wskazuje, że zarządzanie komponentami i ich kontrola to obowiązek każdej świadomej organizacji.

Czym jest artifact repository manager?

To narzędzie, które:

• Przechowuje zależności w bezpieczny sposób,

• Ogranicza dostęp tylko do zatwierdzonych pakietów,

• Umożliwia skanowanie artefaktów pod kątem podatności (np. przez integrację z NVD – National Vulnerability Database),

• Może pełnić funkcję lokalnego cache dla publicznych rejestrów (npm, Maven Central, PyPI itp.),

• Umożliwia śledzenie wersji i aktualizacji w jednym miejscu.

Przykładowy scenariusz

1. Developer dodaje zależność do projektu – ale tylko z repozytorium wewnętrznego.

2. CI/CD pipeline pobiera zależności z artifact repository.

3. Zintegrowany skaner sprawdza artefakty pod kątem CVE z bazy NVD.

4. W przypadku zagrożenia – pipeline zostaje przerwany lub trafia alert do zespołu.

5. Repozytorium pozwala też na szybkie usunięcie lub zablokowanie konkretnej wersji biblioteki.

Powiązanie z OWASP ASVS v5

Funkcje artifact repository managera pokrywają m.in.:

ASVS Punkt	Opis
5.2.1	Weryfikacja znanych podatności w zależnościach
5.2.2	Używanie tylko zaufanych zależności z oficjalnych repozytoriów
14.1.1	Polityka zatwierdzania komponentów firm trzecich
14.2.2	Integracja skanowania bezpieczeństwa w CI/CD

Korzyści

• Standaryzacja pobierania zależności,

• Większa kontrola nad tym, co trafia do aplikacji,

• Automatyczne wykrywanie podatnych wersji bibliotek,

• Zgodność z wymaganiami ASVS, a także np. ISO/IEC 27001 i SOC2,

• Przyspieszenie audytów i przeglądów bezpieczeństwa.

Podsumowanie

Wdrożenie artifact repository managera jako centralnego źródła zależności to nie tylko ułatwienie życia developerom, ale realny krok w stronę bezpieczeństwa aplikacji.

W świetle OWASP ASVS, taka praktyka nie jest „nice-to-have” — to konieczność w dojrzałym procesie wytwarzania oprogramowania.

Jeśli jeszcze nie masz takiego rozwiązania – warto zacząć od audytu zależności i wybrania repozytorium zgodnego z potrzebami zespołu oraz wymaganiami standardów bezpieczeństwa.

dev{tools}: A2A – kolejny protokół AI tym razem od Google

 W świecie, w którym agentowe podejście do architektury systemów opartych na sztucznej inteligencji zyskuje na popularności, Google zaprezentował zupełnie nowy standard komunikacyjny — A2A, czyli Agent-to-Agent Protocol.

To otwarty protokół, który ma szansę stać się tym dla agentów AI, czym HTTP był dla internetu.

Czym jest A2A?

A2A (Agent-to-Agent Protocol) to propozycja Google dotycząca standaryzacji komunikacji pomiędzy inteligentnymi agentami.

Celem A2A jest:

• umożliwienie współpracy wielu agentów w sposób bezpieczny, spójny i rozszerzalny,

• standaryzacja mechanizmu wymiany wiadomości,

• ułatwienie modułowej architektury agentowej, niezależnie od implementacji poszczególnych agentów.

Strona projektu: google.github.io/A2A

Dlaczego A2A?

Wraz z rosnącym zainteresowaniem architekturami typu AI agent + tool + memory, zaczęły się pojawiać problemy związane z:

• chaotyczną komunikacją między komponentami,

• brakiem formalnego protokołu wymiany danych,

• trudnościami w skalowaniu, testowaniu i monitorowaniu współpracy agentów.

A2A ma na celu rozwiązanie tych problemów i umożliwienie łatwego tworzenia rozproszonych, specjalizowanych agentów, które potrafią ze sobą rozmawiać w zunifikowany sposób.

Kluczowe założenia A2A

• Standard JSON jako format wiadomości,

• Role i tożsamości agentów są jawnie zdefiniowane (każdy agent posiada id, capabilities i persona),

• Struktura wiadomości z message_type, sender, receiver, content i metadata,

• Protokół konwersacji — A2A pozwala agentom prowadzić konwersacje stanu, a nie tylko wymieniać zapytania,

• Bezpieczeństwo i prywatność — uwzględniono możliwość uwierzytelniania, podpisów i kontroli dostępu.

Przykładowy format wiadomości

{
  "message_type": "task_request",
  "sender": {
    "id": "agent-calendar",
    "persona": "Calendar Assistant"
  },
  "receiver": {
    "id": "agent-email",
    "persona": "Email Agent"
  },
  "content": {
    "task": "Send meeting invite",
    "time": "2025-06-10T14:00:00Z"
  },
  "metadata": {
    "conversation_id": "abc123",
    "timestamp": "2025-06-01T12:00:00Z"
  }
}

Wspierane typy wiadomości A2A

A2A wyróżnia różne typy komunikatów, m.in.:

• task_request – prośba o wykonanie zadania,

• task_response – odpowiedź (np. sukces, błąd, dane),

• event_notification – informacja o zmianie stanu lub zdarzeniu,

• feedback, query, handoff, intent, memory, plan – typy konwersacyjne wspierające złożone interakcje.

Kiedy warto sięgnąć po A2A?

A2A przydaje się wszędzie tam, gdzie masz:

• wiele agentów AI pełniących różne funkcje (planowanie, wyszukiwanie, analizowanie, podejmowanie decyzji),

• potrzebę modularności i skalowalności – agentów można łatwo zastępować lub rozwijać,

• interfejsy API LLM (np. OpenAI, Gemini, Claude), z których chcesz zbudować większą strukturę agentową,

• świadomość kontekstu – dzięki metadanym każdy agent rozumie, do czego odnosi się wiadomość.

Przykład zastosowania – Agent Meeting Planner

Wyobraźmy sobie agenta planującego spotkania, który:

1. prosi innego agenta o przeszukanie kalendarza (task_request),

2. przekazuje dane do trzeciego agenta odpowiedzialnego za generowanie e-maila (handoff),

3. zbiera potwierdzenia (feedback) i odsyła status do użytkownika.

Dzięki A2A wszystko odbywa się w ramach jednego spójnego protokołu – bez potrzeby wymyślania własnych formatów komunikacji.

Narzędzia i przyszłość

Na stronie A2A GitHub znajdziesz:

• specyfikację JSON Schema,

• gotowe przykłady konwersacji,

• parsery i adaptery w Pythonie,

• wsparcie dla popularnych agent frameworks (LangChain, ReAct, AutoGen).

A2A może stać się HTTP dla agentów AI – fundamentem interoperacyjności w świecie agentowych systemów rozproszonych.

MCP vs. A2A – dwa protokoły, różne cele

Choć MCP i A2A wywodzą się ze świata interakcji z modelami językowymi i agentami, służą zupełnie różnym celom. W rzeczywistości wzajemnie się uzupełniają, a nie konkurują.

🧠 MCP – Model Context Protocol

• 🎯 Cel: przekazanie uporządkowanego kontekstu do modelu językowego (LLM).

• 📦 Zakres: obejmuje prompt, dane wejściowe, reguły działania – wszystkie ujęte w strukturze JSON.

• 💬 Użycie: komunikacja pomiędzy aplikacją a LLM, np. w celu wykonania zadania generatywnego.

• 🧩 Modularność: struktura może być rozbudowywana o dodatkowe metadane.

• 🔄 Interoperacyjność: jeden format może działać z różnymi modelami LLM (OpenAI, Claude, Mistral itp.).

A2A – Agent-to-Agent Protocol

• 🎯 Cel: umożliwienie komunikacji między niezależnymi agentami AI.

• 🔄 Zakres: transmisja wiadomości typu task_request, task_response, notification itp.

• 🗣️ Użycie: koordynacja i delegowanie zadań między agentami (np. jeden planuje, drugi wykonuje).

• 🌐 Infrastruktura: wymaga serwera A2A do pośrednictwa i routowania wiadomości.

• 🔌 Integracja: agenci mogą używać MCP jako jednego ze sposobów interakcji z LLM.

Podsumowanie

• MCP to język opisu kontekstu dla modeli językowych.

• A2A to protokół konwersacji między autonomicznymi agentami.

• Można je stosować razem: agent komunikuje się z innym agentem za pomocą A2A, a z LLM – za pomocą MCP.

A2A to przełomowy krok w kierunku standaryzacji komunikacji między inteligentnymi agentami.

Dzięki strukturze wiadomości, jawnej identyfikacji nadawców i odbiorców oraz obsłudze konwersacji, A2A ułatwia tworzenie złożonych, skalowalnych i współpracujących środowisk AI.

Jeśli tworzysz własne agentowe rozwiązania — warto się z nim zapoznać już teraz.