Context engineering для AI-агентів: практичний дизайн контексту

Context engineering — це керування повним набором інформації, який модель бачить на конкретному кроці: system і developer instructions, user request, доступні tools та їх schemas, retrieved records, message history, tool results, приклади, state і формат відповіді. Prompt engineering залишається частиною цієї роботи, але не володіє всім lifecycle. Для агента в циклі контекст змінюється після кожного observation, тому його потрібно збирати, перевіряти, скорочувати й версіонувати під кожен model call.

Практична ціль — не використати максимум context window, а подати найменший достатній набір високосигнальних токенів для поточного рішення. Велике вікно не усуває суперечливі інструкції, stale facts, надмірний tool catalog або втрату важливої умови під час summarization. Хороший context builder має пояснювані джерела, порядок пріоритетів, token budget, security boundary та eval, який доводить користь кожного класу контексту.

Розділіть context assembly на шари. Policy layer містить незмінні межі поведінки й authority. Task layer описує ціль, acceptance criteria та terminal output. Capability layer публікує лише релевантні tools і schemas. Knowledge layer дістає факти з authoritative sources. Interaction layer зберігає потрібні turns. Working-state layer тримає план, виконані кроки, open questions і evidence references. Output layer задає schema, citations та postconditions. Один монолітний prompt приховує походження і ускладнює rollback; typed layers дозволяють тестувати й замінювати їх окремо.

Власником policy і permissions є застосунок, а не модель. Retrieval service володіє selection та freshness metadata, tool registry — capability contracts, workflow runtime — durable state, conversation store — retention і deletion, model adapter — фінальним serialization. Context builder оркеструє ці inputs, але не має самостійно розширювати scopes, переписувати authoritative state або перетворювати неперевірений document text на instruction.

• Policy: що агенту дозволено, заборонено й коли потрібне approval.
• Task: мета, constraints, definition of done і stop conditions.
• Capabilities: мінімальний набір distinct tools для поточного етапу.
• Knowledge: релевантні факти з provenance, freshness і access checks.
• Working state: progress, decisions, unresolved risks та evidence pointers.
• Output: typed result, citations, uncertainty і verification contract.

Preload виправданий для коротких стабільних правил, task contract, невеликого набору часто потрібних facts і capability hints. Just-in-time retrieval кращий для великих codebases, каталогів, policy libraries, змінних customer records та рідкісних tools: агент спершу отримує identifiers, indexes або search primitives, а деталі дістає після уточнення intent. Hybrid pattern залишає незмінний skeleton у початковому контексті й дозволяє контрольоване дослідження під час run.

Не плутайте retrieval із authorization. Document, який semantic search вважає релевантним, може бути недоступним конкретному actor або містити prompt injection. Filter за tenant, resource ACL і data classification має діяти до передачі тексту моделі; citations посилаються на стабільний record і version. Tool result отримує trust label, timestamp і bounded size. Якщо результат надто великий, збережіть повний artifact поза контекстом, а моделі дайте перевірене summary та reference для точкового читання.

Кожна tool name, description, argument schema та output займає attention budget. Каталог із десятками майже однакових actions збільшує ambiguity навіть тоді, коли всі schemas валідні. Публікуйте stage-specific allowlist: на discovery етапі — read/search tools, після вибору resource — вузькі analysis tools, перед consequential action — один approval-gated command. Names і descriptions повинні розрізняти intent, preconditions та terminal effect, а не лише повторювати назву API endpoint.

Tool output проєктуйте як контекст для наступного рішення: status, verified fields, evidence reference, recoverable error taxonomy і next allowed actions. Не повертайте необмежені logs, HTML або весь database object. Side effect потребує idempotency key, повторної authorization перевірки й authoritative postcondition незалежно від якості контексту. Модель може обрати tool, але tool runtime остаточно вирішує, чи має actor право виконати конкретну операцію.

Message history — журнал взаємодії; memory — відібрані довготривалі факти або preferences; workflow state — authoritative progress процесу; context window — тимчасовий input одного inference. Не зберігайте business state лише в chat transcript і не переносіть увесь transcript у кожен turn. Context builder читає потрібний state з system of record, додає останні meaningful turns та дістає memory лише за scope, relevance, freshness і consent.

Запис у пам’ять має бути окремою policy-controlled операцією. Зберігайте source, subject, confidence або verification status, expiry і deletion binding; припущення моделі не стає фактом через повторення. Для персональних preferences дайте користувачу перегляд і видалення. Для security decisions memory може бути hint, але актуальні permissions завжди читаються з authoritative identity system.

Довгий run потребує compaction до того, як історія витіснить task, decisions і unresolved constraints. Безпечна checkpoint summary зберігає goal, completed work, verified evidence, rejected approaches, open risks, pending approvals, state references і точний next step; сирі повторні tool outputs та проміжна балаканина видаляються. Summary є похідним artifact із власними version, source range і quality check, а не новим authoritative record.

Тестуйте compaction через continuation eval: дайте агенту однаковий checkpoint у повному й стисненому контексті та порівняйте terminal outcome, constraint retention, citation correctness і repeated-action rate. Інжектуйте рідкісну, але критичну умову на початку trace; перевірте, що вона переживає кілька compaction cycles. Якщо provider повертає opaque compacted item, не парсьте його внутрішню структуру й окремо зберігайте application-owned durable state, audit evidence та approvals.

Створіть corpus із реальних task slices: достатній context, missing fact, stale fact, conflicting instruction, irrelevant document, malicious tool result, oversized history і permission change. Порівнюйте baseline із кожною context policy за verified task success, correct-tool selection, groundedness, constraint retention, prohibited-action rate, unnecessary retrieval, latency та cost per accepted outcome. Token count є diagnostic, а не самостійним KPI: коротший контекст поганий, якщо він втрачає необхідний факт, і довший поганий, якщо додає noise без outcome gain.

Використовуйте ablation: приберіть один layer або source class і подивіться, які slices деградують. Це відділяє корисний контекст від cargo cult. Логуйте context manifest — версії prompts, список tool contracts, record IDs, retrieval query, filters, compaction version і token allocation — але не сирі secrets чи персональні дані. Trace повинен дозволити відтворити selection decision у дозволеному test environment.

Почніть з одного bounded workflow і зафіксуйте context contract: required inputs, optional sources, trust levels, budget per layer, freshness, redaction, failure fallback і owner. Реалізуйте deterministic assembler, який повертає model input та machine-readable manifest. Запустіть offline replay, потім shadow assembly без впливу на відповіді, read-only canary і лише після eval — bounded actions. Context policy версіонуйте разом із prompt, tools, retriever і model configuration.

Rollback повертає попередню версію assembler і tool allowlist, але не відміняє вже виконані side effects: їх звіряє reconciliation process. Fail closed для permission або provenance lookup; fail bounded для optional memory чи enrichment, позначаючи відсутній layer у manifest. Не робіть висновок про універсально найкращий token budget або retrieval strategy з vendor прикладу — thresholds визначаються власними tasks, risk tiers і production evidence.

• Описати task outcome, authority та required evidence.
• Розкласти context на typed layers із власниками й trust labels.
• Побудувати minimal baseline та corpus із failure slices.
• Додавати retrieval, memory і compaction лише після виміряного gain.
• Версіонувати manifest, rollout gate, reconciliation і rollback.

Коли якість агента змінюється, команда часто звинувачує model snapshot, хоча фактичний runtime input уже інший. Побудуйте context manifest для кожного model call: policy revision, task contract, exposed tool schemas, retrieved record IDs і revisions, memory items, history range, compaction revision, token allocation та redaction verdict. Порівняння двох runs починається з manifest diff. Новий документ, зниклий tool, ширший ACL filter або інша summary можуть пояснити regression без будь-якої зміни моделі.

Diff має бути семантичним, а не лише текстовим. Для instructions показуйте зміну rule ID і пріоритету; для retrieval — додані й вилучені evidence records, freshness та permission outcome; для tools — schema й authority class; для memory — source, subject, expiry та verification state. Сирий confidential context не потрібно копіювати в audit: зберігайте stable references, hashes і дозволений diagnostic excerpt. Якщо snapshot джерела неможливо відтворити, verdict позначається historical або partially reproducible, а не точним replay.

Перед rollout нової context policy запустіть paired replay на тому самому task corpus: baseline assembler і candidate assembler працюють з однаковим model configuration настільки, наскільки це контролюється. Reviewer бачить outcome і evidence, а не назву варіанта. Promotion вимагає відсутності critical authority failures і покращення визначених slices; менша кількість токенів сама по собі не є перемогою. Це відділяє оптимізацію attention budget від прихованого скорочення потрібних доказів.

• Manifest identity → run, step, assembler version, model surface і timestamp.
• Policy diff → rule ID, priority, scope та approval boundary.
• Evidence diff → record revision, freshness, ACL verdict і selection reason.
• Capability diff → tool schema, authority class і runtime enforcement.
• Outcome diff → task verdict, citations, prohibited actions, latency і accepted cost.

Context incident класифікуйте за точкою походження: неправильна policy, missing task constraint, stale retrieval, permission leak, poisoned document, memory contamination, tool-output overflow або lossy compaction. Не виправляйте кожен випадок додаванням ще одного речення до system prompt. Спочатку заморозьте redacted manifest і outcome evidence, визначте owning layer, обмежте affected workflow та перевірте, чи були зовнішні side effects. Для authority або privacy finding rollout зупиняється fail-closed; для optional enrichment система може перейти на bounded fallback із явною позначкою відсутнього контексту.

Після root-cause review створіть мінімальний regression fixture: task, дозволений source pack, malicious або stale variant, expected context selection і terminal acceptance criteria. Test має падати на старій policy та проходити на candidate fix без розширення permissions. Додайте сусідні negative cases, щоб локальне виправлення не почало відкидати корисні документи чи приховувати tools для інших стадій. Потім replay critical corpus, canary на read-only workflow і лише після evidence gate відновлюйте action authority.

Rollback повертає попередній assembler, retriever filter, tool allowlist або compaction policy, але incident лишається відкритим, доки authoritative systems не звірені. У журналі відокремлюйте observed fact, inference і remediation verdict. Такий цикл перетворює контекст із невидимого prompt payload на керований production contract: кожен збій залишає test, owner, evidence і review trigger замість накопичення непояснених prompt patches.

• Contain → звузити workflow, прибрати action authority, зберегти redacted evidence.
• Classify → знайти owning context layer і trust-boundary failure.
• Regress → відтворити збій мінімальним fixture та сусідніми negative cases.
• Verify → paired replay, read-only canary і reconciliation side effects.
• Learn → versioned policy, named owner, expiry і повторний review trigger.