Боби 9. Аз намунаҳои озмоишӣ то муҳити истеҳсолӣ: шартномаҳо, абзорҳо ва иҷрои боэътимод

Боби 9. Аз намунаҳои озмоишӣ то муҳити истеҳсолӣ: шартномаҳо, абзорҳо ва иҷрои боэътимод

Дар бобҳои пешин таъкид кардем, ки ба агентҳоятон тавре назар кунед, ки гӯё аъзои дастаро ба кор қабул мекунед. Омӯхтед, ки чӣ гуна агентҳоро тарҳрезӣ кунед, масъалаҳоро ба қисмҳо ҷудо намоед ва бо интихоби «корманд»-и муносиб ҳамкории тамоми системаро ҳамоҳанг созед. Бо ин дониш аллакай метавонед намунаҳои озмоишии таъсирбахш созед. Аммо барои ба муҳити истеҳсолӣ бурдани агентҳои зеҳни сунъӣ танзимоти дурусте лозим аст, то система дар амал устувор бимонад. Ин боб дар бораи гузаштан аз ҳамин марз аст.

То ин ҷо тарзи ташкили даста, муайян кардани масъулиятҳо ва ҳамоҳангсозии ҳамкориро омӯхтед. Акнун як сатҳ амиқтар меравем. Дар ҳар ташкилоти воқеӣ танҳо ба кор қабул кардан кофӣ нест. Одамон ба шартнома ва одатан ба дастури корманд низ ниёз доранд: роҳнамои равшане, ки тарзи иҷрои кор ва ҳамкории системаҳоро муайян мекунад.

Ин боб маҳз ба ҳамин масъалаҳо бахшида шудааст: интерфейсҳои равшан, интизориҳои дақиқ ва ҷараёнҳои додаҳое, ки ба агентҳо иҷрои корро имкон медиҳанд. Бе онҳо ҳатто боистеъдодтарин даста бесарусомонӣ ба вуҷуд меорад. Ба забони сода, аллакай медонед чӣ гуна агентро ба сухан оваред. Дар ин боб меомӯзед, ки чӣ гуна агентҳоро дар миқёси калон боэътимод ба кор дароред, бе он ки ҳамеша болои сари система истед.

Ҳақиқати душвор ин аст: дар истеҳсолот омили маҳдудкунанда зеҳни модел нест, балки иҷрои бемаҳдуд аст. Зинда мондани система танҳо аз сифати модел вобаста нест; муҳим он аст, ки муошират, ҷараёни додаҳо ва иҷрои абзорҳо ба таври қатъӣ маҳдуд ва санҷида шаванд. Дар системаҳои бисёрагентӣ баромади як агентро агенти дигар истифода мекунад. Ҳар схемаи номуайян, интерфейси суст ва даъвати санҷиданашудаи абзор ба манбаи хатар табдил меёбад, ки дар тамоми система паҳн мешавад.

Расми 9.1 ҷараёни пурраи иҷрои системаи агентии устуворро дар муҳити истеҳсолӣ нишон медиҳад. Ҷойҳои назорат дар сохтор равшананд: шартномаҳо ва сиёсат пеш аз ҳар амал бор мешаванд, иҷрои абзор аз интерфейси стандартӣ мегузарад ва баромадҳо пеш аз гузаштан ба марҳалаҳои баъдӣ аз дарвозаи санҷиш мегузаранд. Ҳадаф боэътимод кардани система аст.

Расми 9.1. Давраи ҳаёти агенти зеҳни сунъӣ бо нуқтаҳои назорати равшан.

Ҷадвали 9.1 нишон медиҳад, ки ин ҷузъҳо чӣ гуна ба ҳам мепайванданд ва чаро чунин тарҳ барои пешгирии ислоҳи хатои парсинг дар соати дуи шаб муҳим аст. Парсинг — табдил додани матни ҷавоби модел ба додаҳои сохторёфта, масалан табдили матни JSON ба луғати (dict) Python. Дар бахшҳои баъдӣ ин китобхонаҳо ва вазифаҳои онҳоро муфассал мебинем.

Ҷадвали 9.1. Ташбеҳи ташкилотӣ барои зерсохтори асосии агентҳо

Вақте тамоми роҳи иҷрои системаи бисёрагентиро мебинед, равшан мешавад, ки аксари системаҳо дар куҷо ноком мегарданд: дар ҳамкории байни агентҳо ва марзҳои даъвати абзорҳо. Моделҳо аз сабаби камзеҳнӣ ноком намешаванд; вазифаҳо, баромадҳо ва супоридани кор ба абзорҳо ба қадри кофӣ муайян нашудаанд. Пас идоракунии малакаҳо, ҷараёни додаҳо, баромади агент ва даъвати абзор масъалаи шартнома аст. Ин барои ҳар меъмории бисёрагентӣ дуруст мебошад. Бахши баъдӣ нишон медиҳад, ки чӣ гуна ин шартномаҳоро муайян, татбиқ ва санҷиш кунед, то хатогиҳо дар сатҳи интерфейс боздошта шаванд ва дар система занҷирвор паҳн нагарданд.

Шартномаи мувофиқ барои агентҳо: идоракунии ҷараёни додаҳо ва баромади LLM

Ҳамаи мо ин ҳолатро медонем: система дар муҳити пеш аз истеҳсол (staging) комилан хуб кор мекунад, аммо ҳамин ки ба марҳалаи ҷорӣкунӣ мерасед, нокомӣ пайдо мешавад. Барои агентҳои зеҳни сунъӣ ин метавонад номуназзам шудани баромад, вайрон шудани JSON аз тағйири хурд ва фарқ кардани интерфейси ҳар таъминкунандаро ифода кунад. Дар натиҷа иваз кардани таъминкунанда баъди ҷорӣкунӣ ба мушкили ҷиддӣ табдил меёбад. Таъминкунанда ширкате аст, ки моделро тавассути API пешниҳод мекунад, масалан OpenAI ё Anthropic. JSON бошад, қолаби матнии маъмул барои додаҳои сохторёфта аст, ки агентҳо одатан ҷавоби худро дар он медиҳанд.

Доми JSON-и осебпазир

Ғояи асосӣ сода аст: хатоҳои хурд дар занҷири агентҳо ба ҳам зарб мешаванд. Агар ҳар агент дар 98 фоизи ҳолатҳо дуруст кор кунад, занҷири даҳагентӣ ҳамагӣ тақрибан дар 82 фоизи ҳолатҳо бехато анҷом меёбад. Агар баъди ҳар қадам баромадро санҷем ва хатоҳоро дарҳол ислоҳ кунем, эътимоднокии тамоми занҷир боз ба тақрибан 98 фоиз бармегардад. Натиҷаҳо дар ҷадвали 9.2 оварда шудаанд (формулаҳо дар охири боб, қисми «Барои хонандагони пешрафта»).

Ҷадвали 9.2. Эътимоднокии система бо фарзияи дақиқии 98-фоизаи ҳар агент

Санҷиш моделҳоро комил намекунад, аммо барои пешгирии он ёрӣ медиҳад, ки нокомии маҳаллӣ ба ҳолати умумии система табдил ёбад.

Чизе, ки ҳамчун нороҳатии хурд оғоз мешавад, ба соатҳои ислоҳи хато табдил меёбад, то парсинги осебпазир дар системаи агентӣ паҳн нашавад. Дар воқеият ҳар агент, абзор ё таъминкунандаи нав боз як ҳолати махсус меорад. Иваз кардани таъминкунанда баъди ҷорӣкунӣ низ хатарнок мешавад: ҳам сифати модел ва ҳам шакли додаҳои баромад метавонад дигар гардад. Барои устувор ва нигоҳдоришаванда шудани система аз аввал бояд ба татбиқи «шартнома» андеша кунед.

Назорати хароҷот: санҷиши додаҳо ва супоридани кор бо Pydantic

Бовар дорем пештар Pydantic-ро истифода кардаед; агар не, он яке аз маъмултарин китобхонаҳои санҷиши додаҳо дар Python аст. Ба ҷойи танҳо бовар кардан ба он ки агент сохтори «дуруст» медиҳад, бо Pydantic дақиқ муайян мекунед, ки кадом додаҳо ба система даромада метавонанд. Санҷиш фавран дар марз анҷом меёбад, пеш аз он ки навъҳои нодуруст, майдонҳои намерасида ё қиматҳои вайроншуда дар системаи бисёрагентӣ паҳн шаванд. Модели Pydantic синфи оддии Python аст, ки майдонҳо ва навъи ҳар майдонро номбар мекунад; чунин тавсифи шакли додаҳоро схема меноманд.

Дар мисолҳои зерин аввал натиҷаи набудани санҷишро мебинед ва баъд намунаи амалисозиеро меомӯзед, ки Pydantic ин нокомиҳоро ба хатогиҳои ошкору идорашаванда табдил медиҳад.

Мушкил дар он аст, ки ин нокомиҳо метавонанд пинҳонӣ рӯй диҳанд: вайроншавии шартнома одатан ночиз менамояд. Масалан, сатр ба ҷойи адади бутун, майдони намерасида ё шакли андаке дигар аз таъминкунандаи дигар. Агар ҳолатҳои канориро ба назар нагиред, санҷишҳои тозаи staging мегузаранд, вале баъди ҷорӣкунӣ система метавонад вайрон шавад. Намунаи 9.1 ҳолати сатр ба ҷойи адади бутунро нишон медиҳад.

Намунаи 9.1. Сатр ба ҷойи адади бутун

def process_user_data_brittle(data: dict):
    user_id = data.get("user_id")  
    age = data.get("age")         

    result = user_id * 2           
    query = f"SELECT * FROM users WHERE age > {age}"
    return {"processed_id": result, "query": query}

user_id метавонад 123 ё "123" ва age метавонад 25 ё "25" бошад. Агар user_id сатр бошад, натиҷаи зарб ба маънои интизоршуда мувофиқ намеояд.

Намунаи 9.2 нишон медиҳад, ки Pydantic чӣ гуна шакли додаҳоро пеш аз паҳншавии онҳо дар системаи бисёрагентӣ таъмин мекунад.

Намунаи 9.2. Ислоҳ дар марз

class UserData(BaseModel):
    user_id: int
    age: int = Field(ge=0, le=150)

def process_user_data_safe(data: dict):
    user = UserData(**data)  
    return {"processed_id": user.user_id * 2}

Санҷиш ё фавран ноком мешавад, ё қиматро ба навъи дуруст табдил медиҳад. Масалан, "123" ба 123 табдил меёбад, вале "abc" ба хатои ValidationError оварда мерасонад. Дар системаи воқеӣ ҳамин гуна моделҳоро дар ҳар нуқтаи супоридани кор байни агентҳо мегузоранд.

Дар системаҳои калон шартномаҳоро аз файли танзимот месозанд ва нуқтаҳои санҷиш (checkpoint) истифода мебаранд. Нуқтаи санҷиш мисли нуқтаи захира дар бозии компютерӣ аст: агар кор дар миёна қатъ шавад, аз ҳамон ҷо идома медиҳем, на аз аввал. Тафсилот дар охири боб: «Шартномаҳои асосёфта ба сиёсат ва нуқтаҳои санҷиш» (қисми «Барои хонандагони пешрафта»).

Instructor: фикр кардан аз рӯи навъи нокомӣ

Pydantic ҳамчун дарвозаи марзӣ амал мекунад: додаҳои нодурустро бозмедорад. Аммо худи ислоҳи хато — яъне дубора пурсидани модел — бояд дар ҷойи дигари система навишта шавад, масалан дар гиреҳи алоҳидаи графи LangGraph.

Instructor китобхонаест, ки ин корро худаш мекунад: агар ҷавоби модел ба модели Pydantic мувофиқ наояд, хатои санҷишро ба модел бармегардонад ва дубора мепурсад. Instructor вақте муфид аст, ки барқарорсозиро ба манбаи хато наздик кардан мехоҳед. Ин китобхона санҷиши Pydantic-ро мустақиман ба тавлиди модел мепайвандад ва баромади сохторёфтаро таъмин мекунад. Аз модел пайдарпай талаб мешавад, ки баромади мувофиқ ба ҳамон шартномаи собитшудаи Pydantic диҳад; хатои санҷиш ҳамчун бозхӯрд истифода мешавад. Ин шохаҳои графро кам мекунад, ниёз ба гиреҳҳои махсуси «ислоҳгар»-ро бартараф менамояд ва рафтори баромади сохторёфтаро дар моделҳою таъминкунандагони гуногун яксонтар месозад. Pydantic марзи системаро ҳифз мекунад; Instructor кори лозимро барои пайваста расидан ба ҳамин марз кам менамояд.

Намунаи 9.3 муштарии Instructor-ро бо муштарии OpenAI месозад, ки бо OpenRouter низ мувофиқ аст. OpenRouter интерфейси ягона барои LLM ва моделҳои чандмодалӣ мебошад ва гузариш байни садҳо моделро имкон медиҳад: моделҳои хусусии GPT ё Anthropic ва моделҳои кушодаасоси оилаҳои Qwen ё Llama.

Намунаи 9.3. Сохтани муштарии Instructor-и мувофиқ бо OpenAI

model_slug = os.environ.get("OPENROUTER_MODEL", "anthropic/claude-3.5-haiku")

client = instructor.from_provider(
    f"openrouter/{model_slug}",
    base_url="https://openrouter.ai/api/v1",
    mode=instructor.Mode.TOOLS,
)

Instructor санҷишро дар дохил иҷро мекунад; мантиқи дастии такрор лозим нест. Намунаи 9.4 нишон медиҳад, ки муштарии тағйирдодаи шумо акнун response_model ва max_retries-ро дастгирӣ мекунад. Вақте санҷиш ноком мешавад, handle_reask_kwargs() бозхӯрди хатогиро илова менамояд.

Намунаи 9.4. Истифодаи муштарии тағйирдодашуда

# Шартнома: модел бояд маҳз ҳамин майдонҳоро баргардонад
class ImagePrompt(BaseModel):
    prompt: str = Field(..., min_length=50)
    size_px: int = Field(default=1024, ge=512, le=1536)

result = client.create(
    messages=[
        {"role": "user",
         "content": """Generate an image prompt for a blog cover about Pydantic
                    validation in multi-agent systems."""}
    ],
    response_model=ImagePrompt,  # ҷавоб бо ҳамин модел санҷида мешавад
    max_retries=3,  # ҳадди ақсари кӯшишҳои такрорӣ
    temperature=0.2,
)

Маънои промпт: «Барои муқоваи блоге дар бораи санҷиши Pydantic дар системаҳои бисёрагентӣ промпти тасвир тавлид кун». response_model пайвасткунии схема ва абзор, ҳамчунин парсингро фаъол мекунад. max_retries кӯшишҳои такрории санҷишро бо такя ба Tenacity (китобхонаи Python барои такрори амалҳо) маҳдуд менамояд. Натиҷа (result) аллакай объекти тайёри ImagePrompt аст, на матни хом.

Тафсилот дар охири боб: «Ду ҳалқаи ислоҳ: Pydantic ва Instructor» (қисми «Барои хонандагони пешрафта»).

Бо амалисозии ин қабатҳо система нокомиро ба таври назоратшаванда идора мекунад. Шартномаҳо ошкоранд, такрорҳо маҳдуданд ва барқарорсозӣ ба манбаи нокомӣ мутобиқ аст, ба ҷойи он ки дар тамоми ҷараён пароканда бошад. Дар ҳамин марҳала ба агентҳо иҷозат додани ҳамкорӣ бо ҷаҳони берунӣ асоснок мешавад. Вақте баромадҳо маҳдуд, санҷида ва барқароршавандаанд, метавонед агентҳоро ба абзорҳо, API-ҳои берунӣ, тафсиргарҳо ва муҳитҳои иҷро пайваст кунед, бе он ки ҳар нокомӣ ба як шаб ё тамоми рӯзҳои истироҳати ислоҳи хато табдил ёбад. Система дигар танҳо ба «рафтори хуб»-и агентҳо умед намебандад: онро таъмин мекунад.

MCP: идоракунаки умумии агентҳои шумо

Дар декабри 2025 Linux Foundation таъсиси Agentic AI Foundation (AAIF)-ро эълон кард. Аз саҳмҳои бунёдӣ, аз ҷумла, Model Context Protocol (MCP)-и Anthropic ва AGENTS.md-и OpenAI буданд. Pydantic ва Instructor бо шартномаҳои ошкор ва барқарорсозии маҳдуд ҳангоми тавлид баромади агентҳои алоҳидаро боэътимод месозанд; MCP бошад, протоколи умумии пайваст кардани моделҳои зеҳни сунъӣ ба абзорҳо, додаҳо ва барномаҳост. Ба забони сода, MCP маҷмӯи қоидаҳои умумист, ки агент тавассути онҳо мепурсад «кадом абзорҳо дорӣ?» ва баъд онҳоро даъват мекунад. Барномае, ки абзорҳоро бо ин қоидаҳо пешниҳод мекунад, сервери MCP ва тарафи агент муштарии MCP ном дорад.

AGENTS.md як созишномаи содаи умумӣ мебошад, ки ба агентҳои барноманависии AI дастурҳои яксон ва махсуси лоиҳа медиҳад, то дар анборҳо ва маҷмӯаҳои абзории гуногун боэътимод кор кунанд. Он интизориҳоро ҳуҷҷат мекунад, аммо рафторро худ маҷбуран таъмин намекунад. Дар бахши «Агентҳои амиқ: банақшагирӣ пеш аз иҷро» ва қисми пешрафтаи охири боб истифодаи онро барои агентҳое мебинед, ки ба Claude Code ва Manus монанд кор мекунанд.

MCP ҳамчун қабати сабуки мутобиқсозӣ

MCP аз он сабаб кор мекунад, ки интерфейси муштарӣ хурду устувор мемонад. Агент метавонад пурсад кадом абзорҳо дастрасанд ва яке аз онҳоро даъват кунад, бе донистани амалисозии системаи зери он. Дар амал одатан API-и ҳисоббаробаркунӣ, пайвастшавии Slack, пойгоҳи додаҳо ё системаи файлро аз нав наменависед. Системаи мавҷударо бо сервери сабуки MCP мепӯшонед, абзорҳоро тавассути интерфейси стандартӣ пешниҳод мекунед ва агент онҳоро ба таври яксон истифода мебарад.

Дар ин бахш аввал сервери содаи MCP месозед, то пайвасткунии абзорҳо ошкор ва такроран истифодашаванда гардад. Баъд адаптерҳои MCP-и LangChain-ро бо LangGraph истифода мебаред ва ҳамзамон имкониятҳои стандартии сатҳи поёнии MCP-ро нигоҳ медоред. Пеш аз амалисозӣ чанд таҷрибаи беҳтаринро баррасӣ мекунем:

• Интихоби нақлиёт. Нақлиёт роҳест, ки паёмҳо бо он байни агент ва сервер интиқол меёбанд. Стандарти MCP ду нақлиётро муайян мекунад: stdio — сервер дар ҳамон компютер ҳамчун барномаи алоҳида ба кор меафтад ва тавассути вуруду баромади стандартӣ паём мубодила мекунад; барои таҳияи маҳаллӣ ва истифодаи яккорбарӣ, ва Streamable HTTP — барои серверҳои веб ва истифодаи чандкорбарӣ. Ҳар роҳи дигар (gRPC, WebSocket ва ғайра) нақлиёти фармоишӣ аст: онро ҳам сервер ва ҳам муштарӣ бояд алоҳида дастгирӣ кунанд.
• Бехатарии ҳамзамонӣ. Агар якчанд агент як абзорро ҳамзамон даъват кунанд, даъватҳо набояд кори якдигарро вайрон кунанд (тафсилот дар охири боб, қисми «Барои хонандагони пешрафта»).
• Идоракунӣ. Барои риояи сиёсат танҳо ба модел такя накунед. Серверҳои MCP марзи муҳими назоратанд, зеро дастрасӣ ба абзорҳоро миёнаравӣ мекунанд. Аммо системаи истеҳсолӣ бояд сиёсатро дар чанд қабат таъмин кунад: граф, миёнафзор, хизматрасониҳои тасдиқ ва зерсохтори аудит.
• Вуруду баромади навъдор. Барои ҳам вуруд ва ҳам баромад моделҳои Pydantic истифода баред, то шартномаҳо ошкор бошанд. Ин хатоҳои пинҳониро пешгирӣ карда, рафтори абзорро пешгӯишаванда мекунад.

Барои шиносоӣ бо намунаҳои асосии MCP аз сервери содаи идоракунии файлҳо оғоз мекунем.

Сохтани сервери содаи MCP

Ин мисол ба механизмҳои асосӣ диққат медиҳад: муайян кардани абзорҳо бо моделҳои Pydantic ва пешниҳод кардани онҳо тавассути FastMCP. FastMCP роҳи мувофиқ ба услуби Python барои сохтани серверу муштарии MCP аст. Вақте ин намунаро фаҳмидед, ҷузъҳои дигари MCP бар ҳамин поя бунёд мешаванд. Сервер вуруду баромади навъдор, таърифҳои асосии абзор бо FastMCP ва сохтори стандартии серверро нишон медиҳад. Намунаи 9.5 моделҳои Pydantic-ро барои ин кор месозад.

Намунаи 9.5. Моделҳои Pydantic барои вуруду баромади навъдор

class ReadFileRequest(BaseModel):
    """Read a file."""
    file_path: str = Field(..., description="Path to file to read")

class WriteFileRequest(BaseModel):
    """Write content to a file."""
    file_path: str = Field(..., description="Path to file to write")
    content: str = Field(..., description="Content to write")

class ListFilesRequest(BaseModel):
    """List files in a directory."""
    directory: str = Field(..., description="Directory path")
    pattern: Optional[str] = Field(None,
                             description="Optional glob pattern (e.g., '*.py')")

Моделҳо чунин дархостҳоро муайян мекунанд: хондани файл бо роҳи файл; навиштани муҳтаво бо роҳи файл ва муҳтаво; рӯйхати файлҳо бо роҳи ҷузвдон ва қолаби ихтиёрии glob, масалан *.py.

Баъд серверро бо mcp = FastMCP("FileManager") месозед. Пас аз оғоз кардани сервер абзорҳоро месозед. Намунаи 9.6 абзорҳои идоракунандаи содаи файлро нишон медиҳад.

Намунаи 9.6. Амалисозии абзорҳои MCP

@mcp.tool()
def read_file(request: ReadFileRequest) -> str:
    """Read the contents of a file."""
    path = Path(request.file_path)
    if not path.exists():
        raise FileNotFoundError(f"File not found: {request.file_path}")
    return path.read_text(encoding="utf-8")

@mcp.tool()
def write_file(request: WriteFileRequest) -> dict:
    """Write content to a file. Creates file if it doesn't exist."""
    path = Path(request.file_path)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(request.content, encoding="utf-8")
    return {"status": "success", "file_path": str(path),
            "bytes_written": len(request.content)}

@mcp.tool()
def list_files(request: ListFilesRequest) -> list[str]:
    """List files in a directory."""
    dir_path = Path(request.directory)
    if not dir_path.exists():
        raise FileNotFoundError(f"Directory not found: {request.directory}")

    if request.pattern:
        files = list(dir_path.glob(request.pattern))
    else:
        files = list(dir_path.iterdir())

    return [str(f.relative_to(dir_path)) for f in files if f.is_file()]

if __name__ == "__main__":
    mcp.run(transport="stdio")

Абзорҳо муҳтавои файлро мехонанд, онро менависанд — ва ҳангоми зарурат файлро месозанд — ё файлҳои ҷузвдонро рӯйхат мекунанд. Агар файл ё ҷузвдон набошад, хатои мувофиқ баргардонида мешавад. Барои таҳияи маҳаллӣ stdio истифода баред. Барои ҷорӣкунӣ ба нақлиёти стандартии Streamable HTTP гузаред (transport="streamable-http"); WebSocket ва монанди он танҳо ҳамчун нақлиёти фармоишӣ имконпазиранд. Дар бораи gRPC ҳамчун нақлиёти фармоишӣ нигаред ба «gRPC барои ҷорӣкуниҳои ташкилотии MCP» дар қисми «Барои хонандагони пешрафта».

Бо ин идоракунандаи ҳадди ақалли файлҳо акнун намунаи мушаххаси сохтор ва пешниҳоди сервери MCP доред. Ин гузаришро аз абзорҳои ҷудогона ба ҷараёнҳои пурра пайвастшудаи агентӣ дар бахши «Пайваст кардани сервери MCP ба LangGraph» осон мекунад.

Пайваст кардани сервери MCP ба LangGraph

Акнун сервери навсохтаи MCP-ро пайваст карда, ба LangGraph ҳамроҳ мекунем. Дар ҳамин ҷо қувваи MCP равшан мешавад: агент метавонад абзорҳои беруниро бе донистани амалисозии онҳо истифода барад. Намунаи 9.7 муштариро месозад ва ба сервери идоракунии файл пайваст мекунад.

Ба таври пешфарз MultiServerMCPClient ҳолатро нигоҳ намедорад: ҳар даъвати абзор ҷаласаи нави MCP месозад, абзорро иҷро мекунад ва баъд ҷаласаро мепӯшонад. Агар сервер бояд ҳолати ҷаласаро байни даъватҳо ҳифз кунад, ҷаласаи ҳолатдор истифода баред.

Намунаи 9.7. Сохтани муштарии MCP

client = MultiServerMCPClient(
    {
        "file_manager": {
            "command": "python",
            "args": [os.path.abspath("file_manager_server.py")],
            "transport": "stdio",
        }
    }
)

Акнун абзорҳоро бо tools = await client.get_tools() аз сервер бор мекунед. Калимаи await нишон медиҳад, ки функсия асинхронӣ аст: барнома ҷавоби серверро интизор мешавад. Чунин кодро дар дафтари Jupyter бевосита ё дар дохили функсияи async def иҷро мекунед. Баъд онҳоро ба агент мепайвандед ва графро месозед (намунаи 9.8).

Намунаи 9.8. Муайян кардани гиреҳи агент ва сохтани граф

def call_model(state: MessagesState):
    response = model.bind_tools(tools).invoke(state["messages"])
    return {"messages": [response]}

builder = StateGraph(MessagesState)
builder.add_node("call_model", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "call_model")
builder.add_conditional_edges("call_model", tools_condition)
builder.add_edge("tools", "call_model")

graph = builder.compile()

Намунаи 9.9 серверро бо супориши сохтани файли .txt ба агент месанҷад.

Намунаи 9.9. Ба кор андохтани граф

response = await graph.ainvoke({
    "messages": [("user", """Create a file called 'test.txt' with content
                          'Hello from MCP!', then read it back.""")]
})

Маънои супориш: «Файле бо номи test.txt ва муҳтавои Hello from MCP! соз ва баъд онро боз бихон». Маънои муҳтаво: «Салом аз MCP!».

Намунаи 9.10 тарзи нишон додани натиҷаи санҷишро мефаҳмонад.

Намунаи 9.10. Намоиши ҷавоб

for message in response["messages"]:
    if isinstance(message, AIMessage):
        print("Agent Response:")
        print(message.content)
        if message.tool_calls:
            print("\nTool Calls:")
            for tool_call in message.tool_calls:
                print(f"  - {tool_call['name']}({tool_call['args']})")

Ҳангоми иҷро бояд чунин даъватҳо ва ҷавобро бинед:

Tool Calls:
  - write_file({'request': {'file_path': 'test.txt', 'content':
    'Hello from MCP!'}})
  - read_file({'request': {'file_path': 'test.txt'}})

«Файли test.txt бо муҳтавои Hello from MCP! сохта шуд. Ҳангоми хондани дубора муҳтаво чунин аст: Hello from MCP!».

Дар ch05_mcp_langgraph.ipynb инчунин мисоли идоракунандаи захираҳо дар асоси SQLite ҳаст, ки намунаҳои воқеии сервери MCP-ро барои истеҳсолот нишон медиҳад. Ин дафтар ба истеҳсолот наздиктар аст: нишон медиҳад, ки серверҳо чӣ гуна ҳолати доимӣ, кафолатҳои бехатарӣ ва татбиқи сиёсатро дар марзи система таъмин мекунанд. Дар ин тарҳ шуъбаҳо соҳиби системаҳои худанд ва онҳоро тавассути серверҳои MCP пешниҳод мекунанд; системаҳои агентӣ ин имкониятҳоро тавассути шартномаҳои устувору навъдори абзор истифода мебаранд. MCP қабати ҳамкорпазирӣ аст ва имкон медиҳад чанд системаи бисёрагентӣ бе мубодилаи код ба ҳам пайваст шаванд. Назорат дар марз ҷойгир аст: сиёсатро сервер таъмин мекунад.

Агент метавонад абзорҳои лозимро ҳангоми кор худаш ҷустуҷӯ кунад, масалан тавассути платформаи Composio. Тафсилот дар охири боб: «Имкон додан ба агентҳо барои кашфи серверҳои MCP» (қисми «Барои хонандагони пешрафта»).

MCP пули стандартӣ ба API ва пойгоҳи додаҳо медиҳад, аммо баъзе вазифаҳо андешаронӣ ва банақшагирии бештар мехоҳанд. Бахши «Агентҳои амиқ: банақшагирӣ пеш аз иҷро» нишон медиҳад, ки бо ғояи нави малакаҳои агентии Anthropic чӣ гуна як сатҳ амиқтар равед. Малакаҳо маҷмӯи салоҳиятанд: танҳо як амал нестанд, балки мантиқи онанд, ки агентҳо кай ва чӣ гуна пайдарпайии амалҳоро иҷро мекунанд.

Агентҳои амиқ: банақшагирӣ пеш аз иҷро

Дар бахшҳои пешин дидед, ки MCP чӣ гуна дастрасии агентҳоро ба доираи васеи абзорҳо имкон медиҳад. Аммо дар амал дастрасии бемаҳдуд зуд ба хароҷоти бештар, роҳҳои осебпазири иҷро ва нокомиҳои занҷирӣ меорад. Аз ҳамин сабаб бисёр системаҳои муосири агентӣ пеш аз ҳар амал қабати ошкори банақшагирӣ мегузоранд.

Системаҳои машҳури Claude Code ва Manus маҷмӯи принсипҳои муштаракро татбиқ мекунанд: агентҳо пеш аз амал нақша мекашанд. Иҷро дар муҳитҳои назоратшаванда, монанди shell (сатри фармон) ё системаи файл, анҷом мешавад. Кори мураккаб ба зерагентҳои дорои контексти ҷудогона супорида мешавад. Лоиҳаи кушодаасоси Deep Agents-и LangChain ин принсипҳоро дар муҳити сабуки идоракунии агент якҷоя мекунад, ки онро бо абзорҳо, сиёсатҳо ва моделҳои интихобкардаи худ васеъ кардан мумкин аст.

Ғояи асосӣ сода аст: агенти асосӣ аввал рӯйхати қадамҳо (нақша) месозад ва баъд корҳои калонро ба зерагентҳо месупорад. Зерагент агенти ёрирасон аст, ки контексти худро дорад ва ба агенти асосӣ танҳо натиҷаи ниҳоиро бармегардонад. Ҳамин тавр контексти агенти асосӣ бо натиҷаҳои миёнарав пур намешавад. Расми 9.2 ҷузъҳои асосии чунин агентро нишон медиҳад.

Расми 9.2. Намуди умумии ҷузъҳои агенти амиқ.

Тафсилот дар охири боб: «Зерагентҳо ва ҷузъҳои агенти амиқ» (қисми «Барои хонандагони пешрафта»).

Хулоса

Нуктаи асосии ин боб он аст, ки зеҳни модел кам вақт аввалин ҷузъи вайроншаванда мешавад. Одатан чизҳои гирди он вайрон мешаванд: шартномаҳои номукаммал, схемаҳои суст, даъватҳои беназорати абзор ва супоридани осебпазири кор байни агентҳо, абзорҳо ва системаҳои баъдӣ. Вақте агентҳоро ба занҷир мепайвандед, ҳар марзи заиф ба тақвиятдиҳандаи нокомӣ табдил меёбад.

Дар ин боб пайвастшавиро ҳамчун масъалаи шартнома баррасӣ кардед. Pydantic мушаххасоти техникиеро дод, ки муайян мекунад чӣ ба система даромада метавонад. Дарвозаҳои санҷиш таъмин карданд, ки нокомиҳо дар марз боздошта шаванд. Дар қисми пешрафта дидем, ки шартномаҳои асосёфта ба сиёсат, ҳэшҳои схема ва нуқтаҳои санҷиш системаро боз ҳам устувортар мекунанд: аз гиреҳи устувори охирин идома медиҳед ва барои марҳалаҳои гарони пешина дубора пардохт намекунед.

Instructor таъмини мувофиқати схемаро ба қадами тавлид бурд ва бисёр нокомиҳоро ба такрорҳои тезу маҳдуд табдил дод, пеш аз он ки баромад ба мантиқи барнома расад. Ғояи муҳим интихоби китобхона нест; ҷудо кардани маънои кӯшишҳои такрорӣ аз рӯи навъи нокомӣ мебошад. Вайроншавии схемаро Instructor ҳангоми тавлид ислоҳ мекунад; нокомии зерсохтор, муҳлатгузарӣ ва амалҳои бебозгашт ҳамоно масъалаи тамоми система мемонанд.

Дар охир доираи корро аз даъвати алоҳидаи абзор то экосистемаи абзорҳо васеъ кардед. MCP роҳи стандартии муоширати агентҳоро бо абзорҳо, додаҳо ва барномаҳо тавассути шартномаҳои навъдор дод ва назоратро ба масъулияти марз табдил дод. Дар қисми пешрафта қадами баъдӣ — кашфи абзор — оварда шудааст: агентҳо метавонанд ҳангоми иҷро маҷмӯи абзорҳоро ворид кунанд, онро аз рӯи ният маҳдуд созанд ва танҳо баъд иҷрои корро нақша кашанд.

Агентҳои амиқ ин ғояҳоро ба модели иҷрои наздиктар ба амалиёти воқеӣ пайвастанд: пеш аз амал нақша кашед, контекстро бо зерагентҳо ҷудо кунед, истифодаи абзорро тавассути миёнафзор идора намоед ва интизориҳоро дар SKILL.md ва AGENTS.md муайян кунед, то рафтор такроршаванда бимонад.

Чиро бояд дар ёд дошт

• Баромади LLM боэътимод нест. Онро дар ҳар супоридани кор бо модели Pydantic санҷед, то хато дар ҳамон ҷо дастгир шавад ва дар система паҳн нагардад.
• Хатоҳои хурд дар занҷири агентҳо ба ҳам зарб мешаванд: 98 фоиз дар ҳар қадам баъди даҳ қадам тақрибан 82 фоиз мешавад. Санҷиш дар ҳар қадам инро ислоҳ мекунад.
• Instructor моделро худкор водор мекунад, ки то мувофиқ шудани ҷавоб ба схема дубора кӯшиш кунад.
• MCP мисли USB-C барои абзорҳост: абзорро як бор дар сервери MCP мепӯшонед ва ҳар агент метавонад онро истифода барад.
• Агенти амиқ пеш аз амал нақша мекашад ва кори калонро ба зерагентҳо месупорад, то контексти агенти асосӣ пур нашавад.

Барои хонандагони пешрафта

Ин қисм барои хониши аввал ҳатмӣ нест. Дар он тафсилоти техникӣ, формулаҳо ва коди пурра оварда шудаанд. Агар китобро бори аввал мехонед, метавонед онро гузаронед ва ба боби навбатӣ гузаред.

Қонуни Луссер: формулаи эътимоднокии занҷир

Бе санҷиш системаи бисёрагентӣ мисли занҷири пайдарпайи эътимоднокӣ амал мекунад. Агар ҳар агент бо эҳтимоли муайян муваффақ шавад, муваффақияти умумӣ ба таври зарбӣ кам мегардад. Эҳтимол инро аз муҳандисии системаҳо медонед: таъсир бо қонуни Луссер расмӣ карда шудааст. Он мегӯяд, ки ҳангоми иҷрои пайдарпайи ҷузъҳои мустақил эҳтимоли муваффақияти умумӣ ба ҳосилзарби эҳтимолҳои муваффақияти ҳар ҷузъ баробар аст.

Ин модели содаи эътимоднокӣ аст. Он нокомиҳои мустақили агентҳо, иҷрои пайдарпай ва дарвозаҳои санҷишеро фарз мекунад, ки метавонанд баромадҳои нодурустро ошкор карда, барқарор ё манъ намоянд, пеш аз он ки онҳо ба ҳолати марҳалаҳои баъдӣ табдил ёбанд. Барои ҷараёни бисёрагентӣ чунин ифода ҳосил мешавад:

[ R_{\text{ҷараён}} = \prod_{i=1}^{n} R_i = p^{,n} ]

Ин ҷо (R_i) — эътимоднокии агенти (i)-ум, (n) — шумораи агентҳо ва (p) — эътимоднокии якхелаи ҳар агент. Масалан, (0{,}98^{10} \approx 0{,}817).

Ҳатто агентҳои қавӣ ҳангоми пайвастшавӣ нокомиро ҷамъ мекунанд. Бо муваффақияти 98-фоизаи ҳар агент, эътимоднокии ҷараёни даҳагентӣ аллакай аз 82 фоиз кам мешавад.

Дарвозаҳои санҷиш ин рафторро тағйир медиҳанд. Агар вайроншавии схема бо эҳтимоли муайян ошкор шавад, эътимоднокии ҳар гузариш дигар мешавад:

[ p' = p + (1 - p), d, \qquad R_{\text{ҷараён}} = (p')^{,n} ]

Ин ҷо (d) — эҳтимоли ошкор ва барқарор кардани нокомӣ дар дарвозаи санҷиш. Бо (p = 0{,}98) ва (d = 0{,}9): (p' = 0{,}998) ва барои даҳ агент (0{,}998^{10} \approx 0{,}980).

Бо фарзияи содаи барқарорсозӣ, мисоли муаллиф нишон медиҳад, ки санҷиш метавонад коҳиши зарбиро бо ошкор кардани нокомӣ дар марз кам кунад. Натиҷаҳо дар ҷадвали 9.2 оварда шудаанд.

Шартномаҳои асосёфта ба сиёсат ва нуқтаҳои санҷиш

Ин танҳо мисоли сода аст. Дар воқеият ҷараёни истеҳсолии бисёрагентиро бо шартномаҳои асосёфта ба сиёсат таъмин кардан мехоҳед: шартномаҳо барои ҳар иҷро собит ва дар ҳар супоридани кор санҷида мешаванд. Дар мисоли баъдӣ мафҳумҳои муҳимро нишон медиҳем. Дафтари ch05_pydantic_agent_consistency.ipynb дар анбори китоби аслӣ ҷузъиёти амалисозиро бештар шарҳ медиҳад.

Ғояи асосӣ нишон додани тарзи боздоштани хатоҳо дар марз аст, пеш аз он ки ба поёноби ҷараён паҳн шаванд. Вақте ин марзро таъмин мекунед, назорати иҷро ба даст меояд: танзимоти системаро ҳангоми кор тағйир медиҳед, аз охирин нуқтаи санҷишии устувор идома медиҳед ва агентҳои марҳалаҳои пешинаро аз нав иҷро намекунед. Ин мустақиман хароҷоту таъхирро кам карда, нигоҳдорӣ ва пешгӯишавандагии системаро дар истеҳсолот беҳтар мекунад.

Ба ҷойи дар код собит кардани қоидаҳои бехатарӣ ё мантиқи санҷиш, метавонед бо OmegaConf танзимоти марказӣ истифода баред. OmegaConf системаи иерархии танзимот дар асоси YAML аст, ки барои якҷоя кардани маҳдудиятҳо ва танзимоти система дар вақти иҷро сохта шудааст. Он нав кардани танзимоти истеҳсолиро ҳангоми кор имкон медиҳад ва бо танзимоти сохторёфта бехатарии навъҳоро нигоҳ медорад. Пас рафтори тамоми системаро, масалан аз ҳолати «қатъӣ» бо нокомии бевосита ба ҳолати «мулоим» бо бозхӯрди назоратшаванда, бе ҷорӣкунии дубораи код иваз карда метавонед. Намунаи 9.11 порчаи YAML ва истифодаи OmegaConf-ро нишон медиҳад.

Намунаи 9.11. Муайян кардани ҳолатҳои идоракунӣ

GOVERNANCE_CONFIG = """
mode: "strict"

policies: 
  strict:
    max_retries: 3
    prompt:
      min_length: 50
      required_keywords: ["pydantic", "validation", "contract"]
      forbid_markdown: true  
      require_style_tag: true  
      size_px_min: 512
      size_px_max: 1536
    image_output:
      allowed_mime: ["image/png"]
      max_bytes: 2000000
    db:
      serialize_mode: "json"
      schema_version: 1
  # ҳолатҳои дигар бо ҳамин сохтор илова мешаванд (дар ин ҷо оварда нашудаанд)
"""

cfg: DictConfig = OmegaConf.create(GOVERNANCE_CONFIG)

Сиёсатҳо ба ҳолат вобастаанд. Маҳдудиятҳои нишоншуда блокҳои кодро дар промпт манъ мекунанд ва мавҷудияти тавсифи услубро талаб менамоянд. Дар ин ҷо танҳо ҳолати strict нишон дода шудааст; ҳолатҳои дигар бо ҳамин сохтор дар ҳамон файли YAML илова мешаванд.

Намунаи 9.12 нишон медиҳад, ки чӣ гуна бо функсияҳои фабрика моделҳои Pydantic-ро ҳангоми кор созед. Ҳамин тавр мантиқи санҷиши агент ҳамеша сиёсати ҷории ташкилотро инъикос мекунад. Инро намунаи тарроҳии «фабрика» барои шартномаҳои AI тасаввур кунед. Агар бо намунаҳои тарроҳӣ шинос набошед, фабрика усули сохтани объектҳост, ки синфҳои мушаххаси онҳоро дар код собит намекунад.

Ин равиши динамикӣ системаро аз модели муайян мустақил месозад. Моделҳои гуногун намудҳои гуногуни нокомӣ доранд ва намунаи фабрика имкон медиҳад «шартнома»-ро ба ҷиҳатҳои қавӣ ё заифи модели дар вақти иҷро даъватшаванда мутобиқ кунед.

Намунаи 9.12. Сохтани шартномаи Pydantic аз сиёсати фаъол

def build_image_prompt_model(policy_dict: dict[str, Any],
                             mode: str, policy_hash: str):
    prompt_cfg = policy_dict["prompt"]
    min_len = int(prompt_cfg["min_length"])
    required = [str(x).lower() for x in prompt_cfg.get(
    "required_keywords", [])]
    size_min = int(prompt_cfg["size_px_min"])
    size_max = int(prompt_cfg["size_px_max"])
    forbid_md = bool(prompt_cfg.get("forbid_markdown", False))
    require_style = bool(prompt_cfg.get("require_style_tag", False))

    class ImagePrompt(BaseModel):
        model_config = {"title": f"ImagePrompt_{mode}_{policy_hash}"} 

        prompt: str = Field(..., min_length=min_len)
        size_px: int = Field(default=1024, ge=size_min, le=size_max)

        @field_validator("prompt")
        @classmethod
        def forbid_markdown_blocks(cls, v: str) -> str:
            if forbid_md and "```" in v: 
                raise ValueError("Prompt must not contain markdown code blocks")
            return v

            # Боқимондаи синф оварда нашудааст

    return ImagePrompt

Номгузории динамикӣ схемаҳои шуморо дар хотира версиябандӣ мекунад. Санҷишгари Pydantic маҳдудиятҳои мушаххаси сиёсатро таъмин менамояд. Маънои паёми хато: «Промпт набояд блокҳои коди Markdown дошта бошад».

Ҳақиқати муҳити истеҳсолӣ ин аст, ки муҳитҳо метавонанд тағйир ёбанд. Намунаи 9.13 нишон медиҳад, ки чӣ гуна бо собит кардани сиёсат дар оғози иҷро ва сохтани ҳэши ягонаи мушаххасот аз тағйири номувофиқ дар миёнаи иҷро пешгирӣ кунед.

Намунаи 9.13. Собит кардан ва ҳэш кардани ҳолати система дар START

def node_initialize_policy(state: GraphState):
    policy = get_active_policy(cfg)
    policy_dict = OmegaConf.to_container(policy, resolve=True)
    mode = str(cfg.mode)

    policy_hash = hash_policy(policy_dict) 

    ImagePrompt, GeneratedImageToolResult, GeneratedImageRecord = (
        get_models_for_policy(policy_dict, mode, policy_hash)
    )

    prompt_cfg = policy_dict["prompt"] 
    policy_semantics = {
        "required_keywords": sorted([str(x).lower() for x in
         prompt_cfg.get("required_keywords", [])]),  
        "forbid_markdown": bool(prompt_cfg.get("forbid_markdown", False)),
        "require_style_tag": bool(prompt_cfg.get("require_style_tag", False)),
        "max_retries": int(policy_dict["max_retries"]),
    }
    schema_hash = sha256_text( 
            json.dumps(combined, sort_keys=True, separators=(",", ":"),
            ensure_ascii=False))[:16]

    # Баъзе ҷузъиёт дар ин ҷо оварда нашудаанд

    return {
        "active_policy": policy_dict,
        "active_mode": mode,
        "policy_hash": policy_hash,
        "schema_hash": schema_hash,
        "max_retries": int(policy_dict["max_retries"]),  
        "run_id": run_id,  
        "prompt_ok": False,
        "image_ok": False,
        "execution_log": [f"Initialized: mode={mode}, policy_hash={policy_hash}, "
                          f"schema_hash={schema_hash}, run_id={run_id}"],
    }

Дар ин код:

• Ҳэши сиёсат барои кэшкунӣ ва аудит ҳисоб мешавад.
• Моделҳо барои ҳамин сиёсат пешакӣ сохта ва кэш мешаванд. Бо тағйири қоидаҳои санҷиш schema_hash дигар мешавад.
• Маъноҳои сиёсат, ки ба санҷиш таъсир доранд, аммо дар JSON Schema нестанд — required_keywords, forbid_markdown ва require_style_tag — ҷудо мешаванд.
• Барои устувории ҳэш додаҳо ба шакли яксон оварда мешаванд.
• «Из»-и қоидаҳои ҷории идоракунӣ сабт мешавад.
• Қиматҳо барои масирдиҳӣ нигоҳ дошта мешаванд, то ҷустуҷӯи такрорӣ лозим нашавад.
• Идентификатори иҷро сабти пойгоҳи додаҳоро бо нуқтаҳои санҷиш пайгирӣ мекунад.
• Сабти пойгоҳи додаҳо мустақиман ба риштаи нуқтаи санҷишии LangGraph пайваст мешавад.

Намунаи 9.14 хатогиро мегирад ва ба агент бозхӯрди мушаххас медиҳад, то боз кӯшиш кунад. Ҳангоми баргардондани хато ба LLM бозхӯрди маънодорро аз пайгирии хоми хато бартарӣ диҳед. Pydantic аллакай паёмҳои хондашавандаи санҷиш медиҳад, вале хатогиҳои API, нокомии абзор ва пайгирии стекро одатан ба як ҷумлаи равшани амалпазир табдил додан лозим аст.

Намунаи 9.14. Дарвозаи санҷиш бо масирдиҳии ошкор

def node_prompt_validation_gate(state: GraphState):
    ImagePrompt, _, _ = get_models_for_policy( 
        state["active_policy"],
        state["active_mode"],
        state["policy_hash"],
    )

    try:
        valid_prompt = ImagePrompt(  
            **state.get("image_prompt", {})
        )

        return {
            "image_prompt": valid_prompt.model_dump(),
            "prompt_ok": True, 
            "retry_count": 0,
        }

    except ValidationError as e:
        retries = state.get("retry_count", 0) + 1  

        return {
            "prompt_ok": False,
            "retry_count": retries,
            "last_error": e.errors()[0]["msg"],  
        }

Шартномаи барои ҳамин иҷро собитшуда бор мешавад. Схема аз сиёсати фаъол ҳосил мешавад ва дар миёнаи иҷро дигар намегардад. Баромади агент пеш аз гузаштан ба гиреҳҳои баъдӣ дар марз санҷида мешавад. Сигнали муваффақият ошкор аст: қарорҳои масирдиҳӣ набояд ба фарзияҳои пинҳонӣ такя кунанд. Шумораи кӯшишҳо ба таври марказӣ зиёд мешавад ва кӯшишҳо маҳдуду мушоҳидашаванда мемонанд. Бозхӯрди сохторёфтаву амалпазир баргардонида мешавад, то агент такроран маҳз хатои муайянро ислоҳ кунад.

Нигоҳдории нуқтаҳои санҷишӣ ва MemorySaver дар боби 6 (қисми пешрафта, «Мувофиқати FSM/HSM ба чаҳорчӯбаҳои агентӣ») шарҳ дода шудаанд. Нуқтаи санҷиш мисли нуқтаи захира дар бозии компютерист. Онҳо имкон медиҳанд риштаи иҷроро аз охирин гиреҳи анҷомшуда идома диҳед. Инро барои устувории бештари система истифода бурдан мумкин аст. Тасаввур кунед, ки системаи мураккаби бисёрагентӣ доред ва модели андешароние монанди o1 ё o3-ро даъват мекунед (моделҳои OpenAI, ки пеш аз ҷавоб дароз фикр мекунанд ва аз ин рӯ гаронтаранд). Агар система дар марҳалаи баъдии тавлиди тасвир қатъ шавад, набояд барои ҳамон пешнавис дубора пардохт кунед: иҷрои такрории агентҳои пешина метавонад гарон бошад.

Нуқтаи санҷиш бояд аз таърихи паёмҳо бештар чизро нигоҳ дорад. Он бояд ҳолати кории иҷро, натиҷаҳои миёнарави абзорҳо, гиреҳ ё қадами таваққуф, маълумоти масирдиҳии интизор ва танзимоти заруриро барои идома бо ҳамон модел, промпт, абзор ва сиёсат ҳифз кунад. Намунаи 9.15 истифодаи нуқтаи санҷишро ҳамчун таҳаммулпазирӣ ба нокомӣ нишон медиҳад.

Намунаи 9.15. Компилятсияи граф бо нигоҳдории ҳолат

memory = InMemorySaver() 
app = workflow.compile(checkpointer=memory) 
config = {"configurable": {"thread_id": "production_run_001"}}

Нигоҳдорандаи хотира оғоз мешавад. Дар истеҳсолот онро бо PostgresSaver ё воситаи монанд барои нигоҳдории доимӣ иваз мекунед. Граф бо нигоҳдорандаи нуқтаҳои санҷиш компилятсия мешавад. thread_id калидест, ки идома додан ё «сафар дар вақт» ба иҷрои муайянро имкон медиҳад.

Намунаи 9.16 нишон медиҳад, ки ҳангоми такрори аз дарвозаи санҷиш баромада ё қатъи раванд, дубора иҷро кардани гиреҳи нависанда лозим нест. Система нуқтаи санҷишро дида, маҳз аз ҷойи таваққуф идома медиҳад.

Намунаи 9.16. Баррасии ҳолати «сафар дар вақт»

print("\n--- Fault Tolerance: Checkpoint Inspection ---")
snapshot = app.get_state(config) 
print(f"  Last node: {snapshot.next if hasattr(snapshot, 'next') else 'N/A'}") 
print(f"  Policy pinned: {bool(snapshot.values.get('active_policy'))}")
print(f"  Run ID: {snapshot.values.get('run_id', 'N/A')}")
print(f"  Policy hash: {snapshot.values.get('policy_hash', 'N/A')}")
print(f"  Schema hash: {snapshot.values.get('schema_hash', 'N/A')}")

get_state имкон медиҳад ҳар лаҳза ба «мағз»-и агент нигоҳ кунед. Маълумоти нишоншуда сабти пойгоҳи додаҳоро ба нуқтаи санҷиш мепайвандад ва муайян мекунад, ки система ҳоло дар куҷо таваққуф ё интизор шудааст. Баромад ҳолати нуқтаи санҷиш, собит будани сиёсат, идентификатори иҷро ва ҳэшҳои сиёсату схемаро нишон медиҳад.

Бо якҷоя кардани ин ҷузъҳо се пояи асосии системаи агентии устувортарро ба даст меоред:

• Таҳаммулпазирӣ ба нокомӣ. Агар агент аз санҷиш нагузарад, нигоҳдорандаи нуқтаи санҷиш имкон медиҳад танҳо гиреҳи ноком дубора иҷро шавад. Бо иҷро накардани гиреҳҳои пешина, монанди нависандаи муҳтаво, токен сарфа мекунед.
• Имкони аудит. Ҳар сабти пойгоҳи додаҳо policy_hash ва schema_hash дорад, ки дақиқ нишон медиҳанд ҳангоми сохтани додаҳо кадом қоидаҳо амал мекарданд.
• Васеъшавандагӣ. Ҷудо кардани шартномаҳои натиҷаи абзор — ҷаҳони берунӣ — аз шартномаҳои нигоҳдории доимӣ — пойгоҳи додаҳои дохилӣ — пешгирӣ мекунад, ки тағйири API-и берунӣ мантиқи нигоҳдории дарозмуддатро вайрон кунад.

Ин кӯмак мекунад хатоҳо дар сатҳи интерфейс боздошта шаванд ва система аз «бесарусомонӣ»-и иҷрои бемаҳдуди агентҳо ҳифз гардад.

Ду ҳалқаи ислоҳ: Pydantic ва Instructor

Ҷадвали 9.3 қабатҳои санҷиши Pydantic-ро бо таъмини мувофиқат тавассути Instructor муқоиса мекунад. Навъҳои гуногуни нокомӣ ба қабатҳои гуногуни система тааллуқ доранд. Як масъала шуморидани ҳамаи кӯшишҳои такрорӣ ё графро аз ҳад мураккаб мекунад, ё агентро ба қадри кофӣ маҳдуд намесозад.

Истифодаи OpenRouter

OpenRouter дархостҳоро ба беҳтарин таъминкунандагони дастрас барои модели муайян равона мекунад. Стратегияи пешфарз ба нарх асос меёбад. Агар таъхир муҳим бошад, метавонед стратегияи асосёфта ба таъхирро интихоб кунед. Барои мо ин таъхирро нисбат ба афзал донистани нархи паст тақрибан ба чоряк ё панҷяк кам кард. Ҷузъиёти стратегияҳои масирдиҳӣ дар ҳуҷҷатҳои OpenRouter ҳастанд.

Ҷадвали 9.3. Маънои такрор: санҷиши марзӣ ва таъмини мувофиқат ҳангоми тавлид

Расми 9.3 ҷойи кори дарвозаҳои Pydantic ва Instructor-ро аз боло нишон медиҳад.

Ҳалқаи дохилии шумо — Instructor — басомади баланд ва таъхири кам дорад. Он нокомиҳои вобаста ба моделро, монанди калидҳои сохтаи JSON ё майдонҳои намерасидаро ҳал мекунад. Инҳо пеш аз он рух медиҳанд, ки додаҳо ба мантиқи барномаи шумо расанд. Ҳалқаи берунӣ — Pydantic ва ҳамоҳангсозӣ — басомади пасттар ва эҳтимол таъхири бештар дорад. Он нокомиҳои сатҳи система, монанди тағйири сиёсат, маҳдудиятҳои пойгоҳи додаҳо ё хатои мантиқро идора мекунад. Нигоҳдорандаи нуқтаи санҷиш таъмин менамояд, ки нокомӣ дар ин сатҳ пешрафти ҳалқаи дохилиро аз байн набарад.

Расми 9.3. Дар системаи агентии сатҳи истеҳсолӣ ду намуди алоҳидаи «ҳалқаи ислоҳ» кор мекунанд: яке дар равзанаи тавлиди модел (Instructor), дигаре дар ҷараёни кори система (LangGraph + Pydantic).

Меъмориро аз ҳад умумӣ накунед

Instructor кӯшишҳои такрориро ҳамчун масъалаи система бартараф намекунад. Он такрорҳои аз вайроншавии схема ба вуҷудомадаро беҳина мекунад; аммо такрорҳои LangGraph ва нуқтаҳои санҷиш барои муҳлатгузарӣ, нокомии зерсохтор ва таъсирҳои бебозгашт ҳамоно заруранд.

Бехатарии ҳамзамонӣ дар серверҳои MCP

• Бехатарии ҳамзамонӣ. Барои даъватҳои ҳамзамони абзор пайвасти алоҳидаи ҳар даъватро истифода баред, на пайвасти умумӣ. Ҳолати WAL-и SQLite-ро барои ҳамзамонии беҳтар фаъол кунед ва барои пешгирии ҳолатҳои рақобатӣ навсозиҳои атомӣ истифода намоед. WAL тағйиротро дар журнали алоҳидаи пешакии навиштан нигоҳ медорад, ба ҷойи тағйири мустақими файли пойгоҳи додаҳо. Ин хондани ҳамзамон ҳангоми навиштанро имкон дода, самаранокӣ ва эътимоднокиро дар сарбориҳои чандравандӣ ё ҳамзамон беҳтар мекунад.

gRPC барои ҷорӣкуниҳои ташкилотии MCP

gRPC нақлиёти стандартии MCP нест — стандарт танҳо stdio ва Streamable HTTP-ро муайян мекунад. Аммо барои ҷорӣкунии ташкилотӣ gRPC ҳамчун нақлиёти фармоишӣ аҳамият пайдо мекунад, зеро бисёр муҳитҳои истеҳсолӣ аллакай барои муоширати байни хизматрасониҳо gRPC-ро стандарт кардаанд. Вақте абзорҳои MCP микросервисҳои мавҷударо мепӯшонанд, он ниёз ба қабатҳои табдилро кам карда метавонад ва ҳамзамон абстраксияи кашфу даъвати абзорҳои MCP-ро нигоҳ медорад. Онро интихоби ҷорӣкунии ташкилотӣ ҳисобед: ҳам сервер ва ҳам муштарӣ бояд онро дастгирӣ кунанд, ва барои таҳияи маҳаллӣ ҳатман зарур нест.

Имкон додан ба агентҳо барои кашфи серверҳои MCP

Сохтани серверҳои махсуси MCP барои додаҳои дохилӣ ва системаҳои хусусӣ муҳим аст. Аммо фоидаи воқеии MCP вақте пайдо мешавад, ки агент ҳамчун адаптери умумии USB-C ба ҷаҳони рақамӣ амал карда тавонад. Бартарии асосӣ он аст, ки агент абзорҳои лозимро барои вазифа кашф мекунад ва маҷмӯи собити пайвастҳо дар код маҳкам намешавад.

Платформаҳое монанди Composio садҳо пайвастшавии барномаҳои дигар, аз ҷумла Slack, GitHub, Gmail ва Jira-ро тавассути дарвозаи стандартӣ пешниҳод мекунанд. Ҳамчун алтернатива Docker MCP дастрасӣ ба серверҳои контейнеришудаи MCP медиҳад. Экосистемаи дастрасӣ ба серверҳои зиёд тавассути як марказ ҳанӯз рушд мекунад, аммо ин ду интихоби гуногун фароҳам меоранд.

Дар ин бахш SDK-и Composio-ро истифода мебаред. Ба ҷойи дастӣ табдил додани абзорҳои кашфшуда ба қолаби интизории модел, Composio таърифҳои мувофиқ бо OpenAI-ро бармегардонад. Ин гузариш аз кашфи абзор ба даъвати онро бо коди камтар имкон медиҳад. Расми 9.4 ин мисолро ба сервери махсуси бахши пешин мепайвандад ва нишон медиҳад, ки Composio ҳамин ғояро барои идоракунии пайвастҳои берунӣ чӣ гуна васеъ мекунад.

Расми 9.4. Гузариш аз абзорҳои собитшуда дар код ба кашфи абзорҳо.

Дар тарҳи анъанавӣ шояд ба агент абзори send_email диҳед. Дар экосистемаи асосёфта ба MCP агент метавонад ба ин пайвастшавиҳо мисли абзорҳои дохилӣ муносибат кунад: онҳоро кашф кунад, бо онҳо нақша кашад ва ҷараёнҳои кории байни онҳоро созад. Нуктаи асосӣ ин аст, ки муштарӣ пешакӣ дар бораи абзорҳо чизе донистанаш лозим нест. Барои дастрасӣ COMPOSIO_API_KEY ва барои модел OPENROUTER_API_KEY муайян карда, як муштарӣ оғоз мекунед. Намунаи 9.17 ин танзимро нишон медиҳад.

Намунаи 9.17. Оғоз кардани муштарии Composio

COMPOSIO_USER_ID = os.getenv("COMPOSIO_USER_ID", "user@example.com")
composio = Composio(api_key=COMPOSIO_API_KEY, provider=OpenAIProvider())

Бо омода шудани муштарӣ, амали асосии кашф танҳо як даъват аст. Шумо бо забони табиӣ тавсиф мекунед чӣ кардан мехоҳед. Composio байни пайвастшавиҳои дастрас ҷустуҷӯи маъноӣ анҷом медиҳад ва абзорҳои мувофиқро бармегардонад. Намунаи 9.18 инро дар функсияи ёрирасони хурд ҷой медиҳад.

Намунаи 9.18. Кашфи абзорҳои мувофиқ аз рӯи ният

def get_composio_tools_for_use_case(use_case: str, limit: int = 10):
    return composio.tools.get(
        user_id=COMPOSIO_USER_ID,
        search=use_case, 
        limit=limit,
    )

Ҷустуҷӯи маъноӣ абзорҳои аз ҳама мувофиқ ба ниятро бармегардонад. Дар дафтар барои ҳолати холӣ баргаштани ҷустуҷӯ роҳҳои эҳтиётии ҷустуҷӯ аз рӯи маҷмӯаи абзор ва номи дақиқи абзор илова шудаанд.

Дар ин марҳала агент ҳанӯз ҳеҷ амалеро иҷро накардааст. Он танҳо ҳангоми иҷро имкониятҳои дастрасро ба тасаввури худ аз ҷаҳон ворид кардааст. Барои хондашаванда кардани натиҷа абзорҳои кашфшударо аз рӯи маҷмӯаи онҳо гурӯҳбандӣ кардан мумкин аст. Намунаи 9.19 ҳамин корро мекунад.

Намунаи 9.19. Рӯйхати абзорҳои пешниҳодкардаи Composio

def list_composio_tools(tools):
    by_toolkit = {}
    for tool in tools:
        name = tool["function"]["name"] 
        by_toolkit.setdefault(name.split("_")[0], []).append(name)

    for toolkit, names in sorted(by_toolkit.items()):
        print(toolkit.title())
        for name in names:
            print(f"  - {name}")

Абзорҳо дар қолаби OpenAI меоянд, бинобар ин ном дар зери function ҷойгир аст. Дафтар функсияи хурди дастрасиро нигоҳ медорад, ки объектҳои моделии SDK-ро низ дастгирӣ мекунад.

Акнун кашфро бо нияти содаи забони табиӣ оғоз карда метавонед (намунаи 9.20).

Намунаи 9.20. Кашфи динамикии абзорҳо

use_case = "I want to send an email" 
tools = get_composio_tools_for_use_case(use_case)
list_composio_tools(tools)

Маънои ният: «Ман мехоҳам почтаи электронӣ фиристам». Ин промптро ба истифодаи худ мутобиқ карда метавонед.

Дар натиҷа рӯйхати имкониятҳое бармегардад, ки агент акнун бо онҳо кор мекунад:

Gmail
  - GMAIL_SEND_EMAIL
  - GMAIL_CREATE_EMAIL_DRAFT
  - GMAIL_SEND_DRAFT
Outlook
  - OUTLOOK_SEND_EMAIL
Sendgrid
  - SENDGRID_SEND_EMAIL_WITH_TWILIO_SEND_GRID

Акнун агент медонад кадом абзорҳо дастрасанд ва метавонад тарзи истифодаи онҳоро муайян кунад. Ҷараёни пурраи дафтар қадами баъдиро мегузорад: абзорҳоро ба ҳалқаи даъвати мувофиқ бо OpenAI дар OpenRouter медиҳад, ба модел имкон медиҳад онҳоро интихоб ва даъват кунад ва даъватҳои интихобшударо тавассути Composio иҷро менамояд.

Дафтари ин бахш ба чаҳорчӯбаҳои ART ва RULER аз боби 13 (барои хонандагони пешрафта) бармегардад. Акнун онҳо барои беҳтар кардани интихоби абзор аз ҷониби агенти кашфкунанда истифода мешаванд. Ҳамин тавр агент абзори аз ҳама мувофиқ ба нияти ҷориро интихоб мекунад ва танҳо ба аввалин мувофиқати калимаи калидӣ қаноат намекунад.

Кушодаасос ва осон васеъшаванда

deepagents пурра кушодаасос аст ва таҳти иҷозатномаи MIT нашр мешавад. Агар барои истифодаи худ ба Deep Agents ниёз дошта бошед, сохтани система бар пояи ин чаҳорчӯба ва мутобиқ кардани код ба ниёзҳоятон вақти зиёд сарфа мекунад. Ин равиш метавонад аз сохтани агентҳои амиқи махсус аз сифр самараноктар бошад.

Метавонед инчунин зерагентҳои махсус муайян кунед, то ҷараёни кор ба талаботи системаатон мувофиқ гардад. Ҷадвали 9.4 фоидаҳои асосиро ҷамъбаст мекунад.

Ҷадвали 9.4. Фоидаҳои асосии deepagents

Агентҳои амиқ метавонанд корро ба зерагентҳо супоранд. Зерагентҳои махсусро бо параметри subagents муайян мекунед. Онҳо асосан барои ҷудо кардани контекст ва татбиқи дастурҳои махсус истифода мешаванд, то агенти асосӣ ба банақшагирии сатҳи боло диққат диҳад. Намуди умумии ҷузъҳо дар расми 9.2 (бахши «Агентҳои амиқ: банақшагирӣ пеш аз иҷро») оварда шудааст.

Зерагентҳо ва ҷузъҳои агенти амиқ

Зерагентҳо мушкили варам кардани контекстро мустақиман ҳал мекунанд. Амалҳои зиёди абзорӣ, монанди ҷустуҷӯи веб, дастрасӣ ба файл ё дархости пойгоҳи додаҳо, метавонанд равзанаи контекстро зуд бо натиҷаҳои миёнарав пур кунанд. Бо супоридани ин кор ба зерагентҳо танҳо натиҷаи ниҳоӣ ба агенти асосӣ бармегардад, на даҳҳо даъвати миёнарави абзор. Расми 9.5 ин тақсимоти вазифаро аз боло нишон медиҳад.

Расми 9.5. Намунаи ташкили зерагентҳо.

Ҳар ҷузъи зерин мустақиман ба фоидаҳо ва ҷузъиёти амалисозии deepagents мувофиқ аст.

Модели LLM

Модели агент ошкоро танзимшаванда ва ивазшаванда аст. Таъминкунанда ё моделро бе тағйири мантиқи банақшагирӣ ва ҷараёни иҷро иваз карда метавонед. Ин барои беҳина кардани таъхир, хароҷот ё сифати мулоҳиза муҳим аст.

Промпти системавӣ

Промпти системавӣ дастурҳои дарунсохти миёнафзорро пурра мекунад ва ҷараёнҳои махсуси соҳа, намунаҳои иҷро ва меъёрҳои таваққуфро муайян менамояд. Он ҳамчун шартномаи ҷараёни кор амал мекунад.

Абзорҳо

Агентҳои амиқ абзорҳои махсус, абзорҳои MCP ва ҳатто серверҳои пурраи MCP-ро дастгирӣ мекунанд. Дастрасии абзор аз сиёсати истифодаи он ҷудо аст: имкониятҳоро пешниҳод мекунед ва ҳамзамон назорати кай ва чӣ гуна истифода шудани онҳоро нигоҳ медоред.

Миёнафзор (middleware)

Миёнафзор қабати идоракунии агенти амиқро ташкил мекунад. Абзорҳоро ворид менамояд, қоидаҳои банақшагириро таъмин мекунад, нуқтаҳои дахолат дар давраи ҳаёти иҷроро идора менамояд, қатъшавиҳоро коркард мекунад ва кафолатҳои бехатарӣ ва идоракуниро берун аз промпт татбиқ менамояд.

Зерагентҳо

Зерагентҳо равзанаҳои ҷудогонаи контекст бо моделҳо, абзорҳо ва дастурҳои худро доранд. Ин иҷрои мувозиро имкон медиҳад ва пешгирӣ мекунад, ки системаҳои дарозмуддат аз ҷамъшавии контекст заиф шаванд.

Шартномаҳои иҷро

SKILL.md ҳудуди қобилият ва маҳдудиятҳои амалиётиро муайян мекунад. AGENTS.md нақш, лаҳн, меъёрҳои сифат ва интизориҳои ҷараёни корро муайян менамояд. Якҷоя онҳо ҳамчун шартномаҳои татбиқшаванда байни банақшагирӣ, иҷро ва сифати баромад хизмат мекунанд.

Системаи файл ва хотира

Қабатҳои пуштибонии ивазшаванда назорати ошкори ҳолати муваққатӣ ва доимиро медиҳанд. Ҳолати муваққатӣ танҳо дар тӯли як иҷро вуҷуд дорад ва баъди анҷом хориҷ мешавад. Ин хотираи дарозмуддат, натиҷаҳои устувор ва иҷрои такроршавандаро бе пур кардани промпт имкон медиҳад.

Назорат бо иштироки инсон

Агар абзорҳои ҳассос истифода баред, метавонед иштироки инсон дар ҳалқа (HITL)-ро пайваст кунед, то иҷро таваққуф кунад ва пеш аз идома тасдиқи ошкори инсон талаб шавад. Ин автоматизатсияи масъулона медиҳад.

Мо анбори аслии LangChain-ро нусха гирифтем ва аз агенти нависандаи муҳтавои пешниҳодкардаи он оғоз кардем. Меъморӣ ва ҷараёни асосии агентҳои амиқ аз LangChain мебошанд. Мо ин мисоли навиштани муҳтаворо амалӣтар кардем: гузариши содатар байни таъминкунандагон ва пайвастшавӣ ба OpenRouter барои ҳам LLM ва ҳам моделҳои тавлиди тасвир илова шуд. Инчунин таваққуфҳои иштироки инсонро илова кардем, то қадамҳои алоҳидаро тасдиқ, таҳрир ё рад кунед.

Тарҳи ҳосилшуда нишон медиҳад, ки агентҳои амиқ барои навиштани мақолаҳои блог ё муҳтавои шабакаҳои иҷтимоӣ, монанди LinkedIn ё X, чӣ гуна истифода мешаванд. Агентҳо аввал таҳқиқи сохторёфта мекунанд, баъд пешнавис менависанд ва дар охир тасвири мувофиқ месозанд. Анбори мутобиқшударо дар ҳисоби GitHub-и муаллифи китоби аслӣ ва дафтари иҷрои пурраи мисолро дар анбори китоби аслӣ пайдо мекунед.