diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 5d26a894f..864b381a8 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -1,26 +1,27 @@ --- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу + - Ви змінюєте поведінку черги сесій, запису транскриптів або блокування запису сесії summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-04-12T18:22:00Z" + generated_at: "2026-04-23T03:59:22Z" model: gpt-5.4 provider: openai - source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5 + source_hash: 439b68446cc75db3ded7a7d20df8e074734e6759ecf989a41299d1b84f1ce79c source_path: concepts/agent-loop.md workflow: 15 --- # Цикл агента (OpenClaw) -Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі → +Агентний цикл — це повний «реальний» запуск агента: приймання → збирання контексту → інференс моделі → виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення -на дії та фінальну відповідь, водночас зберігаючи узгоджений стан сесії. +на дії та фінальну відповідь, зберігаючи водночас узгоджений стан сесії. -В OpenClaw цикл — це один серіалізований запуск на сесію, який створює події життєвого циклу та потокові події, -поки модель думає, викликає інструменти й передає в потоці вихідні дані. У цьому документі пояснюється, як цей -автентичний цикл з’єднано наскрізно. +У OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потокові події, +поки модель міркує, викликає інструменти й передає вихідні дані потоком. У цьому документі пояснюється, як цей +автентичний цикл з’єднаний наскрізно. ## Точки входу @@ -29,148 +30,157 @@ x-i18n: ## Як це працює (на високому рівні) -1. RPC `agent` перевіряє параметри, визначає сесію (`sessionKey/sessionId`), зберігає метадані сесії та відразу повертає `{ runId, acceptedAt }`. +1. RPC `agent` перевіряє параметри, визначає сесію (`sessionKey/sessionId`), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає типові значення model + thinking/verbose/trace + - визначає модель + типові значення thinking/verbose/trace - завантажує знімок Skills - - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - створює **lifecycle end/error**, якщо вбудований цикл цього не створив + - викликає `runEmbeddedPiAgent` (runtime pi-agent-core) + - генерує **завершення/помилку життєвого циклу**, якщо вбудований цикл сам цього не згенерував 3. `runEmbeddedPiAgent`: - - серіалізує запуски через черги для кожної сесії та глобальну чергу - - визначає профіль model + auth і будує pi-сесію - - підписується на події pi та передає assistant/tool deltas у потоці - - примусово застосовує timeout -> перериває запуск, якщо його перевищено - - повертає корисні навантаження та метадані usage + - серіалізує запуски через черги на рівні сесії та глобальні черги + - визначає модель + профіль автентифікації та будує pi-сесію + - підписується на події pi та передає потоком дельти помічника/інструментів + - примусово застосовує тайм-аут -> перериває запуск, якщо його перевищено + - повертає корисні навантаження та метадані використання 4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`: - події інструментів => `stream: "tool"` - - assistant deltas => `stream: "assistant"` + - дельти помічника => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - - чекає на **lifecycle end/error** для `runId` + - очікує на **завершення/помилку життєвого циклу** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Черги + паралельність -- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) та, за потреби, через глобальну доріжку. -- Це запобігає конфліктам інструментів/сесій і підтримує узгодженість історії сесії. -- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. +- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) і, за потреби, також через глобальну доріжку. +- Це запобігає гонкам інструментів/сесій і підтримує узгодженість історії сесії. +- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. Див. [Черга команд](/uk/concepts/queue). +- Записи транскриптів також захищені блокуванням запису сесії у файлі сесії. Це блокування + враховує процеси та базується на файлі, тому воно виявляє авторів запису, які обходять внутрішньопроцесну чергу або надходять з + іншого процесу. +- Блокування запису сесії типово не є реентерабельними. Якщо допоміжний компонент навмисно вкладає отримання + того самого блокування, зберігаючи одного логічного автора запису, він має явно ввімкнути це через + `allowReentrant: true`. ## Підготовка сесії + робочого простору -- Робочий простір визначається та створюється; ізольовані запуски можуть перенаправлятися до кореня ізольованого робочого простору. -- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt. -- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt. -- Отримується блокування запису сесії; `SessionManager` відкривається та підготовлюється до потокової передачі. +- Робочий простір визначається та створюється; у sandboxed-запусках він може бути перенаправлений до кореня sandboxed-робочого простору. +- Skills завантажуються (або повторно використовуються зі знімка) і впроваджуються в env та prompt. +- Bootstrap/context-файли визначаються та впроваджуються у звіт системного prompt. +- Отримується блокування запису сесії; `SessionManager` відкривається та готується до потокової передачі. Будь-який + пізніший шлях переписування транскрипту, Compaction або обрізання має отримати те саме блокування перед відкриттям або + зміненням файла транскрипту. ## Збирання prompt + системний prompt -- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для конкретного запуску. -- Застосовуються обмеження, специфічні для моделі, і резервні токени для Compaction. -- Див. [Системний prompt](/uk/concepts/system-prompt), щоб побачити, що бачить модель. +- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для окремого запуску. +- Застосовуються обмеження, специфічні для моделі, та резервні токени для Compaction. +- Див. [Системний prompt](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель. ## Точки перехоплення (де можна втрутитися) OpenClaw має дві системи хуків: -- **Внутрішні хуки** (хуки Gateway): скрипти на основі подій для команд і подій життєвого циклу. -- **Plugin hooks**: точки розширення всередині циклу агента/інструментів і конвеєра gateway. +- **Внутрішні хуки** (хуки Gateway): скрипти, керовані подіями, для команд і подій життєвого циклу. +- **Хуки Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. ### Внутрішні хуки (хуки Gateway) -- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до того, як буде фіналізовано системний prompt. +- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до остаточного формування системного prompt. Використовуйте це, щоб додавати/видаляти bootstrap-файли контексту. -- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ про Hooks). +- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ Hooks). -Див. [Hooks](/uk/automation/hooks), щоб переглянути налаштування та приклади. +Див. [Hooks](/uk/automation/hooks), щоб знайти налаштування та приклади. -### Plugin hooks (життєвий цикл агента + gateway) +### Хуки Plugin (життєвий цикл агента + gateway) -Вони запускаються всередині циклу агента або конвеєра gateway: +Вони виконуються всередині циклу агента або конвеєра gateway: - **`before_model_resolve`**: запускається до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі. -- **`before_prompt_build`**: запускається після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` до надсилання prompt. Використовуйте `prependContext` для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt. -- **`before_agent_start`**: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу наведеним вище явним хукам. -- **`before_agent_reply`**: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю приглушити хід. +- **`before_prompt_build`**: запускається після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на поточний хід, а поля системного контексту — для стабільних настанов, які мають розташовуватися в просторі системного prompt. +- **`before_agent_start`**: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу явним хукам вище. +- **`before_agent_reply`**: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю заглушити хід. - **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення. -- **`before_compaction` / `after_compaction`**: дає змогу спостерігати або анотувати цикли Compaction. -- **`before_tool_call` / `after_tool_call`**: перехоплює параметри/результати інструментів. -- **`before_install`**: дає змогу перевірити результати вбудованого сканування й за потреби заблокувати встановлення Skill або Plugin. -- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані до транскрипту сесії. -- **`message_received` / `message_sending` / `message_sent`**: вхідні та вихідні хуки повідомлень. +- **`before_compaction` / `after_compaction`**: дають змогу спостерігати за циклами Compaction або додавати до них анотації. +- **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів. +- **`before_install`**: перевіряє результати вбудованого сканування і за потреби блокує встановлення skill або Plugin. +- **`tool_result_persist`**: синхронно перетворює результати інструментів перед їх записом до транскрипту сесії. +- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних і вихідних повідомлень. - **`session_start` / `session_end`**: межі життєвого циклу сесії. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила рішень хуків для вихідних даних/запобіжників інструментів: +Правила ухвалення рішень у хуках для вихідних повідомлень/захисту інструментів: -- `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування. -- `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування. -- `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує попереднє скасування. +- `before_tool_call`: `{ block: true }` є фінальним і зупиняє обробники з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_install`: `{ block: true }` є фінальним і зупиняє обробники з нижчим пріоритетом. +- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `message_sending`: `{ cancel: true }` є фінальним і зупиняє обробники з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. -Див. [Plugin hooks](/uk/plugins/architecture#provider-runtime-hooks), щоб переглянути API хуків і деталі реєстрації. +Див. [Хуки Plugin](/uk/plugins/architecture#provider-runtime-hooks), щоб знайти API хуків і подробиці реєстрації. ## Потокова передача + часткові відповіді -- Assistant deltas передаються в потоці з pi-agent-core і створюються як події `assistant`. -- Потокова передача блоків може створювати часткові відповіді або на `text_end`, або на `message_end`. -- Потокова передача міркувань може створюватися як окремий потік або як блокові відповіді. -- Див. [Потокова передача](/uk/concepts/streaming), щоб дізнатися про розбиття на частини та поведінку блокових відповідей. +- Дельти помічника передаються потоком з pi-agent-core і генеруються як події `assistant`. +- Потокова передача блоків може генерувати часткові відповіді або на `text_end`, або на `message_end`. +- Потокова передача міркувань може генеруватися як окремий потік або як відповіді блоками. +- Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про фрагментацію та поведінку блокових відповідей. ## Виконання інструментів + інструменти повідомлень -- Події початку/оновлення/завершення інструментів створюються в потоці `tool`. -- Результати інструментів очищуються з урахуванням обмежень розміру та корисних навантажень зображень перед логуванням/створенням подій. -- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дубльовані підтвердження assistant. +- Події початку/оновлення/завершення інструмента генеруються в потоці `tool`. +- Результати інструментів очищуються з урахуванням розміру та зображень перед логуванням/генерацією. +- Надсилання інструментами повідомлень відстежується, щоб уникнути дубльованих підтверджень від помічника. -## Формування відповіді + пригнічення +## Формування відповіді + придушення - Фінальні корисні навантаження збираються з: - - тексту assistant (та, за потреби, reasoning) + - тексту помічника (і, за потреби, міркувань) - вбудованих зведень інструментів (коли verbose увімкнено + дозволено) - - тексту помилки assistant, якщо модель повернула помилку -- Точний маркер безмовності `NO_REPLY` / `no_reply` відфільтровується з вихідних + - тексту помилки помічника, якщо модель завершується з помилкою +- Точний тихий токен `NO_REPLY` / `no_reply` відфільтровується з вихідних корисних навантажень. - Дублікати інструментів повідомлень видаляються з фінального списку корисних навантажень. -- Якщо не лишилося жодних придатних до відображення корисних навантажень і інструмент повернув помилку, створюється резервна відповідь про помилку інструмента - (якщо тільки інструмент повідомлень ще не надіслав видиму для користувача відповідь). +- Якщо не залишається придатних до рендерингу корисних навантажень і інструмент завершився помилкою, генерується + резервна відповідь про помилку інструмента + (якщо тільки інструмент повідомлень ще не надіслав видиму користувачеві відповідь). ## Compaction + повторні спроби -- Автоматичний Compaction створює події потоку `compaction` і може ініціювати повторну спробу. -- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дубльованого виводу. -- Див. [Compaction](/uk/concepts/compaction), щоб ознайомитися з конвеєром Compaction. +- Автоматичний Compaction генерує події потоку `compaction` і може спричинити повторну спробу. +- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дублювання вихідних даних. +- Див. [Compaction](/uk/concepts/compaction), щоб дізнатися про конвеєр Compaction. ## Потоки подій (зараз) -- `lifecycle`: створюється `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) -- `assistant`: потокові deltas з pi-agent-core -- `tool`: потокові події інструментів із pi-agent-core +- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) +- `assistant`: потокові дельти з pi-agent-core +- `tool`: потокові події інструментів з pi-agent-core -## Обробка чат-каналу +## Обробка chat-каналу -- Assistant deltas буферизуються в чат-повідомлення `delta`. -- Чат `final` створюється на **lifecycle end/error**. +- Дельти помічника буферизуються в повідомлення chat `delta`. +- Chat `final` генерується під час **завершення/помилки життєвого циклу**. ## Тайм-аути -- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` його перевизначає. -- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. -- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо жодні фрагменти відповіді не надходять до завершення вікна бездіяльності. Установіть його явно для повільних локальних моделей або provider-ів reasoning/tool-call; установіть 0, щоб вимкнути. Якщо його не задано, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, інакше 120 с. Запуски, ініційовані Cron, без явного тайм-ауту LLM або агента вимикають watchdog бездіяльності й покладаються на зовнішній тайм-аут Cron. +- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає його. +- Runtime агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. +- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо до завершення вікна бездіяльності не надходять жодні фрагменти відповіді. Установіть його явно для повільних локальних моделей або provider-ів міркувань/виклику інструментів; установіть 0, щоб вимкнути. Якщо його не встановлено, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, інакше — 120 с. Для запусків, ініційованих Cron, без явного тайм-ауту LLM або агента watchdog бездіяльності вимикається, а керування передається зовнішньому тайм-ауту Cron. -## Де все може завершитися завчасно +## Де все може завершитися раніше - Тайм-аут агента (переривання) - AbortSignal (скасування) -- Від’єднання Gateway або тайм-аут RPC +- Відключення Gateway або тайм-аут RPC - Тайм-аут `agent.wait` (лише очікування, не зупиняє агента) -## Пов’язані теми +## Пов’язане - [Інструменти](/uk/tools) — доступні інструменти агента -- [Hooks](/uk/automation/hooks) — скрипти на основі подій, що спрацьовують на подіях життєвого циклу агента -- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови -- [Погодження Exec](/uk/tools/exec-approvals) — бар’єри погодження для shell-команд -- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning +- [Hooks](/uk/automation/hooks) — скрипти, керовані подіями, які запускаються подіями життєвого циклу агента +- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови +- [Підтвердження Exec](/uk/tools/exec-approvals) — бар’єри підтвердження для команд оболонки +- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/міркувань