Uwagi praktyczne: LangChain właśnie wypuścił zarządzane głębokie agenty — a Twój agent też jest już dostępny
Praktyczne wskazówki: LangChain właśnie wprowadził zarządzane głębokie agenty — a Twój agent też nimi jest: umowy, sprawdzania oraz gotowe miejsca na kod dla zespołów wdrażających ten model.
To przewodnik pokazuje, jak odtworzyć proces od surowców do działającego systemu dla LangChain Just Shipped Managed Deep Agents — a Twój agent jest teraz katalogiem. Skupiamy się na krokach operacyjnych, wyraźnych sprawdzeniach oraz kodzie, który można bez żadnych domysłów wkleić do repozytorium. Na etapie przeglądu należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Lepiej używać małych, testowalnych jednostek niż rozbudowanych skryptów. Gdy dany krok zawiedzie, powód awarii powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Czym właściwie są Managed Deep Agents
Gdy przechodzisz przez etap What Managed Deep Agents, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Ustaw punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie zrealizować późniejszy element.
uv tool install managed-deepagents
mda init research-assistant
cd research-assistant
uv sync
mda dev . # run locally in LangSmith Studio
mda deploy . # deploy to LangSmith
Zdolności twojego agenta są kontrolowane przez ls
Gdy przechodzisz przez etap Twoich możliwości agenta, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas trwania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do współdzielonych środowisk. Ustal punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłaty za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
my-agent/
├── agent.py # required — the model and core config
├── instructions.md # system prompt, synced to Context Hub
├── skills/
│ └── research/
│ └── SKILL.md # task-specific playbooks
├── tools/ # your LangChain tools
├── middleware/ # logic around model and tool calls
├── connectors/
│ └── mcp.py # remote MCP servers
├── channels/
│ └── slack.py # Slack, GitHub, other entry points
├── schedules/
│ └── daily_digest.py # managed cron jobs
├── sandbox/
│ └── __init__.py # isolated filesystem and shell
├── identity.py # auth and thread scoping
├── memory.py # durable cross-thread memory
├── pyproject.toml
├── .env
└── evals/ # Harbor tasks
Pliki, które wykonywają pracę
Gdy przechodzisz przez etap The Files That Do, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Ustaw punkty kontrolne po kosztownych krokach. Funkcja wznowienia nie powinna ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
agent.py — jedyne wymagane plik
Gdy pracujesz nad agentem py, w pierwszej kolejności zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez człowieka oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Ustaw punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
from managed_deepagents import define_deep_agent
from middleware.audit import log_tool_calls
from tools.search import internet_search
agent = define_deep_agent(
name="research-assistant",
model="openai:gpt-5.5",
tools=[internet_search],
middleware=[log_tool_calls],
interrupt_on={"internet_search": True},
)
tools=[{"type": "web_search"}] # OpenAI
tools=[{"google_search": {}}] # Google
tools=[{"type": "web_search_20260209", "name": "web_search"}] # Anthropic
instructions.md i skills/ — kontekst synchronizowany z chmurą
Gdy przechodzisz przez etap instrukcji i umiejętności, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolę małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Ustalaj punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą funkcję LLM, gdy operator próbuje ponownie wykonać późniejszy element.
# Research assistant
You are a careful research assistant. Use internet search to find sources,
keep notes, and return concise answers with citations.
---
name: research
description: Gather and synthesize context before answering complex questions.
---
# Research
Use this skill when a task needs more than a direct answer.
1. Identify what information is missing.
2. Use `query_db` to look up relevant records.
3. Summarize findings before responding to the user.
memory.py — trwała pamięć, opcjonalna
Gdy przechodzisz przez etap trwałej pamięci w systemie py, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć przypadki cichego, częściowego ukończenia zadania. Ustaw punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą próbę wywołania LLM, gdy operator ponawia działanie w późniejszym etapie.
from managed_deepagents import define_memory
memory = define_memory(scope="agent")
sandbox/ — izolowana środowisko z funkcją robienia kopii stanu
Gdy pracujesz w izolowanym środowisku shell, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy środowisko przechodzi z wersji demonstracyjnej do współdzielonych środowisk. Ustal punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą funkcję LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
from managed_deepagents import define_sandbox
sandbox = define_sandbox(
idle_ttl_seconds=600,
default_timeout=600,
docker_image="python:3.12-slim",
)
#!/usr/bin/env bash
set -euo pipefail
apt-get update && apt-get install -y jq
mkdir -p /workspace
schedules/ — cron z ograniczeniem na etapie kompilacji
Gdy projektujesz harmonogramy w Cron z poszczególnymi etapami, najpierw spisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Ustaw punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą operację LLM, gdy operator próbuje ponownie wykonać późniejszy element procesu.
from managed_deepagents import define_schedule
schedule = define_schedule(
cron="0 8 * * 1-5",
timezone="America/Los_Angeles",
prompt="Review durable memory for reusable research rules. List open questions for today.",
)
Gdy projektujesz harmonogramy w Cron z poszczególnymi etapami, najpierw spisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesu.
channels/ i connectors/ — przychodzące i wychodzące
Etap przetwarzania kanałów i połączeń przychodzących działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, co utrudnia kontynuację pracy po przerwach.
# channels/slack.py
from managed_deepagents import channels
channel = channels.slack(
auto_reply=True,
mention_behavior="strip",
conversation={"app_mention": "thread", "direct_message": "conversation"},
)
# connectors/mcp.py
from managed_deepagents import connectors
connector = connectors.mcp(
mcp_servers={
"langchainDocs": {
"transport": "http",
"url": "https://docs.langchain.com/mcp",
"include_tools": ["search_docs_by_lang_chain"],
},
},
)
identity.py — kto ma prawo to wywoływać
Tożsamość py, która jest używana na scenie, funkcjonuje najlepiej, gdy traktowana jest jako mierzalna powierzchnia. Zapisz jeden idealny przypadek, jeden przypadek awarii oraz notatkę o cofnięciu zmian, zanim rozszerzysz zakres pracy. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwanie kontynuacji po przerwach.
from managed_deepagents import auth, define_identity
identity = define_identity(auth=auth.langsmith_api_key())
identity = define_identity(auth=auth.supabase(project_ref="your-project-ref"))
Co tak naprawdę dzieje się, gdy uruchamiasz mda deploy
Faza „What Actually Happens When” funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Utrzymuj stan struktury w formie prostych, typowanych elementów. Wtórne struktury danych ukrywają informację o tym, który węzeł zapisał dane w danym polu, co utrudnia kontynuację pracy po przerwach. Faza „What Actually Happens When” funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakaś operacja się nie powiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną sekwencję działań.
Jak pasuje do ekosystemu LangChain
W fazie „Jak to pasuje” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Konieczna jest ludzka akceptacja w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się pełnej kompletności biznesowej.
Jedna rzecz, nad którą należy się zastanowić przed wypuszczeniem produktu
W fazie przygotowania „One Thing to Sit” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanej punktacji kontrolnej, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Konieczne jest ludzkie zatwierdzenie w przypadkach, gdy dochodzi do wydatków lub zmian w danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie gwarantują pełnej kompletności rozwiązania biznesowego.
Powierzchnia wciąż się porusza
W fazie The Surface Is Still należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Wprowadź ludzką aprobatę dla operacji, które wiążą się z wydawaniem pieniędzy lub modyfikacją danych produkcyjnych. Połączenia skompilowane w czasie kompilacji nie gwarantują pełnej kompletności biznesowej. W fazie The Surface Is Still należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki nad rozbudowanymi skryptami. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesów.
Kiedy należy (a kiedy nie należy) go używać
Podczas przechodzenia przez etap określania, kiedy należy go używać, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć możliwość cichego, częściowego ukończenia zadania. Ustaw punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Pierwsze kroki
Gdy przechodzisz przez etap wprowadzenia, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas trwania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Ustal punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji nie powinno ponownie naliczać opłaty za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
uv tool install managed-deepagents
mda init test-agent && cd test-agent
LANGSMITH_API_KEY=<your-key>
OPENAI_API_KEY=<your-key>
Odnośniki
Gdy przechodzisz przez etap Referencji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Ustaw kontrolne punkty po kosztownych krokach. System powinien unikać ponownego naliczania opłat za tę samą próbę wywołania LLM, gdy operator ponawia działanie późniejszego węzła. Gdy przechodzisz przez etap Referencji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną ścieżkę przetwarzania.
Etap listy kontrolnej operacyjnej działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres.
Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę przywracania. Próby ponowne, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później.
Zachowaj prostą i typowaną strukturę stanu grafu. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, i utrudniają kontynuację działania po przerwach.
Gdy budżet na to pozwala, dodaj test wstępny, który sprawdza kluczową ścieżkę działania w środowisku CI przy użyciu fixitów, a nie rzeczywistych, płatnych API.
Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakaś etap zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną sekwencję działań.
Zachowaj prostą i typowaną strukturę stanu grafu. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, i utrudniają kontynuację działania po przerwach.
Zanim zaczniesz promować tę architekturę, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów realizacji oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkownika oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca batchu 1ccea3d5e297: trzymaj klucze dostawcy poza repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików testowych, aby późniejsze zamiany modeli pozostały porównywalne.
Podczas pracy nad etapem 0 notatki dotyczącej wzmocnienia bezpieczeństwa najpierw zapisz warunki działania: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolimy małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Szczegół wzmocnienia 0/931: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Faza 1 notatki dotyczącej wzmocnienia działa najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmiany, zanim rozszerzysz zakres badania. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Szczegół wzmocnienia 1/931: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Literatura pokrewna
- Praktyczne notatki: Architektura głębokich agentów, Część 1: Zrozumienie agenta — Szczegółowy przewodnik po Praktycznych notatkach: Architektura głębokich agentów, Część 1: Zrozumienie agenta: kontrakty, sprawdzania oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: Twój agent AI nie jest mądry. Oto jak stworzyć takiego — Szczegółowy przewodnik po Praktycznych notatkach: Twój agent AI nie jest mądry. Oto jak stworzyć takiego: kontrakty, sprawdzania oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.