Справочник API: агенты, MCP и навыки
Управление агентами, службами MCP и их учётными данными, навыками и избранным. Область инструментов агента и настройка утверждения вызовов поддерживаются через эту группу эндпоинтов.
Агенты (/api/v1/agents)
Чтение: Viewer+ (API key read_agents/manage_agents/chat/full); запись: создатель ИЛИ Admin+ (API key manage_agents/full); встроенный агент (is_builtin=true) всегда требует Admin+.
GET /api/v1/agents/placeholders
Назначение: определения плейсхолдеров промпта (должны быть зарегистрированы раньше /:id). Права: Viewer+.
Ответ: 200 {"success":true,"data":{"all":{...},"system_prompt":{...},"agent_system_prompt":{...},"context_template":{...},"rewrite_system_prompt":{...},"rewrite_prompt":{...},"fallback_prompt":{...}}}
curl $BASE/api/v1/agents/placeholders -H "Authorization: Bearer $TOKEN"GET /api/v1/agents/type-presets
Назначение: предустановки типов агентов интеллектуального рассуждения (rag-qa / wiki-qa / hybrid / custom и т. д.). Права: Viewer+.
Ответ: 200 {"success":true,"data":[{type,system_prompt,allowed_tools,kb_compatibility}]}
curl $BASE/api/v1/agents/type-presets -H "Authorization: Bearer $TOKEN"GET /api/v1/agents/tools
Назначение: каталог встроенных инструментов, доступных агенту; права Viewer+. Ответ {"success":true,"data":{"tools":[...],"default_tools":[...],"switch_managed_tools":[...]}}; каждый инструмент несёт требования к возможностям базы знаний requirement.any_of / all_of, по которым редактор определяет, доступен ли он для выбора.
При создании или обновлении неизвестное название инструмента возвращает 400; уже сохранённые неизвестные элементы сохраняются, и в верхнем уровне ответа allowed_tools_warnings.kept_unknown перечисляются эти названия. Инструменты, управляемые отдельными переключателями, и устаревшие инструменты-предки без преемника удаляются из списка, удалённые элементы возвращаются в allowed_tools_warnings.dropped. Старые названия инструментов поиска отображаются на их преемники, дубликаты устраняются.
POST /api/v1/agents
Назначение: создание пользовательского агента. Права: Contributor+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да (binding:"required") | имя |
description | string | нет | описание |
avatar | string | нет | аватар/emoji |
config | object | нет | конфигурация агента (types.CustomAgentConfig, см. ниже) |
Основные поля config: agent_mode (quick-answer/smart-reasoning, при пропуске — smart-reasoning), agent_type (rag-qa/wiki-qa/hybrid-rag-wiki/data-analysis/custom), system_prompt, model_id, temperature (0-2, при недопустимом значении code 2103), max_iterations (1-20, при недопустимом значении code 2102), allowed_tools (при пропуске/null используются инструменты по умолчанию; явный [] — не выбирать встроенные инструменты; интернет, память, MCP и песочница регистрируются по отдельным настройкам), mcp_selection_mode/mcp_services, skills_selection_mode, kb_selection_mode/knowledge_bases, web_search_enabled, question_suggestions и т. д. (полное определение см. в internal/types/custom_agent.go).
Ответ: 201 {"success":true,"data":{id,name,description,avatar,is_builtin,created_by,config,creator_name,...}}
curl -X POST $BASE/api/v1/agents -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"Помощник поддержки","config":{"agent_mode":"quick-answer","kb_selection_mode":"selected","knowledge_bases":["kb-1"]}}'GET /api/v1/agents
Назначение: список агентов (включая встроенные). Права: Viewer+. Параметры запроса: creator (mine/others, необязательно).
Ответ: 200 {"success":true,"data":[Agent],"disabled_own_agent_ids":[...]}
curl $BASE/api/v1/agents -H "X-API-Key: $API_KEY"GET /api/v1/agents/:id
Назначение: подробности агента. Права: Viewer+.
Ответ: 200 {"success":true,"data":{Agent}}
curl $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/agents/:id
Назначение: обновление агента. Права: создатель ИЛИ Admin+. Тело запроса: name/description/avatar/config. name обязателен; пропущенный avatar сохраняет прежний аватар; config заменяется целиком — пропущенные элементы конфигурации не сохраняют прежние значения, для изменения отдельных настроек используйте PATCH. Если агент уже опубликован в организации, новые базы знаний, добавляемые в область, должны быть доступны вызывающему для публикации (создатель базы знаний или Admin+; смена на all требует Admin+), иначе 403.
Ответ: 200 {"success":true,"data":{Agent}}
curl -X PUT $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"Помощник поддержки","description":"Обновлённое описание","config":{...}}'PATCH /api/v1/agents/:id
Назначение: частичное обновление агента — изменяются только присутствующие в запросе поля, остальная конфигурация (включая аватар) остаётся без изменений. Права те же, что у PUT: создатель ИЛИ Admin+; API key manage_agents/full. Переиспользует проверки PUT (включая правило области общедоступных баз знаний из организации, см. выше) и дополнительно проверяет названия навыков.
Поля тела запроса (все необязательны):
| Поле | Тип | Описание |
|---|---|---|
name | string | Название, не может состоять только из пробелов |
description | string | Описание |
agent_mode | string | quick-answer / smart-reasoning. MCP и навыки работают только в smart-reasoning; переключение в этот режим включает многоцикловый диалог |
system_prompt | string | Полный системный промпт (полная замена) |
model_id | string | ID модели диалога |
kb_selection_mode | string | all / selected / none |
knowledge_bases | string[] | Выбранные ID баз знаний, полная замена; если kb_selection_mode не передан одновременно, режим переключается на selected |
mcp_selection_mode | string | all / selected / none |
mcp_services | string[] | Выбранные ID служб MCP, полная замена; если mcp_selection_mode не передан одновременно, режим переключается на selected |
skills_selection_mode | string | all / selected / none; all и none очищают выбранные названия навыков |
selected_skills | string[] | До 50 названий навыков (не ID), полная замена; если skills_selection_mode не передан одновременно, режим переключается на selected |
web_search_enabled | bool | Включён ли поиск в интернете |
multi_turn_enabled | bool | Включён ли многоцикловый диалог |
Названия навыков берутся из GET /api/v1/skills?sandbox_config_id=<agent.config.sandbox_config_id> и действуют только в режиме smart-reasoning. После PATCH, когда режим selected, все названия должны быть доступными в этом пространстве для этой песочницы; недоступные или неизвестные названия возвращают 400 со списком названий. Если песочница не привязана, установка через PATCH навыков в all или selected (включая передачу только selected_skills) возвращает 400 — сначала выберите песочницу в редакторе агента.
Ответ: 200 {"success":true,"data":{Agent}}; 400 — при недопустимом значении agent_mode или режима выбора, пустом названии, списке навыков длиннее 50 или неудаче проверки навыков выше; 404 — агент не существует.
curl -X PATCH $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"model_id":"model-2","knowledge_bases":["kb-1","kb-2"]}'DELETE /api/v1/agents/:id
Назначение: удаление агента. Права: создатель ИЛИ Admin+.
Ответ: 200 {"success":true,"message":"Agent deleted successfully"}
curl -X DELETE $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/agents/:id/copy
Назначение: копирование агента (копия принадлежит вызывающему). Права: Contributor+. Тело запроса отсутствует.
Ответ: 201 {"success":true,"data":{новый агент}}
curl -X POST $BASE/api/v1/agents/agent-1/copy -H "Authorization: Bearer $TOKEN"GET /api/v1/agents/:id/suggested-questions
Назначение: стартовые предлагаемые вопросы агента (зарегистрированы вне группы, чтобы избежать конфликта с /agents/:id/shares). Права: Viewer+; API key read_agents/manage_agents/chat/full.
| Параметр запроса | Тип | Обязательно | Описание |
|---|---|---|---|
knowledge_base_ids | string | нет | список KB через запятую |
knowledge_ids | string | нет | ID знаний через запятую |
tag_scopes | string | нет | области тегов в виде JSON-массива |
limit | int | нет | максимум 30 |
Ответ: 200 {"success":true,"data":{"questions":[{question,source,knowledge_base_id}]}}
curl "$BASE/api/v1/agents/agent-1/suggested-questions?limit=6" -H "X-API-Key: $API_KEY"Службы MCP (/api/v1/mcp-services)
Интеграция внешних служб инструментов уровня пространства. Чтение: Viewer+; запись/тестирование/политики утверждения: Admin+. API key: manage_mcp_services/full. Handler: internal/handler/mcp_service.go
POST /api/v1/mcp-services
Назначение: создание службы MCP. Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | имя |
description | string | нет | описание старого формата, сохраняется для совместимости; в интерфейсе администрирования редактируется единое поле usage_instructions |
usage_instructions | string | нет | назначение службы, сценарии применения и ключевые ограничения; по ним модель определяет, когда использовать службу; в интерфейсе администрирования заполняется на втором шаге |
enabled | bool | нет | включена ли служба |
transport_type | string | да | sse / http-streamable; stdio отклоняется по соображениям безопасности |
url | *string | нет | URL службы (SSE/HTTP) |
headers | map[string]string | нет | HTTP-заголовки |
auth_config | object | нет | auth_type(api_key/bearer/oauth), api_key_header, custom_headers, scopes, auth_server_metadata_url, client_id (заранее зарегистрированный OAuth-клиент; при пустом значении выполняется динамическая регистрация клиента, пустая строка очищает); секреты и client_secret передаются через подресурс credentials, при создании можно передать в теле запроса |
advanced_config | object | нет | {timeout,retry_count,retry_delay}, по умолчанию 30 секунд / 3 попытки / 1 секунда; при timeout больше 60 секунд также увеличивается окно ожидания одного вызова инструмента этой службы агентом |
stdio_config / env_vars | object | нет | сохраняется только для совместимости со старыми данными; stdio отключён и не действует |
Ответ: 200 {"success":true,"data":{MCPServiceResponse}} (включает credentials:{api_key:{configured},token:{configured},client_secret:{configured}}; для служб с уже синхронизированным каталогом инструментов также добавляется catalog:{tool_count,stale,synced_at})
curl -X POST $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"github","transport_type":"sse","url":"https://mcp.example.com/sse"}'GET /api/v1/mcp-services
Назначение: список служб MCP. Права: Viewer+. Ответ: 200 {"success":true,"data":[MCPServiceResponse]}
| Параметр запроса | Тип | Обязательно | Описание |
|---|---|---|---|
agent_id | string | нет | при одновременной передаче с agent_source_tenant_id выводит список служб MCP, которые может упомянуть через @ этот общий агент |
agent_source_tenant_id | int | нет | ID исходного пространства общего агента, совпадает с одноимённым параметром запроса диалога |
Когда переданы оба параметра, используется путь общего агента: возвращаются только службы, указанные для этого агента в исходном пространстве в режиме selected и включённые (в режимах all/none возвращается пустой список), причём каждый элемент содержит только ID, имя, описание, инструкции по использованию, тип транспорта, состояние включения и сводку каталога инструментов, без URL, заголовков запроса, конфигурации аутентификации и прочих деталей подключения; если вызывающий не имеет права использовать этого агента, возвращается 403. Если передан только один из параметров или ни одного, выводится список служб собственного пространства вызывающего.
curl $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id
Назначение: подробности. Права: Viewer+. Ответ: 200 {"success":true,"data":{MCPServiceResponse}}
curl $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id
Назначение: частичное обновление (семантика map; в auth_config нельзя передавать api_key/token). Права: Admin+. Поля те же, что при создании (все необязательны).
При передаче usage_instructions это должна быть непустая строка без ведущих и завершающих пробелов длиной до 16 000 символов. Если изменяются только подключение или состояние включения, поле можно опустить — исходное значение сохраняется.
Ответ: 200 {"success":true,"data":{MCPServiceResponse}}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"enabled":false}'POST /api/v1/mcp-services/:id/usage-instructions/generate
Назначение: генерация кратких инструкций по использованию на основе синхронизированного и не устаревшего каталога инструментов MCP. Права: Admin+; API key должен иметь manage_mcp_services или full.
Запрос: {"language":"zh-CN"}. Поддерживаются zh-CN, en-US, ja-JP, ko-KR, ru-RU, по умолчанию китайский.
Сначала используется доступная диалоговая модель по умолчанию для пространства, иначе — первая доступная диалоговая модель. Входные данные включают имя службы, описание со стороны сервера и названия и описания включённых инструментов; для OAuth-каталога используется текущая область авторизации пользователя. Подключение к MCP, вызов инструментов и автоматическое сохранение результата генерации не выполняются.
Ответ: 200 {"success":true,"data":{"usage_instructions":"Запрос удалённых журналов по модулю и диапазону времени; при наличии query ID читать соответствующий журнал."}}. Цель генерации — 2–3 коротких предложения, максимум 500 символов; пользователь может отредактировать и сохранить через PUT. Если каталог не синхронизирован, устарел, не содержит включённых инструментов или нет доступной диалоговой модели, возвращается 400.
DELETE /api/v1/mcp-services/:id
Назначение: удаление. Права: Admin+. Ответ: 200 {"success":true,"message":"MCP service deleted successfully"}
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/mcp-services/:id/test
Назначение: проверка подключения (проба внешней службы). Права: Admin+. Ответ: 200 {"success":true,"data":{"success","message","oauth_required","tools":[...],"resources":[...]}}
curl -X POST $BASE/api/v1/mcp-services/mcp-1/test -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/metadata
Назначение: чтение сохранённого каталога инструментов без подключения к источнику. Права: Viewer+; каталог OAuth изолирован по текущему действующему субъекту авторизации.
Ответ: 200 {"success":true,"data":null} означает, что каталог не синхронизирован; при наличии синхронизации data — снимок каталога, включающий информацию о сервере, instructions, tools и время синхронизации. Снимок после изменения конфигурации подключения помечается stale:true и не может использоваться для загрузки инструментов во время выполнения.
curl $BASE/api/v1/mcp-services/mcp-1/metadata -H "Authorization: Bearer $TOKEN"POST /api/v1/mcp-services/:id/metadata/refresh
Назначение: явное подключение к источнику, полная загрузка и атомарное обновление каталога инструментов. Для каталога со статической аутентификацией требуется Admin+; пользователь OAuth может синхронизировать свой каталог (Viewer+). API-ключ должен иметь права управления MCP.
Ответ — обновлённый снимок каталога. При сбое сохраняется исходный снимок; если подключение изменилось во время обновления, возвращается 409; недопустимый/слишком большой каталог или сбой синхронизации с источником — 400; недоступность хранилища метаданных — 503. Ручные инструкции по использованию и политики включения/утверждения отдельных инструментов не перезаписываются.
curl -X POST $BASE/api/v1/mcp-services/mcp-1/metadata/refresh -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/tools
Назначение: список инструментов. Права: Viewer+. Ответ: 200 {"success":true,"data":[{name,description,inputSchema,require_approval}]}
curl $BASE/api/v1/mcp-services/mcp-1/tools -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/resources
Назначение: список ресурсов. Права: Viewer+. Ответ: 200 {"success":true,"data":[{uri,name,description,mimeType}]}
curl $BASE/api/v1/mcp-services/mcp-1/resources -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id/credentials
Назначение: установка ключей (api_key/token/client_secret, поля-указатели, при пропуске сохраняются). Права: Admin+. Handler: internal/handler/mcp_credentials.go
Ответ: 200 {"success":true,"data":{"fields":{"api_key":{"configured"},"token":{"configured"},"client_secret":{"configured"}}}}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"token":"ghp_..."}'DELETE /api/v1/mcp-services/:id/credentials/:field
Назначение: удаление поля учётных данных (api_key, token или client_secret). Права: Admin+. Ответ: 204.
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/credentials/token -H "Authorization: Bearer $TOKEN"GET /api/v1/mcp-services/:id/tool-approvals
Назначение: список политик включения/выключения инструментов и ручного утверждения. Права: Viewer+. Ответ: 200 {"success":true,"data":[{service_id,tool_name,require_approval,enabled,...}]}
curl $BASE/api/v1/mcp-services/mcp-1/tool-approvals -H "Authorization: Bearer $TOKEN"PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name
Назначение: обновление enabled (включение/выключение) и require_approval (ручное утверждение) для инструмента. Права: Admin+. Нужно указать хотя бы одно из двух; пропущенное поле сохраняет исходное значение; при отсутствии записи инструмент по умолчанию включён и не требует утверждения.
Ответ: 200 {"success":true}
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/tool-approvals/create_issue \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"require_approval":true}'MCP OAuth
Handler: internal/handler/mcp_oauth.go
GET /api/v1/mcp-oauth/callback
Назначение: обратный вызов авторизации OAuth третьей стороны (без аутентификации, аутентификация по одноразовому параметру state; зарегистрирован вне группы /mcp-services). Параметры запроса: code, state, error.
Ответ: 302 с перенаправлением на фронтенд (успех #mcp_oauth_result=success, ошибка #mcp_oauth_error=<code>).
curl -i "$BASE/api/v1/mcp-oauth/callback?code=xxx&state=yyy"POST /api/v1/mcp-services/:id/oauth/authorize-url
Назначение: генерация URL авторизации уровня пользователя. Права: Viewer+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
redirect_uri | string | да | URL обратного вызова бэкенда (абсолютный адрес) |
frontend_redirect | string | нет | перенаправление фронтенда после обратного вызова (по умолчанию /) |
Ответ: 200 {"success":true,"data":{"authorization_url","authorization_attempt"}}
curl -X POST $BASE/api/v1/mcp-services/mcp-1/oauth/authorize-url -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"redirect_uri":"'$BASE'/api/v1/mcp-oauth/callback"}'POST /api/v1/mcp-services/:id/oauth/assertion
Назначение: получение OAuth-токена для себя через JWT Bearer-авторизацию (RFC 7523) без перенаправления в браузере. Подходит для сценариев, когда aihelpme.ru развёрнут за другим приложением, которое отвечает за вход и вызывает aihelpme.ru от имени пользователя: такое приложение выпускает утверждение от текущего пользователя (например, ID-JAG, используемый в MCP Enterprise-Managed Authorization), aihelpme.ru передаёт его без изменений авторизационному серверу на проверку. Используется уже зарегистрированный для службы OAuth-клиент (динамическая регистрация клиента не выполняется; если клиента ещё нет, возвращается 400). Полученный токен совпадает с токеном, сохранённым при авторизации через обратный вызов; последующие обновление, проверка состояния и отзыв не меняются. Права: Viewer+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
assertion | string | Да | Утверждение JWT, передаваемое авторизационному серверу (лимит тела запроса 16 КиБ) |
Ответ: 200, data совпадает с oauth/status. Если авторизационный сервер отклоняет утверждение (4xx либо 2xx с OAuth error в теле), возвращается 400 с OAuth-кодом ошибки; 5xx авторизационного сервера или сетевая ошибка возвращают 500.
curl -X POST $BASE/api/v1/mcp-services/mcp-1/oauth/assertion -H "X-API-Key: $API_KEY" \
-H "X-External-User-ID: user-1" -H 'Content-Type: application/json' -d '{"assertion":"'$ASSERTION'"}'GET /api/v1/mcp-services/:id/oauth/status
Назначение: запрос состояния собственной авторизации. Права: Viewer+. Параметры запроса: authorization_attempt (необязательно).
Ответ: 200 {"success":true,"data":{"authorized","state":"authorized|pending","refresh_available","expires_at"}}
curl $BASE/api/v1/mcp-services/mcp-1/oauth/status -H "Authorization: Bearer $TOKEN"DELETE /api/v1/mcp-services/:id/oauth/token
Назначение: отзыв собственного токена OAuth. Права: Viewer+. Ответ: 204.
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/oauth/token -H "Authorization: Bearer $TOKEN"Эндпоинты MCP Server (/api/v1/mcp-endpoints)
Управление эндпоинтами MCP, публикуемыми текущим пространством наружу; внешние клиенты MCP подключаются к /mcp/:endpoint_id. Чтение: Viewer+; запись: Admin+. API key: manage_channels/full. Handler: internal/handler/mcp_endpoint.go. Назначение и описание инструментов см. в Интеграция с MCP.
| Метод | Путь | Описание |
|---|---|---|
| GET | /mcp-endpoints | список эндпоинтов (без токенов) |
| GET | /mcp-endpoints/tools | каталог инструментов: {groups,tools:[{name,group,destructive}],default_tools} |
| POST | /mcp-endpoints | создание; 201, ответ содержит одноразовый token |
| GET | /mcp-endpoints/:endpoint_id | подробности |
| PUT | /mcp-endpoints/:endpoint_id | частичное обновление, пропущенные поля сохраняют исходные значения |
| DELETE | /mcp-endpoints/:endpoint_id | удаление; клиенты, использующие этот эндпоинт, немедленно теряют доступ |
| POST | /mcp-endpoints/:endpoint_id/rotate-token | ротация токена, ответ содержит новый token, старый токен немедленно теряет силу |
Поля запроса (одинаковы при создании и обновлении, все необязательны):
| Поле | Тип | Описание |
|---|---|---|
name | string | имя, обязательно при создании |
description | string | описание |
enabled | bool | по умолчанию true; после отключения подключение возвращает 403 |
knowledge_base_ids | string[] | доступные базы знаний, пустой массив означает все в пространстве |
tools | string[] | предоставляемые инструменты, не менее одного; если при создании опущено, используется default_tools (все инструменты только для чтения) |
default_agent_id | string | агент, используемый ask; пустое значение — встроенный быстрый ответ; внутренние встроенные агенты выбрать нельзя |
rate_limit_per_minute | int | максимальное число вызовов инструментов в минуту: 0 или пропуск означает 60, максимум 6000 |
Ответ data имеет вид {id,tenant_id,name,description,enabled,token_hint,knowledge_base_ids,tools,default_agent_id,rate_limit_per_minute,path,last_used_at,created_at,updated_at}; при создании и ротации дополнительно содержит token. При вызове с ограниченным API-ключом требуемые эндпоинту права на базы знаний и инструменты не должны выходить за пределы этого ключа, иначе 403.
curl -X POST $BASE/api/v1/mcp-endpoints -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Помощник по документации продукта","knowledge_base_ids":["kb-1"],"tools":["search_knowledge","read_document","ask"]}'Взаимодействие во время выполнения агента (/api/v1/agent)
Ручное утверждение и восстановление OAuth во время диалога; все права Viewer+ (контекст есть только у инициатора сессии), API key по умолчанию отклоняется.
POST /api/v1/agent/tool-approvals/:pending_id
Назначение: вынесение решения по ожидающему утверждения вызову инструмента. Handler: ResolveToolApproval в internal/handler/mcp_service.go.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
decision | string | да (binding:"required") | approve / reject |
modified_args | JSON | нет | изменённые параметры инструмента |
reason | string | нет | причина |
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/agent/tool-approvals/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"decision":"approve"}'POST /api/v1/agent/mcp-oauth-resolutions/:pending_id
Назначение: возобновление работы агента, приостановленной из-за MCP OAuth. Handler: internal/handler/mcp_oauth.go
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
service_id | string | да (binding:"required") | ID службы MCP |
decision | string | нет | authorize (по умолчанию) / cancel |
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"service_id":"mcp-1"}'POST /api/v1/agent/mcp-oauth-resolutions/:pending_id/cancel
Назначение: отмена приостановленного процесса OAuth. Тело запроса отсутствует.
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1/cancel -H "Authorization: Bearer $TOKEN"Навыки, песочница и персональные переменные
GET /api/v1/skills?sandbox_config_id=... возвращает названия/описания навыков, доступных при указанной конфигурации, и skills_available; при передаче agent_id + agent_source_tenant_id возвращает результаты по исходному пространству общего агента и его конфигурации песочницы, подробнее см. в API песочницы и навыков. Полный набор эндпоинтов для включения в каталог, установки, шаблонов, прогресса, файлов и персональных переменных см. в API песочницы и навыков.
В config агента добавлено sandbox_config_id; вместе с skills_selection_mode, selected_skills оно определяет доступные навыки. Инструменты shell/файлов регистрируются в соответствии с возможностями бэкенда; старые read_skill / execute_skill_script больше не регистрируются.
Долговременная память
Если memory_enabled в config агента равно nil, наследуется пространство; false отключает чтение и запись памяти для данного агента. Персональное управление, темы/предпочтения по документам, экспорт и немедленная консолидация — см. в API долговременной памяти; порядок использования — в разделе Долговременная память между сессиями.
Пользовательское избранное (/api/v1/user/favorites)
Хранится в разрезе пользователя (а не создателя ресурса); все права Viewer+, только JWT (API key по умолчанию отклоняется). Handler: internal/handler/user_resource_favorite.go
GET /api/v1/user/favorites
Назначение: список избранного. Параметры запроса: type (обязательно, kb или agent).
Ответ: 200 {"success":true,"data":[{type,id,created_at}]}
curl "$BASE/api/v1/user/favorites?type=kb" -H "Authorization: Bearer $TOKEN"POST /api/v1/user/favorites
Назначение: добавление в избранное. Тело запроса: {"type":"kb|agent","id":"<ID ресурса>"} (оба обязательны).
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/user/favorites -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"kb","id":"kb-1"}'DELETE /api/v1/user/favorites/:type/:id
Назначение: удаление из избранного. Параметры пути: type, id.
Ответ: 200 {"success":true}
curl -X DELETE $BASE/api/v1/user/favorites/kb/kb-1 -H "Authorization: Bearer $TOKEN"Справочник по реализации
Регистрация маршрутов: вызывается из internal/router/router.go; RegisterCustomAgentRoutes, RegisterSkillRoutes, RegisterUserFavoriteRoutes определены в routes_agent.go; RegisterMCPServiceRoutes (включая MCP OAuth и взаимодействие с /agent во время выполнения) — в routes_infra.go; RegisterMCPEndpointRoutes и публичный /mcp/:endpoint_id — в routes_mcp_endpoint.go. Handler: internal/handler/custom_agent.go, internal/handler/mcp_service.go, internal/handler/mcp_credentials.go, internal/handler/mcp_oauth.go, internal/handler/mcp_endpoint.go, internal/handler/skill_handler.go, internal/handler/user_resource_favorite.go.