trustgraph/docs/tech-specs/tool-group.ru.md

---
layout: default
title: "TrustGraph Tool Group System"
parent: "Russian (Beta)"
---

# TrustGraph Tool Group System

> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
## Техническая спецификация v1.0

### Краткое описание

Эта спецификация определяет систему группировки инструментов для агентов TrustGraph, которая позволяет осуществлять детальный контроль над тем, какие инструменты доступны для конкретных запросов. Система вводит фильтрацию инструментов на основе групп с помощью конфигурации и указания на уровне запроса, что обеспечивает более строгие границы безопасности, управление ресурсами и функциональное разделение возможностей агентов.

### 1. Обзор

#### 1.1 Описание проблемы

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

**Риск безопасности**: Чувствительные инструменты (например, изменение данных) доступны даже для запросов только для чтения.
**Неэффективное использование ресурсов**: Сложные инструменты загружаются даже тогда, когда простые запросы не требуют их.
**Функциональная путаница**: Агенты могут выбирать неподходящие инструменты, когда существуют более простые альтернативы.
**Изоляция для многопользовательских сред**: Различным группам пользователей требуется доступ к разным наборам инструментов.

#### 1.2 Обзор решения

Система группировки инструментов включает в себя:

1. **Классификация по группам**: Инструменты помечаются принадлежностью к группам во время конфигурации.
2. **Фильтрация на уровне запроса**: AgentRequest указывает, какие группы инструментов разрешены.
3. **Принудительное исполнение во время выполнения**: Агенты имеют доступ только к инструментам, соответствующим запрошенным группам.
4. **Гибкая группировка**: Инструменты могут принадлежать к нескольким группам для сложных сценариев.

### 2. Изменения схемы

#### 2.1 Расширение схемы конфигурации инструмента

Существующая схема конфигурации инструмента расширена с помощью поля `group`:

**До:**
```json
{
  "name": "knowledge-query",
  "type": "knowledge-query", 
  "description": "Query the knowledge graph"
}
```

**После:**
```json
{
  "name": "knowledge-query",
  "type": "knowledge-query",
  "description": "Query the knowledge graph",
  "group": ["read-only", "knowledge", "basic"]
}
```

**Спецификация поля группы:**
`group`: Array(String) - Список групп, к которым принадлежит этот инструмент.
**Необязательно**: Инструменты без поля группы принадлежат к группе "по умолчанию".
**Множественная принадлежность**: Инструменты могут принадлежать к нескольким группам.
**Чувствительность к регистру**: Имена групп должны точно соответствовать строке.

#### 2.1.2 Улучшение переходов состояния инструмента

Инструменты могут опционально указывать переходы состояний и доступность, зависящую от состояния:

```json
{
  "name": "knowledge-query",
  "type": "knowledge-query",
  "description": "Query the knowledge graph",
  "group": ["read-only", "knowledge", "basic"],
  "state": "analysis",
  "available_in_states": ["undefined", "research"]
}
```

**Спецификация состояния:**
`state`: String - **Необязательно** - Состояние, в которое система переходит после успешного выполнения инструмента.
`available_in_states`: Array(String) - **Необязательно** - Состояния, в которых этот инструмент доступен.
**Поведение по умолчанию**: Инструменты без `available_in_states` доступны во всех состояниях.
**Переход состояния**: Происходит только после успешного выполнения инструмента.

#### 2.2 Улучшение схемы AgentRequest

Схема `AgentRequest` в `trustgraph-base/trustgraph/schema/services/agent.py` улучшена:

**Текущий AgentRequest:**
`question`: String - Пользовательский запрос.
`plan`: String - План выполнения (может быть удален).
`state`: String - Состояние агента.
`history`: Array(AgentStep) - История выполнения.

**Улучшенный AgentRequest:**
`question`: String - Пользовательский запрос.
`state`: String - Состояние выполнения агента (теперь активно используется для фильтрации инструментов).
`history`: Array(AgentStep) - История выполнения.
`group`: Array(String) - **НОВОЕ** - Группы инструментов, разрешенные для этого запроса.

**Изменения в схеме:**
**Удалено**: Поле `plan` больше не требуется и может быть удалено (изначально предназначалось для указания инструментов).
**Добавлено**: Поле `group` для указания групп инструментов.
**Улучшено**: Поле `state` теперь контролирует доступность инструментов во время выполнения.

**Поведение полей:**

**Группа (Group):**
**Необязательно**: Если не указано, по умолчанию используется ["default"].
**Пересечение**: Доступны только инструменты, соответствующие хотя бы одной указанной группе.
**Пустой массив**: Ни один инструмент не доступен (агент может использовать только внутренние рассуждения).
**Подстановочный знак**: Специальная группа "*" предоставляет доступ ко всем инструментам.

**Состояние (State):**
**Необязательно**: Если не указано, по умолчанию используется "undefined".
**Фильтрация по состоянию**: Доступны только инструменты, доступные в текущем состоянии.
**Состояние по умолчанию**: Состояние "undefined" позволяет использовать все инструменты (с учетом фильтрации по группам).
**Переходы состояний**: Состояние инструментов может меняться после успешного выполнения.

### 3. Примеры пользовательских групп

Организации могут определять группы, специфичные для домена:

```json
{
  "financial-tools": ["stock-query", "portfolio-analysis"],
  "medical-tools": ["diagnosis-assist", "drug-interaction"],
  "legal-tools": ["contract-analysis", "case-search"]
}
```

### 4. Детали реализации

#### 4.1 Загрузка и фильтрация инструментов

**Фаза конфигурации:**
1. Все инструменты загружаются из конфигурации вместе с их групповыми назначениями.
2. Инструменты, не имеющие явных групповых назначений, назначаются в группу "default".
3. Групповая принадлежность проверяется и сохраняется в реестре инструментов.

**Фаза обработки запросов:**
1. Запрос AgentRequest поступает с опциональной спецификацией группы.
2. Agent фильтрует доступные инструменты на основе пересечения групп.
3. Только соответствующие инструменты передаются в контекст выполнения агента.
4. Agent работает с отфильтрованным набором инструментов на протяжении всего жизненного цикла запроса.

#### 4.2 Логика фильтрации инструментов

**Комбинированная фильтрация по группам и состоянию:**

```
For each configured tool:
  tool_groups = tool.group || ["default"]
  tool_states = tool.available_in_states || ["*"]  // Available in all states
  
For each request:
  requested_groups = request.group || ["default"]
  current_state = request.state || "undefined"
  
Tool is available if:
  // Group filtering
  (intersection(tool_groups, requested_groups) is not empty OR "*" in requested_groups)
  AND
  // State filtering  
  (current_state in tool_states OR "*" in tool_states)
```

**Логика переходов состояний:**

```
After successful tool execution:
  if tool.state is defined:
    next_request.state = tool.state
  else:
    next_request.state = current_request.state  // No change
```

#### 4.3 Точки интеграции агента

**Агент ReAct:**
Фильтрация инструментов происходит в файле agent_manager.py во время создания регистрации инструментов.
Список доступных инструментов фильтруется как по группе, так и по состоянию перед генерацией плана.
Изменения состояния обновляют поле AgentRequest.state после успешного выполнения инструмента.
Следующая итерация использует обновленное состояние для фильтрации инструментов.

**Агент, основанный на оценке уверенности:**
Фильтрация инструментов происходит в файле planner.py во время генерации плана.
Проверка ExecutionStep гарантирует, что используются только инструменты, соответствующие группе и состоянию.
Контроллер потока обеспечивает доступность инструментов во время выполнения.
Изменения состояния управляются контроллером потока между шагами.

### 5. Примеры конфигурации

#### 5.1 Конфигурация инструментов с группами и состояниями

```yaml
tool:
  knowledge-query:
    type: knowledge-query
    name: "Knowledge Graph Query"
    description: "Query the knowledge graph for entities and relationships"
    group: ["read-only", "knowledge", "basic"]
    state: "analysis"
    available_in_states: ["undefined", "research"]
    
  graph-update:
    type: graph-update
    name: "Graph Update"
    description: "Add or modify entities in the knowledge graph"
    group: ["write", "knowledge", "admin"]
    available_in_states: ["analysis", "modification"]
    
  text-completion:
    type: text-completion
    name: "Text Completion"
    description: "Generate text using language models"
    group: ["read-only", "text", "basic"]
    state: "undefined"
    # No available_in_states = available in all states
    
  complex-analysis:
    type: mcp-tool
    name: "Complex Analysis Tool"
    description: "Perform complex data analysis"
    group: ["advanced", "compute", "expensive"]
    state: "results"
    available_in_states: ["analysis"]
    mcp_tool_id: "analysis-server"
    
  reset-workflow:
    type: mcp-tool
    name: "Reset Workflow"
    description: "Reset to initial state"
    group: ["admin"]
    state: "undefined"
    available_in_states: ["analysis", "results"]
```

#### 5.2 Примеры запросов с рабочими процессами, зависящими от состояния.

**Первоначальный запрос на исследование:**
```json
{
  "question": "What entities are connected to Company X?",
  "group": ["read-only", "knowledge"],
  "state": "undefined"
}
```
*Доступные инструменты: knowledge-query, text-completion*
*После knowledge-query: состояние → "analysis"*

**Фаза анализа:**
```json
{
  "question": "Continue analysis based on previous results",
  "group": ["advanced", "compute", "write"],
  "state": "analysis"
}
```
*Доступные инструменты: complex-analysis, graph-update, reset-workflow*
*После complex-analysis: состояние → "results"*

**Фаза результатов:**
```json
{
  "question": "What should I do with these results?",
  "group": ["admin"],
  "state": "results"
}
```
*Доступные инструменты: только reset-workflow*
*После выполнения reset-workflow: состояние → "undefined"*

**Пример рабочего процесса - Полный цикл:**
1. **Начало (undefined):** Используйте knowledge-query → переходы в состояние "analysis"
2. **Состояние анализа:** Используйте complex-analysis → переходы в состояние "results"
3. **Состояние результатов:** Используйте reset-workflow → возврат в состояние "undefined"
4. **Возврат к началу:** Все начальные инструменты снова доступны

### 6. Вопросы безопасности

#### 6.1 Интеграция с контролем доступа

**Фильтрация на уровне шлюза:**
Шлюз может применять ограничения для групп на основе прав доступа пользователя
Предотвращение повышения привилегий путем манипулирования запросами
Журнал аудита включает запрошенные и предоставленные группы инструментов

**Пример логики шлюза:**
```
user_permissions = get_user_permissions(request.user_id)
allowed_groups = user_permissions.tool_groups
requested_groups = request.group

# Validate request doesn't exceed permissions
if not is_subset(requested_groups, allowed_groups):
    reject_request("Insufficient permissions for requested tool groups")
```

#### 6.2 Аудит и мониторинг

**Расширенный журнал аудита:**
Регистрировать запрошенные группы инструментов и начальное состояние для каждого запроса.
Отслеживать переходы состояний и использование инструментов по принадлежности к группе.
Мониторить попытки несанкционированного доступа к группам и недопустимые переходы состояний.
Оповещать об необычных шаблонах использования групп или подозрительных рабочих процессах состояний.

### 7. Стратегия миграции

#### 7.1 Обратная совместимость

**Этап 1: Аддитивные изменения**
Добавить необязательное поле `group` в конфигурации инструментов.
Добавить необязательное поле `group` в схему AgentRequest.
Поведение по умолчанию: Все существующие инструменты принадлежат к группе "default".
Существующие запросы без поля группы используют группу "default".

**Сохранение существующего поведения:**
Инструменты без конфигурации группы продолжают работать (группа "default").
Инструменты без конфигурации состояния доступны во всех состояниях.
Запросы без указания группы получают доступ ко всем инструментам (группа "default").
Запросы без указания состояния используют состояние "не определено" (доступны все инструменты).
Отсутствуют изменения, нарушающие работу существующих развертываний.

### 8. Мониторинг и наблюдаемость

#### 8.1 Новые метрики

**Использование групп инструментов:**
`agent_tool_group_requests_total` - Счетчик запросов по группе.
`agent_tool_group_availability` - Показатель количества доступных инструментов для каждой группы.
`agent_filtered_tools_count` - Гистограмма количества инструментов после фильтрации по группе и состоянию.

**Метрики рабочих процессов состояний:**
`agent_state_transitions_total` - Счетчик переходов состояний по инструменту.
`agent_workflow_duration_seconds` - Гистограмма времени, проведенного в каждом состоянии.
`agent_state_availability` - Показатель количества доступных инструментов для каждого состояния.

**Метрики безопасности:**
`agent_group_access_denied_total` - Счетчик несанкционированного доступа к группам.
`agent_invalid_state_transition_total` - Счетчик недопустимых переходов состояний.
`agent_privilege_escalation_attempts_total` - Счетчик подозрительных запросов.

#### 8.2 Улучшения ведения журнала

**Ведение журнала запросов:**
```json
{
  "request_id": "req-123",
  "requested_groups": ["read-only", "knowledge"],
  "initial_state": "undefined",
  "state_transitions": [
    {"tool": "knowledge-query", "from": "undefined", "to": "analysis", "timestamp": "2024-01-01T10:00:01Z"}
  ],
  "available_tools": ["knowledge-query", "text-completion"],
  "filtered_by_group": ["graph-update", "admin-tool"],
  "filtered_by_state": [],
  "execution_time": "1.2s"
}
```

### 9. Стратегия тестирования

#### 9.1 Юнит-тесты

**Логика фильтрации инструментов:**
Расчет пересечений тестовых групп
Логика фильтрации на основе состояния теста
Проверка назначения групп и состояний по умолчанию
Тестирование поведения групп с подстановочными знаками
Проверка обработки пустых групп
Тестирование сценариев комбинированной фильтрации групп и состояний

**Проверка конфигурации:**
Тестирование загрузки инструментов с различными конфигурациями групп и состояний
Проверка валидации схемы для неверных спецификаций групп и состояний
Тестирование обратной совместимости с существующими конфигурациями
Проверка определений и циклов переходов состояний

#### 9.2 Интеграционные тесты

**Поведение агента:**
Проверка того, что агенты видят только инструменты, отфильтрованные по группам и состояниям
Тестирование выполнения запросов с различными комбинациями групп
Тестирование переходов состояний во время выполнения агентом
Проверка обработки ошибок, когда ни один инструмент недоступен
Тестирование прогресса рабочего процесса через несколько состояний

**Тестирование безопасности:**
Тестирование предотвращения повышения привилегий
Проверка точности журнала аудита
Тестирование интеграции шлюза с разрешениями пользователей

#### 9.3 Сценарии сквозного тестирования

**Многопользовательское использование с рабочими процессами состояний:**
```
Scenario: Different users with different tool access and workflow states
Given: User A has "read-only" permissions, state "undefined"
  And: User B has "write" permissions, state "analysis"
When: Both request knowledge operations
Then: User A gets read-only tools available in "undefined" state
  And: User B gets write tools available in "analysis" state
  And: State transitions are tracked per user session
  And: All usage and transitions are properly audited
```

**Прогрессия состояний рабочего процесса:**
```
Scenario: Complete workflow execution
Given: Request with groups ["knowledge", "compute"] and state "undefined"
When: Agent executes knowledge-query tool (transitions to "analysis")
  And: Agent executes complex-analysis tool (transitions to "results")
  And: Agent executes reset-workflow tool (transitions to "undefined")
Then: Each step has correctly filtered available tools
  And: State transitions are logged with timestamps
  And: Final state allows initial workflow to repeat
```

### 10. Соображения производительности

#### 10.1 Влияние загрузки инструментов

**Загрузка конфигурации:**
Метаданные группы и состояния загружаются один раз при запуске
Минимальные накладные расходы памяти на каждый инструмент (дополнительные поля)
Отсутствие влияния на время инициализации инструмента

**Обработка запросов:**
Объединенная фильтрация группы+состояния выполняется один раз для каждого запроса
Сложность O(n), где n = количество настроенных инструментов
Переходы состояний добавляют минимальные накладные расходы (назначение строки)
Незначительное влияние для типичного количества инструментов (< 100)

#### 10.2 Стратегии оптимизации

**Предварительно вычисленные наборы инструментов:**
Кэширование наборов инструментов по комбинации группа+состояние
Избежание повторной фильтрации для распространенных шаблонов группы/состояния
Компромисс между памятью и вычислениями для часто используемых комбинаций

**Отложенная загрузка:**
Загрузка реализаций инструментов только при необходимости
Уменьшение времени запуска для развертываний с большим количеством инструментов
Динамическая регистрация инструментов на основе требований группы

### 11. Будущие улучшения

#### 11.1 Динамическое назначение групп

**Группировка, учитывающая контекст:**
Назначение инструментов группам на основе контекста запроса
Доступность групп во времени (только в рабочее время)
Ограничения групп на основе нагрузки (дорогие инструменты при низком использовании)

#### 11.2 Иерархии групп

**Вложенная структура групп:**
```json
{
  "knowledge": {
    "read": ["knowledge-query", "entity-search"],
    "write": ["graph-update", "entity-create"]
  }
}
```

#### 11.3 Рекомендации по инструментам

**Предложения, основанные на группах:**
Предлагать оптимальные группы инструментов для типов запросов.
Учиться на основе моделей использования для улучшения рекомендаций.
Предоставлять резервные группы, когда предпочитаемые инструменты недоступны.

### 12. Открытые вопросы

1. **Проверка групп**: Должны ли недопустимые имена групп в запросах вызывать критические ошибки или предупреждения?

2. **Обнаружение групп**: Должна ли система предоставлять API для перечисления доступных групп и их инструментов?

3. **Динамические группы**: Должны ли группы быть настраиваемыми во время выполнения или только при запуске?

4. **Наследование групп**: Должны ли инструменты наследовать группы от своих родительских категорий или реализаций?

5. **Мониторинг производительности**: Какие дополнительные метрики необходимы для эффективного отслеживания использования инструментов на основе групп?

### 13. Заключение

Система групп инструментов обеспечивает:

**Безопасность**: Гранулярный контроль доступа к возможностям агента.
**Производительность**: Снижение накладных расходов на загрузку и выбор инструментов.
**Гибкость**: Многомерная классификация инструментов.
**Совместимость**: Бесшовная интеграция с существующими архитектурами агентов.

Эта система позволяет развертываниям TrustGraph лучше управлять доступом к инструментам, улучшать границы безопасности и оптимизировать использование ресурсов, сохраняя полную обратную совместимость с существующими конфигурациями и запросами.