Agenci Zasoby: Standard folderów dla umiejętności i referencji
Jak harness rozszerza umiejętności agenta za pomocą pliku HARNESS.md, katalogów umiejętności i referencji, stopniowego ujawniania informacji oraz układów nawzajem powiązanych elementów dla dużych agentów.
Źródła: Agent Harnesses — Intuitively and Exhaustively Explained
„Harness” dla agenta to sposób na stworzenie struktury okalającej sposób działania i myślenia systemu AI, dzięki czemu jeden podstawowy model może być wykorzystywany do wielu różnych zadań. Ta koncepcja opiera się na kilku wcześniejszych elementach, więc najpierw omówimy je: czym jest model językowy, czym jest agent, jak łączą się rozumowanie i używanie narzędzi oraz jakie umiejętności są dodatkowo potrzebne. Gdy te elementy będą już znane, sam „Harness” stanowi niewielki krok naprzód – wystarczy prosta struktura folderów, aby go opisać.
Baza wiedzy
Modele językowe jako funkcje
W tym celu model językowy można traktować jako funkcję: tekst wpływa do niego, a tekst wychodzi z niego. Jego jedynym zadaniem jest odpowiadanie na tekst tekstem, a mimo to większość najnowszych produktów AI jest budowana na tej podstawowej funkcji.
Czym jest agent
Słowo „agent” pozostaje bardzo ogólne. Prace akademickie opisują kilka rodzajów agentów, które działają w zupełnie różny sposób. W codziennej rozmowie jednak prawie wszyscy mają na myśli to samo: system czatowy, który otrzymuje wiadomość, wykonuje pewne działania i odpowiada. Ten model nazywany jest powszechnie ReAct – to cienka warstwa kodu łącząca model z funkcjonalnościami, dzięki czemu może on rozumować, działać i obserwować. ReAct umożliwia modelowi przemyślenie tego, co ma zrobić, wybór działania wpływającego na otoczenie, a następnie odczytanie informacji o wyniku. Wszystko poniżej używa terminu „agent” w tym, ReAct-owym znaczeniu.
Rozumowanie i działanie
Dwie koncepcje leżą u podstaw tego mechanizmu. Rozumowanie jest zazwyczaj realizowane poprzez łańcuch myśli, co oznacza skłanianie modelu do przemyślenia rozwiązania przed podjęciem decyzji co do odpowiedzi. Artykuł, który to wprowadził, zrobił to poprzez umieszczenie przykładu rozwiązania w instrukcjach oraz pytania, które nie dawały rezultatu przy zwykłych instrukcjach, ale zostało rozwiązane za pomocą tego samego modelu po dodaniu przykładu.
Ta technika stała się tak kluczowa, że wiele modeli jest teraz szkolenych tak, aby same generować łańcuch myśli. Zwykłe modele mają tendencję do przemyślenia problemu przed udzieleniem odpowiedzi, natomiast modele rozumujące upowszechnione przez DeepSeek posiadają specjalną fazę, w której model rozwiązuje problem przy użyciu bardzo długiego łańcucha myśli.
Historia używania narzędzi jest podobna: istnieje już od dłuższego czasu, ciągle okazuje się przydatne i staje się standardem. W swojej najprostszej formie informuje model, że jeśli wygeneruje określony fragment tekstu, zostanie uruchomiony pewien kod, a następnie powróci wynik. Model decyduje wtedy, kiedy przeszukać internet, przejrzeć pliki lub, w najgorszym przypadku, wysłać pieniądze tam, gdzie nie powinien. Złożone pytania często wymagają połączenia rozumowania i działań, a porównania strategii formułowania zapytań pokazują, że ich połączenie jest skuteczniejsze niż każda z nich osobno.
Umiejętności
W miarę rozwoju agentów, używania narzędzi oraz strategii formułowania zapytań powstają określone praktyki. Załóżmy, że agent ma dodać wiersze do bazy danych. Potrzebuje narzędzi, które umożliwią modelowi zobaczenie i edycję bazy danych, a także instrukcji opisujących jej strukturę oraz dostępne narzędzia.
Umiejętność to standardowy sposób na strukturyzację tego zestawu. Informacje i funkcjonalności są łączone w jedną jednostkę, dzięki czemu agent otrzymuje je jako kompletny pakiet. Umiejętność to folder:
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
Większość umiejętności to w rzeczywistości zwykłe pliki tekstowe. Mimo to umożliwiają one agentowi zrozumienie i obsługę złożonych systemów, a także dostarczają programistom agentów przenośnej i wielokrotnie używalnej warstwy do tworzenia planów i procedur.
Czym jest zestaw umiejętności
Zestaw umiejętności najlepiej postrzegać jako rozszerzenie pojedynczych umiejętności. Jedna umiejętność obejmuje szeroką gamę funkcji, takich jak edycja strony internetowej, zarządzanie bazą danych czy analiza opinii klientów. Poważne zadania, np. pełnienie roli asystenta programistów tworzących produkt, mogą wymagać jednoczesnego wykorzystania wielu umiejętności. Zestaw umiejętności łączy kilka takich umiejętności wraz z materiałami referencyjnymi, których agent potrzebuje, aby zrozumieć swoją rolę oraz środowisko, w którym pracuje.
Format Agent Harnesses
Zgodnie z tym proponowanym standardem uprząż składa się z trzech elementów: pliku markdown opisującego ją, zestawu umiejętności niezbędnych do interakcji z otoczeniem oraz zestawu odniesień pomagających agencji zrozumieć, gdzie dokonuje działań. Standard ten jest projektem otwartego oprogramowania utrzymywanym publicznie.
my-harness/
├── HARNESS.md # Required: metadata + instructions
├── skills/ # Optional: a set of skills
└── references/ # Optional: a set of reference documents
Plik najwyższego poziomu, HARNESS.md, powinien być krótki. Daje agentowi szybki, ogólny obraz problemu oraz wskazówki, gdzie znaleźć szczegóły w ramach umiejętności i odniesień.
Projekt opiera się na zasadzie stopniowego ujawniania informacji, wzorcu ostatnio popularizowanym przez standard Agent Skills. Proces ten przebiega w trzech fazach:
- Odkrywanie. Podczas uruchamiania agent ładuje tylko plik HARNESS.md, który przedstawia strukturę systemu. Gdy przychodzi zapytanie, agent porównuje je z tymi opisami i stopniowo przegląda nazwy oraz opisy umiejętności i odniesień, aż znajdzie to, czego potrzebuje.
- Aktywacja. Gdy zostanie znaleziony odpowiedni materiał, ładuje się i czyta pełna dokumentacja dotycząca tych umiejętności i odniesień.
- Egzekucja. Agent postępuje zgodnie z instrukcjami zawartymi w systemie i może uruchomić odpowiednie umiejętności.
Plik HARNESS.md
Tak jak w przypadku umiejętności, narzędzie to wykorzystuje frontmatter – kluczowe informacje umieszczone na początku pliku markdown, aby agent mógł efektywnie przeszukiwać zasoby.
---
name: <name of the harness>
description: <description of what the harness is for>
---
<body>
Imię i opis są obowiązkowe, aby agent mógł od razu wiedzieć, czym jest pas bezpieczeństwa. Ciało tekstu to krótkie wyjaśnienie głównych elementów, które wskazują agentowi na umiejętności i odniesienia, których powinien użyć.
Katalog umiejętności
W tym katalogu znajdują się umiejętności zgodne ze standardem Agent Skills, który definiuje je w następujący sposób:
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
Pas dodaje do tego kolejne elementy, więc katalog umiejętności wygląda w ten sposób:
my-harness/
├── HARNESS.md
├── skills/
| ├── my-skill-1/
| | ├── SKILL.md
| | ├── scripts/
| | ├── references/
| | ├── assets/
| | └── ...
| └── my-skill-2/
| ├── SKILL.md
| ├── scripts/
| ├── references/
| ├── assets/
| └── ...
└── references/
Katalog odniesień
Katalog odniesień zawiera dowolne dokumenty, które pomagają agencie zrozumieć jego otoczenie, rolę lub inny kontekst na wyższym poziomie.
Umiejętności również zawierają odniesienia, a te dwa poziomy różnią się zakresem. Odniesienia w obrębie danej umiejętności wyjaśniają, jak korzystać z tej konkretnej umiejętności. Odniesienia na poziomie platformy powinny zawierać to, co jest wspólne dla kilku umiejętności, na wyższym poziomie abstrakcji.
Weźmy na przykład agenta stworzonego do pomocy w tworzeniu treści marketingowych. Może on mieć jedną umiejętność do pisania postów na blogu, jedną do generowania obrazów i jedną do analizy mediów społecznościowych:
my-mraketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/
Każda umiejętność może mieć swoje własne odniesienia. Umiejętność skanowania mediów społecznościowych może wymieniać konta firmy, umiejętność obsługi obrazów może wskazywać miejsce przechowywania gotowych zdjęć, a umiejętność prowadzenia bloga może opisywać proces publikacji. Odniesienia na poziomie całego systemu stanowią naturalne miejsce dla elementów używanych we wszystkich trzech obszarach, takich jak przewodniki stylowe i priorytety marki:
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
Każdy treść może znajdować się w katalogu odniesień na poziomie harness, ale zdecydowanie zaleca się użycie markdowna oraz krótkiego opisu na górze każdego pliku, aby agent mógł szybko ocenić jego istotność. Przewodnik stylu w tym przykładzie mógłby zaczynać się w ten sposób:
---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---
<body>
Organizowanie dużego zestawu
Zestaw może zawierać wiele umiejętności i odniesień. Gdy zestawy stają się zbyt duże, ich konserwacja staje się skomplikowana, a przekazywanie informacji agentowi jest nieskuteczne.
my-harness/
├── HARNESS.md
├── skills/
| ├── skill1/
| ├── skill2/
| ├── skill3/
| └── ...
└── references/
├── reference1
├── reference2
├── reference3
└── ...
Odpowiedzią są podkatalogi. Zarówno w sekcji umiejętności, jak i referencje, foldery mogą grupować elementy w podzbiory:
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
Aby agent mógł w pełni, ale efektywnie zrozumieć tę strukturę, HARNESS.md powinien ją opisać. Każdy podkatalog zawiera również plik opisowy: SKILLS.md omawia umiejętności znajdujące się w danym podkatalogu, a REFERENCES.md przedstawia odniesienia do nich.
Tutaj właśnie przydaje się stopniowe ujawnianie informacji. Agent czyta plik najwyższego poziomu, aby poznać ogólny układ, a następnie otwiera konkretne pliki SKILLS.md i REFERENCES.md tylko wtedy, gdy jest to konieczne – to najskuteczniejsza droga do uzyskania istotnych informacji.
Nestowanie może być tak głębokie, jak wymagają to treści, dzięki czemu duża kolekcja może być zorganizowana na wyższym poziomie. Każdy podkatalog powinien mieć swój własny plik SKILLS.md lub REFERENCES.md, aby agent mógł zrozumieć każdą warstwę w miarę przechodzenia na niższy poziom:
...
└── references/
└── data-sources/
├── REFERENCES.md
├── relational/
│ ├── REFERENCES.md
│ └── schema-overview.md
└── warehouse/
├── REFERENCES.md
└── dataset-catalog.md
Dlaczego taka struktura działa
Format nie wymaga od autora zbyt wiele. Wszystko znajduje się w formie pliku tekstowego w folderze, co oznacza, że zestaw dokumentów może być wersjonowany, sprawdzany i udostępniany tak jak każdy inny projekt. Agent nie musi nigdy ładować całej kolekcji, ponieważ każdy plik opisowy pełni rolę małego wskaźnika, który decyduje, czy kontynuować przeglądanie. Zestaw przeznaczony dla zespołu marketingowego różni się od zestawu dla administratora bazy danych jedynie treścią, natomiast proces wykrywania, aktywacji i realizacji pozostaje identyczny.
Dwa nawyki pomagają utrzymać zestaw w dobrym stanie. Po pierwsze, pisz opisy tak, aby określały, kiedy materiał jest istotny, a nie tylko to, co zawiera, ponieważ agent wybiera, co otworzyć, na podstawie samego tego zdania. Po drugie, upewnij się, że odniesienia na poziomie zestawu są rzeczywiście udostępniane. Jeśli dokument dotyczy jednej umiejętności, powinien znajdować się wewnątrz tej umiejętności, a przenoszenie go na wyższy poziom dodaje jedynie szum do wszystkich innych wyszukiwań.
Powiązane materiały
- Pięć warstw agent harness, wraz z kodem, który nie działa bez nich — Praktyczny przegląd pięciu miejsc, w których agent harness egzekwuje zasady w kodzie, od granic wykonywania po łańcuchy kontekstowe, oraz tego, co badania mogą, a czego nie mogą udowodnić.
- Dlaczego logi agenta nie spełnią wymogów Artykułu 12: Rejestry decyzji, przyczynowość i pochodzenie — Ślady nie są dowodem odpowiedzialności. Jak rejestrować decyzje agenta jako trwałe obiekty z powiązaniami przyczynowymi, łańcuchami pochodzenia opartymi na haszach oraz deterministycznymi regułami polityki, wykorzystując Semantica.