Deep Agents з 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/`.

Każы файл мае 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.

Як на самае працюе маршрутызацыя

Няма ні рутэра, ні класыфікатора, таму што сама LLM адзначае маршруты. Калі бібліятэка стварае сістэмны запрос, яна дадае тэкст працоўныя такія:

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, які паказвае працэс размышлення агента ў рэальны час. Функцыя LangGraph’s stream("updates") генеруе запіс для кожнай екзекуцыі вузла, а прыстанок перакладае іх у вызвы інструментаў, пазначкі пра завантажэнне навыкаў, абнаўленні плану і заканчоўны адказ.

Дадаць навык без жадных змян у кодзе

Спачатку падумайце пра навыке для перагляду коду. Створыце папку для яго радом з іншымі:

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, уключаючы словы-трыгеры і негатывныя межы, такія як "Не вжываць для...", займало больш часу, чым напісанне самага тэксту навыку, адтолькі што гэты тэкст ёсць логікаю керавання.
• Файловая сістэма часта недаўаецца належнага значэння. Большасць інструкцый па стварэнні агентоў заставляе усё зберагаць у історыі паведамленняў, што падходзіць толькі для простых задач і не функцыонуе пад час багатаэтапных прац.

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

Пачніце з генерычных рашэнняў і спецыялізавацеся за дапамогою навыкаў. Існуе спакуса запісваць усе знаёмства пра конкрэтную галіну ў сістэмны прапанунек, але калі заставіць оркестрабітар генерычным, а кожную спецыялізацыю размясціць у файлах SKILL.md, сістэма стане модульнаю і практычнай для тэставання. Навыкі можна змянюваць без вплыву на агента.

Што могла б дадаць версія для практычнага выкарыстоўвання

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

Напрамак развіцця выглядае ясным. Стварэнне агентаў — гэта не столькі напісання больш коду, сколькі напісанне каліцейных файлаў SKILL.md. Фрэймворк абавяваеся тэхнічнымі аспектамі, навыкі несу экспертызу, а LLM вяршыць, калі і які з іх выкарыстоўваць.