Uwagi praktyczne: Orkiestracja wielu agentów: tworzenie i obserwowanie systemów z wieloma agentami
Praktyczne wskazówki: Orchestracja wielu agentów – tworzenie i obserwowanie struktur dla wielu agentów, w tym umowy, sprawdzania oraz gotowe elementy kodu przeznaczone dla zespołów wdrażających ten wzorzec.
To przewodnik pokazuje, jak odtworzyć proces od surowców do działającego systemu w ramach: Orkiestracji wielu agentów: budowanie i obserwacja systemów wieloagentowych za pomocą LangGraph i LangSmith. Skupiamy się na krokach operacyjnych, wyraźnych sprawdzeniach oraz kodzie, który można bez problemu dodać do repozytorium, nie musząc zgadywać intencji. Na etapie przeglądu należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać oddzielnie od kodu aplikacji. Pliki środowiskowe, magazyny tajemnic oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić, nie musząc czytać całego grafu.
Wprowadzenie: Czym jest orkiestracja agentów LangSmith?
Gdy przechodzisz przez etap Wprowadzenia: Co to jest LangSmith, 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. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Ustal punkty kontrolne po kosztownych krokach. System powrotu nie powinien ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Architektura: Jak działa orkiestracja w LangGraph
Gdy przechodzisz przez etap Architektura i Orkiestracja, 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 od rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. 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 uruchomić późniejszy węzeł.
Sposób konfiguracji orkiestracji:
Gdy przechodzisz przez etap „Jak wygląda orkiestracja”, 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ć przypadkowe częściowe ukończenie 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ł. Gdy przechodzisz przez etap „Jak wygląda orkiestracja”, 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.
Krok po kroku – przykład możliwy do odtworzenia
Etap „Przykład krok po kroku, łatwy do odtworzenia” funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny przepływ działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Zdokumentuj zarówno pomyślny, jak i alternatywny przepływ naprawczy. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później w celu udoskonalenia. Utrzymuj stan grafu w formie prostych, spójnych struktur. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane w danym polu, co utrudnia kontynuację działania po przerwach.
Wymagania wstępne
Etap wstępny funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wtórne struktury danych ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwę w kontynuacji pracy po zakłóceniach.
Krok 1: Konfiguracja środowiska
Etap ustawiania środowiska w Kroku 1 funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, 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 odrzuć ciche, częściowe ukończenie zadań. Utrzymuj stan grafu w prostej formie i określonej strukturze typów. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, co powoduje przerwanie kontynuacji pracy po zakłóceniach. Etap ustawiania środowiska w Kroku 1 funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny poufnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą audytować bez konieczności czytania całego grafu.
uv add langgraph langchain-anthropic langsmith python-dotenv
Krok 2: Kod w Pythonie
W drugim kroku, na etapie Pythona, należy zdefiniować dane wejściowe, osobę odpowiedzialną za ten krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponownego uruchomienia, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Należy oddzielić budowę klienta od pętli przetwarzania wiadomości, aby można było zmieniać dostawców bez konieczności przepisywania automatu stanu rozmowy.
import os
from typing import TypedDict, Literal
from dotenv import load_dotenv
from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import StateGraph, END
# ==========================================
# 0. Load Environment Variables
# ==========================================
# This loads the API keys and LangSmith configs from the .env file
load_dotenv()
# ==========================================
# 1. Define the Shared State
# ==========================================
class AgentState(TypedDict):
messages: list
next_agent: str
# ==========================================
# 2. Define the Nodes (The Agents)
# ==========================================
# Initialize Claude 3.5 Sonnet
llm = ChatAnthropic(model="claude-sonnet-4-5-20250929", temperature=0)
def router_node(state: AgentState):
"""Acts as the router. Classifies the user query and directs it to the correct department."""
system_prompt = SystemMessage(content=(
"You are a router agent. Look at the user's message and classify it as either "
"'billing' or 'technical'. Reply with ONLY the word 'billing' or 'technical'."
))
response = llm.invoke([system_prompt] + state["messages"])
classification = response.content.strip().lower()
# Update state with the routing decision
return {"next_agent": classification, "messages": [response]}
def billing_node(state: AgentState):
"""Handles billing-related queries."""
system_prompt = SystemMessage(content=(
"You are a billing support agent. Help the user with invoices, refunds, and payments. "
"Be polite and professional."
))
response = llm.invoke([system_prompt] + state["messages"])
return {"messages": [response]}
def tech_support_node(state: AgentState):
"""Handles technical issues."""
system_prompt = SystemMessage(content=(
"You are a technical support agent. Help the user troubleshoot bugs, login issues, "
"and software errors. Be analytical and helpful."
))
response = llm.invoke([system_prompt] + state["messages"])
return {"messages": [response]}
# ==========================================
# 3. Define the Routing Logic
# ==========================================
def route_decision(state: AgentState) -> Literal["billing", "technical"]:
"""Reads the state to decide which node to visit next."""
next_agent = state.get("next_agent", "technical")
# Claude is highly instruction-following, but we use 'in' to safely handle
# any edge cases where it might add conversational filler.
if "billing" in next_agent:
return "billing"
return "technical"
# ==========================================
# 4. Build and Compile the Graph
# ==========================================
workflow = StateGraph(AgentState)
# Add nodes
workflow.add_node("router", router_node)
workflow.add_node("billing", billing_node)
workflow.add_node("technical", tech_support_node)
# Define edges
workflow.set_entry_point("router")
# The magic of orchestration: Conditional routing based on state
workflow.add_conditional_edges(
"router",
route_decision,
{
"billing": "billing",
"technical": "technical",
}
)
# Both specialized agents end the workflow
workflow.add_edge("billing", END)
workflow.add_edge("technical", END)
# Compile the graph
app = workflow.compile()
# ==========================================
# 5. Run the Orchestration
# ==========================================
if __name__ == "__main__":
# Test Case 1: Billing Query
print("--- Running Billing Test ---")
inputs = {"messages": [HumanMessage(content="I was charged twice for my subscription!")]}
result = app.invoke(inputs)
print(result["messages"][-1].content)
print("\n")
# Test Case 2: Tech Support Query
print("--- Running Tech Support Test ---")
inputs = {"messages": [HumanMessage(content="My app keeps crashing when I click the save button.")]}
result = app.invoke(inputs)
print(result["messages"][-1].content)
Krok 3: Uruchom skrypt w celu przetestowania
W trzecim kroku, przed zmianą kodu, należy zdefiniować dane wejściowe, osobę odpowiedzialną za ten krok oraz kryteria zakończenia jego wykonywania. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, łatwe do przetestowania jednostki nad rozbudowanymi skryptami. Gdy krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesów. Konieczna jest ludzka akceptacja w przypadkach, gdy dochodzi do wydawania pieniędzy lub modyfikacji danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności rozwiązania biznesowego.
uv run multiagent-orchestration.py
Krok 4: Przegląd orkiestracji w LangSmith
W etapie 4 „View the stage” należy zdefiniować dane wejściowe, osobę odpowiedzialną za ten etap oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten etap od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. 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ń. Zapewnij ludzką aprobatę 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 procesu biznesowego. W etapie 4 „View the stage” należy zdefiniować dane wejściowe, osobę odpowiedzialną za ten etap oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten etap od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. 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.
To, co zobaczysz w LangSmith:
Gdy przechodzisz przez etap „To, co zobaczysz”, 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. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędowych są częścią produktu, a nie elementem dodatkowej optymalizacji. Ustaw punkty kontrolne po kosztownych krokach. System powrotu nie powinien ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Wniosek
Lista kontrolna operacyjna
Literatura pokrewna
- Praktyczne notatki: Agentic AI z LangChain — Część 7: Budowanie Multi-Agent — Szczegółowy przewodnik po Praktycznych notatkach: Agentic AI z LangChain — Część 7: Budowanie Multi-Agent: kontrakty, sprawdzenia oraz gotowe fragmenty kodu dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: Budowanie systemu triagowania zapytań podtrzymywania interakcji multi-agent za pomocą LangGraph — Szczegółowy przewodnik po Praktycznych notatkach: Budowanie systemu triagowania zapytań podtrzymywania interakcji multi-agent za pomocą LangGraph: kontrakty, sprawdzenia oraz gotowe fragmenty kodu dla zespołów wdrażających ten wzorzec.