Платформа Tech With Tim у новому форматі: замість короткої демки — повноцінний курс із побудови продакшн‑готових AI‑агентів на Python. Перший приклад у цій системі — базовий, але показовий: простий розмовний агент із памʼяттю, підключеним LLM та власними інструментами, який працює через сервер Agentspan і повністю проглядається у веб‑дашборді.
Від «hello world» до живого асистента
Початкова ціль — зробити «простого розмовного агента, що має доступ до розмовної памʼяті». Тобто чат‑асистента, з яким можна спілкуватися у терміналі, а всі його кроки при цьому видно в інтерфейсі Agentspan.
Архітектура виглядає так: на локальній машині працює Python‑воркер, що містить логіку агента, а окремо запускається Agentspan Server. Сервер відповідає за стан виконання, історію, черги задач, ретраї й те, що тут особливо важливо, — observability: повний лог кожного запиту, відповіді та виклику інструментів у веб‑UI.
У Python‑коді все починається з ініціалізації середовища та базового агента. Через .env задається AGENTSPAN_SERVER_URL — URL локального сервера на http://localhost:6767/api. Потім за допомогою load_dotenv() Agentspan автоматично дізнається, куди стукатись.
Далі створюється агент:
assistant = Agent(
name="personal assistant",
model="openai/gpt-4.5-mini" # в курсі використовувалась GPT‑5.4, але синтаксис той самий
instructions="""
You are a concise personal assistant.
Use tools when they help and remember useful user details across turns.
""",
tools=[],
memory=None, # памʼять додадуть пізніше
)
Головна «оболонка» для спілкування — нескінченний while‑loop з введенням тексту, у якому виконуються запити до агента через run() у контексті AgentRuntime. Так формується мінімальний, але вже цілком продакшн‑орієнтований скрипт: є підключення до серверу, модель, цикл діалогу і можливість дивитися все це в дашборді.
«Усе, що ми фактично зробили, — імпортували кілька потрібних речей, налаштували ENV для звʼязку з сервером, створили асистента — це супер базовий асистент — і запустили while‑loop, щоб спілкуватися з ним», — так характеризується перша версія.
Чому без памʼяті агент «забуває» все, що ви сказали
Після першого запуску цей асистент працює як типовий LLM‑чат без контексту між сесіями. Можна сказати: «Мене звати Тім», отримати ввічливе «Приємно познайомитися, Тім», але наступне питання «Як мене звати?» поверне чесне «Я не знаю вашого імені».
Причина проста: «За замовчуванням, якщо ви не додаєте памʼять, я можу сказати: “Гей, моє імʼя Тім.” … А потім наступного разу, коли я щось запитаю, він це повністю забуде, бо не зберігає попередні відповіді».
У цій моделі памʼять не «вбудована» автоматично, її потрібно явно створити й підʼєднати. Для цього використовується ConversationMemory з модуля agentspan.agents. Після додавання змінної:
conversation_memory = ConversationMemory(max_messages=50)
агент отримує параметр memory=conversation_memory. Це обмежує контекст 50 останніми повідомленнями — після цього старі записи просто вирізаються, щоб не роздувати prompt.
Спочатку розробник забуває ще один крок: додати реальні повідомлення до памʼяті. Через це агент, навіть із підключеною ConversationMemory, не може згадати імʼя користувача. Проблему вирішує явне додавання в кожному циклі:
readable_result = result.output.get("result")
conversation_memory.add_user_message(prompt)
conversation_memory.add_assistant_message(readable_result)
Після цього сценарій «Мене звати Тім» → «Як мене звати?» нарешті працює: агент дістає імʼя з памʼяті й відповідає коректно. Підкреслюється, що це класична помилка інтеграції: памʼять створено й передано в агент, але історія діалогів туди не записується, тож у моделі немає, що читати.
Інструменти: від голого тексту до дій у реальному світі
Базовий агент без інструментів фактично «вміє» лише одне: формувати текстову відповідь. Щоб перетворити його на корисного помічника, треба дати можливість виконувати дії чи отримувати дані ззовні.
У термінах Agentspan це роблять tools. Формулювання просте: «Інструмент — це щось, що AI‑агент може викликати, щоб отримати певну відповідь або виконати певну дію».
Як оголошується інструмент
У курсі для демонстрації беруть елементарну функцію отримання поточного часу:
@tool
def get_current_time() -> str:
"""Returns the current local time."""
now = datetime.now()
return str(now)
Структура має кілька обовʼязкових елементів.
По‑перше, імпорт декоратора @tool із Agentspan.
По‑друге, у сигнатурі функції треба явно вказати тип виходу (і, за потреби, типи вхідних аргументів). Коментар до цього підкреслює: «наприклад, я скажу: функція get_current_time повертатиме рядок… а потім ви просто конвертуєте це в рядок і повертаєте».
По‑третє, докстрінг. Саме він стає описом інструмента для моделі: що робить, які аргументи приймає, що повертає. Це критично, тому що LLM ухвалює рішення, який інструмент викликати, орієнтуючись саме на такі текстові описи.
«Щоб додати інструмент — супер просто… Ми просто визначаємо функцію, позначаємо її як інструмент через цей декоратор @tool… Назва інструмента автоматично буде назвою функції», — так описується типовий патерн.
Як Agentspan викликає інструменти під капотом
Коли інструмент оголошено, його треба додати до списку tools в агенті:
assistant = Agent(
...,
tools=[get_current_time],
memory=conversation_memory,
)
Із цього моменту модель може, орієнтуючись на інструкції та запит користувача, вирішити, що їй потрібні свідчення ззовні, й сформувати спеціальний «виклик інструмента» замість прямої відповіді.
Цей процес описується так: «Тепер Agentspan нативно визначає можливість виклику інструментів… назва цього інструмента була get_current_time… потім ми викликали інструмент, отримали вихід… і передали його в модель».
Механіка така:
- Асистент отримує запит, наприклад: «Котра зараз година?».
- Модель, замість відповіді, повертає JSON із інструкцією викликати
get_current_time. - Runtime Agentspan, що обертає агента, автоматично викликає однойменну Python‑функцію.
- Отриманий результат (рядок з датою й часом) додається до контексту діалогу.
- Модель вдруге викликається вже з новим контекстом, де є результат інструмента, і формує фінальну текстову відповідь.
Це добре видно в дашборді: окремо показаний крок LLM із запитом на виклик get_current_time, результат функції й фінальна відповідь для користувача.
Після запуску й запиту «What time is it?» система повертає коректний час, а в UI Agentspan можна побачити, як у логах зʼявляється крок із викликом get_current_time та його результатом.
Веб‑дашборд як обовʼязковий елемент продакшн‑агента
Цей перший агент навмисно простий логічно, але вже повністю використовує інфраструктурні переваги Agentspan. Одне з ключових — прозорість виконання.
У дашборді для кожного «запуску» агента видно, що саме відбулося:
- вхідний prompt користувача;
- вихід моделі (проміжні та фінальний);
- виклики інструментів: імʼя, аргументи та повертовані дані;
- метадані на кшталт тривалості кроку та токенів.
Саме цей сценарій — задати запит у терміналі, а потім зайти в браузер та подивитися повний трейс — і демонструє, як Agentspan пропонує робити продакшн‑розробку: навіть найпростіша версія агента з самого початку будується «поверх сервера» з durable execution та observability, а не як ізольований скрипт.
Крок до продакшну: один файл — вже робочий агент
У підсумковій версії «агент №1» — це один Python‑файл, який:
- підʼєднується до Agentspan Server через змінну середовища;
- створює агента з моделлю, інструкціями, розмовною памʼяттю та хоча б одним інструментом;
- запускає нескінченний цикл спілкування в терміналі, де користувач може вийти, ввівши
q; - додає кожне повідомлення користувача й відповіді асистента до памʼяті;
- дозволяє Agentspan автоматично обробляти виклики інструментів і зберігати повний лог сесій.
Важливий акцент — цей агент із перших рядків коду задуманий для реального середовища, а не як «демо в ноутбуку». Памʼять, інструменти, підключення до серверу та веб‑дашборд — усе це розглядається не як add‑on, а як базовий набір для практичного використання.
Джерело
YouTube — Build 3 PRODUCTION AI Agents in Python – Full Course (Agentspan)