Приложение: Справочники¶

Зачем это нужно?¶

Этот раздел содержит справочную информацию: глоссарий терминов, чек-листы, шаблоны SOP и таблицы решений. Используйте его как справочник при работе над проектами.

Глоссарий¶

Основные концепции¶

Agent (Агент) — система, использующая LLM в качестве "движка рассуждений" для восприятия окружения, принятия решений и выполнения действий. Состоит из: LLM (мозг) + Tools (руки) + Memory (память) + Planning (планирование).

См. также: Глава 00: Предисловие

Runtime (Среда выполнения) — код агента, который вы пишете на Go. Связывает LLM с инструментами и управляет циклом работы агента. Выполняет парсинг ответов LLM, валидацию, выполнение инструментов и управление историей диалога.

Важно: Runtime — это не отдельная система или фреймворк. Это ваш код в main.go или отдельных модулях.

См. также: Глава 09: Анатомия Агента

Tool (Инструмент) — функция Go, API-вызов или команда, которую агент может выполнить для взаимодействия с реальным миром. Описывается в формате JSON Schema и передается модели в поле tools[].

Синонимы: Function (в контексте Function Calling)

См. также: Глава 03: Инструменты и Function Calling

Tool Call / Function Call (Вызов инструмента) — структурированный JSON-запрос, который LLM генерирует для вызова инструмента. Содержит имя инструмента и аргументы в формате JSON. Возвращается в поле tool_calls ответа модели.

Примечание: "Tool Call" и "Function Call" — это одно и то же. "Function Calling" — название механизма в API, "Tool Call" — конкретный вызов инструмента.

См. также: Глава 03: Инструменты и Function Calling

MCP (Model Context Protocol) — протокол подключения инструментов и данных к LLM-агентам (Anthropic). Предоставляет стандартный интерфейс для Resources, Tools и Prompts.

Artifact / artifact_id (Артефакт) — большой результат инструмента (файл, лог, JSON, HTML и т.д.), который рантайм сохраняет вне messages[], а в контекст модели возвращает только короткий excerpt + artifact_id. Это снижает стоимость/latency и уменьшает риск переполнения контекста.

См. также: Глава 20: Cost & Latency Engineering

AgentState (Состояние агента) — каноническая структура состояния agent run: цель, ограничения (в т.ч. HITL), бюджеты, план, известные факты, открытые вопросы, артефакты и risk flags. Это контракт между итерациями agent loop и между компонентами (например, "оркестратор" и "аналитик").

StatePatch (Патч состояния) — структурированное обновление AgentState (например: добавить факты, заменить план, добавить открытые вопросы). Удобно, когда один компонент анализирует результаты (нормализует), а другой выбирает следующее действие.

Risk Level (Уровень риска) — классификация сайд-эффектов шага/инструмента, которую использует политика и HITL-гейты. Типичный минимум: read_only, write_local, external_action.

ReAct Loop (Цикл Рассуждения и Действия) — паттерн работы автономного агента: Reason (рассуждает) → Act (действует) → Observe (наблюдает) → повторяет. Агент анализирует ситуацию, выполняет действие, видит результат и решает, что делать дальше.

Этимология: ReAct = Reason + Act

См. также: Глава 04: Автономность и Циклы

Skills (Навыки) — переиспользуемые модули поведения агента. Содержат инструкции, загружаемые в контекст в зависимости от задачи.

LLM и контекст¶

Context Window (Контекстное окно) — максимальное количество токенов, которые модель может обработать за один запрос. Ограничивает размер истории диалога. Примеры: GPT-4o: 128k токенов, GPT-4o-mini: 128k токенов, Claude 3.5 Sonnet: 200k токенов.

См. также: Глава 01: Физика LLM

Token (Токен) — единица текста, которую обрабатывает модель. Один токен ≈ 0.75 слова (английский) или ≈ 1.5 токена на слово (русский). Все, что агент "знает" о текущей задаче, ограничено количеством токенов в контекстном окне.

См. также: Глава 01: Физика LLM

System Prompt (Системный промпт) — инструкции для модели, которые задают роль, цель, ограничения и процесс работы агента. Передается в messages[0].content с ролью "system". Состоит из: Role (Persona), Goal, Constraints, Format, SOP.

См. также: Глава 02: Промптинг

Temperature (Температура) — параметр энтропии распределения вероятностей токенов. Temperature = 0 — детерминированное поведение (для агентов), Temperature > 0 — случайное поведение (для креативных задач).

Правило: Для всех агентов устанавливайте Temperature = 0.

См. также: Глава 01: Физика LLM

Техники промптинга¶

Chain-of-Thought (CoT) — техника промптинга "думай по шагам", заставляющая модель генерировать промежуточные рассуждения перед финальным ответом. Критична для агентов, решающих сложные многошаговые задачи.

См. также: Глава 02: Промптинг

Few-Shot Learning / Few-Shot (Обучение с примерами) — техника промптинга, при которой в промпт добавляются примеры желаемого поведения. Модель адаптируется к формату на основе примеров в контексте.

Антоним: Zero-Shot (только инструкция, без примеров)

См. также: Глава 02: Промптинг

Zero-Shot Learning / Zero-Shot (Обучение без примеров) — техника промптинга, при которой модели дается только инструкция без примеров. Экономит токены, но требует точных инструкций.

Антоним: Few-Shot (с примерами)

См. также: Глава 02: Промптинг

In-Context Learning (ICL) — способность модели адаптировать поведение на основе примеров внутри промпта, без изменения весов модели. Работает в режимах Zero-shot и Few-shot.

См. также: Глава 02: Промптинг

SOP (Standard Operating Procedure) — алгоритм действий, закодированный в промпте. Задает последовательность шагов для решения задачи. CoT помогает следовать SOP шаг за шагом.

См. также: Глава 02: Промптинг

Память и контекст¶

Memory (Память агента) — система хранения и извлечения информации между разговорами. Включает кратковременную память (история текущего разговора) и долговременную память (постоянное хранилище фактов).

См. также: Глава 12: Системы Памяти Агента

Working Memory (Рабочая память) — недавние повороты разговора, которые всегда включены в контекст. Наиболее релевантны для текущей задачи. Управляется через Context Engineering.

См. также: Глава 13: Context Engineering

Long-term Memory (Долговременная память) — постоянное хранилище фактов, предпочтений и прошлых решений. Хранится в базе данных/файлах и сохраняется между разговорами. Может использовать векторную базу данных (RAG) для семантического поиска.

См. также: Глава 12: Системы Памяти Агента

Episodic Memory (Эпизодическая память) — память о конкретных событиях: "Пользователь спрашивал о месте на диске 2026-01-06". Полезна для отладки и обучения.

См. также: Глава 12: Системы Памяти Агента

Semantic Memory (Семантическая память) — общие знания, извлеченные из эпизодов: "Пользователь предпочитает JSON ответы". Более абстрактная, чем эпизодическая память.

См. также: Глава 12: Системы Памяти Агента

Context Engineering (Управление контекстом) — техники эффективного управления контекстом: слои контекста (рабочая память, саммари, факты), саммаризация старых разговоров, отбор релевантных фактов, адаптивное управление контекстом.

См. также: Глава 13: Context Engineering

RAG (Retrieval Augmented Generation) — техника дополнения контекста агента релевантными документами из базы знаний через векторный поиск. Документы разбиваются на чанки, преобразуются в векторы (embeddings), при запросе ищутся похожие векторы.

См. также: Глава 06: RAG и База Знаний

Agentic RAG — RAG, встроенный в Agent Loop. Агент сам решает, когда и где искать, оценивает качество результатов и может искать повторно.

Self-RAG — RAG с самооценкой качества. Модель оценивает релевантность найденных документов и решает: ответить, уточнить запрос или искать ещё.

Hybrid Search (Гибридный поиск) — комбинация keyword-поиска (BM25) и векторного поиска. Объединяет результаты через Reciprocal Rank Fusion.

Планирование и архитектура¶

Planning (Планирование) — способность агента разбить сложную задачу на последовательность простых шагов и выполнить их в правильном порядке. Уровни: имплицитное (ReAct), явное (Plan-and-Solve), иерархическое.

См. также: Глава 09: Анатомия Агента

State Management (Управление состоянием) — управление состоянием выполнения задачи: прогресс, что сделано, что ожидает, возможность возобновления. Включает идемпотентность инструментов, retries с экспоненциальным backoff, дедлайны, persist state.

См. также: Глава 11: State Management

Checkpoint (Контрольная точка) — снимок состояния агента в определённый момент. Позволяет восстановить работу после сбоя без потери прогресса.

Reflexion (Рефлексия) — техника самокоррекции агента через анализ ошибок. Цикл: Act → Observe → Fail → REFLECT → Plan Again. Агент анализирует, почему действие не сработало, и планирует заново.

См. также: Глава 09: Анатомия Агента

Безопасность и надежность¶

Grounding (Заземление) — привязка агента к реальным данным через Tools/RAG, чтобы избежать галлюцинаций. Агент должен использовать инструменты для получения фактов, а не выдумывать их.

См. также: Глава 01: Физика LLM

Human-in-the-Loop (HITL) — механизм подтверждения критических действий человеком перед выполнением. Включает Confirmation (подтверждение), Clarification (уточнение), Risk Scoring (оценка риска).

См. также: Глава 05: Безопасность и Human-in-the-Loop

Prompt Injection (Инъекция промпта) — атака на агента через манипуляцию входными данными. Злоумышленник пытается "обмануть" промпт, чтобы агент выполнил нежелательное действие.

См. также: Глава 05: Безопасность и Human-in-the-Loop

Defense in Depth (Глубокая защита) — многоуровневая стратегия безопасности. Каждый слой (input validation, runtime checks, output filtering, monitoring) защищает от разных типов атак.

Red Teaming — систематическое тестирование агента на уязвимости. Команда "атакующих" пытается заставить агента нарушить правила.

Eval (Evaluation) — тест для проверки качества работы агента. Может проверять корректность ответов, выбор инструментов, следование SOP, безопасность. В промышленных системах используется в CI/CD.

См. также: Глава 08: Evals и Надежность

DeepEval — фреймворк для оценки качества LLM-приложений. Предоставляет метрики: faithfulness, answer relevancy, context precision.

Multi-turn Evaluation (Многоходовая оценка) — оценка агента в многошаговых диалогах. Проверяет связность контекста и корректность действий на каждом шаге.

RAGAS — фреймворк метрик для RAG-систем. Измеряет context precision, context recall, faithfulness и answer relevance.

Мультиагентные системы¶

Multi-Agent System (MAS) — система из нескольких агентов, работающих вместе. Может использовать паттерны Supervisor/Worker, изоляцию контекста, маршрутизацию задач между специализированными агентами.

См. также: Глава 07: Multi-Agent Systems

A2A (Agent-to-Agent) — протокол межагентной коммуникации (Google). Стандартизирует обмен задачами между агентами через Agent Card, Task lifecycle и Message/Artifact.

Handoff (Передача управления) — передача управления от одного агента другому с частью контекста. Используется при эскалации или смене домена.

Router Agent (Агент-маршрутизатор) — агент-маршрутизатор. Классифицирует запрос и направляет его к подходящему специалисту.

Subagent (Под-агент) — под-агент, создаваемый динамически для подзадачи. В отличие от Worker, создаётся "на лету" под конкретную задачу.

Чек-листы¶

Чек-лист: Настройка модели для агента¶

Модель поддерживает Function Calling (проверено через Lab 00)
Temperature = 0 установлена
Контекстное окно достаточно большое (минимум 4k токенов)
System Prompt запрещает галлюцинации
История диалога управляется (обрезается при переполнении)

Чек-лист: Создание System Prompt¶

Роль (Persona) четко определена
Цель (Goal) конкретна и измерима
Ограничения (Constraints) явно указаны
Формат ответа (Format) описан
SOP (если применимо) детально расписан
CoT включен для сложных задач
Few-Shot примеры добавлены (если нужно)

Capability Benchmark (Characterization)¶

Перед тем как строить агентов, необходимо научно подтвердить, что выбранная модель обладает необходимыми способностями. В инженерии это называется Characterization (характеризация).

Зачем это нужно?¶

Мы не верим этикеткам ("Super-Pro-Max Model"). Мы верим тестам.

Проблема без проверки: Вы скачали модель "Llama-3-8B-Instruct" и начали строить агента. Через час работы обнаружили, что модель не вызывает инструменты, а только пишет текст. Вы потратили время на отладку кода, хотя проблема была в модели.

Решение: Запустите capability benchmark перед началом работы. Это сэкономит часы.

Что мы проверяем?¶

1. Basic Sanity (Базовая работоспособность)¶

Модель отвечает на запросы
Нет критических ошибок API
Базовая связность ответов

2. Instruction Following (Следование инструкциям)¶

Модель может жестко придерживаться ограничений
Важно для агентов: они должны возвращать строго определенные форматы
Тест: "Напиши стих, но не используй букву 'а'"
Зачем: Агент должен возвращать строго определенные форматы, а не "размышления"

3. JSON Generation (Генерация JSON)¶

Модель может генерировать валидный синтаксис
Все взаимодействие с инструментами строится на JSON
Если модель забывает закрыть скобку }, агент падает
Тест: "Верни JSON с полями name и age"

4. Function Calling (Использование инструментов)¶

Специфический навык модели распознавать определение функций и формировать специальный токен вызова
Без этого невозможны инструменты (см. Главу 03: Инструменты)
Зачем: Это основа для Lab 02 и всех последующих лаб

Почему не все модели умеют Tools?¶

LLM (Large Language Model) — это вероятностный генератор текста. Она не "знает" про функции из коробки.

Механизм Function Calling — это результат специальной тренировки (Fine-Tuning). Разработчики модели добавляют в обучающую выборку тысячи примеров вида:

User: "Check weather"
Assistant: <special_token>call_tool{"name": "weather"}<end_token>

Если вы скачали "голую" Llama 3 (Base model), она не видела этих примеров. Она просто продолжит диалог текстом.

Как проверить: Запустите Lab 00 перед началом работы с инструментами.

Почему `Temperature = 0` критично для агентов?¶

Температура регулирует "случайность" выбора следующего токена:

High Temp (0.8+): Модель выбирает менее вероятные слова. Хорошо для стихов, творческих задач.
Low Temp (0): Модель всегда выбирает самое вероятное слово (ArgMax). Максимальная детерминированность.

Для агентов, которые должны выдавать строгий JSON или вызов функции, нужна максимальная детерминированность. Любая "творческая" ошибка в JSON сломает парсер.

Правило: Для всех агентов устанавливайте Temperature = 0.

Как интерпретировать результаты?¶

Все тесты прошли¶

Модель готова для курса. Можно продолжать работу.

Предупреждение: 3 из 4 тестов прошли¶

Можно продолжать, но с осторожностью. Возможны проблемы в краевых случаях.

Function Calling провален¶

Критично: Модель не подходит для Lab 02-08. Нужна другая модель.

Что делать:

Скачайте модель с поддержкой tools:
- Hermes-2-Pro-Llama-3-8B
- Mistral-7B-Instruct-v0.2
- Llama-3-8B-Instruct (некоторые версии)
- Gorilla OpenFunctions
Перезапустите тесты

JSON Generation провален¶

Модель генерирует сломанный JSON (пропущенные скобки, кавычки).

Что делать:

Попробуйте другую модель
Или используйте Temperature = 0 (но это не всегда помогает)

Связь с Evals¶

Capability Benchmark — это примитивный Eval (Evaluation). В промышленных системах (LangSmith, PromptFoo) таких тестов сотни.

Развитие темы: См. Главу 08: Evals и Надежность для понимания, как строить комплексные evals для проверки качества работы агента.

Практика¶

Для выполнения capability benchmark см. Lab 00: Model Capability Benchmark.

Шаблоны SOP¶

SOP для инцидента (DevOps)¶

SOP для падения сервиса:
1. Check Status: Проверь HTTP код ответа
2. Check Logs: Если 500/502 — читай последние 20 строк логов
3. Analyze: Найди ключевые слова:
   - "Syntax error" → Rollback
   - "Connection refused" → Check Database
   - "Out of memory" → Restart
4. Action: Примени фикс согласно анализу
5. Verify: Проверь HTTP статус снова

SOP для обработки тикета (Support)¶

SOP для обработки тикета:
1. Read: Прочитай тикет полностью
2. Context: Собери контекст (версия, ОС, браузер)
3. Search: Поищи в базе знаний похожие случаи
4. Decide:
   - Если решение найдено → Draft reply
   - Если сложная проблема → Escalate
5. Respond: Отправь ответ пользователю

Таблицы решений¶

Таблица решений для инцидента¶

Симптом	Гипотеза	Проверка	Действие	Верификация
HTTP 502	Сервис упал	`check_http()` → 502	-	-
HTTP 502	Ошибка в логах	`read_logs()` → "Syntax error"	`rollback_deploy()`	`check_http()` → 200
HTTP 502	Ошибка в логах	`read_logs()` → "Connection refused"	`restart_service()`	`check_http()` → 200

FAQ: Что происходит на деле?¶

Q: Агент сам решает, что делать. Это магия?¶

A: Нет. Агент работает по простому алгоритму:

LLM видит описание инструментов в tools[]
LLM генерирует JSON с именем инструмента и аргументами
Ваш код (Runtime) парсит JSON и выполняет реальную функцию
Результат добавляется в историю
LLM видит результат в контексте и генерирует следующий шаг

Никакой магии тут нет — это просто цикл, где модель видит результаты предыдущих действий.

См. также: Глава 04: Автономность

Q: Как модель "знает", какой инструмент вызвать?¶

A: Модель не "знает". Она выбирает инструмент на основе:

Описания инструмента (Description в JSON Schema)
Запроса пользователя (семантическое соответствие)
Контекста предыдущих результатов (если есть)

Чем точнее Description, тем лучше выбор.

См. также: Глава 03: Инструменты

Q: Модель "помнит" прошлые разговоры?¶

A: Нет. Модель stateless. Она видит прошлое только в messages[], который вы передаете в каждом запросе. Если вы не передаете историю, модель ничего не помнит.

См. также: Глава 01: Физика LLM

Q: Почему агент иногда делает разные действия на один и тот же запрос?¶

A: Это происходит из-за вероятностной природы LLM. Если Temperature > 0, модель выбирает случайный токен из распределения. Для агентов всегда используйте Temperature = 0 для детерминированного поведения.

См. также: Глава 01: Физика LLM

Q: Модель выдумывает факты. Как это исправить?¶

A: Используйте Grounding (Заземление):

Запретите выдумывать факты в System Prompt
Дайте агенту доступ к реальным данным через Tools
Используйте RAG для доступа к документации

См. также: Глава 01: Физика LLM

Q: Агент "забывает" начало разговора. Что делать?¶

A: Это происходит, когда история диалога превышает размер контекстного окна. Решения:

Саммаризация: Сжимайте старые сообщения через LLM
Отбор фактов: Извлекайте важные факты и храните отдельно
Слои контекста: Рабочая память + саммари + факты

См. также: Глава 13: Context Engineering

Q: Модель не вызывает инструменты. Почему?¶

A: Возможные причины:

Модель не поддерживает Function Calling (проверьте через Lab 00)
Плохое описание инструмента (Description неясное)
Temperature > 0 (слишком случайно)

Решение: Используйте модель с поддержкой tools, улучшите Description, установите Temperature = 0.

См. также: Глава 03: Инструменты

Мини-упражнения¶

Упражнение 1: Создайте свой SOP¶

Создайте SOP для вашего домена по образцу из раздела "Шаблоны SOP":

SOP для [ваша задача]:
1. [Шаг 1]
2. [Шаг 2]
3. [Шаг 3]

Ожидаемый результат:

SOP четко описывает процесс действий
Шаги последовательны и логичны
Включены проверки и верификация

Упражнение 2: Создайте таблицу решений¶

Создайте таблицу решений для вашей задачи по образцу из раздела "Таблицы решений":

Симптом	Гипотеза	Проверка	Действие	Верификация
...	...	...	...	...

Ожидаемый результат:

Таблица покрывает основные сценарии
Для каждого симптома есть гипотеза, проверка, действие и верификация

Связь с другими главами¶

Промптинг: Как использовать SOP в промптах, см. Главу 02: Промптинг
Кейсы: Примеры использования SOP в реальных агентах, см. Главу 15: Кейсы

Приложение: Справочники¶

Зачем это нужно?¶

Глоссарий¶

Основные концепции¶

LLM и контекст¶

Техники промптинга¶

Память и контекст¶

Планирование и архитектура¶

Безопасность и надежность¶

Мультиагентные системы¶

Чек-листы¶

Чек-лист: Настройка модели для агента¶

Чек-лист: Создание System Prompt¶

Capability Benchmark (Characterization)¶

Зачем это нужно?¶

Что мы проверяем?¶

1. Basic Sanity (Базовая работоспособность)¶

2. Instruction Following (Следование инструкциям)¶

3. JSON Generation (Генерация JSON)¶

4. Function Calling (Использование инструментов)¶

Почему не все модели умеют Tools?¶

Почему Temperature = 0 критично для агентов?¶

Как интерпретировать результаты?¶

Все тесты прошли¶

Предупреждение: 3 из 4 тестов прошли¶

Function Calling провален¶

JSON Generation провален¶

Связь с Evals¶

Практика¶

Шаблоны SOP¶

SOP для инцидента (DevOps)¶

SOP для обработки тикета (Support)¶

Таблицы решений¶

Таблица решений для инцидента¶

FAQ: Что происходит на деле?¶

Q: Агент сам решает, что делать. Это магия?¶

Q: Как модель "знает", какой инструмент вызвать?¶

Q: Модель "помнит" прошлые разговоры?¶

Q: Почему агент иногда делает разные действия на один и тот же запрос?¶

Q: Модель выдумывает факты. Как это исправить?¶

Q: Агент "забывает" начало разговора. Что делать?¶

Q: Модель не вызывает инструменты. Почему?¶

Мини-упражнения¶

Упражнение 1: Создайте свой SOP¶

Упражнение 2: Создайте таблицу решений¶

Связь с другими главами¶

Почему `Temperature = 0` критично для агентов?¶