mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 17:06:22 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
499
docs/tech-specs/ru/tool-group.ru.md
Normal file
499
docs/tech-specs/ru/tool-group.ru.md
Normal file
|
|
@ -0,0 +1,499 @@
|
|||
---
|
||||
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 лучше управлять доступом к инструментам, улучшать границы безопасности и оптимизировать использование ресурсов, сохраняя полную обратную совместимость с существующими конфигурациями и запросами.
|
||||
Loading…
Add table
Add a link
Reference in a new issue