🏠 Главная › Developer Guide › context engine plugin

sidebar_position: 9 title: "Context Engine Plugins" description: "How to build a context engine plugin that replaces the built-in ContextCompressor" lang: ru

Создание плагина контекстного движка

Плагины механизма контекста заменяют встроенный ContextCompressor альтернативной стратегией управления контекстом разговора. Например, механизм управления контекстом без потерь (LCM), который создает базу данных знаний вместо обобщения с потерями.

Как это работает

Управление контекстом агента построено на ContextEngine ABC (agent/context_engine.py). Встроенный ContextCompressor является реализацией по умолчанию. Механизмы плагинов должны реализовывать один и тот же интерфейс.

Одновременно может быть активен только один механизм контекста. Выбор зависит от конфигурации:

# config.yaml
context:
  engine: "compressor"    # default built-in
  engine: "lcm"           # activates a plugin engine named "lcm"

Механизмы плагинов никогда не активируются автоматически — пользователь должен явно указать context.engine для имени плагина.

Структура каталогов

Каждый контекстный движок находится в plugins/context_engine/<name>/:

plugins/context_engine/lcm/
├── __init__.py      # exports the ContextEngine subclass
├── plugin.yaml      # metadata (name, description, version)
└── ...              # any other modules your engine needs

Азбука ContextEngine

Ваш движок должен реализовать следующие обязательные методы:

from agent.context_engine import ContextEngine

class LCMEngine(ContextEngine):

    @property
    def name(self) -> str:
        """Short identifier, e.g. 'lcm'. Must match config.yaml value."""
        return "lcm"

    def update_from_response(self, usage: dict) -> None:
        """Called after every LLM call with the usage dict.

        Update self.last_prompt_tokens, self.last_completion_tokens,
        self.last_total_tokens from the response.
        """

    def should_compress(self, prompt_tokens: int = None) -> bool:
        """Return True if compaction should fire this turn."""

    def compress(self, messages: list, current_tokens: int = None,
                 focus_topic: str = None) -> list:
        """Compact the message list and return a new (possibly shorter) list.

        The returned list must be a valid OpenAI-format message sequence.

        ``focus_topic`` is an optional topic string from manual
        ``/compress <focus>``; engines that support guided compression should
        prioritise preserving information related to it, others may ignore it.
        """

Атрибуты класса, которые должен поддерживать ваш движок

Агент считывает их непосредственно для отображения и регистрации:

last_prompt_tokens: int = 0
last_completion_tokens: int = 0
last_total_tokens: int = 0
threshold_tokens: int = 0        # when compression triggers
context_length: int = 0          # model's full context window
compression_count: int = 0       # how many times compress() has run

Дополнительные методы

У них есть разумные значения по умолчанию в ABC. Переопределите при необходимости:

Метод По умолчанию Переопределить, когда
on_session_start(session_id, **kwargs) Нет операции Вам необходимо загрузить постоянное состояние (DAG, DB)
on_session_end(session_id, messages) Нет операции Вам нужно очистить состояние, закрыть соединения
on_session_reset() Сбрасывает счетчики токенов Вам нужно очистить состояние каждого сеанса
update_model(model, context_length, ...) Обновления context_length + порог Вам необходимо пересчитать бюджеты при смене модели
get_tool_schemas() Возвращает [] Ваш движок предоставляет инструменты, вызываемые агентом (например, lcm_grep)
handle_tool_call(name, args, **kwargs) Возвращает ошибку JSON Вы реализуете обработчики инструментов
should_compress_preflight(messages) Возвращает False Вы можете сделать дешевую оценку перед вызовом API
get_status() Стандартный токен/пороговый словарь У вас есть специальные метрики для раскрытия

Инструменты двигателя

Механизмы контекста могут предоставлять инструменты, которые агент вызывает напрямую. Возвращать схемы из get_tool_schemas() и обрабатывать вызовы из handle_tool_call():

def get_tool_schemas(self):
    return [{
        "name": "lcm_grep",
        "description": "Search the context knowledge graph",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"}
            },
            "required": ["query"],
        },
    }]

def handle_tool_call(self, name, args, **kwargs):
    if name == "lcm_grep":
        results = self._search_dag(args["query"])
        return json.dumps({"results": results})
    return json.dumps({"error": f"Unknown tool: {name}"})

Инструменты ядра добавляются в список инструментов агента при запуске и отправляются автоматически — регистрация в реестре не требуется.

Регистрация

Через каталог (рекомендуется)

Поместите свой движок в plugins/context_engine/<name>/. __init__.py должен экспортировать подкласс ContextEngine. Система обнаружения автоматически находит и создает экземпляр.

Через общую систему плагинов

Общий плагин также может зарегистрировать контекстный движок:

def register(ctx):
    engine = LCMEngine(context_length=200000)
    ctx.register_context_engine(engine)

Можно зарегистрировать только один двигатель. Второй плагин, пытающийся зарегистрироваться, отклонен с предупреждением.

Жизненный цикл

1. Engine instantiated (plugin load or directory discovery)
2. on_session_start() — conversation begins
3. update_from_response() — after each API call
4. should_compress() — checked each turn
5. compress() — called when should_compress() returns True
6. on_session_end() — session boundary (CLI exit, /reset, gateway expiry)

on_session_reset() вызывается на /new или /reset для очистки состояния каждого сеанса без полного завершения работы.

Конфигурация

Пользователи выбирают ваш движок через hermes plugins → Плагины провайдера → Context Engine или редактируя config.yaml:

context:
  engine: "lcm"   # must match your engine's name property

Блок конфигурации compression (compression.threshold, compression.protect_last_n и т. д.) предназначен для встроенного ContextCompressor. При необходимости ваш движок должен определить свой собственный формат конфигурации, считывая из config.yaml во время инициализации.

Тестирование

from agent.context_engine import ContextEngine

def test_engine_satisfies_abc():
    engine = YourEngine(context_length=200000)
    assert isinstance(engine, ContextEngine)
    assert engine.name == "your-name"

def test_compress_returns_valid_messages():
    engine = YourEngine(context_length=200000)
    msgs = [{"role": "user", "content": "hello"}]
    result = engine.compress(msgs)
    assert isinstance(result, list)
    assert all("role" in m for m in result)

См. tests/agent/test_context_engine.py для полного набора тестов контракта ABC.

См. также