агенты: добавить поиск инструментов по каталогу
This commit is contained in:
@@ -206,6 +206,7 @@ Auth profile хранит ссылки на secrets и способ примен
|
||||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish`
|
||||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive`
|
||||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings`
|
||||
- `POST /api/admin/workspaces/{workspace_id}/agents/tool-search/preview`
|
||||
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`
|
||||
|
||||
Пример создания агента:
|
||||
@@ -223,6 +224,36 @@ curl https://crank.example.com/api/admin/workspaces/ws_default/agents \
|
||||
}'
|
||||
```
|
||||
|
||||
Привязки и политика доступа сохраняются одной атомарной операцией:
|
||||
|
||||
```json
|
||||
{
|
||||
"bindings": [
|
||||
{
|
||||
"operation_id": "op_01",
|
||||
"operation_version": 1,
|
||||
"tool_name": "create_invoice",
|
||||
"tool_title": "Создать счёт",
|
||||
"enabled": true
|
||||
}
|
||||
],
|
||||
"tool_selection_policy": {
|
||||
"mode": "search",
|
||||
"groups": [
|
||||
{
|
||||
"id": "finance",
|
||||
"name": "Расчёты",
|
||||
"description": "Счета, платежи и возвраты",
|
||||
"tool_names": ["create_invoice"]
|
||||
}
|
||||
],
|
||||
"search": { "max_results": 8 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Старый формат тела из одного массива привязок поддерживается и сохраняет текущую политику агента. Предварительная проверка принимает те же `bindings` и `tool_selection_policy`, а также `query` и необязательный `group_ids`.
|
||||
|
||||
## Agent API keys
|
||||
|
||||
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/platform-api-keys`
|
||||
|
||||
@@ -122,6 +122,17 @@ curl https://crank.example.com/mcp/v1/default/currency-rates \
|
||||
frankfurter_latest_rate
|
||||
```
|
||||
|
||||
Если опубликованная версия агента использует подбор по запросу, `tools/list` содержит только:
|
||||
|
||||
```text
|
||||
search_tools
|
||||
call_tool
|
||||
```
|
||||
|
||||
`search_tools` принимает текст задачи, необязательные идентификаторы разделов и предел результатов. Ответ содержит полные входные схемы найденных инструментов и `catalog_revision`.
|
||||
|
||||
`call_tool` принимает имя найденного инструмента, его аргументы и полученную `catalog_revision`. Если за время между поиском и вызовом опубликована новая версия агента, вызов отклоняется с кодом `catalog_revision_changed`: клиент должен повторить поиск.
|
||||
|
||||
## Пример `tools/call`
|
||||
|
||||
```bash
|
||||
@@ -226,6 +237,10 @@ curl https://crank.example.com/mcp/v1/default/sales/approvals/<approval_id>/deny
|
||||
|
||||
MCP-клиент видит только опубликованные операции, которые привязаны к опубликованному агенту.
|
||||
|
||||
Способ выдачи, разделы и предел результатов входят в версионируемый контракт агента. Прямой режим не меняет обычный MCP-поток. Режим подбора скрывает исходные инструменты за совместимыми метаинструментами `search_tools` и `call_tool`; динамическое изменение `tools/list` и специальные расширения клиента не требуются.
|
||||
|
||||
Базовый поиск использует BM25 по имени, заголовку, описанию инструмента и описаниям его разделов. Фильтр по разделу применяется до ранжирования. По умолчанию возвращается не более восьми результатов, допустимый предел — от одного до двадцати.
|
||||
|
||||
Черновики операций не попадают в MCP-каталог. Если два пользователя работают в одном workspace, один может редактировать черновик, а второй публиковать агента. В опубликованный каталог попадут только опубликованные версии операций.
|
||||
|
||||
При каждом обновлении каталога Crank анализирует фактические определения `tools/list` и записывает в структурированный журнал:
|
||||
|
||||
+1
-1
@@ -156,7 +156,7 @@ Crank возвращает структурированные ошибки. MCP-
|
||||
|
||||
Crank измеряет опубликованный каталог по тому же компактному JSON, который возвращается в `tools/list`. В расчёт входят имя, заголовок, описание, входная JSON-схема и добавляемое Crank описание подтверждения опасной операции. Для сравнения используется независимая от конкретной модели консервативная оценка: один токен на три байта UTF-8. Это не счётчик токенов конкретного поставщика, а стабильная инженерная метрика для поиска регрессий.
|
||||
|
||||
Рекомендуемый бюджет одного агентского каталога — не более 4096 оценочных токенов. Превышение не блокирует публикацию, потому что допустимый объём зависит от модели, но создаёт предупреждение. Сначала сокращайте лишние описания и схемы. Если инструменты решают разные задачи, разделяйте их между специализированными агентами. Выбор нужного агента и постепенное раскрытие каталогов выполняет оркестратор Drivetrain, а не Crank.
|
||||
Рекомендуемый бюджет одного агентского каталога — не более 4096 оценочных токенов. Превышение не блокирует публикацию, потому что допустимый объём зависит от модели, но создаёт предупреждение. Сначала сокращайте лишние описания и схемы. Если инструменты решают разные задачи, разделяйте их между специализированными агентами. Если большой каталог является осознанным бизнес-требованием, включайте в версии агента режим подбора по запросу и проверяйте его на характерных задачах. Drivetrain выбирает нужного агента и строит связи между агентами, но не подменяет внутренний поиск по каталогу одного агента.
|
||||
|
||||
## Проверочный список
|
||||
|
||||
|
||||
@@ -58,6 +58,15 @@
|
||||
- делать названия и описания инструментов однозначными;
|
||||
- публиковать агента только после проверки операций.
|
||||
|
||||
В карточке агента явно выбирается способ доступа к каталогу:
|
||||
|
||||
- **Показывать сразу** — `tools/list` возвращает все привязанные инструменты. Это основной режим для небольшого каталога.
|
||||
- **Подбирать по запросу** — `tools/list` возвращает только `search_tools` и `call_tool`. Модель сначала находит несколько подходящих инструментов, затем вызывает выбранный через прокси-инструмент.
|
||||
|
||||
В режиме подбора каталог можно разделить на именованные разделы. Название и описание раздела видит модель, а один инструмент можно включить в несколько разделов. Раздел ограничивает область поиска, но поиск без раздела всегда охватывает весь каталог.
|
||||
|
||||
Перед сохранением можно ввести пробную задачу и проверить результат подбора. Эта проверка использует тот же алгоритм, что и MCP-сервер.
|
||||
|
||||
## API ключи
|
||||
|
||||
API-ключ выдается на конкретного агента. В Community есть два режима ключей.
|
||||
|
||||
Reference in New Issue
Block a user