2.1 KiB
ADR-0001: APM jako łańcuch dostaw kontekstu agentowego
- Status: przyjęty
- Data: 2026-08-28
Kontekst
Prompty, skille i guardraile dla agentów mają wszystkie cechy zależności: są współdzielone między repozytoriami, zmieniają się w czasie, mają właścicieli i wpływają na wynik. Trzymane jako pliki w repozytorium silnika stają się nierozróżnialne od kodu: nie da się ich niezależnie wersjonować, nie da się powiedzieć "ten przebieg użył wiedzy migracyjnej w wersji 1.2.0".
Decyzja
Kontekst agentowy dostarczamy pakietami APM (Microsoft Agent Package Manager):
apm.yml deklaruje zależności, apm install rozwiązuje je do apm_modules/,
apm.lock.yaml pinuje commity i hashe, apm-policy.yml ogranicza dopuszczalne źródła
i prymitywy, apm audit wykrywa dryf.
Silnik (Python + agno) czyta prymitywy z .apm/ oraz apm_modules/ i kompiluje je
do obiektów agno. Prymitywy lokalne mają pierwszeństwo przed zainstalowanymi.
Konsekwencje
Pozytywne
- Zespół właściciela SDK dostarcza wiedzę migracyjną jako pakiet, bez dostępu do silnika.
- Hash lockfile'a w manifeście przebiegu odpowiada na pytanie "co dokładnie wiedział model".
- Polityka instalacyjna jest egzekwowana w CI, a nie w regulaminie.
Negatywne
- Dodatkowa zależność narzędziowa (APM CLI) w obrazie runnera.
- Potrzebny wewnętrzny rejestr pakietów (w praktyce: repozytoria GitLaba) i dyscyplina tagowania.
- Ryzyko rozjazdu między wersją silnika a formatem prymitywów - łagodzone testem
test_apm_context.py, który waliduje kontekst przy każdym MR.
Rozważane alternatywy
- Prompty w repozytorium silnika. Najprostsze, ale uniemożliwia niezależne wersjonowanie wiedzy dziedzinowej i rozmywa własność.
- Baza wektorowa z dokumentacją migracji. Nieodtwarzalne: dwa przebiegi na tym samym commicie mogą dostać inny kontekst. Odpada w środowisku wymagającym audytu.
- Własny format pakietu. Koszt utrzymania bez zysku; APM daje lockfile, politykę i skanowanie ukrytego Unicode z pudełka, opierając się na otwartych standardach (AGENTS.md, Agent Skills, MCP).