Патерн Code Execution Agent: безпечне виконання коду

Як агент запускає код у sandbox, щоб надійно рахувати, перевіряти гіпотези й автоматизувати задачі з guardrails для production.

На цій сторінці

Суть патерна
Проблема
Рішення
Як працює
У коді це виглядає так
Як це виглядає під час виконання
Коли підходить — і коли ні
Підходить
Не підходить
Чим відрізняється від Guarded-Policy
Коли використовувати Code-Execution (vs інші патерни)
Як комбінувати з іншими патернами
Коротко
Переваги та Недоліки
FAQ
Що далі

Суть патерна

Code-Execution Agent - це патерн, у якому агент не лише міркує текстом, а й запускає згенерований код у контрольованому середовищі, отримує фактичний результат і працює з ним далі.

Коли потрібен: коли відповідь треба обчислити або перевірити запуском коду, а не просто згенерувати текстом.

Агент:

Generate: генерує короткий код під задачу
Run: виконує його в sandbox
Observe: отримує реальний результат
Explain: повертає результат із поясненням

Патерн Code-Execution Agent: безпечний запуск коду

Проблема

Уяви, що ти просиш:

"Порахуй середню конверсію з цього CSV."

Агент пише скрипт і каже: "Середня конверсія - 3.84%".

Але без контрольованого середовища ти не бачиш:

що саме виконувалось
які файли читались
чи були спроби мережевих викликів
скільки ресурсів спожив код

У виконанні коду важлива не лише логіка коду, а й межі середовища, в якому цей код запускається.

У цьому й проблема: результат залежить одночасно від коду і середовища виконання, тому "просто запустити" небезпечно й непрозоро.

Рішення

Code-Execution Agent запускає код тільки через контрольований шар виконання.

Аналогія: це як лабораторія з технікою безпеки. Експеримент можна робити лише в ізольованій кімнаті й за правилами. Це зменшує ризик пошкодити середовище або витягнути зайві дані.

Ключовий принцип: Модель може написати код, але запуск дозволений лише в sandbox і після перевірки політики.

Базові обмеження:

sandbox runtime
обмежений доступ до файлів
без мережі
ліміти CPU/RAM/часу

Керований цикл:

Планування: визначити мінімальний скрипт для задачі
Генерація: згенерувати код
Перевірка політики: перевірити безпеку й дозволені операції
Запуск в ізоляції: виконати код у sandbox
Перевірка результату: перевірити коректність і ризики результату

Якщо перевірка політики або результату не пройдена, виконання зупиняється або ескалується.

Це захищає від ситуацій, коли агент може:

читати чутливі файли
відправляти дані назовні
зависати на довгих циклах
виконувати небезпечні операції

Надійне виконання коду - це не "просто запуск", а запуск, який runtime-policy технічно не дає обійти.

Як працює

Diagram

Ключовий елемент - sandbox.

Зазвичай він обмежує:

файлову систему: доступ лише до робочої директорії
мережу: часто повністю вимкнена
ресурси: CPU/RAM/time quotas
середовище виконання: дозволені бібліотеки та системні виклики

Опис повного флоу: Plan → Generate Code → Policy Check → Execution Layer → Sandbox Run → Validate → Return

Планування
Агент визначає, що саме треба обчислити і який формат результату очікується.

Генерація коду
Модель генерує мінімальний код під конкретний крок, без зайвого обсягу.

Перевірка політики
Згенерований код проходить policy-engine: дозволені бібліотеки, тип обчислень і допустимий рівень ресурсоємності.

Шар виконання
Система готує контрольоване виконання: середовище, ліміти та правила доступу.

Запуск у sandbox
Код виконується в ізоляції з жорсткими лімітами.

Валідація
Система перевіряє формат результату, помилки, політики безпеки і відповідність очікуваній схемі.

Повернення результату
Користувач отримує валідну відповідь або контрольовану зупинку/ескалацію.

У коді це виглядає так

PYTHON

code = agent.generate_code(goal, constraints={
    "language": "python",
    "no_network": True,
    "max_seconds": 5,
})

exec_result = execution_layer.run_code(
    code=code,
    policy="sandboxed_python",
)

if not exec_result.success:
    return fallback_or_stop(exec_result.error)

validated = validate_output(exec_result.stdout, schema=expected_schema)
if not validated.ok:
    return stop_with_reason(validated.reason)

return format_answer(validated.data)

Головне правило: ніколи не виконувати згенерований код поза sandbox та policy-контролем.

Як це виглядає під час виконання

TEXT

Goal: порахувати конверсію по CSV-звіту

Generate Code:
- читання sales.csv
- обчислення conversion_rate = paid / leads
- вивід таблиці по днях

Sandbox Run:
- timeout: 5s
- memory: 256MB
- network: disabled

Output:
- таблиця з 7 рядків
- середня конверсія: 3.84%

Повний приклад Code-Execution агента

PYPython

TSTypeScript · скоро

Коли підходить — і коли ні

Підходить

	Ситуація	Чому Code-Execution підходить
✅	Потрібні реальні обчислення, а не текстові припущення	Виконання коду дає фактичний результат замість здогадок моделі.
✅	Робота з таблицями, файлами, формулами	Тут потрібен фактичний запуск кроків, а не лише текстовий опис.
✅	Важлива відтворюваність результату	Запуск у контрольованому середовищі виконання робить перевірку результатів простішою.
✅	Є sandbox + примусове застосування політик	Безпечна інфраструктура дозволяє виконувати код без критичних ризиків.

Не підходить

	Ситуація	Чому Code-Execution не підходить
❌	Суто текстова задача	Запуск коду додає зайву складність без користі.
❌	Немає ізольованого середовища виконання	Без sandbox неможливо безпечно виконувати згенерований код.
❌	Ризик вищий за користь	Потенційна шкода не виправдовує підхід виконання у цьому кейсі.

Бо виконання коду додає операційні вимоги: sandbox, ліміти ресурсів, моніторинг і аудит запусків.

Чим відрізняється від Guarded-Policy

	Guarded-Policy	Code-Execution
Головний фокус	Що дозволено виконувати	Як безпечно виконати згенерований код
Ключовий механізм	Policy gate	Sandbox runtime + output validation
Коли спрацьовує	Перед дією	Під час і після запуску коду
Ризик без патерна	Небезпечна дія потрапить у виконання	Ненадійні або небезпечні результати виконання

Guarded-Policy вирішує, чи взагалі можна діяти. Code-Execution вирішує, як безпечно і відтворювано виконати кодову дію.

Коли використовувати Code-Execution (vs інші патерни)

Використовуйте Code-Execution, коли агент має запускати код, перевіряти результати і безпечно ітерувати.

Короткий тест:

якщо потрібно "виконати код і працювати з фактичним output" -> Code-Execution
якщо потрібно "спершу лише розбити велику задачу на підзадачі" -> Task Decomposition Agent

Порівняння з іншими патернами та приклади

Швидка шпаргалка:

Якщо задача виглядає так...	Використовуйте
Після кожного кроку треба вирішити, що робити далі	ReAct Agent
Спочатку треба розбити велику ціль на менші виконувані задачі	Task Decomposition Agent
Потрібно запускати код, перевіряти результати і безпечно ітерувати	Code Execution Agent
Потрібно досліджувати дані та повертати висновки на основі аналізу	Data Analysis Agent
Потрібне дослідження з кількох джерел зі структурованими доказами	Research Agent

Приклади:

ReAct: "Знайди причину падіння API: перевір логи -> подивись помилки -> запусти наступну перевірку за результатом".

Task Decomposition: "Підготуй запуск нового тарифу: розбий задачу на підзадачі для контенту, техніки, QA і підтримки".

Code Execution: "Порахуй retention за 12 місяців у Python і перевір коректність формул на реальних даних".

Data Analysis: "Проаналізуй CSV із продажами: знайди тренди, аномалії та дай короткі висновки".

Research: "Збери дані про 5 конкурентів із кількох джерел і зроби порівняльне резюме".

Не впевнені, чи тут справді потрібен запуск коду? Спроєктувати Агента →

Як комбінувати з іншими патернами

Code-Execution + Guarded-Policy: перед запуском агент перевіряє код за правилами безпеки і блокує небезпечні дії.
Code-Execution + Fallback-Recovery: якщо виконання зависло або впало з помилкою, агент переходить на безпечний резервний сценарій.
Code-Execution + Supervisor: ризикові запуски агент не виконує сам, а передає на погодження людині.

Коротко

Code-Execution Agent:

Генерує код під конкретну задачу
Виконує його в ізольованому sandbox
Валідовує результат перед відповіддю
Підвищує точність у задачах з обчисленнями

Переваги та Недоліки

Переваги

дає точніші результати в обчисленнях

результат легко перевірити й повторити

видно, який код і що саме запускалось

зручно працювати з файлами та даними

Недоліки

потрібне ізольоване середовище

через запуск коду відповідь може бути повільнішою

можливі помилки під час виконання коду

FAQ

Q: Чи можна виконувати код просто на сервері без ізольованого середовища?
A: Для продакшну: ні. Потрібна ізоляція, ліміти ресурсів і контроль дозволених операцій.

Q: Чи гарантує виконання коду правильність результату?
A: Не повністю. Потрібні валідація результату, тести на інваріанти і перевірка політик.

Q: Що робити, якщо код падає під час виконання?
A: Застосовувати обмежене відновлення: retry, резервне середовище виконання або контрольовану зупинку зі stop reason.

Що далі

Code-Execution підхід дозволяє агенту надійно виконувати обчислення.

А як застосувати це для повноцінної аналітики: очистки даних, агрегатів, графіків і висновків?

Патерн Data Analysis Agent: надійна аналітика даних

Повернутися

Патерн Guarded-Policy Agent: безпечні дії за політиками

Патерн Data Analysis Agent: надійна аналітика даних

⏱️ 10 хв читання • Оновлено 6 березня 2026 р.Складність: ★★★

Практичне продовження

Приклади реалізації патерна

Перейди до реалізації на готових прикладах.

Python

Code-Execution Agent на Python: повний приклад

Відкрити приклад

Використовується в патернах

Пов’язані відмови

Потрібні контролі

Реалізувати в OnceOnly

Pattern-specific prompts stay in your codebase. OnceOnly handles policy enforcement, dedupe, and audit.

Використати в OnceOnly

from onceonly import OnceOnly

client = OnceOnly(api_key="once_live_...")

client.gov.policy_from_template(
    agent_id="billing-agent",
    template="moderate",
    overrides={
        "allowed_tools": ["stripe.charge", "send_email"],
        "max_spend_usd_per_day": 75.0,
    },
)

result = client.ai.run_tool(
    agent_id="billing-agent",
    tool="stripe.charge",
    args={"amount": 9999, "currency": "usd", "order_id": "ord_123"},
    run_id="run_billing_ord_123",
    spend_usd=0.25,
)
if not result.allowed:
    raise RuntimeError(result.policy_reason)

Integrated: pattern runtime boundaryOnceOnly

Ship agent patterns without rebuilding control-plane primitives

Keep pattern logic in your app, and use OnceOnly for policy, dedupe, and incident controls:

Execute side-effect tools through `client.ai.run_tool(...)`.
Attach budgets and allowlists with `client.gov.upsert_policy(...)`.
Propagate `run_id` across steps for end-to-end traceability.
Branch on `allowed / decision / policy_reason` safely.
Avoid duplicate writes when retries happen across workers.

Спробувати OnceOnly Документація та приклади

Practical shortcut: you can keep your current pattern architecture and add this boundary instead of building governance infra from scratch.

Pattern Integration (Python SDK)

from onceonly import OnceOnly

client = OnceOnly(api_key="once_live_...")

client.gov.upsert_policy({
    "agent_id": "support-agent",
    "max_actions_per_hour": 400,
    "allowed_tools": ["kb.search", "ticket.reply"],
    "blocked_tools": ["user.delete"],
})

step = client.ai.run_tool(
    agent_id="support-agent",
    tool="kb.search",
    args={"query": "refund policy"},
    run_id="run_support_042",
    spend_usd=0.02,
)
if not step.allowed:
    raise RuntimeError(step.policy_reason)

Автор

Микола — інженер, який будує інфраструктуру для продакшн AI-агентів.

Фокус: патерни агентів, режими відмов, контроль рантайму та надійність систем.

🔗 GitHub: https://github.com/mykolademyanov

Редакційна примітка

Ця документація підготовлена з допомогою AI, із людською редакторською відповідальністю за точність, ясність і продакшн-релевантність.

Приклади є навчальними й можуть використовувати імітовані інструменти та дані. Перед використанням у production перевірте надійність, безпеку й відновлення у власному середовищі.