mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
128 lines
9.8 KiB
Markdown
128 lines
9.8 KiB
Markdown
---
|
||
layout: default
|
||
title: "Спецификация аргументов для инструмента MCP"
|
||
parent: "Russian (Beta)"
|
||
---
|
||
|
||
# Спецификация аргументов для инструмента MCP
|
||
|
||
> **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.
|
||
|
||
## Обзор
|
||
**Имя функции**: Поддержка аргументов для инструмента MCP
|
||
**Автор**: Claude Code Assistant
|
||
**Дата**: 21.08.2025
|
||
**Статус**: Завершено
|
||
|
||
### Краткое описание
|
||
|
||
Позволить агентам ReACT использовать инструменты MCP (Протокол контекста модели) с правильно определенными аргументами, добавив поддержку спецификации аргументов в конфигурацию инструмента MCP, аналогично тому, как работают инструменты с шаблонами запросов.
|
||
|
||
### Проблема
|
||
|
||
В настоящее время инструменты MCP в фреймворке агента ReACT не могут указывать ожидаемые аргументы. Метод `McpToolImpl.get_arguments()` возвращает пустой список, заставляя LLM угадывать правильную структуру параметров, основываясь только на именах и описаниях инструментов. Это приводит к:
|
||
- Ненадежным вызовам инструментов из-за угадывания параметров
|
||
- Плохой пользовательской опыту, когда инструменты не работают из-за неправильных аргументов
|
||
- Отсутствию проверки параметров инструментов перед выполнением
|
||
- Отсутствия документации параметров в запросах агента
|
||
|
||
### Цели
|
||
|
||
- [ ] Разрешить конфигурации инструментов MCP указывать ожидаемые аргументы (имя, тип, описание)
|
||
- [ ] Обновить менеджер агентов, чтобы он предоставлял аргументы инструментов MCP LLM через запросы
|
||
- [ ] Сохранить обратную совместимость с существующими конфигурациями инструментов MCP
|
||
- [ ] Поддерживать проверку аргументов, аналогичную инструментам с шаблонами запросов
|
||
|
||
### Нецелевые области
|
||
- Динамическое обнаружение аргументов от серверов MCP (будущее улучшение)
|
||
- Проверка типов аргументов за пределами базовой структуры
|
||
- Сложные схемы аргументов (вложенные объекты, массивы)
|
||
|
||
## Предыстория и контекст
|
||
|
||
### Текущее состояние
|
||
Инструменты MCP настраиваются в системе агента ReACT с минимальными метаданными:
|
||
```json
|
||
{
|
||
"type": "mcp-tool",
|
||
"name": "get_bank_balance",
|
||
"description": "Получить баланс банковского счета",
|
||
"mcp-tool": "get_bank_balance"
|
||
}
|
||
```
|
||
Метод `McpToolImpl.get_arguments()` возвращает `[]`, поэтому LLM не получают никаких указаний по аргументам в своих запросах.
|
||
|
||
### Ограничения
|
||
|
||
1. **Отсутствие спецификации аргументов**: Инструменты MCP не могут определять ожидаемые параметры
|
||
2. **Угадывание параметров LLM**: Агенты должны выводить параметры из имен/описаний инструментов
|
||
3. **Отсутствие информации в запросах**: Запросы агента не содержат деталей аргументов для инструментов MCP
|
||
4. **Отсутствие проверки**: Неправильные параметры обнаруживаются только во время выполнения инструмента MCP
|
||
|
||
### Связанные компоненты
|
||
- **trustgraph-flow/agent/react/service.py**: Загрузка конфигурации инструментов и создание AgentManager
|
||
- **trustgraph-flow/agent/react/tools.py**: Реализация McpToolImpl
|
||
- **trustgraph-flow/agent/react/agent_manager.py**: Генерация запросов с аргументами инструментов
|
||
- **tg-invoke-mcp-tool**: Клиентские инструменты для управления инструментами MCP
|
||
- **Workbench**: Внешний UI для конфигурации инструментов агента
|
||
|
||
## Требования
|
||
|
||
### Функциональные требования
|
||
|
||
1. **Конфигурация аргументов для инструмента MCP**: Конфигурации инструментов MCP ДОЛЖНЫ поддерживать необязательный массив `arguments` с полями `name`, `type` и `description`
|
||
2. **Предоставление аргументов**: `McpToolImpl.get_arguments()` ДОЛЖЕН возвращать сконфигурированные аргументы, а не пустой список
|
||
3. **Интеграция с запросами**: Запросы агента ДОЛЖНЫ содержать детали аргументов инструментов MCP, когда аргументы указаны
|
||
4. **Обратная совместимость**: Существующие конфигурации инструментов MCP без аргументов ДОЛЖНЫ продолжать работать
|
||
5. **Поддержка CLI**: Существующие CLI инструменты tg-invoke-mcp-tool поддерживают аргументы (уже реализовано)
|
||
|
||
### Нефункциональные требования
|
||
1. **Обратная совместимость**: Без каких-либо изменений для существующих конфигураций инструментов MCP
|
||
2. **Производительность**: Отсутствие существенного влияния на генерацию запросов агента
|
||
3. **Согласованность**: Обработка аргументов ДОЛЖНА соответствовать шаблонам инструментов с шаблонами запросов
|
||
|
||
### Истории пользователей
|
||
|
||
1. Как **разработчик агента**, я хочу указывать аргументы инструментов MCP в конфигурации, чтобы LLM могли вызывать инструменты с правильными параметрами
|
||
2. Как **пользователь Workbench**, я хочу настраивать аргументы инструментов MCP в UI, чтобы агенты использовали инструменты правильно
|
||
3. Как **LLM в ReACT агенте**, я хочу видеть спецификации аргументов инструментов в запросах, чтобы я мог предоставлять правильные параметры
|
||
|
||
## Проектирование
|
||
|
||
### Высокоуровневая архитектура
|
||
Расширить конфигурацию инструмента MCP, чтобы соответствовать шаблону инструмента с шаблоном запросов, путем:
|
||
1. Добавления необязательного массива `arguments` в конфигурацию инструментов MCP
|
||
2. Модификации `McpToolImpl` для приема и возврата сконфигурированных аргументов
|
||
3. Обновления загрузки конфигурации инструментов для обработки аргументов инструментов MCP
|
||
4. Обеспечения включения информации об аргументах инструментов MCP в запросы агента
|
||
|
||
### Схема конфигурации
|
||
```json
|
||
{
|
||
"type": "mcp-tool",
|
||
"name": "get_bank_balance",
|
||
"description": "Get bank account balance",
|
||
"mcp-tool": "get_bank_balance",
|
||
"arguments": [
|
||
{
|
||
"name": "account_id",
|
||
"type": "string",
|
||
"description": "Bank account identifier"
|
||
},
|
||
{
|
||
"name": "date",
|
||
"type": "string",
|
||
"description": "Date for balance query (optional, format: YYYY-MM-DD)"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Поток данных
|
||
1. **Загрузка конфигурации**: Конфигурация инструмента MCP с аргументами загружается с помощью `on_tools_config()`
|
||
2. **Создание инструмента**: Аргументы парсятся и передаются в `McpToolImpl` через конструктор
|
||
3. **Генерация запросов**: `agent_manager.py` вызывает `tool.arguments` для включения в LLM запросы
|
||
4. **Вызов инструмента**: LLM предоставляет параметры, которые передаются инструменту MCP без изменений
|
||
|
||
### Изменения API
|
||
Нет изменений API - это чисто внутренняя конфигурация и обработка аргументов
|