Przejdź do treści

Migracja z wycofanego SDK akceptacji HumanLayer do DueReason

SDK akceptacji HumanLayer (require_approval, human_as_tool) jest wycofane wg jego własnego README. Jak przenieść to samo sprawdzenie do withApproval().

Aktualizacja · 8 min czytania

W skrócie

  • HumanLayer przebudował się w przestrzeń roboczą agentów kodujących; repozytorium z dekoratorem require_approval i human_as_tool jest teraz zamrożoną gałęzią legacy, której własne README nazywa ten kod "praktycznie w całości wycofanym".
  • Zadanie dekoratora - zablokować funkcję do decyzji człowieka, a potem pozwolić agentowi działać dalej albo zobaczyć powód odmowy - odpowiada wprost withApproval() z @duereason/sdk, które opakowuje ten sam rodzaj funkcji.
  • Różnica jest w tym, co dzieje się po kliknięciu akceptuj: DueReason weryfikuje podpisany, jednorazowy grant względem dokładnego payloadu przed uruchomieniem kodu, więc zmieniona kwota czy cel zostaje odrzucona zamiast zaufana.
  • Migracja to głównie przełożenie: nadaj temu, co już bramkujesz, klucz czynności, tytuł i uzasadnienie, opisz payload, który wykonasz, i ustaw, jak długo wywołanie ma czekać.

Jeśli budowałeś na dekoratorze @hl.require_approval() HumanLayer albo na human_as_tool, być może już wiesz, że nie są dłużej utrzymywane. Publiczne repozytorium HumanLayer mówi to wprost: jego README głosi "the code here is pretty much all deprecated - you can try the rebuild of humanlayer at humanlayer.com" (ten kod jest praktycznie w całości wycofany - spróbuj przebudowanej wersji na humanlayer.com). Firma przeszła na produkt będący przestrzenią roboczą agentów kodujących; SDK akceptacji, jego kanały kontaktowe Slack i e-mail oraz stare strony dokumentacji zostały pozostawione na tagu legacy-final. Jeśli to właśnie sprowadziło Cię tutaj, ten przewodnik pokazuje, jak przenieść to samo sprawdzenie z udziałem człowieka do withApproval() z @duereason/sdk.

Co robił stary dekorator

Podejście HumanLayer to dekorator w Pythonie owijający funkcję, którą agent mógł wywołać jako narzędzie. Z ich własnego opisu na PyPI:

```python from humanlayer import HumanLayer hl = HumanLayer()

@hl.require_approval() def send_email(to: str, subject: str, body: str): """Send an email to the customer""" ... ```

Wywołanie send_email wstrzymywało się, aż człowiek zaakceptuje albo odrzuci je przez kanał kontaktowy skonfigurowany dla klienta (domyślnie Slack albo e-mail), i uruchamiało ciało funkcji dopiero po zgodzie. Nie było osobnego kroku weryfikacji: dekorator pytał, czekał i wywoływał funkcję - akceptacja i wykonanie były tą samą granicą zaufania.

Ten sam kształt w DueReason

withApproval() opakowuje funkcję w ten sam sposób, ale rozdziela "ktoś się zgodził" od "dokładnie to, na co się zgodzono, jest wykonywane" na dwa osobne sprawdzenia:

```js import { createClient, withApproval } from "@duereason/sdk";

const duereason = createClient({ apiKey: process.env.DUEREASON_API_KEY });

// Wywoływane z { to, subject, body }, przez Twój kod albo przez agenta. export const sendEmail = withApproval( duereason, { action: "customer-email", organization: "acme", title: (input) => "Email to " + input.to + ": " + input.subject, reason: "Szkic odpowiedzi dla klienta; zaakceptuj, by wysłać w tej formie.", payload: (input) => ({ to: input.to, subject: input.subject, body: input.body }), agent: { name: "support-agent" }, timeoutMs: 15 * 60 * 1000, }, // Działa tylko po akceptacji, z payloadem, względem którego zweryfikowano grant. (input, { payload }) => mailer.send(payload), ); ```

Linia po linii: udekorowana funkcja staje się trzecim argumentem, fn; to, co wcześniej było niejawne (który kanał zostanie zapytany, co zobaczy), staje się jawnymi polami - action nazywa rodzaj decyzji, więc trafia do właściwych akceptujących, title i reason to to, co czytają przed decyzją, a payload to dokładnie to, z czym wykonywane jest fn. organization i timeoutMs zastępują konfigurację po stronie klienta, którą HumanLayer odczytywał z ustawień kanału kontaktowego.

Co się zmienia, a nie tylko przenosi

  • Grant, nie tylko zgoda. Po akceptacji DueReason wydaje podpisany, jednorazowy token powiązany z hashem payload(input). withApproval() weryfikuje go przed uruchomieniem fn i rzuca GrantVerificationError, jeśli payload zmienił się w międzyczasie - stary dekorator nie miał żadnego odpowiednika tego sprawdzenia między "zaakceptowano" a "wykonuję".
  • Typowane odmowy, które odczyta agent. Odrzucenie, wygaśnięcie, anulowanie albo przekroczenie czasu rzucają NotApprovedError ze status, po którym obsługa błędów agenta może rozgałęziać logikę, oraz komunikatem napisanym tak, by powiedzieć modelowi, by nie pytał ponownie o tę samą rzecz licząc na inną odpowiedź.
  • Wykonanie jest raportowane, raz. withApproval() raportuje wynik z powrotem do DueReason jako succeeded albo failed po uruchomieniu fn, więc grantu nie da się powtórzyć w drugą wysyłkę, płatność czy wdrożenie.
  • Akceptujący widzą więcej niż powiadomienie na kanale. Tytuł, uzasadnienie, payload i to, kto pyta, pojawiają się w konsoli razem z podobnymi wcześniejszymi decyzjami, a nie tylko w treści, jaką renderował kanał kontaktowy.

Przenoszenie udekorowanej funkcji

  1. Wybierz klucz czynności dla tego, co robi funkcja (customer-email, payment, deployment) - czynności to coś, do czego w konsoli DueReason podpinają się ścieżki akceptacji i grupy akceptujących, w miejsce kanału kontaktowego.
  2. Zamień parametry funkcji na payload: zwykłą funkcję wejścia zwracającą dokładnie to, co zostanie wykonane, zgodnie z kształtem, jakiego potrzebuje fn.
  3. Napisz title i reason jako ciągi znaków albo funkcje wejścia - uzasadnienie to to, na czym decydują akceptujący, więc trzymaj je konkretnie zamiast ogólnego "wymagana akceptacja".
  4. Wybierz timeoutMs, czyli jak długo jedno wywołanie ma czekać; wniosek wygasa w tym samym czasie, jeśli nikt nie odpowie (od 60 sekund do 7 dni).
  5. Zastąp ciało udekorowanej funkcji trzecim argumentem withApproval() - otrzymuje on (input, { payload, grant }), więc wykonuj payload, czyli wartości, względem których zweryfikowano grant, a nie surowy input.
  6. Łap NotApprovedError i GrantVerificationError tam, gdzie wcześniej obsługiwałeś odrzucenie, oraz ExecutionNotRecordedError na przypadek, gdy fn się powiodło, ale raportowanie zawiodło - nie uruchamiaj wtedy ponownie.

guard() to ten sam mechanizm dla pojedynczego wywołania, dla którego masz już gotowy payload, gdy nie chcesz budować narzędzia wielokrotnego użytku - przydatne przy jednorazowej migracji, na przykład kroku wdrożenia w skrypcie release.

Co nie ma bezpośredniego odpowiednika

DueReason nie ma odpowiednika human_as_tool do zadawania przez agenta otwartego pytania poza przepływem akceptacji; każdy wniosek dotyczy zdefiniowanej czynności ze schematem payloadu, co jest też tym, co pozwala wykonawcy zweryfikować powstały grant offline. Jeśli Twój agent używał human_as_tool wyłącznie do zadania pytania tekstowego, a nie do bramkowania czynności, to inny problem niż ten, który rozwiązuje withApproval(), i utrzymanie obok DueReason lekkiej integracji komunikatorowej do tego celu jest rozsądnym podziałem.

Pytania

Czy SDK akceptacji HumanLayer naprawdę zniknęło, czy tylko przestało być utrzymywane?
Jego własne publiczne repozytorium (na tagu legacy-final, gdzie ostatnio żyły require_approval i human_as_tool) mówi, że ten kod jest praktycznie w całości wycofany, i odsyła do przebudowanego produktu na humanlayer.com. Główna gałąź jest dziś przestrzenią roboczą agentów kodujących bez dekoratora akceptacji.
Czy DueReason trzyma mój payload prywatnie, czy opuszcza on UE?
Dane wniosków, payloady i dowody zostają w regionie, w którym wdrażasz; powiadomienia Slack, Teams, e-mail i push domyślnie niosą tylko tytuł i link z powrotem do konsoli, a nie payload ani uzasadnienie, właśnie po to, by dane nie musiały opuszczać regionu razem z powiadomieniem. Pokazywanie więcej w kanale to jawna opcja włączana tylko przez właściciela.
Ile to kosztuje w fazie beta?
DueReason jest dziś darmowy dla jednej organizacji z maksymalnie pięcioma członkami, ze wszystkimi podstawowymi funkcjami dostępnymi od razu; roczny klucz licencyjny znosi te limity - weryfikowany w całości offline, bez łączenia się z serwerem, i uruchamiany w Ustawieniach > Licencja. Ścieżkę bez SLA, samodzielnie prowadzoną, opisuje przewodnik o samodzielnym hostingu, jeśli wolisz w ogóle nie korzystać z produktu hostowanego.
Czy mogę zamiast produktu hostowanego postawić własny?
Tak. Samodzielny hosting działa na jednej bazie Postgres i jednym gotowym obrazie uruchamianym przez Docker Compose, bez klonowania repozytorium; withApproval() rozmawia z wdrożeniem self-host dokładnie tak samo jak z hostowanym, bo oba mówią tym samym API.
Czy muszę przepisać agenta na TypeScript, żeby użyć withApproval()?
Nie. @duereason/sdk to klient TypeScript, ale API, które wywołuje, to zwykłe HTTP, więc agent w Pythonie (na przykład zbudowany na starym SDK HumanLayer) może poprosić o akceptację, poczekać na decyzję i zweryfikować grant bezpośrednio względem API bez przechodzenia na TypeScript; SDK po prostu ułatwia to z poziomu Node.

Przenieś swoją bramkę akceptacji do DueReason

Załóż konto i klucz API, a potem skieruj withApproval() na czynność, którą już bramkujesz - bez przekonfigurowywania kanału kontaktowego.

Załóż konto

Źródła

Poradnik wyjaśnia przepisy tak, jak je rozumiemy; nie jest poradą prawną. Sprawdź tekst urzędowy i prawo krajowe, które może dodać obowiązki.

Zacznij z DueReason

Załóż bezpłatne konto, wypróbuj na żywo albo porozmawiaj z nami o swoim procesie.

Otrzymuj nowości o produkcie