Co wersjonować, żeby wynik agenta dało się później wyjaśnić

Zachowanie zmienia nie tylko prompt

Zespoły zwykle wersjonują kod, a czasem prompt. Pozostałe elementy zmieniają się niezauważenie, choć każdy może zmienić wynik sprawy:

• Identyfikator modelu i ustawienia, takie jak effort albo limity odpowiedzi
• Opisy narzędzi, w których według przewodnika Anthropic o pisaniu narzędzi nawet drobne zmiany sformułowań potrafią wyraźnie przesunąć wyniki
• Implementacja narzędzia, na przykład serwer MCP wdrażany według własnego harmonogramu
• Reguły biznesowe i progi, często trzymane w tabeli konfiguracyjnej edytowanej przez zespół operacyjny
• Indeks wyszukiwania przebudowywany co noc
• Kod workflow, wersja frameworka i oceniacze w ewaluacjach

Jeden manifest na wydanie

Zbierz te odwołania w jednym pliku generowanym przy wydaniu i przechowywanym razem z kodem. Jego identyfikator staje się wersją agenta. Przykład jest hipotetyczny; odwołania do commitów i wersje to wartości zastępcze.

agent: invoice-matching
release: 2026.10.3
model:
  id: claude-sonnet-5-5          # exact ID sent to the provider
  settings: {effort: medium, max_tokens: 4000}
prompt: prompts/invoice-agent.md@3f2a91c
examples: examples/invoice-fewshot.jsonl@3f2a91c
tool_descriptions: tools/descriptions.yaml@3f2a91c
tool_servers:
  erp-mcp: 1.8.2
policy: ap-tolerance-policy v4
retrieval_index: supplier-terms build 2026-10-20
workflow_code: 3f2a91c
lockfile: uv.lock@3f2a91c
test_set: invoice-cases v12, passed 2026-10-21

Oznaczaj wydaniem każdy rekord sprawy i każdy span. Konwencje semantyczne OpenTelemetry dla spanów agentów zawierają do tego atrybut gen_ai.agent.version, wciąż ze statusem Development. Zapisuj dokładny identyfikator modelu, który wysyłasz. Przegląd modeli Anthropic mówi na przykład, że każdy aktualny identyfikator modelu Claude to przypięty snapshot, a jednocześnie podaje daty wycofania, co jest kolejnym powodem, by nie liczyć na późniejsze uruchomienie starej wersji.

Rekonstrukcja to nie odtworzenie

Żeby później wyjaśnić sprawę, potrzebujesz wydania, danych wejściowych w postaci, w jakiej przeczytał je agent, każdego wywołania narzędzia z wynikiem, odpowiedzi modelu i wszystkich decyzji ludzi. Checkpointy w tym pomagają. W LangGraph każdy checkpoint zawiera wartości stanu, metadane, znacznik czasu i odwołanie do poprzedniego checkpointu, a get_state_history wymienia je dla danego wątku.

Odtworzenie to coś innego. Ta sama dokumentacja wyjaśnia, że wznowienie od wcześniejszego checkpointu ponownie uruchamia późniejsze węzły, w tym wywołania modelu i żądania API, więc powstaje nowy przebieg na dzisiejszych systemach. Zapisany rekord służy do wyjaśniania przeszłości, a ponowne uruchomienia na bieżącym wydaniu do testów regresji. Zauważ też, że dokumentacja persistence w LangGraph zaleca czyszczenie checkpointów albo politykę retencji, więc retencję potrzebną do wyjaśnień trzeba ustalić świadomie.

Sprawy, które obejmują zmianę wydania

Sprawa wstrzymana w poniedziałek do akceptacji może zostać wznowiona po środowym wydaniu. Silniki trwałych workflow traktują to jako znany problem. Dokumentacja Temporal wyjaśnia, że kod workflow musi być deterministyczny na potrzeby odtwarzania, że dodanie, usunięcie albo przestawienie niektórych kroków bez wersjonowania powoduje w działających workflow błąd niedeterminizmu i że do obsługi takich zmian służą worker versioning i patching.

Niezależnie od frameworka wybierz regułę: sprawy w toku albo kończą się na wydaniu, na którym się zaczęły, albo przechodzą na nowe przez jawną migrację zapisanego stanu. Zapisuj wydanie przy każdym kroku, nie tylko przy sprawie, żeby dało się wyjaśnić także sprawę mieszaną.

Typowe luki

Luki zwykle leżą poza głównym repozytorium: prompt edytowany w konsoli dostawcy, serwer narzędzi wdrażany przez inny zespół, próg zmieniony w bazie danych, indeks odświeżany w nocy. Każdą z nich trzeba albo włączyć do manifestu, albo zapisywać przy każdej sprawie z użytą wartością. Traktuj każdą zmianę wpisu w manifeście jako wydanie, które przechodzi przez zestaw testowy. Przydatny pierwszy krok to spisanie manifestu dla agenta, którego dziś uruchamiasz, i zaznaczenie każdego pola, którego nie umiesz wypełnić.