Практычныя прытамулі: Оркестрацыя калькольнікаў: стварэнне та аблікаванне калькольнікаў з калькольнікамі

У гэтым карыце парадоксу перадстаўляецца шлях ад сыр'ёчных матэрыялаў да рабочай системы для: Кантролю калькі ля агентаў: стварэнне та адзірванне систем калькі ля агентаў з LangGraph і LangSmith. Акцэнт ставіцца на практычныя крокі, чысткія перакананні та код, які можна падставіць у репазітарый без неабязковасці з'ясаваць мету. У стадыі агледку неабходна практычна з'явіць вхідныя даны, адпаведальнага за крок та критэрыя завершэння прычым перад зменай коду. Аперацыйныя працавнікі павінны магчымае перадзначыць крок з вядомай точкі контролю без неабязковасці з'ясаваць схованы стан. Конфігурацыю трэба залічыць параду ад коду прыкладнення. Файлы сераў, сховішчы секрэтных даных та флагі функцияў павінны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць без падчытання всей структуры.

Введэнне: Чым ёсць кантроль калькі ля агентаў LangSmith?

Калі працуеце над этапам «Што такое LangSmith?» у введзенні, спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконтроўкі дапамагае заліцварыць пазнейшыя змены ў кодзе. Документавайце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў ёсць часткаю продукту, а не пазнейшым дапрацоўкам. Зробіце пераконтроль пасля дорогіх крокаў. Система вярнення не павинна знову вырахоўваць адплату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел.

Архітектура: як працюе оркестрацыя ў LangGraph

Калі працуеце над стадзіяй «Архітектура: як аранжавацыя», спачатку запісайце умовы кантракту: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны коду пазнейша. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, прычына нявыпання павінна вказваць на адзіну адпаведальнасць, а не на заплутаны ланцюг задач. Зрабіце пераконтроль пасля дорогіх крокаў. Програма для продакцыі не павінна зноў выклікаць той самы кантакт з LLM, калі аператар праказвае спробу на болей пазнім вузле.

Як настаўляецца аранжавацыя:

Калі працуеце над этапам «Як функцыонуе оркестрацыя», спачатку запісайце контракт: неабяжлівыя даннэ, сигнал працягу, а таксама тое, што выканаецца у разе частковага нявыполнення. Такі список пераканальвае ў тым, каб пазнейшыя змены коду былі чыстымі. Спрыятліваеце гэты этап як контракт межу вхіднымі даннэмі і перакананымі выходнымі результатамі. Дайце назвы артыфактам, задаце критэрыя успеху і не падзволяйце частковаму завершэнню без паведамлення. Зробіце контрольны пункт пасля дорогіх крокаў. Система вярнення не павинна зноў выклікаць той самы вызов LLM, калі аператар праканае пазнейшы вузел. Калі працуеце над этапам «Як функцыонуе оркестрацыя», спачатку запісайце контракт: неабяжлівыя даннэ, сигнал працягу, а таксама тое, што выканаецца у разе частковага нявыполнення. Такі список пераканальвае ў тым, каб пазнейшыя змены коду былі чыстымі. Зберагаце настройкі паза кодам прыемленае. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функций павинны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры.

Практычны прыклад па кроках

Этап «Прыгунковыя, павтораблівыя прыклады» работае наўзям лепш, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Дакументавайце як шлях успеху, так і шлях вярнэння ў нормальны стан адночасна. Перапрыбуткі, людзкія контрольны пункты і обработка некоректных паведамленняў є часткай продукту, а не элементамі пазнейшай дапрацоўкі. Храніце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакшуюць возз'яджанне пасля перарываў.

Прыямыя прычыны

Этап падчынных абяцейкаў работае наякша, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідеальная транскрыпцыю, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштаб. Валіце маленькія, тэставаныя элементы замест большых скрыптов. Калі якісь крок не выйшае, прычына неудачы павінна вказываць на адну конкрэтную абяцейку адпаведальнасці, а не на заплутаны ланцужок задач. Рэгулюйце стан графа так, каб ён быў простым і з адзіным типам дадзеных. Вярнутыя структуры дадзеных маскуюць інфармацыю пра тое, який вузол запісаў кожны поле, і спакоююць працу пасля перарываў.

Крок 1: Наладка сяродавысці

Этап налагоджэння сяродавішча пасоў 1 працуе найэфектывней, калі яго спрыяваць як мерыемую плошчу. Зберагачыце адну ідеальную транскрыпцію, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштаб. Спрыяйце гэтам этапу як кантракту межа вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаць критэрыя успеху і адмовіцеся ад тых падчасовых завершэнняў, калі няма інформацыі. Храніце стан графа ў простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць возз'яданне пасля перерываў. Этап налагоджэння сяродавішча пасоў 1 працуе найэфектывней, калі яго спрыяваць як мерыемую плошчу. Зберагачыце адну ідеальную транскрыпцію, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштаб. Храніце налашчанні за межамі коду прыкладнага праграмы. Файлы сяродавішча, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць аудытаваць іх без неабяжнага чытання всего графа.

uv add langgraph langchain-anthropic langsmith python-dotenv

Пасоў 2: Код на Python

Для другога крока, стадіі Python, перш чым зменшыць код, неабяжна задаць вхідныя даны, адпаведальнага за крок і критэрыі завершэння. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней. Раздзеліце стварэнне кліента ад цыклу паведамленняў, каб можна было зменіць прадаўцаў без перапісвання машыны стану размовы.

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)

Крок 3: Запуск скрыпту для тэставання

Для трэцьяго крока, тымчасовага адзейнання, неабяжна пазначыць даныя, якія будуць вводзіцца, адпаведальнага за крок і критэрыя завершэння пры перадзеіснавленні коду. Аператары должны магчымаць перадзеіснавлення крока з вядомага пункта контролю, не спрабоўваючы з’ясаваць захаваны стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшоў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны процес. Неабяжна ўключыць людзкія парады на тыя этапы, дзе відбываецца выдатак грошэй або зміняюцыся даныя для працы системы. Компіляцыйны механізм не є адпаведным для падтрымкі полной роботы бізнес-процэсаў.

uv run multiagent-orchestration.py

Крок 4: Адзіроўка оркестрацыі ў LangSmith

Для этапа 4 «Адзіёнка» перад змянайом кодам неабходна дэфініцыя вхідных даных, адпаведальнага за шаг адпаведальнага, а таксама крэтарыяў выходу. Аператары должны магчыма было перзапускаць шаг з вядомай точкі контролю, не спрабоўваючы здагадвацца пра захаваны стан. Спрыяйце цэму этапу як кантракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задайце крэтарыі успеху і адмовіцеся ад тыхчасовага частковага завершэння. Забезпечыце людскія апраўдкі для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны праўай працы. Кампіляцыйныя налашчэння не ўзроўнаўцуюцься з пачатковым станом бізнесу. Для этапа 4 «Адзіёнка» перад змянайом кодам неабходна дэфініцыя вхідных даных, адпаведальнага за шаг адпаведальнага, а таксама крэтарыяў выходу. Аператары должны магчыма было перзапускаць шаг з вядомай точкі контролю, не спрабоўваючы здагадвацца пра захаваны стан. Зберагачыце налашчэнні за межамі коду прыкладнення. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаючы весь ланцуг.

Што вы паблікуеце ў LangSmith:

Калі працуеце над этапам «Што вы паблікуеце», спачатку запісайце умовы кантракту: неабяжлівыя даны, сігнал успеху і тое, што выканаецца у разе частковага невыпалення. Такі список контроля дапамагае заліцвачваць змяны коду. Документавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія перакрыцця і обробка некоректных паведамленняў є частью продукту, а не дадатковымі правкамі. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не должна занова ставіць плату за той самы вызыв LLM, калі аператар перапрыбуе пазнейшы вузел.

Вывад

Чэк-ліст для эксплуатацыі