Pięć wzorców inżynierii agentów, które warto zapożyczyć z Harness od DeepSeek
Log wydarzeń jako źródło prawdy, stopniowane ostrzeżenia o pętlach, jawne skracanie danych, tryb kodu z weryfikacją uprawnień oraz przenoszenie stanu agenta – pięć wzorców budowy systemów agentowych nadających się do debugowania.
Źródła: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness
Agenci coraz lepiej radzą sobie z pisaniem kodu, używaniem narzędzi, wyszukiwaniem plików oraz realizacją długotrwałych zadań. Pod tym wszystkim kryje się jednak poważniejszy problem: co powstrzymuje agenta przed staniem się chaotycznym, nieprzewidywalnym i niemal niemożliwym do debugowania? Przeglądając decyzje inżynieryjne zastosowane w otwartym oprogramowaniu do zarządzania agentami DeepSeek, można znaleźć pięć pomysłów, które warto przejąć, nawet jeśli nigdy nie będziemy korzystać z tego oprogramowania. Nie są to tak bardzo triki DeepSeek, ile raczej wzorce działania przydatne dla systemów agentowych w ogóle.
1. Uczyń dziennik zdarzeń źródłem prawdy
Większość systemów agentowych przechowuje informacje o rozmowie w liście, który jest przekazywany modelowi:
messages = [...]
W innym miejscu dziennikarz zapisuje to, co się wydarzyło:
logger.info({
"messages": messages,
"tool_calls": tool_calls,
"tokens": tokens
})
To wydaje się rozsądne, ale powoduje to dwa opisy tych samych wydarzeń, a to jest właśnie niebezpieczna część. Załóżmy, że aplikacja edytuje listę wiadomości przed jej wysłaniem, na przykład dodając dodatkową instrukcję:
messages.append({
"role": "system",
"content": "Remember to be concise."
})
Jeśli dziennik zdarzeń w ogóle nie odnotował tej edycji, model zaobserwował coś, o czym twoje logi nic nie wiedzą. Sześć godzin później agent postępuje w dziwny sposób, a ty otwierasz logi, zastanawiając się dlaczego. Wyjaśnieniem może być wiadomość systemowa, która nie pojawia się nigdzie w zapisanej historii.
Lepsze podejście
Niech dziennik zdarzeń będzie jedynym źródłem prawdy. Zawiera on fakty, takie jak prośba użytkownika, każde wezwanie narzędzia, każdy wynik oraz odpowiedzi asystenta:
events = [
UserMessage("Fix the authentication bug"),
ToolCall("grep", {"query": "auth"}),
ToolResult("Found 12 matches"),
AssistantMessage("I'll inspect the middleware")
]
Kontekst modelu jest następnie wyprowadzany z tych wydarzeń i nie jest przechowywany jako odrębna lista:
def build_context(events):
return [
event.to_message()
for event in events
if event.visible_to_model
]
Kluczowe jest to, że nie istnieje żaden prywatny, ukryty zbiór wiadomości. Obliczasz go za każdym razem. Porównaj obie struktury. Ta preferowana biegnie od logu, przez konstruktor kontekstu, aż do żądania:
Event Log
↓
Context Builder
↓
LLM Request
Należy unikać rozdzielania dziennika – jedna gałąź ma za zadanie przekazywać dane z dziennika, a druga informacje kierowane do modelu:
Event Log ─────────→ Logs
\
→ Messages ─→ LLM
To niewielka zmiana strukturalna znacznie ułatwia debugowanie.
Pójdź dalej i to sprawdź
W trakcie rozwoju możesz dodać sprawdzenie, które odbudowuje oczekiwany kontekst na podstawie logów i porównuje go z tym, co faktycznie ma zostać wysłane:
expected = build_context(event_log)
actual = request.messages
if actual != expected:
raise RuntimeError(
"log-reconstruction desync"
)
Gdy to zostanie wdrożone, drift w kontekście staje się nieudanym testem, a nie zagadkową błędem w produkcji. Jest jeszcze jeden plus – możliwości obserwacji stają się znacznie bardziej przydatne. Jeśli widok trajektorii pokazuje wywołania modelu, wywołania narzędzi, wyniki tych narzędzi, użycie tokenów oraz czas trwania operacji, nikt nie musi składać osobnej historii tego, co się wydarzyło, ponieważ informacje te są już dostępne: agent potrzebuje ich do odbudowy własnego kontekstu. Jedno źródło prawdy pełni w ten sposób dwie funkcje.
2. Nie blokuj od razu pętli agenta
Każdy deweloper agentów prędzej czy później napotyka ten problem. Model wielokrotnie uruchamia tę samą wyszukiwarkę:
grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...
Problem jest prosty, a oczywiste rozwiązanie również: odrzucaj powtarzające się połączenia.
if previous_call == current_call:
raise LoopError()
Problem polega na tym, że powtarzanie jest czasami uzasadnione. Prośba sieciowa może się nie powieść, plik mógł ulec zmianie i rzeczywiście może być konieczna ponowna próba. Zamiast blokować model, należy go ostrzec.
Załóżmy system ciśnienia, który rośnie wraz z liczbą powtórzeń:
3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder
Pierwszy poziom może stwierdzić, że ten sam wywołanie narzędzia jest powtarzane, i zasugerować ponowne przeczytanie ostatniego wyniku:
if repeat_count >= 3:
inject(
"You are repeating the same tool call. "
"Re-read the last result and consider another approach."
)
Drugi poziom jest bardziej stanowczy i nakazuje agentowi zatrzymanie się oraz ponowną ocenę sytuacji:
if repeat_count >= 5:
inject(
"You have repeated this exact operation several times. "
"Stop and reassess the approach."
)
W trzecim przypadku komunikat wskazuje, że sytuacja przypomina pętlę i konieczna jest zmiana podejścia, albo praca powinna zostać zakończona:
if repeat_count >= 8:
inject(
"This appears to be a loop. "
"Change your approach or wrap up."
)
Zwróć uwagę, czego pas nie robi. Nigdy nie zwraca takiej prostej odmowy:
return False
Kontrola pozostaje w rękach modelu. Pas dostarcza jedynie dodatkowych informacji i pozwala modelowi podjąć decyzję, co stanowi ważną różnicę.
Liczba rzeczywistych powtórzeń
Dobry detektor nie może dać się oszukać niepowiązanymi wywołaniami wplecionymi pomiędzy nimi. Ta sekwencja powinna nadal być uznawana za powtórzenie:
grep foo
todo update
grep foo
W przeciwnym razie model mógłby resetować swój własny licznik, wykonywając bezsensowne zadania pomiędzy identycznymi wywołaniami. Argumenty również powinny być znormalizowane, dzięki czemu te dwa przypadki będą traktowane jako ta sama operacja:
{"query": "foo", "path": "src"}
i:
{"path": "src", "query": "foo"}
Kolejność kluczy w słowniku nie powinna mieć znaczenia. Powinny być uwzględniane również odrzucone połączenia. Jeśli model nadal próbuje robić coś takiego:
run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied
To właśnie wtedy musi uświadomić sobie, że może być mądre przestać próbować.
Ogólny wzorzec
Słaba strategia to bezrefleksyjna reakcja na złe zachowanie:
Bad behavior → hard block
Mocniejszy model wykrywa takie zachowanie, zwiększa informacje zwrotne i umożliwia modelowi odzyskanie równowagi:
Bad behavior
↓
Detect
↓
Increase feedback
↓
Let model recover
To myląco prosta koncepcja, która pasuje do niemal każdego frameworku agenta umożliwiającego wywoływanie narzędzi.
3. Powiedz modelowi to, czego nie widział
To brzmi oczywiste, a mimo to wiele narzędzi robi to błędnie. Załóżmy, że repozytorium zawiera tyle danych:
4,000 files
a narzędzie wyszukiwania zwraca tylko to:
100 files
Jeśli odpowiedzią są po prostu te sto plików, model może dojść do wniosku, że dokładnie sto plików pasuje. W rzeczywistości narzędzie mówiło „oto sto plików, bo przestałem szukać”, a oba znaczenia są zupełnie różne.
Jasno określ wycinek
Lepsza odpowiedź wyjaśnia, co się stało i gdzie znajduje się reszta:
Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt
Model wie teraz trzy rzeczy: istnieje więcej wyników, to, co ma, to tylko ich podzbiór, a pełna lista jest dostępna w razie potrzeby. To o wiele bezpieczniejsza sytuacja.
Próbkowanie może być lepsze niż wybranie pierwszych N elementów
Załóżmy, że istnieje 4 000 plików, a miejsca na 100. Prosty sposób to po prostu wycinek:
results[:100]
Uporządkowane wyniki mogą być niebezpieczne, ponieważ można otrzymać setki plików z jednego katalogu lub według jednego wzoru nazewnictwa. Rozmieszczenie przykładów w całej liście dostarcza więcej informacji:
def sample_results(results, limit=100):
step = len(results) / limit
return [
results[int(i * step)]
for i in range(limit)
]
Dokładny algorytm ma mniejsze znaczenie niż zasada: nigdy nie pozwól modelowi mylić tego, co istnieje, z tym, co pokazało narzędzie.
Błędy wymagają takiej samej uwagi
Błędy narzędzia również mogą wprowadzić w błąd agenta. Załóżmy, że jakiś polecenie jest zablokowane z powodu polityki bezpieczeństwa. Taka prosta wiadomość jest niewystarczająca:
Permission denied
Ponieważ model może uznać, że jego składnia była błędna, i wtedy próbować ponownie, raz po raz. O wiele lepszym komunikatem jest jasny przekaz:
Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.
To nie jest zwykła przyjazna wiadomość – to wskazówki dla agenta. Twoje narzędzia robią coś więcej niż tylko wykonywają operacje, ponieważ komunikują się z innym systemem rozumowania. Wynik działania narzędzia powinien odpowiadać na jedno pytanie: co model musi wiedzieć, aby podjąć prawidłową decyzję?
4. Wykonywanie kodu nie może obejść się bez uprawnień
Kolejnym wzorcem w nowoczesnych systemach agentów jest tryb kodowy. Zamiast zezwalać na jedno wezwanie narzędzia na rundę, dostarczasz modelowi środowisko programistyczne:
files = search("authentication")
for file in files:
content = read_file(file)
print(analyze(content))
To jest potężne. Zwykły pętla polega na naprzemiennym wywoływaniu modelu i narzędzia, runda po rundzie:
LLM
↓
search
↓
LLM
↓
read
↓
LLM
↓
read
↓
LLM
↓
read
tryb kodu umożliwia modelowi uruchomienie programu, który dokonuje wielu wywołań i zwraca streszczenie:
LLM
↓
run_code(...)
↓
50 tool calls
↓
summary
To może znacznie skrócić czas podróży i zużycie zasobów, ale rodzi poważne pytania dotyczące bezpieczeństwa.
Kto sprawdza wywołania wewnątrz programu?
Zwykła architektura przesyła każdą akcję modelu przez warstwę uprawnień, zanim dotrze do narzędzia:
Model
↓
Permission Layer
↓
Tool
Jeśli lekkomyślnie dodasz wykonywanie kodu, ten może bezpośrednio dotrzeć do narzędzi:
Model
↓
Code
↓
Tool
Jeśli tak jest, stworzyłeś tajne wejście wokół swojego systemu uprawnień, co jest wyraźnie złe. Prawidłowe projektowanie zapewnia, że każde wezwanie z programu odbywa się po tym samym ścieżce bezpieczeństwa:
Model
↓
run_code
↓
Program
↓
Permission Layer
↓
Tool
Każde wezwanie narzędzia nadal przechodzi przez ten sam proces. Koncepcyjnie sama funkcja odczytu pliku sprawdza uprawnienia przed wykonaniem jakichkolwiek działań:
def read_file(path):
permission = check_permission(
operation="read",
path=path
)
if not permission.allowed:
raise PermissionError(
"File access denied"
)
return actual_read(path)
Interpretator kodu nie otrzymuje żadnej specjalnej wersji funkcji. Otrzymuje tę samą, którą używają wszyscy inni.
Zmiana odrzuceń na zwykłe błędy programu
Następuje jeszcze jeden subtelny szczegół. Jeśli program próbuje zrobić coś, czego nie ma prawa robić:
try:
delete_file("/important/file")
except PermissionError as e:
print(e)
Powinno otrzymać zwykły błąd, który można złapać. Nie powinno pozostawać w takim stanie nieograniczenie długo:
hang forever
Nie powinno w tajemnicy otrzymywać pustego wyniku:
return None
I nie powinno zachowywać się tak, jakby nic się nie stało:
pretend nothing happened
Program musi zrozumieć, że operacja się nie powiodła, co jest szczególnie ważne, gdy model pisze programy w czasie rzeczywistym. Tryb kodu jest tak potężny właśnie dlatego, że daje modelowi większą kontrolę, a to oznacza, że zasady uprawnień muszą być bardziej restrykcyjne, a nie mniej.
5. Czasami najlepszą strategią kontekstu jest brak kontekstu
To jest pomysł, którego powinni spróbować więksi twórcy agentów. Agenty działające przez długi czas gromadzą ogromne ilości historii rozmów. Na początku to pomaga, potem staje się obciążeniem. W rezultacie otrzymujemy łańcuch rund, które karmią gigantyczny kontekst:
Round 1
↓
Round 2
↓
Round 3
↓
Round 4
↓
Round 5
↓
Huge context
Teraz model poświęca swoją uwagę ponownemu przeglądaniu własnej historii, zamiast rozwiązywać zadanie. Streszczanie to jeden ze sposobów na rozwiązanie tego problemu, ale istnieje też inny: należy zakończyć rozmowę i zachować przestrzeń roboczą.
Weźmy zadanie programistyczne składające się z pięciu rund. W pierwszej rundzie pierwszy agent sprawdza repozytorium, wprowadza zmiany, zapisuje swoją pracę i pisze notatkę przekazującą zadanie:
Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff
Druga runda zaczyna się od zupełnie nowego agenta, który analizuje przestrzeń roboczą i przejęcie zadań, a następnie kontynuuje pracę:
Agent B
→ read workspace
→ read handoff
→ continue
Nie ma tu żadnej ogromnej historii, żadnego przestarzałego rozumowania ani zbędnego hałasu pochodzącego z narzędzi. Jedyne, co istnieje, to aktualny stan.