Nauczanie Deep Agents nowych umiejętności: planowanie, podagenty i pliki SKILL.md
W jaki sposób DeepAgents w LangChain łączą planowanie, podagenty, pamięć plikową oraz stopniowe ładowanie umiejętności z planem budowy, wskazówkami dotyczącymi testowania i notatkami dotyczącymi wdrożenia.
Sztuczna inteligencja agentowa dotyczy systemów składających się z kilku współpracujących agentów, które dzielą na części złożone problemy, wymieniają informacje i działają jak mały zespół specjalistów. Samotny chatbot odpowiada na jedno pytanie. System agentowy wymaga planowania, pamięci oraz wykorzystania narzędzi, aby móc wykonać zadanie w wielu krokach. Uczenie się przez wzmocnienie to klasyczna metoda dla agentów, które uczą się na podstawie prób i błędów: głęboka sieć obserwuje otoczenie, wybiera działania takie jak wywołanie narzędzi lub wykonanie kodu oraz otrzymuje nagrody, które kierują jej strategią. Głębokie uczenie się przez wzmocnienie przyniosło wyniki przewyższające możliwości ludzi w grach takich jak Go i szachy, a także dobre rezultaty w robotyce, wszystko dzięki maksymalizacji oczekiwanej kumulatywnej nagrody. Zastosowanie tych koncepcji do agentów napędzanych dużymi modelami językowymi otwiera ciekawą możliwość – mianowicie agenty, które mogą wykorzystywać powtarzalne procedury lub umiejętności, a następnie planować i działać z mniejszym wysiłkiem.
Co czyni agenta „głębokim”?
Agenci głębokie rozszerzają asystenta LLM o cztery funkcje:
- Narzędzie planowania, które dzieli złożone zadania na kroki.
- Podagenci do pracy równoległej i izolacji kontekstu.
- Trwały system plików pełniący również rolę pamięci.
- Szczegółowy prompt systemowy zawierający cele i ograniczenia.
Wspólnie umożliwiają one agentowi planowanie, przechowywanie stanu oraz wykonywanie złożonych procesów bez utraty kontekstu promptu. Bot powierzchowny odpowiada raz. Agent głęboki działa w pętli: planuje, wyszukuje, zapisuje znalezione informacje, syntetyzuje je i udoskonala. Gdy poproszony o raport, może stworzyć listę zadań, przeprowadzić wyszukiwania w internecie lub analizy, przechować notatki w plikach, a następnie napisać i poprawić tekst, przy czym wszystko to jest kierowane przez model bez udziału człowieka.
Uczenie się wzmacniające i źródło umiejętności
RL stanowi podstawę dla agentów, które uczą się poprzez działanie. Agent obserwuje stan, podejmuje działanie i otrzymuje nagrodę lub karę, a poprzez maksymalizację oczekiwanej sumy przyszłych nagród udoskonala swoją politykę. Różni się od uczenia się nadzorowanego, które wykorzystuje etykiety, oraz od uczenia się nienadzorowanego, które szuka ukrytej struktury, ponieważ zajmuje się sekwencyjnymi decyzjami w warunkach niepewności. Deep RL wykorzystuje sieci neuronowe jako aproksymatory funkcji, dzięki czemu można obsługiwać obrazy, tekst oraz surowe dane z czujników. Do dobrze znanych osiągnięć należą sieci Deep Q-Networks do gier Atari oraz metody oparte na gradientach polityki, takie jak PPO i A2C, stosowane w grach kontrolnych i strategicznych. Nowsze badania koncentrują się na hierarchicznym uczeniu się umiejętności, w którym agenci odkrywają opcje, czyli czasowo rozszerzone działania rozwiązujące podceli, co ułatwia eksplorację i przenoszenie wiedzy.
Dla agentów opartych na LLM, RL pełni dwie role. Po pierwsze, służy do drobnej optymalizacji samego modelu za pomocą sygnałów zwrotnych. Na przykład RLHF doprowadził do tego, że modele stały się bezpieczniejsze i bardziej związane z tematem. DeepSeek-R1 pokazał, że czysta RL bez danych oznaczonych może nauczyć model rozumowania, który może konkurować z najlepszymi systemami w dziedzinie matematyki i kodowania: model generuje kilka odpowiedzi, automatyczny oceniający nagradza te prawidłowe i karze pozostałe, a po wielu rundach algorytm taki jak PPO udoskonala strategię modelu. W rzeczywistych procesach mogą być dodane dodatkowe metody takie jak nadzorowana drobna optymalizacja i sampling odrzuceniowy w celu poprawy czytelności i bezpieczeństwa.
Druga rola występuje na poziomie ram agenta, gdzie metody inspirowane sztuczną inteligencją mogą pomóc w nabywaniu umiejętności. Agent może rejestrować ślady swoich działań (jakie narzędzia zostały użyte, jakie wyniki uzyskano) i przekazywać je do sztucznej inteligencji działającej offline lub uczenia się przez naśladowanie, aby wyodrębnić powtarzalne procedury. Analizując wcześniejsze sukcesy i porażki, może skompresować często powtarzane sekwencje narzędzi w rutyny wyższego poziomu. Te rutyny, zapisane jako pliki skryptów lub instrukcje w formacie Markdown, mogą być stopniowo ujawniane agentowi podczas kolejnych zadań. System w ten sposób osiąga formę uczenia się ciągłego: w obliczu czegoś nowego uczy się umiejętności „na miejscu” i przechowuje ją jako moduł.
Jak budowana jest biblioteka DeepAgents
Biblioteka DeepAgents od LangChain przekształca te koncepcje w gotowe rozwiązania przygotowane do użycia w praktyce, przy czym jej architektura jest kształtowana przez wieloetapowe agenty takie jak Claude Code i Manus.
- Planowanie za pomocą
write_todos. Wbudowany narzędzie umożliwia agentowi stworzenie kroku po kroku listy przed podjęciem działań. Lista ta kieruje pracą i może ulegać zmianom wraz z pojawianiem się nowych informacji. - System plików i pamięć. Narzędzia do obsługi plików (
ls,read_file,write_file,edit_file) pozwalają agentowi przechowywać dane w plikach lub bazach danych. Przechowywanie tymczasowych wyników i notatek zapobiega przepełnieniu okna kontekstowego i umożliwia ponowne sprawdzenie wcześniejszych kroków. Modułowy backend, niezależnie od tego, czy znajduje się w pamięci, na dysku lokalnym, w chmurze, czy w izolowanej przestrzeni sandbox, zajmuje się trwałym przechowywaniem danych oraz bezpieczną eksploatacją kodu.
task tworzy specjalistycznych pomocników, takich jak podagent do badań lub podagent do krytyki. Każdy z nich działa we własnym kontekście, dzięki czemu główny agent pozostaje uporządkowany, i może mieć własne instrukcje systemowe oraz narzędzia. Główny agent może przekazać mu zadania związane z wyszukiwaniem w sieci lub analizą kodu i otrzymać od niego streszczenia. Podagent uniwersalny po prostu odzwierciedla ustawienia głównego agenta, gdy potrzebna jest jedynie izolacja.SKILL.md oraz, opcjonalnie, skrypty lub dokumenty. Umiejętności różnią się od narzędzi tym, że nie są w pełni ładowane do promptu. Do kontekstu trafia jedynie YAML frontmatter (nazwa, opis, tagi), a pełne instrukcje są ujawniane stopniowo, gdy agent uzna je za istotne. Dzięki temu znacznie zmniejsza się zużycie tokenów. Umiejętność w formacie PDF może zawierać długi tutorial, który agent czyta tylko wtedy, gdy zadanie użytkownika dotyczy plików PDF. Umiejętności umożliwiają rozprzestrzenianie wiedzy i procedur między agentami, a ci mogą nawet tworzyć nowe definicje umiejętności w miarę realizacji nowych zadań.Dzięki takiemu projektowi agenci głębokie radzą sobie znacznie lepiej niż te płytkie przy długich, wieloetapowych zadaniach. Planują z wyprzedzeniem, korzystają z pamięci, uczą się na doświadczeniach i radzą sobie z dużymi kontekstami. Raporty branżowe wskazują, że zadania dla agentów stają się coraz bardziej złożone – ich długość mniej więcej podwaja się co kilka miesięcy, i to właśnie w takich sytuacjach te cechy są kluczowe. Zachodzi przejście od odpowiadania na pojedyncze zapytania do samodzielnego rozwiązywania problemów.
Krok po kroku – budowa
Poniższy plan łączy architekturę agenta z koncepcjami uczenia się przez wzmacnianie, tam gdzie to możliwe. Wykorzystuje Python oraz DeepAgents SDK. Zacznij od zainstalowania bibliotek i przygotowania środowiska:
# Install deepagents and necessary tools
!pip install --upgrade deepagents langchain tavily-python
# Import libraries and set API keys (e.g., for LLM and search tool)
import os
from getpass import getpass
os.environ["OPENAI_API_KEY"] = getpass("OpenAI API Key: ")
os.environ["TAVILY_API_KEY"] = getpass("Tavily API Key: ")
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FileData
from langchain.chat_models import init_chat_model
from tavily import TavilyClient
Definicja agenta i jego umiejętności
Następnie mamy do czynienia z zaawansowanym agentem wraz z jego narzędziami oraz dowolnymi z góry zdefiniowanymi umiejętnościami. Do zastosowań produkcyjnych lepszym wyborem niż tymczasowa pamięć jest trwały backend, taki jak dysk lokalny lub LangGraph. Ta wersja wykorzystuje FilesystemBackend umieszczony w katalogu bieżącym oraz ładuje foldery z umiejętnościami:
from deepagents import create_deep_agent
# Assume we have local skill directories under "./skills"
skill_dirs = ["./skills/pdf_processing", "./skills/data_analysis"]
agent = create_deep_agent(
model=model,
system_prompt="""
You are a highly capable AI assistant. Your objectives:
1. Break tasks into steps using write_todos().
2. Use internet_search and file tools to gather and store information.
3. When given a task, plan and execute it step-by-step, writing to files as needed.
4. Load skills from the filesystem to handle specialized tasks when relevant.
5. Summarize results and refine final output before returning.
""",
tools=[internet_search], # Web search tool
backend=FilesystemBackend(root_dir="./workspace"), # Persistent file storage
skills=skill_dirs, # Load skills from local directories
)
Wskazówki systemowe kładą nacisk na planowanie i wykorzystywanie umiejętności. Parametr skills wskazuje na katalogi, w których poszczególne podkatalogi zawierają plik SKILL.md oraz pliki pomocnicze. Na przykład ./skills/pdf_processing/SKILL.md może nauczyć agenta, jak analizować pliki PDF. Gdy umiejętności są w ten sposób załadowane, agent początkowo widzi tylko nazwy i opisy. Gdy zadanie użytkownika dotyczy plików PDF, agent czyta odpowiedni plik SKILL.md oraz wszystkie odnoszone do niego pliki, aby poznać procedurę.
Przykładowa struktura:
skills/
├── pdf_processing/
│ └── SKILL.md
└── data_analysis/
├── SKILL.md
└── analysis_script.py
A możliwy pdf_processing/SKILL.md:
---
name: pdf-processing
description: Skill to extract and analyze content from PDF documents.
---
# PDF Processing Skill
To use this skill, follow these steps:
1. Use `pdf-tools` to read PDF content.
2. Summarize key findings from the PDF text.
...
Pełne instrukcje są odczytywane tylko wtedy, gdy agent decyduje, że aktualna prośba dotyczy plików PDF. To właśnie jest progresywne ujawnianie informacji: duże pliki z instrukcjami nie powodują rozszerzania się każdego zapytania.
Jak wygląda proces wykonywania zadań
Teraz zadaj agentowi złożone zadanie. Początkowe zapytanie zachęca go najpierw do stworzenia planu.
from langchain.schema import HumanMessage
query = "Organize the latest quarterly sales data and write a summary report."
response = agent.invoke({
"messages": [HumanMessage(content=query)]
})
print(response["messages"][-1]["content"])
Koncepcyjnie agent prawdopodobnie wykona następujące czynności:
- Wywoła funkcję
write_todos(), aby stworzyć listę kontrolną – na przykład załaduje plik z danymi sprzedaży, utworzy wykresy, obliczy sumy i napisze raport. - Wykonuje wywołania narzędzi, korzystając z
internet_searchlub wbudowanych funkcji odczytu plików w celu zebrania istniejących danych. - W razie potrzeby przekazuje zadania związane z czyszczeniem lub analizą podagentowi, jeśli wymagane jest specjalistyczne podejście.
- Wykorzystuje posiadane umiejętności. Jeśli istnieje umiejętność analizy danych, może odczytać plik
SKILL.mdz katalogu./skills/data_analysisi postępować zgodnie z jego instrukcjami. - Zapisuje tymczasowe wyniki, takie jak wyczyszczone zbiory danych lub wykresy, w systemie plików.
- Pisze i dopracowuje ostateczny podsumowanie.
Pełna implementacja wywołuje zdalne modele LLM, więc weryfikacja polega głównie na poprawnym ułożeniu struktury. Kod wybiera niezawodny backend, otacza ryzykowne kroki blokami try/except (pełna wersja powinna łapać błędy API i plików) i można go rozszerzyć o middleware do logowania. Jednostkowe testy dla każdego narzędzia, z symulowanymi odpowiedziami modeli LLM, miałyby je zweryfikować.
Testowanie i ocenianie
Prace agentów ocenia się głównie na podstawie osądu. Sprawdza się, czy agent prawidłowo kończy zadania i trzyma się swojego planu. Jednym z podejść jest używanie syntetycznych zadań o znanych odpowiedziach: daje się mu mały projekt matematyczny i porównuje ostateczny raport z rozwiązaniem. Pomagają również automatyczne metryki, takie jak wskaźnik skuteczności zadań (czy każdy krok został zakończony) lub podobieństwo do odpowiedzi referencyjnej ocenianej przez model LLM. Tekst w formie swobodnej może nadal wymagać ludzkiej oceny lub krytyki opartej na modelu przed ostatecznym wykorzystaniem.
Jeśli RL jest wykorzystywane do nauki umiejętności, postępy można mierzyć za pomocą krzywych nagród. Stwórz środowisko, w którym ukończenie podzadań przynosi nagrodę, i przedstaw łączną nagrodę za każdą epizodę, być może używając OpenAI Gym lub własnego rozwiązania. Istotne wskaźniki to efektywność próbek (jak szybko następuje konwergencja nauki), ostateczna wydajność oraz stabilność przy różnych wartościach „random seed”. W praktyce należy również przeprowadzić serię zadań z zakresu badań, programowania i analizy, śledząc wskaźnik skuteczności oraz ilość użytych tokenów dla każdego z nich.
Obserwowalność jest kluczowa w środowisku produkcyjnym. Wyposaż agenta w funkcje śledzenia i rejestracji działań, ponieważ LangSmith może rejestrować każde wezwanie narzędzia oraz odpowiedź modelu LLM. W wdrożonym systemie logi mogą być przekazywane do CloudWatch lub Prometheus wraz z liczbą kroków, opóźnieniem na każde wezwanie oraz informacjami o błędach. W przypadku komponentów opartych na sztucznej inteligencji rejestruj historię nagród, krzywe strat oraz hiperparametry. Testy obciążeniowe z dużymi grupami danych, długimi sesjami oraz nietypowymi danymi pomagają potwierdzić stabilność.
Wdrożenie jako usługa
W rzeczywistym wdrożeniu agent działa jako mikrousługa. Skalowalna architektura wygląda w ten sposób:
+------------------+ +--------------+
| Client/User | <--> | API Gateway | <---> [HTTP requests]
+------------------+ +------+-------+
|
v
+-------------+
| AgentCore | <-- AWS Bedrock AgentCore (managed runtime)
+-------------+
|
+-------------+-------------+
| |
+-------------------+ +-------------------+
| Deep Agent Service | | Storage (S3/DB) | <-- File/memory backend, logs
+-------------------+ +-------------------+
| |
+-------------+-------------+
|
+---------------+
| LLM Models | <-- e.g., OpenAI, Anthropic, local LLMs
+---------------+
Usługa agenta w AWS AgentCore lub podobnym rozwiązaniu otrzymuje polecenia, koordynuje podagenty i wykonywa żądania do narzędzi, przy czym każda interakcja jest zapisywana w trwałym magazynie w celu umożliwienia monitorowania i przechowywania informacji. Wyróżnia się kilka kluczowych aspektów projektowych.
- Skalowalność i niezawodność. Agent powinien być uruchamiany w środowisku bezserwerowym lub kontenerowym, takim jak AWS Bedrock AgentCore, Azure AI Agent Service lub Kubernetes. Skaluje się on w zależności od obciążenia, uruchamiając nowe instancje na każde żądanie, a każda sesja może przebiegać w osobnej mikro-VM. Trwały backend (S3, baza danych lub magazyn LangGraph) przechowuje stan i informacje pamięciowe pomimo restartów.
- Obserwowalność. Śledź każde wezwanie. W AWS zestaw startowy Bedrock AgentCore łączy CloudWatch i X-Ray w celu monitorowania opóźnień i awarii. Rejestrowanie hashów zapytań i odpowiedzi zamiast surowych, wrażliwych danych nadal umożliwia śledzenie wydajności, a także użycia tokenów, liczby wywołań API oraz wskaźników skuteczności.
- Bezpieczeństwo. Ogranicz dostęp agenta do określonych zasobów. Narzędzia systemu plików powinny działać wyłącznie w wyznaczonych katalogach, a wykonywanie kodu w tle za pomocą
sandboxpowinno odbywać się w zabezpieczonych środowiskach takich jak Modal lub Daytona. Przypisz zasobom chmurowym, do których agent ma najmniejszy dostęp, role IAM o ograniczonych uprawnieniach, a także wdroż funkcje walidacji danych wejściowych i filtrowania treści poprzez kontrole bezpieczeństwa LLM przeciwko złośliwym zapytaniom. - Koszt. Należy pogodzić model z wyborami backendu. Tańszy model Anthropic może być używany do zadań rutynowych, natomiast model premium taki jak GPT-4o służy do kluczowych kroków planowania. Przenoszenie kontekstu do pamięci oraz ponowne wykorzystywanie wyników narzędzi zmniejsza liczbę powtarzających się tokenów promptu.
Pełny przykład
To przykładowe kodowanie w Pythonie realizuje plan, zawierając obsługę błędów i komentarze. Jest to wersja koncepcyjna – do działania wymagają rzeczywistych kluczy API oraz odpowiedniego środowiska.
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FileData
from langchain.chat_models import init_chat_model
from tavily import TavilyClient
import os
def setup_agent():
"""Initialize the Deep Agent with tools, skills, and system prompt."""
# Model and tools initialization
model = init_chat_model(model="openai:gpt-4o")
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def web_search(query: str, max_results: int = 3) -> str:
results = tavily_client.search(query, max_results=max_results)
return "\n".join(f"{r.title}: {r.summary}" for r in results)
# Create the deep agent with planning, files, and skills
try:
agent = create_deep_agent(
model=model,
tools=[web_search],
system_prompt="""You are an expert agent. Your workflow:
1. Create a plan with write_todos().
2. Use tools (e.g. web_search) and file system to research and work.
3. If specialized tasks arise, load relevant skills from the 'skills' directory.
4. Save results and refine the output at each step.
""",
backend=FilesystemBackend(root_dir="./workspace"),
skills=["./skills/pdf_processing", "./skills/data_analysis"]
)
return agent
except Exception as e:
print(f"Error initializing agent: {e}")
raise
def invoke_agent(agent, user_query):
"""Invoke the agent on a user query and return the final answer."""
try:
messages = [{"role": "user", "content": user_query}]
result = agent.invoke({"messages": messages})
return result["messages"][-1]["content"]
except Exception as e:
print(f"Agent invocation failed: {e}")
return None
# Example usage
if __name__ == "__main__":
agent = setup_agent()
task = "Analyze the recent research on climate change and summarize key findings."
answer = invoke_agent(agent, task)
print("Agent response:", answer)
Tworzenie i wywoływanie agenta odbywa się za pomocą funkcji z opisami dokumentacyjnymi oraz blokami try/except. Narzędzie web_search wykorzystuje Tavily do pozyskiwania danych z zewnątrz, a instrukcja systemowa nakazuje agentowi planowanie działań, wykorzystywanie posiadanych umiejętności oraz udoskonalanie swoich wyników. Wersja produkcyjna sprawdzałaby przypadki krawędziowe, takie jak puste wyniki wyszukiwania czy przekroczenie czasu oczekiwania API, oraz rejestrowałaby szczegóły wyjątków zamiast je wyświetlać. Sekrety powinny znajdować się w zabezpieczonym środowisku, a nie w kodzie źródłowym. Struktura ta naturalnie rozszerza się o kolejne narzędzia lub podagenty.
Aby prawidłowo to zweryfikować, należy napisać testy jednostkowe. Należy symulować LLM tak, aby zwracał ustalone wyniki planowania, i sprawdzić, czy agent tworzy oczekiwane pliki lub wywołuje narzędzia we właściwej kolejności. Należy również zmierzyć czas wykonywania zadań oraz koszt tokenów w ramach testów benchmarkowych.
Kwestie do rozważenia podczas planowania
Agenty zaawansowane łączą funkcje planowania, pamięci, delegowania zadań podagentom oraz możliwość ładowania różnych umiejętności, aby radzić sobie z zadaniami wieloetapowymi, których nie potrafią proste chatboty. Jasny prompt systemowy, podejście oparte na planowaniu oraz bogata lista narzędzi stanowią solidne podstawy dla autonomicznych asystentów. Umiejętności zawierają modułową wiedzę, na przykład pdf-processing lub deploy-to-prod, które są ładowane na żądanie, dzięki czemu kontekst pozostaje zwięzły, a agent może nadal się uczyć.
- Prawidłowość w stosunku do kosztów. Silne modele takie jak GPT-4o lub Claude Sonnet w połączeniu z rozległymi wyszukiwaniami poprawiają dokładność, ale zwiększają koszty tokenów i usług API. Mieszanie różnych rozmiarów modeli oraz wykorzystanie cache pomaga zrównoważyć jakość z wydatkami.
- Skalowalność w stosunku do złożoności. Serwerless runtime dla agentów, takie jak AWS AgentCore, zapewnia automatyczne skalowanie i możliwość monitorowania, ale wymaga integracji: konieczne jest konteneryzowanie kodu agenta oraz konfiguracja sieci.
W perspektywie przyszłości sam proces nabywania umiejętności mógłby zostać zautomatyzowany: uczenie się reinkarnacyjne lub beznadzorowane na podstawie wcześniejszych ścieżek mogłoby tworzyć nowe definicje umiejętności. Frameworki wieloagentowe, takie jak Microsoft AutoGen czy Salesforce AgentForce, mogłyby koordynować kilka specjalistycznych agentów komunikujących się za pośrednictwem protokołów LangGraph.
Stworzenie agenta, który uczy się umiejętności, wymaga dwóch rzeczy: odpowiedniego zestawu oprogramowania oraz, w razie potrzeby, technik uczenia się reinkarnacyjnego, które poprawiają jego funkcjonowanie z czasem. Dzięki DeepAgents i starannemu projektowaniu można stworzyć asystentów, którzy potrafią samodzielnie rozwiązywać złożone problemy, uczyć się nowych procedur i niezawodnie działać w dużych skali.
Literatura pokrewna
- LangGraph Multi-Agent Workflows: Porównanie zespołu agentów a nadzorcy — Podziel proces LangGraph na podagenty z funkcją przechowywania stanu, a następnie stwórz asystenta finansowego działającego zarówno jako zespół agentów, jak i nadzorca, aby zobaczyć, w którym momencie każdy z tych modeli przestaje być skuteczny.
- Triaging zapytań użytkowników za pomocą Multi-Agent i LangGraph — Stwórz graf triagingu zapytań składający się z trzech agentów przy użyciu LangGraph: klasyfikatora, osoby odpowiadającej na zapytania oraz ludzkiego moderatora, działających na lokalnym Ollama lub przez API, przy jedynie jednej zmienionej linii kodu.