У новому повному курсі на каналі Tech With Tim автор покроково розбирає, як будувати AI‑агентів у Python на базі фреймворка Agentspan — від першого локального запуску до сценаріїв близьких до реального продакшну. Окрема частина курсу присвячена саме розгортанню: як вийти за межі локального сервера, підʼєднати Postgres, запустити Agentspan через Docker Compose і безпечно підключати Python‑воркери до віддаленого оркестратора.
Цей матеріал концентрується саме на цій фінальній частині — переході від «запустив на ноуті» до інфраструктури, яку можна ставити в продакшн.
Локальний сервер Agentspan: SQLite і швидкий старт
Для розробки Agentspan пропонує максимально просту модель запуску. Достатньо встановити Python‑пакет та сервер, експортувати ключ LLM‑провайдера, запустити команду agentspan server start (у прикладі — через uv run), і веб‑дашборд стає доступним на http://localhost:6767/api.
У такому режимі вся інформація про виконання агентів — стейт, історія кроків, результати викликів інструментів — зберігається в локальній SQLite‑базі:
«If you just want to use local development like we were doing, right, you just run the AgentSpan server and that’s it… it will just store in a local SQLite database.»
Для перших прототипів цього більш ніж достатньо. Розробник може:
- запускати воркер‑код локально;
- дивитися історію виконань у веб‑інтерфейсі;
- користуватися всіма можливостями платформи — черги, ретраї, human‑in‑the‑loop, multi‑agent, guardrails тощо.
Однак така конфігурація очевидно не розрахована на продакшн‑навантаження й масштабування.
Чому для продакшну потрібні Postgres і Docker Compose
Коли постає питання реального деплойменту, архітектурні вимоги змінюються. Потрібне стійкіше сховище стану, передбачуваний спосіб запуску серверу, можливість масштабувати його в межах інфраструктури.
У курсі це формулюється прямо:
«However, if you want to go to a deployed environment, you probably want to use Postgres SQL and some kind of Docker Compose to be running this for you.»
SQLite на одному хості зручна для локального деву, але:
- погано підходить під високий паралелізм;
- важко вбудовується в стандартні продакшн‑патерни бекенд‑сховищ;
- не масштабується горизонтально.
Postgres натомість дає стандартну, керовану й добре відому точку зберігання стану, яку можна розмістити на окремому сервері чи кластері. Docker Compose забезпечує відтворюваний запуск самого Agentspan‑сервера, який можна легко обгорнути в CI/CD.
GitHub‑репозиторій Agentspan і директорія deployment/docker‑compose
Для виходу за межі локального запуску пропонується не вигадувати власні YAML‑файли з нуля, а скористатися готовими артефактами з офіційного репозиторію:
«In order to do that, you can just pull the GitHub repo that AgentSpan has… you can go into the deployment and then docker‑compose directory.»
У структуру репозиторію входить директорія deployment/docker-compose, де зібрано все необхідне для старту сервера в контейнерному середовищі. Звідси й починається шлях до продакшн‑конфігурації.
Сам репозиторій, за словами автора, містить:
- готовий Docker Compose‑файл для Agentspan‑сервера;
- приклад конфігурації змінних середовища;
- інструкції, як запускати сервер із зовнішньою Postgres‑базою.
Це дозволяє перевести розгортання в режим «склонувати і адаптувати», замість писати весь стек із нуля.
Налаштування .env.sample: Postgres, API‑ключі й інші секрети
Ключовою частиною цієї docker‑композиції є .env.sample. Саме тут зосереджена конфігурація сервера — від доступу до бази до провайдерських ключів для LLM і додаткових сервісів.
«From docker‑compose you can just adjust the variables here inside of the .env.sample… you can put any environment variables or like API keys that you want to have. You can put the Postgres database that you want to connect to.»
Файл .env.sample виступає шаблоном:
- його копіюють у
.env; - заповнюють власними значеннями;
- Docker Compose підхоплює ці змінні при старті.
У цьому файлі задаються, зокрема:
- URL для підключення до Postgres, який сервер використовуватиме замість локальної SQLite;
- ключі для LLM‑постачальників;
- будь‑які додаткові API‑ключі, що має знати оркестратор (наприклад, для веб‑інструментів чи вбудованих сервісів).
Цей підхід узгоджується з тим, як Agentspan працює з credentials загалом: частина секретів може зберігатися безпосередньо на сервері й підтягуватися воркерами лише під час виклику конкретного інструмента.
Виносимо оркестратор: як Python‑воркери підʼєднуються до віддаленого сервера
Після налаштування Docker Compose і Postgres наступний крок — повʼязати з цим сервером воркер‑код, який запускається вже не обовʼязково на тому ж хості. Логіка при цьому залишається в Python‑процесах, а Agentspan‑сервер бере на себе стейт, черги, human‑in‑the‑loop та інше.
Схема підключення гранично проста:
«As soon as this server is deployed, all you need to do is just point your workers to this server… all you have to do is just say, “Hey, here’s the URL where this is running.”»
У практичному коді це виглядає як налаштування змінної AGENTSPAN_SERVER_URL (у курсі це робиться через .env):
- для локальної розробки значенням є
http://localhost:6767/api; - для продакшну — вже зовнішній URL або внутрішнє імʼя сервісу в кластері.
Python‑воркер, який створює та запускає агентів, просто читає цю змінну. Решту — зʼєднання, реєстрація виконань, збереження стану, відновлення після крашу — бере на себе сервер.
Ключовий момент: воркери можуть жити на окремих машинах, масштабуватись незалежно від оркестратора, а сервер стає єдиною точкою координування та спостереження за всіма агентами.
Базова безпека: OAuth‑ключі між воркером і сервером
У публічній або навіть внутрішній інфраструктурі недостатньо просто відкрити HTTP‑ендпойнт Agentspan‑сервера й довіритися тому, що ним ніхто сторонній не скористається. Фреймворк дозволяє ввести базовий рівень автентифікації за допомогою OAuth‑секретів.
«You can also set an OAuth key, you can set an OAuth secret, and then you can also just configure those directly from code… so now if someone wants to connect to it, they do need to pass those values from their worker.»
Ідеться про два параметри:
- OAuth key;
- OAuth secret.
Вони налаштовуються на стороні сервера (у тій же Docker/.env‑конфігурації чи через параметри запуску), а у воркер‑коді додаються до конфігурації підключення. У результаті:
- будь‑який Python‑воркер, який намагається спілкуватися з оркестратором, має передати коректні значення;
- без них запити відхиляються, що захищає сервер від випадкових або шкідливих підключень.
Такий механізм особливо важливий, коли сервер Agentspan розгорнутий у мережевому сегменті, доступному кільком командам чи сервісам, або має публічний вхідний URL.
Самохостинг та масштабування: «просто розгорнути сервер і вказати на нього воркери»
Вся ця модель розгортання задумана як самохостинг — із власним сервером, власною базою й керуванням усією інфраструктурою з боку команди, що розробляє агентів.
Фінальне резюме звучить так:
«You also can obviously self‑host this as it says right here… it’s just a matter of essentially deploying the server and then once the server is deployed pointing your workers towards it and then adding that basic OAuth… so that not anyone can connect to the worker.»
Ланцюжок дій у підсумку виглядає лінійно:
- Розгорнути Agentspan‑сервер (за допомогою Docker Compose з репозиторію).
- Підʼєднати його до Postgres через змінні середовища.
- Налаштувати OAuth‑ключ і secret.
- У воркер‑коді:
- вказати
AGENTSPAN_SERVER_URLна новий сервер; - передавати OAuth‑дані при підключенні.
Після цього всі фічі, які в курсі демонструвалися локально — durable execution з можливістю підʼєднатися до наявного execution_id, human‑in‑the‑loop, багатокрокові пайплайни, логування кроків агентів, — починають працювати поверх уже продакшн‑орієнтованого середовища з Postgres та контейнеризованим сервером.
Висновок
Agentspan у курсі подається не як ще один «дев‑тул для красивих демо», а як оркестратор, який із самого початку орієнтований на продакшн. Локальний запуск з SQLite зручний, щоб швидко зібрати агента й побачити всі його кроки в дашборді. Але перехід до реального деплойменту будується за прозорою схемою: Postgres як бекенд‑сховище, Docker Compose як спосіб запуску сервера, OAuth як мінімум для контролю доступу, віддалені воркери, які просто «вказують» на новий URL.
Це дозволяє командам зберегти знайому Python‑розробку агентів, але винести стейт і оркестрацію в окремий, керований шар, який можна масштабувати, моніторити й відновлювати після збоїв.
Джерело
Build 3 PRODUCTION AI Agents in Python – Full Course (Agentspan)