Практические замечания: почему никто не говорит о LangChain, LangGraph или AutoAgent
Пошаговое руководство по практическим заметкам: почему никто не говорит о LangChain, LangGraph или AutoAgent: контракты, проверки и готовые блоки кода для команд, использующих эту архитектуру.
В этом руководстве пошагово описывается путь от сырья до функционирующей системы для темы «Почему никто не говорит о LangChain, LangGraph или AutoAgent». Основное внимание уделяется практическим шагам, четкой проверке и коду, который можно просто добавить в репозиторий без необходимости угадывать намерения автора. Для получения обзора сначала определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не пытаясь угадать скрытое состояние. Документируйте как успешный ход выполнения, так и способы восстановления после сбоев. Повторные попытки, проверка человеком и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями.
┌────────────────────────────────────────┐
│ POST-FRAMEWORK PARADIGM │
└──────────────────┬─────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PIPELINE │ │ HARNESS │
│ MODE │ │ MODE │
├──────────────┤ ├──────────────┤
│ • Bounded │ │ • Unbounded │
│ • Code-Run │ │ • Model-Run │
│ • Compute │ │ • Context │
│ Bound │ │ Bound │
└──────────────┘ └──────────────┘
Оглавление
При работе над оглавлением сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Вносите контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий элемент.
1. Классификация работ, которую никто не выполняет
При работе над разделом «1. Классификация задач, которую никто не выполняет», сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не допускайте безответственного частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Is the work decomposable into a finite set of
named states with deterministic transitions?
[ YES ] ──► PIPELINE MODE
• Invoice Extraction
• Document Classification
• Approval Routing
• KYC Verification
• Data Enrichment
[ NO ] ──► HARNESS MODE
• Coding Agents
• Research Agents
• Ephemeral Tool/Shell Use
• Legacy Code Migrations
• Open-Ended Investigation
2. Режим конвейера: когда задачу можно разложить на части
При работе с разделом 2. Режим конвейера: когда задача делимая, сначала запишите контракт: необходимые входные данные, сигнал о успехе и последствия частичной неудачи. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Очевидность затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить последующий узел. При работе с разделом 2. Режим конвейера: когда задача делимая, сначала запишите контракт: необходимые входные данные, сигнал о успехе и последствия частичной неудачи. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.
[Input Data payload]
│
▼
┌──────────────┐
│ State 1 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
┌──────────────┐
│ State 2 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
[Final Success Output]
3. Режим Harness: когда работу нельзя разложить на части
- Режим Harness: когда работу нельзя разложить на части наилучшим образом работает, если рассматривать его как измеримую поверхность. Соберите один идеальный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы вместо обширных скриптов. Когда какой-либо шаг срабатывает некорректно, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Используйте инструменты с узкими схемами и четкими метками побочных эффектов. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят действия.
┌──────────────────────────────────────────────┐
│ HARNESS LAYER │
│ Executes container limits & system safety │
├──────────────────────────────────────────────┤
│ [Safety Hooks] [Budgets] [Time Constraints] │
├──────────────────────────────────────────────┤
│ ┌────────────────────────────────────────┐ │
│ │ MODEL OWNS LOOP │ │
│ │ Plan ──► Execute ──► Observe ──► Plan │ │
│ │ │ │
│ │ Native capabilities: │ │
│ │ • File / Sandboxed Shell access │ │
│ │ • Context-isolated subagent spawning │ │
│ │ • Skill discovery & loading │ │
│ └────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────┘
▼
Result, Partial State, or Escalation
Способы сбоев в режиме Harness
Режим Harness Mode работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия всем элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи. Используйте инструменты с узкими схемами и четкими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.
4. Математическая реальность обоих режимов
- Математическая реальность обоих режимов наилучшим образом проявляет себя при рассмотрении их как измеримой поверхности. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
- Математическая реальность обоих режимов наилучшим образом проявляет себя при рассмотрении их как измеримой поверхности. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Режим конвейера: закон масштабирования времени инференса
Для режима Pipeline: согласно закону масштабирования времени инференса, необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру всей системы. Внедрять человеческое утверждение для операций, связанных с расходованием средств или изменением производственных данных. Конфигурация на этапе компиляции не гарантирует полноты функционала системы.
Режим Harness: кривая деградации контекста
Для режима Harness: для кривой ухудшения качества контекста необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безответственного частичного завершения работы. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне передачи данных. Одного лишь токена-носителя недостаточно для обозначения границы тенантности.
P(Success)
▲
1.0├───────────┐
│ │
│ └───┐
0.5│ │
│ └─────────────► Context Size (Tokens)
0└───────────┬───┬─────────────
50k 100k
5. Форма Harness в 2026 году (план реализации)
Для раздела 5. «Формат средства управления 2026 года (план реализации)» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне передачи данных. Один только токен-носитель не является границей аренды. Для раздела 5. «Формат средства управления 2026 года (план реализации)» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно успешный сценарий выполнения и сценарий восстановления. Повторные попытки, человеческое вмешательство и обработка некорректных сообщений являются частью профессионального подхода.
канал, позже не полировать.import logging
import os
from typing import Dict, Any, List
from pydantic import BaseModel, Field
# 2026 SDK abstractions (analogous across major provider frameworks)
from modern_agent_sdk import Agent, Skill, SubAgent
from modern_agent_sdk.hooks import PreToolUse, PostToolUse
from modern_agent_sdk.budgets import TokenBudget, StepBudget, WallTimeBudgetlogger = logging.getLogger("EnterpriseHarness")# 1. Skills are dynamically loaded from disk, not declared inline.
# Each skill is an isolated directory containing metadata (SKILL.md),
# runtime scripts, and specialized sandbox requirements.
SKILLS_DIR = "./skills"
all_skills = Skill.load_directory(SKILLS_DIR)# 2. Safety Hooks: Gateway controls running in the host environment.
# These run on the host *before* any action is committed inside the sandbox.
def pre_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel) -> PreToolUse:
"""
Validates security boundaries and consumption limits before the model executes a tool.
"""
# Hard safety boundary: Prevent destructive shell operations
if tool_call.name == "execute_shell":
command = tool_call.args.get("command", "")
if any(bad_cmd in command for bad_cmd in ["rm -rf", "chmod", "wget"]):
logger.error(f"Execution blocked: Blocked command detected: '{command}'")
return PreToolUse.deny("Destructive shell operations are prohibited in this sandbox.")
# Budget check: Halt network tools if API budget is running low
if tool_call.name == "network_request":
if context["budget"].remaining_tokens < 15_000:
return PreToolUse.deny("Insufficient remaining token budget to execute external network calls.")
logger.info(f"Approved tool call: {tool_call.name}")
return PreToolUse.allow()def post_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel, result: Any) -> PostToolUse:
"""
Evaluates tool execution outcomes to detect systemic failure loops.
"""
# Detect repeating error patterns to prevent infinite execution loops
if result.is_error and context["consecutive_failures"] >= 3:
logger.warning("System detected a repeating error loop. Forcing escalation.")
return PostToolUse.escalate("Agent is stuck in an execution failure loop.")
return PostToolUse.continue_loop()# 3. Context Isolation via Subagents
# To prevent context poisoning, the parent agent never sees the child's
# scratchpad or intermediate execution steps—only the final verified output.
def spawn_research_subagent(target_query: str) -> str:
"""
Spawns a specialized subagent in a separate context window to perform a task,
keeping the parent's working context completely clean.
"""
logger.info(f"Spawning isolated subagent for query: '{target_query}'")
subagent = SubAgent(
model="claude-sonnet-4-5",
skills=all_skills.filter_by_tag("research"),
budgets=[
TokenBudget(max_input_tokens=40_000, max_output_tokens=8_000),
StepBudget(max_steps=12)
]
)
# Run task and return only the clean, compiled summary
output = subagent.execute(task=target_query)
return output.summary# 4. Assembling the Harness Container
# The harness manages the execution sandbox, enforces constraints, and handles state.
agent_harness = Agent(
model="claude-opus-4-7",
skills=all_skills,
subagent_factories={
"researcher": spawn_research_subagent
},
hooks={
"pre_tool_use": pre_tool_execution_hook,
"post_tool_use": post_tool_execution_hook
},
budgets=[
TokenBudget(max_total_tokens=600_000),
StepBudget(max_steps=100),
WallTimeBudget(max_seconds=1800) # 30-minute hard cap
],
persistence_store="./.agent_state_db", # State is persisted per step to survive restarts
escalation_handler=lambda issue: open_human_review_ticket(issue)
)# 5. Execution
if __name__ == "__main__":
task_input = "Migrate this legacy Django 4.2 codebase to FastAPI with 100% endpoint parity."
try:
# The agent loop is entirely internal to the model.
# There is no manual 'while True' in our orchestration code.
result = agent_harness.run(task=task_input)
logger.info(f"Task completed. Result: {result.status}")
except Exception as e:
logger.critical(f"Harness terminated execution: {e}")
Основные отличия от старых фреймворков 2024 года:
При анализе Основных отличий от старых фреймворков 2024 года сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг терпит неудачу, ошибка должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Выполняйте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий узел.
6. Архитектурные конфликты: применение неподходящего решения к неподходящей проблеме
При работе над разделом 6. «Архитектурные коллизии: применение неподходящей структуры к неправильной проблеме» сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
┌─────────────────────────────────────────────────────┐
│ ARCHITECTURAL MATCH │
├──────────────────────────┬──────────────────────────┤
│ PIPELINE WORKLOAD │ HARNESS WORKLOAD │
├──────────────────────────┼──────────────────────────┤
│ • Goal: Exact Extraction │ • Goal: Code Refactoring,│
│ & Routing │ Agent Tasks, Migration │
│ │ │
│ • WRONG: Harness │ • WRONG: Pipeline │
│ (High latency, costly, │ (FSM State explosion, │
│ non-deterministic) │ inflexible schema) │
│ │ │
│ • RIGHT: Pipeline FSM │ • RIGHT: Sandbox Harness │
│ (Predictable transitions)│ (Dynamic loop execution)│
└──────────────────────────┴──────────────────────────┘
Случай 1: Ошибка Harness-on-Pipeline (чрезмерная инженерия)
При решении задачи №1: Ошибка «Harness-on-Pipeline» (чрезмерная инженерия), сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает часы. При решении задачи №1: Ошибка «Harness-on-Pipeline» (чрезмерная инженерия), сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.
Случай 2: Ошибка «Pipeline-on-Harness» (недостаточная проектировка)
Случай 2: Ошибка «Pipeline-on-Harness» (недостаточная проектировка) лучше всего рассматривать как измеримую характеристику. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-либо шаг срабатывает некорректно, причина сбоя должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных. Используйте инструменты с узкими схемами и чёткими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние системы, прежде чем они автоматически одобрят действия.
Как выбрать правильную архитектуру
Метод «Как выбрать правильную архитектуру» работает наилучшим образом, если рассматривать его как измеримую величину. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
7. Уровень навыков: открытый стандарт 2026 года
- Слой навыков: Открытый стандарт 2026 года работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и нарушают возможность продолжения работы после прерываний.
- Слой навыков: Открытый стандарт 2026 года работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный путь выполнения задачи и путь восстановления после сбоя. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
skills/
├── document_parser/
│ ├── SKILL.md <-- Human/Model readable metadata & capabilities
│ ├── run.py <-- The execution logic running inside the sandbox
│ └── reference_rules.pdf <-- Domain-specific constraints and edge-cases
8. Заключение: Новая инженерная работа
8. Заключение: при создании новой инженерной задачи необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной областью ответственности, а не с запутанной структурой процессов. Внедрять человеческое утверждение для операций, связанных с расходованием средств или изменением производственных данных. Наличие связей во время компиляции не гарантирует полноты реализации бизнес-логики.
Чек-лист операций
Чек-лист операций наиболее эффективен, когда его рассматривают как измеримую основу для контроля. Перед расширением объема работ необходимо зафиксировать один эталонный пример работы, один случай сбоя и записку о возможности отката.
Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф.
Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний.
При наличии бюджета добавляйте тесты для проверки критического пути в процессе CI с использованием фикстчеров, а не реальных платных API.
Документируйте как успешный, так и восстановительный пути работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями.
Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний.
Перед внедрением данной стек-технологии необходимо заморозить версии, сгенерировать эталонный отчет для критически важных этапов и уточнить шаги отката. В совместных средах требуются ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.
Примечание для 9f921d978495: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте отчеты рядом с фикстурами для оценки, чтобы последующие замены моделей оставались сопоставимыми.