ai-agents-for-beginners

Розгортання масштабованих агентів з Microsoft Foundry

Розгортання масштабованих агентів

До цього моменту в курсі ви створювали агентів, які працюють на вашому ноутбуці, всередині блокнота, керованого az login і кількома змінними середовища. Це саме правильний спосіб навчання. Проте це не правильний спосіб запуску агента, від якого залежать тисячі клієнтів о 3 годині ночі.

Цей урок стосується розриву між “все працює на моєму комп’ютері” і “це працює надійно та економно у виробництві”. Ми закриваємо цей розрив за допомогою Microsoft Foundry та Microsoft Foundry Agent Service, створюючи реального агента підтримки клієнтів із інструментами, пошуком, пам’яттю, оцінкою та моніторингом.

Вступ

Цей урок охоплює:

Навчальні цілі

Після завершення цього уроку ви знатимете, як:

Необхідні знання

Цей урок передбачає, що ви пройшли попередні уроки і комфортно працюєте з:

Вам також знадобиться:

Від прототипу до виробництва: що справді змінюється

Прототипний агент та виробничий агент мають спільний основний цикл — міркування, виклик інструментів, відповідь. Змінюється все, що оточує цей цикл. Модель — це приблизно 20% виробничого агента; решта 80% — це операційний каркас.

Питання Прототип Виробництво
Розміщення Працює у вашому блокноті Працює як хостингова служба, версіонується та розгортається
Ідентичність Ваш токен az login Керована ідентичність з обмеженим RBAC
Стан В пам’яті, втрачається при перезапуску Зовнішній (сховище потоків, сервіс пам’яті)
Збої Ви бачите трейсбек Повтори, резервні варіанти, dead-letter, оповіщення
Вартість “Це кілька центів” Відстежується за запит, маршрутизована, кешована, бюджетована
Якість Ви оцінюєте візуально Автоматично оцінюється перед кожним релізом
Довіра Ви схвалюєте кожну дію Політика + людський контроль для ризикованих дій

Пам’ятайте цю таблицю. Кожен розділ нижче відповідає одній з цих рядків.

Патерни розгортання агентів

Є три патерни, які ви часто використовуватимете у комбінації.

1. Клієнтське розміщення агентів

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

2. Hosted Agents (Foundry Agent Service)

Агент реєструється як ресурс у Microsoft Foundry. Foundry розміщує цикл розмірковування, зберігає потокові повідомлення, забезпечує безпеку контенту та RBAC, робить агента видимим у порталі Foundry. Ваш застосунок стає тонким клієнтом, який створює потоки та читає відповіді.

3. Робочі процеси агентів

Декілька агентів (та інструментів) поєднані у граф з явним контролем потоку — послідовні кроки, розгалуження, вузли людського схвалення, та стійкі контрольні точки, які можуть призупинятися і відновлюватися. Це можливість Workflows Microsoft Agent Framework, застосована на рівні розгортання.

flowchart TB
    subgraph P1[Client-Hosted]
        A1[Your App Process] --> M1[Model Provider]
    end
    subgraph P2[Hosted Agent]
        A2[Thin Client] --> F2[Foundry Agent Service]
        F2 --> M2[Model + Tools + Thread Store]
    end
    subgraph P3[Agent Workflow]
        A3[Orchestrator] --> S1[Triage Agent]
        S1 --> S2[Resolver Agent]
        S2 --> H[Human Approval Node]
        H --> S3[Action Agent]
    end

Життєвий цикл агента в Microsoft Foundry

Розгортання агента — це не одноразове push. Це цикл, і він дуже схожий на цикл випуску програмного забезпечення, тому що це саме він.

flowchart LR
    Create[Create / Author] --> Version[Version]
    Version --> Evaluate[Evaluate offline]
    Evaluate -->|passes gate| Deploy[Deploy hosted]
    Evaluate -->|fails gate| Create
    Deploy --> Observe[Observe online]
    Observe --> Improve[Collect failures]
    Improve --> Create
    Deploy --> Retire[Retire old version]

Ключова ідея, взята з Урок 10: офлайн оцінка — це ворота, а не післямова. Нова версія агента не випускається, якщо не проходить ваші пороги оцінки. Онлайн спостережуваність повертає реальні збої назад у ваш офлайн тестовий набір. Це весь цикл.

Стратегії масштабування

Масштабування агента відрізняється від масштабування безстанного веб-API, бо кожен запит може викликати кілька дорогих звернень до моделі та інструментів. Чотири техніки беруть на себе більшість навантаження.

Обробка без стану. Не зберігайте стан користувача у пам’яті процесу. Зберігайте потоки розмов у сховищі Foundry або сервісі пам’яті, щоб будь-який екземпляр міг обробити будь-який запит. Це дозволяє масштабуватися горизонтально — додавати екземпляри, без “липких” сесій.

Маршрутизація моделей. Не кожен запит потребує вашої найпотужнішої (і найдорожчої) моделі. Направляйте прості запити — класифікація наміру, короткі фактичні відповіді — на маленьку, швидку модель, а велику модель залишайте для справжнього розмірковування. Foundry має вбудований Model Router, або ви можете реалізувати легку класифікацію самостійно. Ви створите таку версію в лабораторії.

Кешування відповідей. Багато запитів служби підтримки є близькими дублями (“як скинути пароль?”). Кешуйте відповіді на поширені запитання і видавайте їх без звернення до моделі. Навіть скромний відсоток попадання у кеш значно знижує вартість і затримку.

Паралельність та зворотній тиск. Провайдери моделей мають обмеження швидкості. Обмежуйте паралельність, використовуйте повтори з експоненційним збільшенням затримки, і відмовляйтеся з гідністю (черговий “ми працюємо над цим” кращий за 500).

flowchart LR
    Q[User query] --> C{Cache hit?}
    C -->|yes| R[Return cached answer]
    C -->|no| Router{Complexity?}
    Router -->|simple| SLM[Small model]
    Router -->|complex| LLM[Large model]
    SLM --> Out[Response]
    LLM --> Out
    Out --> Store[Cache + trace]

Спостережуваність у виробництві

Ви не можете керувати тим, чого не бачите. Як було описано в Уроці 10, Microsoft Agent Framework нативно робить OpenTelemetry трасування — кожен виклик моделі, інструменту та крок оркестрації стає спаном. У виробництві ви експортуєте ці спани в Microsoft Foundry (або будь-який сумісний бекенд OTel), щоб:

from agent_framework.observability import get_tracer

tracer = get_tracer()

with tracer.start_as_current_span("support_request") as span:
    span.set_attribute("customer.tier", "enterprise")
    span.set_attribute("routed.model", "gpt-5-nano")
    # agent execution is traced automatically inside this span

Атрибути як customer.tier та routed.model перетворюють гору трасувань у питання з відповідями (“чи часто корпоративних клієнтів спрямовують до маленької моделі?”).

Оптимізація вартості

Вартість у виробничих агентах переважно складається з токенів. Три важелі за ступенем впливу:

  1. Правильний розмір моделі. Мала модель, що проходить вашу оцінку, майже завжди дешевша за велику, що також проходить. Використовуйте оцінку, щоб довести, що мала модель достатньо добра, а не за замовчуванням обирайте найбільшу для перестороги.
  2. Маршрутизація за складністю. Як вище — сплачуйте за велику модель лише для запитів, які потребують її розмірковування.
  3. Агресивне кешування. Найдешевший виклик моделі — той, який ви ніколи не робите.

Ворота оцінки та контроль вартості — це одна дисципліна, подивлена з двох боків: оцінка каже про базову якість, маршрутизація й кешування тримають вас якнайближче до вартості цього рівня.

Питання розгортання на підприємстві

Управління. Hosted Agents успадковують RBAC, безпеку контенту та аудит Foundry. Кожному агенту призначайте керовану ідентичність з мінімальними правами — доступ тільки для читання до бази знань, обмежений доступ до API тикетів, нічого зайвого.

Людина у циклі. Деякі дії надто важливі для повної автоматизації — видача відшкодування, видалення облікового запису, ескалація до юридичного відділу. Microsoft Agent Framework підтримує інструменти із необхідним затвердженням: агент пропонує дію, виконання призупиняється, людина схвалює або відхиляє, і робочий процес відновлюється. Ви бачили примітив у Уроці 6; тут ви його розгортаєте.

MCP у виробництві. MCP дозволяє вашому агенту використовувати зовнішні інструменти через стандартний інтерфейс. У виробництві трактуйте кожен MCP сервер як недовірену межу: фіксуйте версію сервера, запускайте з обмеженою ідентичністю, перевіряйте його результати, і ніколи не розкривайте йому секрети. MCP сервер — це залежність, а залежності патчаться, проходять аудит і мають обмеження швидкості.

flowchart TB
    subgraph Dev[Development Architecture]
        D1[Notebook] --> D2[Agent Framework]
        D2 --> D3[Model Provider]
        D2 --> D4[Local tools]
    end
    subgraph Deploy[Deployment Architecture]
        E1[CI pipeline] --> E2[Evaluation gate]
        E2 -->|pass| E3[Foundry Agent Service]
        E3 --> E4[Versioned hosted agent]
    end
    subgraph Run[Runtime Architecture]
        F1[Client app] --> F2[Hosted agent]
        F2 --> F3[Model Router]
        F2 --> F4[Azure AI Search RAG]
        F2 --> F5[Memory service]
        F2 --> F6[MCP tools]
        F2 --> F7[OTel -> Foundry tracing]
        F2 --> F8[Human approval]
    end

Ці три діаграми — розробка, розгортання, середовище виконання — це один агент на трьох етапах його життя. Лабораторна робота, що слідує, проведе вас крізь його створення.

Практична лабораторія: агент підтримки клієнтів, готовий до виробництва

Відкрийте code_samples/16-python-agent-framework.ipynb і пройдіть його повністю. Ви зберете агента підтримки клієнтів Contoso з усіма виробничими аспектами:

  1. Виклик інструментів — перевірка статусу замовлення та відкриття запитів у підтримці.
  2. RAG — відповіді на політичні запитання з бази знань (Azure AI Search, з запасним in-memory-варіантом для роботи блокнота без Search-ресурсу).
  3. Пам’ять — запам’ятовування клієнта між ходами розмови.
  4. Маршрутизація моделей — класифікатор складності направляє кожен запит до малої або великої моделі.
  5. Кешування відповідей — повторювані питання видаються з кешу.
  6. Людське затвердження — відшкодування вище порога призупиняються для підпису людиною.
  7. Конвеєр оцінки — невеликий офлайн тестовий набір оцінює агента та служить воротами для релізу.
  8. Спостережуваність — OpenTelemetry трасування для кожного запиту.

Покроковий огляд

Блокнот організовано так, що кожен виробничий аспект є самостійною, запускаємою секцією. Серцем є обробник запитів із маршрутизацією і кешуванням:

async def handle_support_request(query: str, customer_id: str) -> str:
    # 1. Serve from cache when we can.
    cached = response_cache.get(normalize(query))
    if cached:
        return cached

    # 2. Route by complexity to control cost.
    model = "gpt-5-nano" if is_simple(query) else "gpt-5-mini"

    # 3. Run the agent inside a trace span for observability.
    with tracer.start_as_current_span("support_request") as span:
        span.set_attribute("routed.model", model)
        span.set_attribute("customer.id", customer_id)
        response = await support_agent.run(query, model=model)

    # 4. Cache and return.
    response_cache.set(normalize(query), response.text)
    return response.text

Ворота оцінки, що охороняють реліз, виглядають так:

async def evaluation_gate(agent, test_cases, threshold: float = 0.8) -> bool:
    passed = 0
    for case in test_cases:
        result = await agent.run(case["input"])
        if score_response(result.text, case["expected"]) >= 0.8:
            passed += 1
    pass_rate = passed / len(test_cases)
    print(f"Evaluation pass rate: {pass_rate:.0%} (gate: {threshold:.0%})")
    return pass_rate >= threshold  # only deploy if the gate passes

Читайте уважно кожен рядок — блокнот свідомо лишає примітиви невеликими, щоб нічого не було сховано за викликами фреймворку.

Валідація розгорнутого агента за допомогою smoke-тестів

Ворота оцінки вище запускаються офлайн на вашому об’єкті агента. Після розгортання агента як Hosted Agent потрібно ще одну, навіть дешевшу перевірку: чи агент на розгорнутій точці дійсно відповідає?

«Успішне» розгортання лише доводить, що контрольна площина прийняла визначення — воно не доводить, що агент відповідає. Відсутність залежності, неправильна маршрутизація моделі або прострочене з’єднання може залишити зелене розгортання, яке нічого не повертає. Smoke-тест ловить це за секунди, при кожному розгортанні, без витрат на повну оцінку.

Цей репозиторій постачає готову піплайн smoke-тестів на базі GitHub Action AI Smoke Test:

- name: Smoke-test hosted agent
  uses: JFolberth/ai-smoketest@v1
  with:
    project_endpoint: $
    agent_name: ContosoSupportAgent
    tests_file: tests/lesson-16-smoke-tests.json

Запустіть це з вкладки Дії після розгортання вашого агента, подавши кінцеву точку проекту Foundry та ім’я агента. Федеральна ідентичність повинна мати роль Azure AI User в межах області проекту Foundry. Уявіть шари як піраміду: димові тести (досяжний і відповідає?) запускаються при кожному розгортанні, офлайн-оцінка (достатньо гарний для релізу?) виконується перед промоцією, а онлайн-оцінка (як він працює в реальних умовах?) запускається безперервно.

Перевірка знань

Перевірте свої знання перед переходом до завдання.

1. Приблизно яка частина виробничого агента — це «модель», а що є рештою?

Відповідь Модель є меншістю в системі — часто згадується приблизно 20%. Решта — це операційний «скелет»: хостинг і версіонування, ідентифікація та RBAC, зовнішній стан, обробка збоїв, відстеження вартості, оцінка та контролі з участю людини. Перехід у production переважно про побудову всього *навколо* циклу мислення.

2. Коли ви оберете Hosted Agent замість агента, розміщеного на клієнті?

Відповідь Коли ви хочете кероване середовище виконання з вбудованою стійкістю (потоки, які зберігаються і можуть продовжуватися), спостережливістю, безпекою контенту та RBAC, і готові пожертвувати деяким низькорівневим контролем циклу мислення заради меншої операційної поверхні. Розміщення на клієнті переважне, коли потрібен повний контроль над циклом або агент інтегрується в існуючий бекенд.

3. Чому масштабований агент повинен бути безстанним у власній пам’яті процесу?

Відповідь Щоб будь-який екземпляр міг обробити будь-який запит, що дозволяє горизонтальне масштабування без «липких» сесій. Стан розмови для користувача винесений у сховище потоків або сервіс пам’яті. Якби стан зберігався в пам’яті процесу, він губився б при перезапуску і навантаження не можна було б розподіляти вільно.

4. Яку проблему вирішує маршрутизація моделей і як це пов’язано з оцінкою?

Відповідь Маршрутизація надсилає прості запити до малої, дешевої, швидкої моделі і залишає велику модель для справжнього мислення, контролюючи час відповіді і вартість. Це пов’язано з оцінкою, оскільки оцінка *підтверджує*, що мала модель достатньо хороша для певного класу запитів — маршрутизація без оцінки — це здогадки.

5. Що таке «evaluation gate» і де він розташований у життєвому циклі?

Відповідь Evaluation gate запускає офлайн-набір тестів для нової версії агента і блокує розгортання, якщо відсоток проходження нижчий за поріг. Він розміщений між «версією» і «розгортанням» у життєвому циклі, роблячи якість передумовою релізу, а не тим, що перевіряється після випуску.

6. Чому MCP сервер у production слід розглядати як ненадійний кордон?

Відповідь Тому що це зовнішня залежність, до якої звертається ваш агент. Варто зафіксувати його версію, запускати з обмеженою ідентичністю, перевіряти вихідні дані, обмежувати швидкість запитів і ніколи не передавати йому секрети — ті самі дисципліни, що й до будь-якої сторонньої залежності. Його результати впливають на мислення агента, тому необґрунтована довіра — це ризик безпеки.

7. Яка одна зміна зазвичай має найбільший вплив на вартість виробничого агента і чому?

Відповідь Правильний вибір моделі — використання найменшої моделі, яка все ще проходить ваш evaluation gate. Вартість визначають токени, і менша модель, що відповідає стандартам якості, майже завжди дешевша за більшу. Кешування і маршрутизація знижують вартість далі, але вибір базової моделі має найбільший первинний вплив.

8. Яку роль відіграють атрибути span, такі як customer.tier та routed.model, у спостережливості?

Відповідь Вони перетворюють сирі трасування на питання, на які можна дати відповідь у бізнесі. Без атрибутів ви маєте стіну span; з ними можна запитати «чи надто часто корпоративних клієнтів направляють до малої моделі?» або «яка модель обробляє наші найповільніші запити?» Атрибути показують, як розрізати телеметрію за вимірами, важливими для вашої роботи.

Завдання

Візьміть агента підтримки клієнтів з лабораторної роботи і адаптуйте його для конкретного сценарію: агент підтримки передплати для SaaS компанії.

Ваше завдання:

  1. Замініть інструменти на релевантні для білінгу: get_subscription_status, get_invoice і issue_credit (кредити понад $50 потребують затвердження людиною).
  2. Додайте три документи RAG з політикою повернення, циклом білінгу і політикою скасування компанії.
  3. Розширте набір оцінки до щонайменше восьми випадків, включно з двома, що мають активувати шлях затвердження людиною, і переконайтеся, що ваш evaluation gate правильно проходить або блокує.
  4. Додайте звіт про вартість: після виконання десяти змішаних запитів через агента виведіть, скільки виконано через малу модель, скільки через велику і скільки обслуговано із кешу.

Напишіть короткий абзац (у маркдаун-комірці), пояснюючи, яке правило маршрутизації моделі ви обрали і як ви його перевірите на реальному трафіку. Правильної єдиної відповіді немає — оцінюють, наскільки чітко пов’язані продакшн-проблеми в одне ціле.

Підсумок

У цьому уроці ви перевели агента з прототипу у production з Microsoft Foundry:

Наступний урок іде протилежним шляхом: замість масштабування агентів у хмарі ви перенесете їх назовні на один комп’ютер розробника і запустите цілком локально.

Додаткові ресурси

Попередній урок

Створення агентів для комп’ютерного використання (CUA)

Наступний урок

Створення локальних AI агентів

Відмова від відповідальності: Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу Co-op Translator. Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу.

This site is open source. Improve this page.