Przekazy zadań pomiędzy agentami w LangChain: budowa procesu pracy w IT Help Desk
Jeden agent LangChain, który zmienia swój prompt i narzędzia na każdym kroku: etapowy punkt obsługi IT z rzeczywistymi weryfikacjami tożsamości, przekazywaniem danych między warstwami oraz możliwością wyjścia poza zakres zadań.
Wyobraź sobie, że dzwonisz na infolinię IT po tym, jak zostaniesz wykluczony z konta. Osoba po drugiej stronie nie zadaje tych samych pytań na każdym etapie, a to, co może zrobić, zależy od tego, na jakim etapie znajduje się rozmowa. Najpierw potwierdza tożsamość, zazwyczaj poprzez numer identyfikacyjny pracownika lub nazwisko kierownika, i nie zajmie się problemem konta, dopóki to nie zostanie rozwiązane. Następnie dowiaduje się, co jest nie tak: zablokowane konto, zapomniane hasło lub brak urządzenia autoryzacyjnego. Dopiero wtedy podejmuje działania – ponownie aktywuje konto, wysyła link do sprostowania hasła lub przenosi rozmowę do zespołu bezpieczeństwa. Dla dzwoniącego wydaje się to jedną rozmową, chociaż jej zakres zmienia się w miarę jej trwania.
Przekazy informacji zapewniają agentowi AI taką samą strukturę. Agent zmienia to, co może robić, w zależności od aktualnego etapu interakcji. Na początku zbiera jedynie dane identyfikacyjne. Gdy to zostanie zrobione, pyta o rzeczywisty problem, a gdy problem stanie się jasny, podejmuje działania.
Dwa sposoby jego budowy
- Typ 1, podejście oparte na middleware, wykorzystuje jednego agenta, którego uprawnienia zmieniają się w miarę postępu rozmowy. Można to porównać do pracownika obsługi klienta, który korzysta z listy kontrolnej.
- Typ 2, podejście wieloagentowe, wykorzystuje kilku agentów, którzy przekazują sobie rozmowę, podobnie jak w przypadku przeniesienia sprawy do innego działu, gdy pierwsza osoba nie może pomóc.
Budowa opisana poniżej odpowiada typowi 1, często nazywanemu pojedynczym agentem, ponieważ kod zawiera dokładnie jednego agenta. Ten agent weryfikuje tożsamość, następnie diagnozuje problem, a potem go rozwiązuje. W żadnym momencie nie pojawia się nowy agent. Zmieniają się jedynie jego instrukcje oraz zestaw narzędzi na początku każdego etapu. Typ 2 różni się tym, że tworzy oddzielne agenty i przekazuje im rozmowę między sobą.
Projekt
Celem jest agent obsługi klienta w dziale IT, a w kodzie stosuje się trzy zasady:
- Nie omawia się żadnego problemu z kontem, dopóki tożsamość użytkownika nie zostanie potwierdzona na podstawie rzeczywistych danych.
- Nie podejmuje się żadnych działań, dopóki problem nie należy do jednej z trzech obsługiwanych kategorii.
- Gdy problem nie pasuje do żadnej z nich, agent o tym informuje zamiast zgadywać.
Przykład działania
Użytkownik skontaktowuje się z obsługą klienta po tym, jak nie może uzyskać dostępu do konta firmowego. Pracownik obsługi prosi o numer identyfikacyjny pracownika oraz imię menedżera. Pierwsza próba nie znajduje żadnej informacji o pracowniku, więc pracownik obsługi pyta ponownie, a druga próba potwierdza dane. Następnie pracownik obsługi pyta o problem. Użytkownik najpierw wspomina o osobistym koncie bankowym internetowym, który pracownik obsługi słusznie oznacza jako poza zakresem swoich obowiązków. Gdy użytkownik wyjaśnia, że problem dotyczy firmowego portalu IT, pracownik obsługi klasyfikuje go jako konto zablokowane, przywraca dostęp i kończy rozmowę po potwierdzeniu rozwiązania problemu.
Przebieg kodu
1. Schemat stanów
class HelpdeskState(AgentState):
current_step: NotRequired[HelpdeskStep]
identity_verified: NotRequired[bool]
verification_attempts: NotRequired[int]
issue_type: NotRequired[Literal["locked_account", "forgotten_password", "lost_mfa_device"]]
Pole current_step określa, która pozycja z STEP_CONFIG wpływa na następną odpowiedź, co ponownie zostanie omówione w rozdziale 4. Trzy dodatkowe pola (identity_verified, verification_attempts oraz issue_type) przechowują informacje zebrane dotychczas w trakcie rozmowy. Są one wstawiane do zapytań za pomocą .format(), dzięki czemu zapytanie służące do rozwiązania problemu może zawierać linijkę taką jak EMPLOYEE STATUS: identity_verified = {identity_verified}.
2. Prawda podstawowa do weryfikacji
EMPLOYEE_DIRECTORY = {
"EMP-4471": {"name": "Amit Rao", "manager": "Priya Nair", "department": "Finance"},
"EMP-1029": {"name": "Sara Khan", "manager": "David Chen", "department": "Engineering"},
"EMP-3305": {"name": "Neha Verma", "manager": "Priya Nair", "department": "Finance"},
}
MAX_VERIFICATION_ATTEMPTS = 3
def normalize_employee_id(raw_id: str) -> str:
digits = "".join(ch for ch in raw_id if ch.isdigit())
return f"EMP-{digits}" if digits else raw_id.strip().upper()
Model nigdy nie decyduje, czy numer identyfikacyjny pracownika jest ważny. Funkcja verify_identity porównuje ten numer z bazą EMPLOYEE_DIRECTORY, więc odpowiedź pochodzi z tej bazy, a nie z opinii modelu. Normalizator radzi sobie również z różnymi sposobami zapisywania tego samego numeru przez użytkowników: 4471, emp4471 oraz EMP-4471 są wszystkie przekształcane do jednego formatu przed wyszukiwaniem, co zapobiega odrzuceniu ważnych numerów z powodu różnic w formacie.
3. Narzędzia
Narzędzia dzielą się na dwa rodzaje. Narzędzia przejściowe zwracają obiekt Command. Zapisują one nowe wartości w stanie procesu i przesuwają current_step do następnego etapu.
@tool
def verify_identity(
employee_id: str,
manager_name: str,
runtime: ToolRuntime[None, HelpdeskState],
) -> Command:
attempts = (runtime.state.get("verification_attempts") or 0) + 1
normalized_id = normalize_employee_id(employee_id)
record = EMPLOYEE_DIRECTORY.get(normalized_id)
verified = bool(record and manager_name.strip().lower() == record["manager"].lower())
if verified:
content = f"Identity verified for {normalized_id} ({record['name']})."
elif attempts >= MAX_VERIFICATION_ATTEMPTS:
content = f"Verification failed {attempts} times. Session locked — visit IT in person."
elif record is None:
content = f"No employee found with ID '{employee_id}'. Please retry."
else:
content = "The manager name doesn't match our records. Please retry."
return Command(
update={
"messages": [ToolMessage(content=content, tool_call_id=runtime.tool_call_id)],
"identity_verified": verified,
"verification_attempts": attempts,
"current_step": "issue_diagnosis" if verified else "identity_verification",
}
)
Weryfikacja może skończyć się czterema możliwymi wynikami. Udaje się ona tylko wtedy, gdy zarówno numer identyfikacyjny pracownika, jak i nazwisko kierownika odpowiadają danym w bazie. Pozostałe trzy wyniki to osiągnięcie maksymalnej liczby prób, użycie numeru identyfikacyjnego, który nie istnieje, oraz podanie istniejącego numeru z błędnym nazwiskiem kierownika. Każdy z tych przypadków powoduje wyświetlenie innej wiadomości. Użytkownik, którego tożsamość została potwierdzona, przechodzi do kroku issue_diagnosis, natomiast we wszystkich pozostałych przypadkach pozostaje on w kroku identity_verification; nic więc nie może przejść dalej, dopóki tożsamość nie zostanie potwierdzona.
Narzędzia terminalowe zwracają zwykłą ciąg znaków i nie zmieniają wartości pola current_step, ponieważ proces pracuje już na swoim ostatnim etapie.
@tool
def flag_out_of_scope(reason: str) -> str:
return (
f"This request appears to be about a personal account, not your "
f"company IT account ({reason}). This helpdesk can't assist with "
f"that — please contact the relevant provider directly."
)
flag_out_of_scope ma takie samo znaczenie jak klasyfikator. Bez niego proces pracy próbowałby przyporządkować każdą prośbę do jednego z obsługiwanych typów problemów, nawet tych niespowiązanych, przez co problem z osobistym bankowaniem mógłby zostać błędnie oznaczony jako problem z obsługą IT. Narzędzie to daje agentowi prosty sposób na rozpoznawanie próśb wykraczających poza zakres procesu pracy.
4. Wskazówki i konfiguracja kroków
Każdy etap ma swoje własne wskazówki oraz listę narzędzi, przechowywane w jednym słowniku i wybierane na podstawie aktualnej wartości current_step.
STEP_CONFIG = {
"identity_verification": {"prompt": IDENTITY_VERIFICATION_PROMPT, "tools": [verify_identity], "requires": []},
"issue_diagnosis": {"prompt": ISSUE_DIAGNOSIS_PROMPT, "tools": [record_issue_type, flag_out_of_scope], "requires": ["identity_verified"]},
"resolution": {"prompt": RESOLUTION_PROMPT, "tools": [unlock_account, send_password_reset_link, escalate_mfa_recovery, go_back_to_verification], "requires": ["identity_verified", "issue_type"]},
}
Pole requires pełni rolę zabezpieczenia dla middleware, które sprawdza, czy spełnione są wymagane warunki, zanim zostanie zastosowana konfiguracja danej kroku.
5. Middleware
@wrap_model_call
def apply_step_config(
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
current_step = request.state.get("current_step", "identity_verification")
step_config = STEP_CONFIG[current_step]
for key in step_config["requires"]:
if request.state.get(key) is None:
raise ValueError(f"'{key}' must be set before reaching '{current_step}'")
system_prompt = step_config["prompt"].format(**request.state)
request = request.override(system_prompt=system_prompt, tools=step_config["tools"])
return handler(request)
Nazwa pochodzi od miejsca, w którym działa ten kod: pomiędzy obecnym stanem procesu a wywołaniem modelu. Zanim model wygeneruje odpowiedź, middleware odczytuje stan, zastępuje prompt oraz narzędzia odpowiednimi dla bieżącego kroku, a następnie przekazuje kontrolę dalej. Działa przed każdym wywołaniem modelu. Odczytuje current_step, ładuje odpowiadającą konfigurację, sprawdza, czy spełnione są wymagane warunki, formatuje prompt przy użyciu wartości z obecnego stanu i przydziela odpowiednie narzędzia. W ten sposób zachowanie agenta zmienia się w miarę postępu procesu.
6. Budowa agenta
agent = create_agent(
model,
tools=all_tools,
state_schema=HelpdeskState,
middleware=[apply_step_config],
checkpointer=InMemorySaver(),
)
Checkpointer jest niezbędny, ponieważ przechowuje stan procesu roboczego pomiędzy wiadomościami. Bez niego current_step jest resetowany przy każdym wywołaniu, przez co agent zaczyna od pierwszego kroku za każdym razem i nigdy nie postępuje dalej.
Decyzje projektowe zapobiegające błędom
Istnieje kilka szczegółów, które pomagają uniknąć częstych awarii w tego typu procesach roboczych.
- Weryfikacja sprawdza rzeczywisty rekord. Gdyby
verify_identityzadawało pytanie modelowi, czy numer identyfikacyjny i nazwa kierownika wydają się prawidłowe, wszystko, co brzmi wiarygodnie, zostałoby zaakceptowane. Sprawdzanie wEMPLOYEE_DIRECTORYeliminuje konieczność domysłów. - Identyfikatory są normalizowane przed dopasowaniem. Wymaganie dokładnego formatu, np. EMP-4471, odrzuciłoby ważne dane takie jak 4471 lub emp4471 wyłącznie ze względu na sposób ich wpisania. Normalizator najpierw przekształca powszechne formaty na jeden standardowy wzór.
- Klasyfikator ma opcję wyjścia „żadne z tych”. Funkcja
record_issue_typeprzyjmuje tylko trzy kategorie. Bez flagiflag_out_of_scopeprośby niespowiązane, takie jak pytania o bankowość, byłyby przymuszane do najbliższej kategorii. - Sprawdzenie wyjścia w interfejsie wiersza poleceń odpowiada konkretnej frazie. Prosty test typu
user_input in {"quit", "exit"}działa tylko wtedy, gdy cała wiadomość to dokładnie jedno z tych słów. Reguła regex oparta na granicach słów wykrywa takie przypadki w dowolnym miejscu zdania, włączając coś w rodzaju „quit and exit”.
W każdym przypadku najprostsza implementacja wydaje się poprawna, ale zawodzi przy rzeczywistych danych wejściowych.
Krótki opis wzorca
Przenoszenie stanu między agentami wymaga zaledwie trzech elementów. Pole current_step przechowuje aktualny etap, narzędzia je zmieniają, a middleware korzysta z nich przed każdym wywołaniem modelu. Razem determinują one przebieg procesu pracy. Prawidłowe działanie zależy jednak od szczegółów: weryfikacji na podstawie rzeczywistych danych, normalizacji identyfikatorów, proponowania ścieżek poza zakresem zadania oraz prawidłowego dopasowywania słów służących do zakończenia procesu. Maszyna stanów kontroluje kolejność kroków w procesie, a logika walidacji zapewnia, że każdy krok będzie działał poprawnie.