Wskazówki praktyczne: Używka agenta — wyjaśnione intuicyjnie i w sposób kompleksowy
Krok po kroku przewodnik po „Praktycznych notatkach: Agent Harnesses – wyjaśnione intuicyjnie i w sposób kompleksowy”: umowy, sprawdzania oraz miejsca na kod do wklejenia dla zespołów implementujących ten wzorzec.
Niech to służy jako przebudowa idei z „Agent Harnesses — Intuitively and Exhaustively Explained” dostosowana do operatorów: wyraźne etapy, uporządkowane pola kodu oraz notatki odzyskawcze, które przetrwają przeniesienie obowiązków. Etap Przeglądu działa najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Kształtowanie podstawowego zrozumienia
W fazie budowania podstawowego zrozumienia należy określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni być w stanie ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dopiero późniejszej optymalizacji. Autoryzacja powinna odbywać się przy bramce wejściowej, a ponowna autoryzacja – na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.
Przegląd: LLM
W fazie przeglądu modeli LLM należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, łatwe do przetestowania jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinno to wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. W przypadku, gdy następnym krokiem jest kod lub wywołanie narzędzia, lepsze są ustrukturyzowane wyniki z walidacją schematu niż tekst w formie swobodnej.
Przegląd: Agenci
W fazie Review Agents należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć przypadkowe, częściowe ukończenie zadań. Zaloguj się przy bramie dostępu i ponownie uzyskaj uprawnienia na poziomie warstwy danych. Sam token nie stanowi granicy między poszczególnymi usługami. W fazie Review Agents należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Przegląd: Łańcuch myślenia i używanie narzędzi
Podczas przechodzenia przez etap przeglądu Łańcucha myślenia, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie pętli agenta marnuje godziny.
Przegląd: Umiejętności
Gdy przechodzisz przez etap sprawdzania umiejętności, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie agenta trwa godzinami.
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
Zasada podstawowa Harnessa
Gdy przechodzisz przez etap „The Fundamental Idea of”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Zapisuj nazwę narzędzia, hash argumentów, czas opóźnienia oraz wynik każdego wywołania. Bez takich informacji debugowanie agenta trwa godzinami. Gdy przechodzisz przez etap „The Fundamental Idea of”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Agent wykorzystuje standardy
Narzędzie The Agent Harnesses Standard działa najlepiej, gdy traktuje się je jako mierzalną powierzchnię do analizy. Zapisz jeden przykład udanego działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Używaj narzędzi o wąskich schematach i wyraźnych etykietach opisujących efekty uboczne. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim je automatycznie zatwierdzą.
my-harness/
├── HARNESS.md # Required: metadata + instructions
├── skills/ # Optional: a set of skills
└── references/ # Optional: a set of reference documents
Definiowanie HARNESS.md
Najlepiej funkcjonuje etap HARNESS md, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Używaj narzędzi o wąskich schematach oraz z wyraźnymi etykietami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą.
---
name: <name of the harness>
description: <description of what the harness is for>
---
<body>
Definiowanie katalogu umiejętności
Faza Definiowania Katalogu Umiejętności funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Używaj narzędzi o wąskich schematach oraz z wyraźnymi etykietami opisującymi efekty uboczne. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim automatycznie je zatwierdzą. Faza Definiowania Katalogu Umiejętności funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
my-harness/
├── HARNESS.md
├── skills/
| ├── my-skill-1/
| | ├── SKILL.md
| | ├── scripts/
| | ├── references/
| | ├── assets/
| | └── ...
| └── my-skill-2/
| ├── SKILL.md
| ├── scripts/
| ├── references/
| ├── assets/
| └── ...
└── references/
Definicja katalogu referencji
Na etapie definiowania katalogu referencji należy określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownego wykonania, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Uwierzytelnianie odbywa się przy bramce, a ponowne upoważnienie – na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.
my-mraketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/
my-mraketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/
├── style-guide.md
└── brand-priorities.md
---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---
<body>
Strukturyzacja dużych systemów
W fazie strukturyzowania dużych systemów należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu. Należy preferować małe, łatwe do przetestowania jednostki nad rozbudowanymi skryptami. Gdy jakiś krok zawiedzie, powinno to wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę przepływu danych. Uwierzytelniaj się przy bramie wejściowej, a ponownie autoryzuj na poziomie warstwy danych. Sam token nie stanowi granicy między poszczególnymi użytkownikami.
my-harness/
├── HARNESS.md
├── skills/
| ├── skill1/
| ├── skill2/
| ├── skill3/
| └── ...
└── references/
├── reference1
├── reference2
├── reference3
└── ...
my-harness/
├── HARNESS.md
├── skills/
│ ├── software-development/
│ │ ├── SKILLS.md
│ │ ├── skill1/
│ │ │ └── SKILL.md
│ │ └── skill2/
│ │ └── SKILL.md
│ ├── market-analysis/
│ │ ├── SKILLS.md
│ │ └── skill3/
│ │ └── SKILL.md
│ └── social-media/
│ ├── SKILLS.md
│ ├── skill4/
│ │ └── SKILL.md
│ └── skill5/
│ └── SKILL.md
└── references/
├── brand-assets/
│ ├── REFERENCES.md
│ ├── reference1.md
│ └── reference2.md
├── software-infrastructure/
│ ├── REFERENCES.md
│ ├── reference3.md
│ └── reference4.md
└── product-information/
├── REFERENCES.md
└── reference5.md
...
└── references/
└── data-sources/
├── REFERENCES.md
├── relational/
│ ├── REFERENCES.md
│ └── schema-overview.md
└── warehouse/
├── REFERENCES.md
└── dataset-catalog.md
Lista kontrolna operacyjna
Podczas pracy nad fazą listy kontrolnej operacyjnej najpierw zapisz warunki funkcjonowania systemu: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie.
Zapisuj czas trwania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie agenta trwa godzinami.
Zachowuj stan grafu w formie prostych, spójnych struktur. Zagłębione struktury danych ukrywają informację o tym, który węzeł zapisał dane do którego pola, co utrudnia kontynuację pracy po przerwach.
Gdy budżet na to pozwala, dodaj test sprawdzający kluczową ścieżkę w procesie CI przy użyciu przygotowanych danych testowych, a nie rzeczywistych, płatnych API.
Wolij małe, łatwe do przetestowania jednostki nad rozbudowane skrypty. Gdy jakiś krok zawiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną sekwencję operacji.
Zanim wdrożysz tę architekturę, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów realizacji oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkowników oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca 52aa6b4e7ebd: trzymaj klucze dostawcy poza repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików testowych, aby późniejsze zmiany modeli pozostawały porównywalne.