Англійська мова для розробників Mastra AI Agent
Ключовий англійський словник і фрази для створення агентів штучного інтелекту з Mastra — робочі потоки, інструменти, пам' ять, оцінки і конвеєри RAG — для розробників TypeScript, які працюють у транскордонних командах агентів.
Mastra — це TypeScript-фреймворк для створення агентів штучного інтелекту, робочих потоків і конвеєрів генерації з розширеним пошуком (RAG). Якщо ви приєднуєтесь до команди, яка постачає агентні продукти з Mastra, ви будете постійно обговорювати « інструменти », « робочі потоки », « пам’ ять » і « оцінки » — часто у виступах і проектних документах, де точний словник має таке ж значення, як і правильний код. У цьому посібнику ви дізнаєтеся про терміни і речення, які ви використовуватимете під час пояснення системи, заснованої на Mastra, колегам по команді, учасникам або співбесідникам.
Основні будівельні блоки
Agent
** Агент ** у Mastra — це об’ єкт, який підтримується LLM, налаштований з інструкціями, моделлю і набором інструментів, які він може викликати. Агент відрізняється від однієї команди виклику, оскільки він може вирішувати під час виконання, який інструмент викликати і коли зупинити.
- “Ми визначили
supportAgentз трьома інструментами -lookupOrder,refundPaymentіescalateToHuman- і дали йому чіткі інструкції про те, коли ескалувати, а не вгадувати.” *
Tool
** tool ** — це типова функція, яку агент може викликати — описана з назвою, описом і схемою вводу (зазвичай Zod), щоб модель точно знала, які аргументи слід надати.
“Опис інструменту має більше значення, ніж люди очікують — якщо він неоднозначний, агент викликає його в неправильний момент або з неправильно сформованими аргументами.”
Workflow
** Робочий потік ** — це детермінований, багатокроковий конвеєр, який може викликати агентів і інструменти послідовно, паралельно або умовно — з вбудованими повторними спробами і розгалуженнями. Робочі потоки надають вам контроль над частинами конвеєра, які ви не бажаєте залишати повністю на розсуд моделі.
“Ми перенесли крок оплати з вільної форми роздумів агента в крок робочого процесу - надто ризиковано дозволяти моделі вирішувати, коли заряджати карту.”
Step
У рамках потоку робіт, ** крок ** є єдиною одиницею роботи з визначеними вхідними і вихідними даними. Кроки можуть бути з’єднані, виконуватися паралельно з .parallel(), або бути умовними.
- “Кожен крок записує у журнал власні вхідні і вихідні дані, отже, якщо поток дій зазнає невдачі на кроці 4, нам не потрібно вгадувати, у якому стані він перебував.” *
Пам’ять і контекст
Memory
** Пам’ ять ** у Mastra зберігає історію розмов і факти, отримані за допомогою сеансів, отже агент може відновлювати попередні взаємодії, замість того, щоб кожного разу починати з порожнього контексту.
“Без пам’яті, агент ставив ті ж самі кваліфікаційні питання кожного сеансу - як тільки ми підключили постійну пам’ять, він запам’ятав рівень плану користувача і перестав повторювати себе.”
Робоча пам’ять
** Робоча пам’ ять ** — це менший, структурований підмножина пам’ яті, яку агент активно підтримує і оновлює — це корисно для відстеження таких речей, як вказані користувачем параметри або стан завдання, яке виконується.
Семантичне відновлення
** Семантичний відгук ** отримує відповідні повідомлення з минулого шляхом вбудовування подібності, а не строго недавнього часу, отже агент може витягнути факт з трьох тижнів тому, якщо він відповідає поточному запитові.
“Семантичне відновлення витягнуло раніше надіслану користувачем скаргу щодо повільного експорту, що було саме тим контекстом, який агенту був потрібен, щоб відповісти на їхню відповідь.”
Ретроспективний огляд (рос.)
Chunking
** Розділення на частини ** розділяє джерельний документ на менші частини перед вбудовуванням, отже, при отриманні буде повернено сконцентровані, відповідні пасажири замість цілих документів.
- “Ми перейшли від дроблення з фіксованим розміром до рекурсивного дроблення, яке дотримується заголовків markdown — якість отримання значно поліпшилась.” *
Векторний магазин
** Векторний магазин ** містить вбудовані елементи і підтримує пошук за подібністю. Mastra інтегрується з кількома — Pinecone, PgVector, Qdrant та іншими.
Retriever
retriever є компонентом, який запитує векторний магазин і повертає відповідні верхні шматки для даного запиту, які потім вводяться в контекст агента.
- “Програма- витягувач повертала застарілі шматки, тому що ми забувають переіндексувати після оновлення документації — це завжди добре, коли першим чином перевіряють застарілі відповіді RAG.” *
Оцінка та спостереження
Eval
eval є автоматизованим, оціненим тестом виводу агента — перевірка таких речей, як вірність джерельному матеріалу, токсичність або відповідність відповіді. Evals дозволяє вам ловити регресії до того, як вони потраплять до виробництва.
- “Ми додали оцінку вірності, яка позначає будь- яку відповідь, яка не базується на отриманих документах — вона виявила галюцинацію під час нашого останнього оновлення моделі.” *
Trace
Trace це повний записаний шлях виконання агента — кожен виклик інструменту, кожне завершення моделі, кожен крок — використовується для зневадження і спостереження.
“Коли поток повернення поводився несподівано, трасування показало, що агент викликав
lookupOrderз неправильним форматом ID — просте виправлення, як тільки ми змогли це побачити.”
Guardrail
** Захисні стіни ** це правило або перевірка, яка обмежує поведінку агента — наприклад, блокування виклику інструменту над певною сумою без схвалення людини.
“Ми додали захист, щоб будь-який повернення більше $200 призупиняє роботу і чекає, поки людина схвалить його.”
Використання лексики
Streaming
** Стрімування ** надсилає частковий вивід агента до клієнта під час його створення, замість очікування повної відповіді — важливо для сприйняття швидкості реакції у інтерфейсах балачки.
Людина-в-пятлі
** Людина у циклі ** описує крок потоку робіт, який призупиняє виконання і чекає на затвердження, відхилення або редагування людиною перед тим, як продовжити.
*“Робочий процес викликає
suspend()перед кроком повернення коштів і чекає на підтвердження його керівником підтримки — це наш контрольний пункт «людина в циклі». *“
Основні положення, що регулюють діяльність мовної системи
| Situation | Phrase |
|---|---|
| Explaining why you used a workflow instead of pure agent reasoning | ”We wanted deterministic control over the payment step, so we moved it into a workflow instead of leaving it to the agent’s judgment.” |
| Describing a memory bug | ”The agent lost context between sessions because memory wasn’t configured to persist — it’s fixed now.” |
| Justifying an eval | ”We added this eval specifically because a previous model upgrade introduced a subtle hallucination we didn’t catch until a customer reported it.” |
| Discussing tool design | ”The tool description needs to be unambiguous — otherwise the agent picks the wrong tool for edge cases.” |
Практичні вправи
- Напишіть два речення, які пояснюють, для нетехнічного менеджера продукту, чому агенту потрібна «пам’ять», щоб почуватися корисним у чатботі підтримки.
- Опишете вашими словами різницю між « інструментом » і « кроком потоку робіт », ніби ви пояснюєте це новому члену команди.
- Написати коротке повідомлення Slack, у якому буде повідомлено, що eval виявив регресію після оновлення моделі, а також вказати, що слід робити далі.
Зв’язані ресурси
Переклади з англійської мови: «The End of the World» (переклад з англійської)
Сила Mastra полягає в її здатності організовувати складні робочі потоки, що включають великі мовні моделі і системи пошуку. Це часто включає міжнародні команди, які спілкуються про ці складні процеси, що по суті вводить виклики, які виходять за рамки простого перекладу слів. Незначні відмінності у формулюваннях, очікування щодо ясності і навіть рівень необхідних деталей можуть значно вплинути на ефективність співпраці і, врешті- решт, на успіх ваших проектів з агентами. Багато не-рідних носіїв, зрозуміло, зосереджуються на точному виборі слів, але так само важливо розуміти, як ці поняття обговорюються * професійно * - зосереджуючись менше на буквальному перекладі і більше на ефективному передачі намірів і контексту.
Однією з поширених пасток є надмірне формалізування комунікації. Хоча ясність є найважливішою, надмірно технічний жаргон або надмірно складне формулювання можуть бути неправильно інтерпретовані в культурах і рівнях досвіду. Просте «Давайте повторимо це» може здатися вимогливим в деяких контекстах, в той час як «Ми повинні вдосконалити відповідь» може відчуватися покірним в інших. Навчання виражати ідеї коротко і зосередитися на реальних кроках - як запит на «незначну коректування» або запропонувати «швидкий тест» - це ключ. Аналогічно, коли ви надсилаєте зворотній зв’язок під час перегляду коду, уникайте простого зауваження про те, що не так; замість цього, оформіть його як пропозицію щодо поліпшення: «Чи можемо ми дослідити додавання контекстуальної інформації тут, щоб поліпшити розуміння агента?» Повідомлення Slack, що вимагає пояснення складного конвеєра RAG, повинно бути прямим і зосередженим на конкретному аспекті, що потребує уваги: «Щодо інтеграції векторної бази даних - чи ми використовуємо вбудовування з Cohere або OpenAI?»
Крім того, нюансовані обговорення про оцінювальну метрику вимагають обережного формулювання. Замість того, щоб сказати «Модель зазнала невдачі», що може звучати осуду, спробуйте «Ми повинні переглянути критерії оцінки для цього завдання. Поточні показники неадекватно відображають [спеціфічний аспект]». Це переносить фокус на спільний процес вдосконалення, а не на приписування вини. Розгляньте також, що очікування щодо документації та описів PR різні - деякі команди вимагають вичерпних деталей, інші пріоритетують короткість, зосереджену на функціональності.
І нарешті, не бійтеся просити про пояснення, якщо щось не ясно. Це * набагато * краще визнати плутанину, ніж продовжувати на основі припущень. Просте «Чи можете ви розібратися в цьому?» або «Тільки щоб підтвердити, чи ми прагнемо до результату X?» демонструє залученість і бажання розуміння - якості, які цінуються в будь-якому колективному середовищі.
Ось приклад використання бібліотеки faiss у потоці робіт Mastra:
# Example using faiss to index embeddings for RAG retrieval (simplified)
python -m faiss.index create --type InnersProduct --dim 128 --nlist 100 ./my_embedding_indexЗа допомогою цієї команди можна ініціалізувати індекс FAISS, популярний інструмент для ефективного пошуку подібності у базах даних векторів, який часто використовується у конвеєрах RAG Mastra для швидкого отримання відповідної інформації на основі семантичної подібності. --type InnersProduct вказує на метрику, що використовується для порівняння векторів, а --dim 128 встановлює розмірність вбудованих об’ єктів (що представляють векторний простір). --nlist 100 вказує, що ми створюємо індекс зі 100 списками для зберігання векторів.