Глибокі агенти з SKILL.md: Оркестратор LangChain, який завантажує навички

Що, якби у агента не було фіксованого списку здібностей, і він міг би дізнатися, що може робити, лише оглядаючись навколо? Саме такий підхід використовується тут: це робочий глибокий агент у LangChain, який за потреби завантажує файли SKILL.md для відповідей на запити. Немає жодних закодованих ланцюгів та жодного користувацького маршрутизатора. Лише універсальний оркестратор, папка з навичками та бібліотека deepagents, яка виконує всю складну роботу.

Проблема з фіксованими наборами інструментів

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

Альтернативою є оркестратор, який не знає, що може робити, поки не перевірить. Під час виконання він сканує каталог skills/, спочатку читає лише метадані, а повні інструкції завантажує, коли певна навичка відповідає запиту. Замість того, щоб жорстко вказувати „цей агент досліджує та пише“, ви розміщуєте файли research/SKILL.md та writer/SKILL.md у папці, і агент сам визначає решту. Завтра ви можете додати навичку code-reviewer, і вона буде використана без необхідності змінювати жодного рядка коду. Це і є паттерн SKILL.md, застосований у LangChain.

Як все взаємопов’язано

Чотири ідеї керують роботою файлу agent.py:

1. Спочатку відбувається планування. Оркестратор завжди складає план, перетворюючи загальну мету користувача на конкретні технічні кроки.

Делегування залишається узагальненим. Замість спеціалістів, які працюють у конкретних ролях, завдання передаються універсальному підагенту з тими самими інструментами та таким самим доступом до бібліотеки навичок.

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

Робоче простір контролюється. Інструменти та дії, засновані на навичках, зберігаються у каталозі ./workspace/ для стабільності, тоді як кореневий каталог залишається видимим для налаштувань та навичок.

Усій проекту властива компактність, і справжню роботу виконують три файли.

Крок 1: налаштування проекту

Залежності знаходяться у файлі pyproject.toml:

# pyproject.toml
[project]
name = "deep-agents-langchain"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "deepagents>=0.4.12",
    "langchain-anthropic>=1.4.0",
    "langchain-openai>=1.1.12",
    "python-dotenv>=1.2.2",
    "streamlit>=1.55.0",
    "tavily-python>=0.7.23",
]

Основною є бібліотека deepagents від LangChain — це програмне забезпечення з відкритим кодом, яке формалізує патерн глибоких агентів. Вона вже заздалегідь надає можливості планування за допомогою write_todos, інструменти для роботи з файловою системою, створення підагентів через task, стиснення контексту, а також, що дуже важливо, завантаження навичок.

Крок 2: визначення інструментів

У файлі agent.py єдиним користувацьким інструментом є стандартний обгорток для пошуку Tavily:

import os
from typing import Literal
from dotenv import load_dotenv
from langchain_anthropic import ChatAnthropic
from langchain_openai import ChatOpenAI
from tavily import TavilyClient
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
load_dotenv()
# --- Generic Tools ---
tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
):
    """Search the web for current information."""
    return tavily.search(query, max_results=max_results, topic=topic)

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

Крок 3: фабрика агентів

Саме тут усе об’єднується:

def get_deep_agent():
    model = ChatAnthropic(
        model="claude-3-5-sonnet-20240620",
        temperature=0,
    )
return create_deep_agent(
        model=model,
        system_prompt="""You are a generic Deep Agent orchestrator.
1. Use `write_todos` to plan complex requests.
2. You have access to skills in the `skills/` directory.
   - You ONLY see names and descriptions initially.
   - For specialized tasks, load the matching SKILL.md first.
3. Use the `task` tool to delegate to subagents.
4. ALL outputs go to `./workspace/` exclusively.""",
        tools=[internet_search],
        skills=["./skills"],          # <-- This is the magic line
        memory=["./AGENTS.md"],
        backend=FilesystemBackend(root_dir="."),
        name="generic_deep_agent",
    )

Три параметри варто розглянути уважніше.

skills=[„./skills“] наказує deepagents сканувати цю директорію, аналізувати YAML-фронтметер кожного файлу SKILL.md, який він знаходить, та додавати каталог навичок у системний запит. Агент бачить щось на кшталт цього:

Available Skills:
- research: "Conducts comprehensive web research on any topic..."
- writer: "Specialized in writing high-quality content..."

Для двох навичок це коштує приблизно 200 токенів. Агент читає каталог та вирішує, яку навичку завантажити для запиту. Це суто маршрутизація за допомогою LLM без класифікаторів, ембеддингів чи регулярних виразів.

memory=["./AGENTS.md"] завантажує конвенції рівня проекту до системного запиту. Він слугує спільним контекстом для основного агента та кожного підагента, своєрідною сторінкою „Як ми тут працюємо“ для команди.

backend=FilesystemBackend(root_dir=".") надає агенту інструменти для роботи з файлами (read_file, write_file, edit_file) з каталогом проекту як коренем, тож файлова система стає постійним робочим простором агента.

Крок 4: написання навичок

Навмисно проста дослідницька навичка:

---
name: research
description: >
  Conducts comprehensive web research on any topic using search APIs
  and web scraping. Use when the user asks for research, information
  gathering, competitive analysis, or needs current data from the web.
license: MIT
compatibility: Requires internet access and Tavily API key
allowed-tools: internet_search Read Write
---
# Web Research Skill
## Instructions
1. Parse the research query to identify key topics.
2. Use the `internet_search` tool to gather initial results.
3. If results are insufficient, try alternative search queries.
4. Synthesize findings into a structured summary.
5. Save detailed findings to `./workspace/` as a markdown file.

І навичка письменника:

---
name: writer
description: >
  Specialized in writing high-quality, creative, and technical content.
  Use when the user needs a blog post, report, technical guide,
  or any form of structured writing.
license: MIT
---
# Creative Writer Skill
## Instructions
1. Review the input notes or research data provided.
2. Define an outline (Introduction, Body, Conclusion).
3. Use a tone appropriate for the target audience.
4. Ensure all claims are backed by provided data.
5. Save the final draft to `./workspace/`.

Кожен файл містить YAML-фронтматер, який виконує функцію ідентифікаційного картку навички, а після нього йде тіло у форматі Markdown, яке є посібником з використання. Агент бачить фронтматер на рівні 1, а тіло — лише на рівні 2. Це відповідає специфікації, опублікованій на agentskills.io.

Крок 5: спільна пам’ять у AGENTS.md

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

# Project Context: Deep Agents Demo
## Conventions
- Skills are stored as directories under `skills/`.
- Every skill must have a `SKILL.md` file.
- Subagents should be used for complex, multi-step tasks.
- All intermediate work goes to `./workspace/`.
## Known Entities
- **Main Agent**: The orchestrator who plans and delegates.
- **Researcher**: Specialized in web search and data aggregation.
- **Writer**: Specialized in formatting and synthesizing information.

Як насправді працює маршрутизація

Немає жодного маршрутизатора та класифікатора, оскільки сама ШІ виконує маршрутизацію. Коли бібліотека створює системний запит, вона додає текст приблизно такого змісту:

You have access to a library of skills in the `skills/` directory.
You ONLY see names and descriptions initially.
For any specialized task, look for matching skills and use
`read_file` to load the SKILL.md before executing.
Available skills:
- research: "Conducts comprehensive web research..."
- writer: "Specialized in writing high-quality content..."

Модель читає повідомлення користувача та описи навичок, а потім вирішує, чи викликати read_file("skills/research/SKILL.md"), чи ні. Усе рішення приймається під час виконання алгоритму трансформера без зовнішньої логіки. Іншими словами, опис навички є механізмом направлення дій, і достатньо добре написаного опису з ключовими словами та межами.

Фронтенд Streamlit

app.py обгортає все у інтерфейс Streamlit, який відображає процес мислення агента у реальному часі. Функція stream("updates") від LangGraph генерує подію для кожного виконання вузла, і додаток обробляє їх на предмет викликів інструментів, позначок завантаження навичок, оновлень плану та кінцевої відповіді.

Додавання навички без змін у коді

Припустимо, ви хочете навичку для перегляду коду. Створіть для неї папку поруч з іншими:

skills/
├── research/
│   └── SKILL.md
├── writer/
│   └── SKILL.md
└── code-reviewer/
    └── SKILL.md

Потім напишіть його SKILL.md:

---
name: code-reviewer
description: >
  Reviews code for bugs, security issues, and best practices.
  Use when the user asks for a code review, security audit,
  or wants feedback on code quality. Do NOT use for writing
  new code or debugging runtime errors.
license: MIT
allowed-tools: Read Write
---
# Code Review Skill
## Instructions
1. Read the target file using `read_file`.
2. Analyze for: bugs, security issues, performance, readability.
3. Write a structured review to `./workspace/review.md`.

Перезапустіть додаток — тоді агент знатиме, як переглядати код. Файл agent.py залишився недоторканим, як і системний запит. Ви додали лише папку, більше нічого. Такий підхід дозволяє створювати більш складних глибоких агентів.

Уроки, які з цього випливли

• Описи навичок мають більше значення, ніж інструкції до них. Якщо опис слабкий, навичка ніколи не буде активована. Налаштування поля description, включаючи ключові слова та негативні обмеження на кшталт „Не використовувати для...“, зайняло більше часу, ніж написання самого тексту навички, адже цей текст є логікою направлення дій.
• Файлова система недооцінюється. Багато посібників з агентами зберігають усе в історії повідомлень, що підходить для простих задач, але не ефективно при багатоетапній роботі. Зберігання проміжних результатів у ./workspace/ та надання можливості підагентам їх читати дозволяє елементам правильно поєднуватися.

AGENTS.md об’єднує всі елементи. Без нього оркестратор та його підагенти працюють окремо. З ним вони діляться стандартами, знають структуру проекту та уникають дублювання зусиль — це невеликий файл із величезним впливом.

Почніть з загальних принципів та спеціалізуйтесь через навички. Хочеться вмістити всі знання про домен у системний запит, але залишення оркестратора загальним та розміщення кожної спеціалізації у файлах SKILL.md робить систему модульною та піддається тестуванню. Навички можна змінювати, не торкаючись агента.

Що додала б версія для продакшну

Цей додаток свідомо мінімалістичний. Реальне впровадження, ймовірно, включатиме постійну пам’ять за допомогою LangMem для епізодичного та семантичного відтворення інформації між сеансами, інтеграцію MCP з корпоративними інструментами, такими як Slack, Jira та бази даних, контрольні точки з участю людини за допомогою механізму переривання LangGraph, стиснення контексту для довгих дослідницьких завдань, а також більше навичок — кожна з яких є просто папкою з файлом SKILL.md.

Напрямок розвитку здається очевидним. Створення агентів полягає не стільки у написанні більшої кількості коду, скільки у написанні кращих файлів SKILL.md. Фреймворк відповідає за технічну частину, навички несуть експертизу, а LLM вирішує, коли використовувати кожну з них.