mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 08:56:21 +02:00
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 - это чисто внутренняя конфигурация и обработка аргументов
|