My master blog 0159

Szukasz sposobu, by agenty ai nie tylko gadały, ale też robiły? OpenClaw to lekkie podejście do łączenia modeli językowych z narzędziami, API i twoją logiką biznesową. W praktyce: uczysz model, kiedy i jak wzywać funkcje, a on zwraca wynik, który napędza następny krok. Działa to z dowolnym LLM obsługującym funkcje lub narzędzia, od OpenAI, przez Anthropic i Google, po lokalne modele. Ten tekst pokazuje, jak myśleć o integracjach, jak je zaprojektować bezpiecznie, i jak uniknąć znanych pułapek. Wszystko po polsku, bez marketingowego dymu. Co to jest OpenClaw i dlaczego ma sens OpenClaw rozumiem jako praktyczną konwencję oraz zestaw lekkich komponentów do budowy agentów sterowanych narzędziami. Nie stawia wielkich wymagań. Zamiast monolitu dostajesz proste elementy: rejestr narzędzi z dobrze opisanymi interfejsami, pętlę decyzyjną, adaptery do LLM i mechanizmy egzekwowania uprawnień, limitów oraz obserwowalności. Możesz użyć go z istniejącym stosem: FastAPI, Celery, Redis, Postgres, Twój ulubiony model i Twoje API. Najczęściej szukasz odpowiedzi na trzy pytania: Jak sprawić, żeby model wzywał właściwe narzędzia we właściwym momencie. Jak pilnować bezpieczeństwa i kosztów, kiedy agent ma dostęp do prawdziwych systemów. Jak debugować, testować i rozwijać takie rozwiązania bez magii i bezlosowości. OpenClaw adresuje te punkty, stawiając na jawne definicje narzędzi, przejrzyste logi i testowalne pętle działania. Dość teorii, przejdźmy do mięsa. Mentalny model: rozmowa, decyzja, działanie, obserwacja Agent zbudowany w duchu OpenClaw działa w cyklu: 1) model dostaje kontekst, 2) wybiera narzędzie i parametry, 3) system wykonuje wywołanie, 4) wynik wraca do modelu, 5) model postanawia, czy zamknąć sprawę, czy wołać kolejne narzędzie. To ReAct w wersji praktycznej. Na wierzchu masz politykę: co wolno, ile razy, ile to może kosztować, kiedy przerwać. Najważniejsze: narzędzia są pierwszoplanowe. Każde narzędzie to mała umowa: opis, parametry, ograniczenia, efekty uboczne. Model może wymyślać odpowiedzi, ale narzędzi nie wymyśli, jeśli mu ich nie dasz. Minimalny przepływ: definicja narzędzia, jedno wywołanie, wynik Załóżmy, że budujesz agenta, który sprawdza pogodę i umawia kuriera, jeśli ma padać. Pseudokod w Pythonie poniżej pokazuje układ typowy dla OpenClaw: deklarujesz narzędzia, przekazujesz je do modelu, a pętla wykonawcza robi resztę. # narzędzia From pydantic import BaseModel, Field Import requests Class WeatherArgs(BaseModel): City: str = Field(..., description="Miasto, np. 'Kraków'") Date: str = Field(..., description="Data w ISO, np. '2026-05-22'") Def get_weather(city: str, date: str) -> dict: # wywołanie dowolnego API pogodowego (tu prosty szkic) Resp = requests.get("https://api.example.com/weather", params="city": city, "date": date, timeout=5) Resp.raise_for_status() Return resp.json() Class CourierArgs(BaseModel): Address: str Date: str Note: str | None = None Def schedule_courier(address: str, date: str, note: str | None = None) -> dict: # wysyłka do systemu kurierskiego Return "ok": True, "eta": "10:00-12:00", "job_id": "JOB-12345" Tools = [ "name": "get_weather", "description": "Sprawdza prognozę pogody dla miasta w danym dniu", "args_schema": WeatherArgs, "handler": get_weather, "side_effects": "none", "timeout_s": 5 , "name": "schedule_courier", "description": "Umawia kuriera na odbiór przesyłki pod wskazany adres", "args_schema": CourierArgs, "handler": schedule_courier, "side_effects": "writes", "timeout_s": 10 ] # adapter LLM z funkcjami/narzędziami From my_llm_adapter import chat_with_tools System_prompt = """Jesteś asystentem logistycznym. Jeśli prognoza deszczu >= 50%, zaproponuj umówienie kuriera; w innym wypadku grzecznie odmów. Najpierw sprawdź pogodę przez 'get_weather'. Umawiaj kuriera tylko jeśli użytkownik potwierdzi adres.""" User_msg = "Hej, jutro z Krakowa wysyłam paczkę. Czy zamówić kuriera? Adres: ul. Konopnickiej 1." Result = chat_with_tools( System=system_prompt, Messages=["role": "user", "content": user_msg], Tools=tools, Max_tool_calls=3, Budget_tokens=3000 ) Print(result.final_answer) Print(result.trace) # pełna ścieżka: decyzje, parametry, czasy, błędy Co się dzieje pod spodem: model widzi definicje narzędzi, wybiera get weather z parametrami, wynik trafia z powrotem do modelu, ten decyduje, czy wzywać schedulecourier. Twoja pętla pilnuje limitów i wyłącza agentowi zasilanie, gdy robi się drogo lub niebezpiecznie. Dobre narzędzie to proste narzędzie Najlepiej działają małe, jednoznaczne funkcje. Jedna rola, jeden efekt. Wielofunkcyjne kombajny wprowadzają zamieszanie w głowach modeli i ludzi. Argumenty powinny być jawne i nazwane tak, jak mówi użytkownik. Jeśli użytkownik mówi klient, nie nazywaj parametru party_id. Mała checklista projektowania narzędzi: Czy opis narzędzia mówi, kiedy go użyć i kiedy nie używać. Czy każde pole ma krótki, niebudzący wątpliwości opis w języku użytkownika. Czy narzędzie ma klasę idempotency_key, jeśli ma skutki uboczne. Czy ustaliłeś restrykcyjne timeouty i sensowną politykę retry. Czy wynik zawiera stan, datę, ewentualny identyfikator transakcji. Ta piątka wystarcza, by 80 procent kłopotów w ogóle się nie pojawiło. Strategie łączenia modeli z narzędziami: nie zawsze trzeba robić orkiestrę symfoniczną Nie każde zadanie wymaga wieloagentowego spektaklu. Cztery wzorce pokrywają większość potrzeb. Single-shot z narzędziem. Użytkownik pyta o konkretną rzecz, model natychmiast wywołuje narzędzie, a potem pisze odpowiedź. Sprawdzenie statusu paczki, stanu magazynu, kursu walut. Plan and execute. Model najpierw układa krótki plan kroków, a następnie realizuje go przez kolejne wywołania. Dobre, gdy trzeba wykonać od 2 do 5 powiązanych akcji z kontrolą po drodze. ReAct z pamięcią krótką. Model tłumaczy na głos swoje myślenie, następnie wzywa narzędzia, ocenia wynik, idzie dalej. Przydatne w zawiłych zadaniach, ale pamiętaj o limitach tokenów i o tym, że to gadatliwe. Routowanie do wyspecjalizowanych agentów. Jeden agent tylko klasyfikuje zadanie i przekazuje je do agenta domenowego: finanse, logistyka, HR. Pomaga ujarzmić uprawnienia i ograniczyć powierzchnię ataku. Integracje: HTTP, bazy danych, pliki, zadania wsadowe Z technicznego punktu widzenia kluczowe jest ustabilizowanie krawędzi. Narzędzie niech konsumuje i zwraca Pydanticowe modele albo jawne JSON-y z wersją i typem. Na granicy zewnętrznego świata zadbaj o: Pragmatyczne timeouts: agresywne dla API publicznych, łagodniejsze dla twoich systemów, ale z deadline overall pętli. Retry z backoff i idempotencją: jeśli wywołanie coś zapisuje, przekaż idempotency_key i sprawdzaj, czy operacja nie wykonała się wcześniej. Ograniczenie rozmiaru odpowiedzi: ucinasz lub paginujesz dane, a do modelu przekazujesz streszczenie i wycinek, nie 10 MB JSON-a. Transformacje: osobna, testowalna funkcja mapująca wynik API do struktury wejściowej modelu. Dla baz danych często wystarcza, by model wzywał jedno narzędzie query_kb, które przyjmuje predefiniowane zapytania lub parametryzowane kwerendy, a nie pełny SQL. Pełny SQL brzmi kusząco, ale bywa zaproszeniem do prompt injection i przypadkowego DROP TABLE. Bezpieczeństwo: ogranicz zaufanie i powierzchnię Agent nie jest administratorem twoich systemów, tylko przechodniem z przepustką. To wymusza kilka praktyk. Oddziel narzędzia tylko-do-odczytu od tych ze skutkami ubocznymi. Te drugie wymagają dodatkowego warunku, na przykład pozytywnego potwierdzenia użytkownika, a czasem drugiej opinii modelu klasyfikującego ryzyko. Red team dla prompt injection. Zakładaj, że odpowiedzi z zewnętrznych źródeł mogą zawierać instrukcje, które mają zmylić agenta. Filtruj i skracaj wejście, dodawaj splatane instrukcje systemowe, nie przepuszczaj surowych treści do roli systemu. Uprawnienia i polityki. Każde narzędzie z metadanymi: owner, risk level, maxcalls persession, max callsper_minute. W pętli OpenClaw egzekwuj politykę niezależnie od tego, co powie model. PII i audyt. Jeśli agent przetwarza dane osobowe, loguj ścieżkę decyzyjną z pseudonimizacją i trzymaj dzienniki w bezpiecznym miejscu. W razie incydentu będziesz wiedzieć, co się stało, a nie tylko że się stało. Obserwowalność i testy: bez tego agent będzie świecił oczami, a ty czerwienią Najbardziej niedoceniane części projektu to telemetria i testy. W przypadku agentów są obowiązkowe. Śledzenie kroków. Każde wywołanie: timestamp, tokeny wejścia/wyjścia, narzędzie, parametry (z wyciętym PII), czas trwania, wynik lub błąd, koszt. To daje wykres przepływu i pozwala zobaczyć wąskie gardła. Testy regresyjne z próbkami rozmów. Zapisujesz złote ścieżki: wejście, przewidziane wywołania, oczekiwane odpowiedzi. Przy zmianie promptów lub wersji modelu odpalasz zestaw i szukasz różnic. Nie ma magii, jest diff. Symulatory narzędzi. W testach developmentowych handler narzędzia ma wariant stub i wariant chaos: czasem opóźnia, czasem zwraca błąd 502, czasem puste pole. Dzięki temu widzisz, czy agent rozumie, że życie nie jest deterministyczne. Koszt i wydajność: niskie latency to nie przypadek Z perspektywy kosztów najwięcej dają proste decyzje. Mniej gadania, więcej struktury. Zamiast skłaniać model do długich autowyjaśnień, poproś o krótkie myślenie w polu hidden thoughts lub po prostu wyłącz verbose chain-of-thought. Model nie potrzebuje pisać eseju, żeby wywołać getweather. Agresywne skracanie kontekstu. Kompresuj poprzednie narady do bulletów, używaj pamięci narzędziowej zamiast werbalnej. Dwa akapity streszczenia zamiast piętnastu ekranów czatu to gigabajty tokenów w skali miesiąca. Cache i deterministyczne narzędzia. Jeśli get_weather na ten sam parametr zwróci to samo w 5 minutowym oknie, kejsuj i dołącz metadane Freshness: 4 min. Model będzie pytał rzadziej. Batching i równoległość. Jeśli agent ma wykonać serię niezależnych zapytań, np. Pięć wyszukiwań, uruchom je równolegle i zepnij wyniki w jeden krok dla modelu. Kiedy prosty glue code wystarczy, a kiedy warto użyć OpenClaw Jeśli budujesz jednorazowe narzędzie: LLM tłumaczy dokument i uderza raz w twoje API, zwykły glue code wystarczy. Gdy pojawia się więcej narzędzi, polityk, uprawnień i testów, projekt rośnie w poprzek, nie tylko w głąb. Wtedy OpenClaw lub podobne podejście oszczędzi ci czasu na ujednolicenie rzeczy, które i tak napiszesz pięć razy. Różnica nie polega na magii, tylko na dyscyplinie: jawne definicje, ślad wykonania, testy i bezpieczne domyślne wartości. Jeśli jesteś już po uszy w dużym frameworku i cierpisz na rozbudowany graf przepływów, podejście OpenClaw da się wdrożyć stopniowo: najpierw ustandaryzuj definicje narzędzi i logowanie, potem dołóż polityki, na końcu uprość orkiestrację. Najczęstsze błędy przy łączeniu LLM z narzędziami Za szerokie narzędzia. Jedna funkcja do wyszukiwania, filtrowania, sortowania i zapisu. Model gubi, co jest kiedy dozwolone, i wzywa potwora na proste pytanie. Ukryte wymagania. Narzędzie potrzebuje address id z ERP, ale model ma tylko adres tekstowy. Agent prosi użytkownika o numer, którego nigdy nie widział na oczy, i rozmowa grzęźnie. Lepiej mieć narzędzie resolveaddress, które robi translację. Brak limitów. Bez max toolcalls, max totaltokens i kosztu per sesja agent może kręcić się w kółko. Pamiętaj o twardym stopie i sensownym komunikacie do użytkownika. Zbyt bogata pamięć. Trzymanie pełnych transkryptów całych rozmów przez dni jest drogie i obniża trafność. Kompresuj, kategoryzuj, odkładaj do pamięci wektorowej tylko to, co naprawdę potrzebne. Testy tylko na happy path. W produkcji najwięcej czasu schodzi na 429 i 502. Jeśli nie testujesz retry i degradacji, robisz to w niedzielę o 3 rano na prodzie. Przykład end-to-end: agent księgowy, który tworzy fakturę i wysyła ją klientowi Scenariusz: użytkownik pisze, że chce wystawić fakturę pro forma dla firmy ABC Sp. Z o.o. Na 12 300 zł, z terminem 14 dni i opisem usługi. Agent powinien: 1) zidentyfikować klienta w CRM, 2) utworzyć dokument w systemie faktur, 3) wysłać link e-mailem, 4) zwrócić streszczenie i numer. Jak do tego podejść. Definiujemy trzy narzędzia: find customer, createinvoice, send_email. Każde jest małe, z jasnym kontraktem. Pętla OpenClaw pilnuje, by email poszedł dopiero po potwierdzeniu. Class FindCustomerArgs(BaseModel): Query: str Def find_customer(query: str) -> dict: # minimalne pole: id, nazwa, email Res = requests.get("https://crm.local/customers/search", params="q": query, timeout=3).json() # załóżmy, że zwraca listę; my wybieramy najlepszy match heurystycznie Best = res["results"][0] if res["results"] else None Return "match": best, "count": len(res["results"]) Class CreateInvoiceArgs(BaseModel): Customer_id: str Amount_pln: float Due_days: int Description: str Proforma: bool = True Idempotency_key: str Def create_invoice(**kwargs) -> dict: # idempotentne wywołanie Headers = "Idempotency-Key": kwargs["idempotency_key"] Resp = requests.post("https://billing.local/invoices", json=kwargs, headers=headers, timeout=5) Resp.raise_for_status() Return resp.json() Class SendEmailArgs(BaseModel): To: str Subject: str Body: str Def send_email(to: str, subject: str, body: str) -> dict: # zewnętrzna bramka Return "ok": True, "provider_id": "mail-778" Tools = [ "name": "find_customer", "description": "Znajduje klienta po nazwie, NIP lub e-mailu", "args_schema": FindCustomerArgs, "handler": find_customer, "side_effects": "none", "timeout_s": 3, "name": "create_invoice", "description": "Tworzy fakturę lub pro formę", "args_schema": CreateInvoiceArgs, "handler": create_invoice, "side_effects": "writes", "timeout_s": 7, "name": "send_email", "description": "Wysyła wiadomość e-mail w sprawie dokumentu", "args_schema": SendEmailArgs, "handler": send_email, "side_effects": "writes", "timeout_s": 5, ] System = """Jesteś asystentem księgowym. Kroki: 1) identyfikuj klienta, 2) potwierdź szczegóły z użytkownikiem, 3) utwórz pro formę, 4) zapytaj, czy wysłać link e-mailem, 5) jeśli tak, wyślij. Nigdy nie wysyłaj e-maila bez wyraźnej zgody. W polu subject podaj numer dokumentu.""" W praktyce taki agent powinien mieć politykę: max 6 wywołań narzędzi, limit 2000 tokenów, retry 2 dla billing, a dla maila brak retry, jeśli provider zwrócił 4xx. Efekt uboczny maila można potwierdzić dodatkowym mini-LLM, który sprawdza treść pod kątem wrażliwych danych. Tak, to dodatkowy krok, ale sporo kosztownych wpadek bierze się z jednego bezrefleksyjnego send. Kwestia modeli: który LLM i jak go poustawiać Nie ma jednego zwycięzcy. Ważniejsze od wyboru modelu jest to, jak opakujesz narzędzia i jakie dasz prompty. Kilka wskazówek praktycznych. Ujednolicaj kontrakty narzędzi. Jeśli migrujesz między modelami, nie chcesz przerabiać pół systemu. Trzymaj spójne nazwy i opisy, a adapter LLM rób cienki. Preferuj tryb function calling lub tool use. Modele w tych trybach rzadziej halucynują parametry i lepiej trzymają się schematów. Zadbaj o walidację wejścia i domyślne wartości w Pydantic. Dopasuj styl promptu do modelu. Niektóre modele świetnie radzą sobie z krótkimi, dyrektywnymi instrukcjami. Inne potrzebują jednego przykładu użycia narzędzia. Sprawdź to empirycznie na 20 do 50 zadań z twojej domeny. Uważaj na długość odpowiedzi. Jeśli model generuje długie elaboraty, skróć system prompt o regułę: Odpowiadaj zwięźle, 2 do 4 zdań. Kiedy agent ma wykonać akcję, niech najpierw to zrobi, potem podsumuje. Ewaluacja: jak mierzyć jakość bez statystyk z księżyca W ocenie agentów najlepiej sprawdzają się metryki zadaniowe. Czy dokument został utworzony poprawnie? Czy zamówienie ma właściwe pozycje? Czy wiadomość dotarła? Liczby typu średnia długość odpowiedzi czy procent wywołań narzędzi to tylko sygnały pośrednie. Zbuduj zestaw 50 do 200 scenariuszy ze złotymi wynikami. Każdy scenariusz ma dane wejściowe, oczekiwany polski openclaw ciąg wywołań narzędzi i wynik końcowy. Uruchamiaj go przy każdej zmianie promptu, wersji modelu lub logiki polityk. Dodaj testy chaosu: celowo popsute odpowiedzi API, brakujące pola, dziwne daty. Lepiej wyłapać to w piątek przed południem niż w poniedziałek po fakturze. Szybka ścieżka wdrożenia OpenClaw w zespole Zrób katalog narzędzi z kontraktami i przykładami wejść/wyjść, w tym błędów. Postaw lekki trace: każda sesja ma identyfikator, listę kroków i koszt. Dodaj polityki: limity wywołań, timebox sesji, zasady dla narzędzi ze skutkami ubocznymi. Napisz 30 scenariuszy testowych z mockami narzędzi i jedną ścieżką chaosu. Wypuść do 5 procent użytkowników i mierz realne błędy oraz satysfakcję. To nie czary. To rzemiosło. Gdzie OpenClaw błyszczy, a gdzie niekoniecznie OpenClaw po polsku brzmi: rób prosto, jawnie i testowalnie. Najlepiej sprawdzi się, gdy: masz kilka do kilkunastu narzędzi o jasno określonych granicach, potrzebujesz wyraźnych polityk i śledzenia przebiegu, zespół ceni kod, który można przeczytać bez mapy metra. Mniej sensu ma tam, gdzie: rozwiązanie to pojedyncze zapytanie bez efektów ubocznych, środowisko jest ściśle zamknięte, a jedyną potrzebą jest generacja tekstu, masz już stabilny, jednorodny pipeline, który nie wymaga decyzji w locie. Jeśli jednak projekt ma rozmawiać z prawdziwym światem, a nie tylko pisać haiku, narzędzia i polityki staną się centrum. OpenClaw daje tu zdrowy szkielet, bez zbędnej muskulatury. FAQ, które naprawdę się pojawia Czy mogę używać różnych modeli w jednym przebiegu? Tak, jeśli adaptery są spójne. Często warto: szybki, tańszy openclaw instalacja Linux model do klasyfikacji i routingu, droższy do precyzyjnej decyzji lub generacji treści do klienta. Jak ograniczyć halucynacje parametrów? Twarda walidacja Pydantic, enumeracje zamiast stringów, wartości domyślne i jasne przykłady. Jeśli pole jest kluczowe, rozważ wymuszenie potwierdzenia użytkownika lub dodatkowe narzędzie resolve_x. Co z lokalnymi modelami? Działają, o ile obsługują funkcje lub strukturalny output. Musisz bardziej dopracować prompty i tolerować inną dynamikę błędów, ale zyskujesz kontrolę nad danymi i kosztami. Czy agent powinien sam poprawiać swoje błędy? Do pewnego stopnia. Retry na poziomie narzędzia to dobry start. Auto-reflection przez mały model może pomóc, ale wprowadza latency. Unikaj nieskończonych pętli poprawiania się. Jak mierzyć ROI? Liczba spraw załatwionych end-to-end bez człowieka, skrócenie czasu odpowiedzi, spadek liczby eskalacji i koszt tokenów na sprawę. Jeśli te cztery wskaźniki idą w dobrym kierunku, agent działa. Ostatnia rada praktyka Projektując agenta, zapomnij na chwilę o wielkich słowach, a pomyśl jak o junior developerze. Daj mu małe, dobrze opisane funkcje, ustaw limity, patrz w logi, wdróż testy i nie pozwalaj na operacje nieodwracalne bez potwierdzenia. Taki junior awansuje na pewnego specjalistę szybciej, niż myślisz. Jeśli chcesz, by openclaw po polsku nabrał kształtu w twojej firmie, zacznij od jednego sensownego przypadku, który kończy się realną akcją: zamówienie, rezerwacja, faktura, wysyłka. Pokaż wynik, podlicz czas i koszt, potem dopiero dorzucaj kolejne narzędzia. Agenty ai lubią rosnąć stopniowo. Ty i twoi użytkownicy też.