46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
# 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).
|