AgentValet/AgentValet

agent_register: самостоятельно регистрирует этого агента у владельца. Аутентификация не требуется. Входные данные: owner_id (string), agent_name (string), requested_scopes (массив {platformId, scopes}). Пара ключей RSA агента генерируется на этой машине; отправляется только открытый ключ, а закрытый остаётся здесь. Возвращает: registration_token, poll_url, client_id, scope, keypair_source, key_stored_locally. Далее: как только владелец одобрит в панели управления, вызовите agent_status с registration_token, чтобы установить ключ. Аутентификация: не требуется.

agent_status: Опрашивает статус регистрации, используя токен из agent_register. Вход: token (string, required). При одобрении он устанавливает приватный ключ агента на этой машине (~/.agentvalet/agents/<agent_id>.key, а также идентификатор по умолчанию, если его нет) и активирует его для этой сессии, когда у сервера ещё не было идентификатора. Приватный ключ никогда не возвращается в результате. Возвращает: status ("pending"|"approved"|"rejected"|"expired"), agent_id, key_installed, key_path, activated, mcp_config (если одобрено). Аутентификация: Нет.

authzen_evaluate: Оценивает, есть ли у этого агента доступ к определённому разрешению (scope) платформы. Вызывайте этот инструмент ПЕРЕД use_platform, если хотите выполнить предварительную проверку без обращения к вышестоящему серверу. Входные данные: platform_id (строка), scope (строка). Возвращает: decision (булево), reason ("approved"|"denied"|"revoked"|"scope_not_granted"). Аутентификация: Bearer agent JWT (отправляется автоматически этим MCP-сервером).

delete_platform: Удаляет данные на платформе, которую владелец подключил, через прокси AgentValet. Вызывает собственный публичный REST API платформы (например, GitHub REST API, Slack Web API, Stripe API); endpoint - это путь в этом API, точно как его определяет документация. Для платформы, чей callStyle равен 'graphql', передавайте "/" в качестве endpoint и помещайте операцию в body в виде {query, variables}: путь и HTTP-метод не имеют значения на этой платформе. Всегда отправляет DELETE. Это удаляет данные, и AgentValet не может обратить это действие. Может блокировать до 50 секунд в ожидании одобрения владельца. Входные данные: platform, endpoint, scope, body (необязательно), connection_id (необязательно), reason (необязательно). Аутентификация: Bearer JWT.

Выдаёт кратковременную учётную запись дочернего агента для сабагента, которого вы собираетесь породить. Дочерний агент получает собственный идентификатор агента, собственный урезанный набор разрешений (области дочернего агента должны быть подмножеством ваших) и собственный журнал аудита; его можно отозвать отдельно, не затрагивая вас или его собратьев. Возвращает bearer-токен, который сабагент должен отправлять в заголовке Authorization. TTL 60-3600 секунд (по умолчанию 900). Внедряйте в контекст сабагента ТОЛЬКО bearer_token, никогда не передавайте собственные учётные данные.

list_my_pending_actions: Возвращает текущие ожидающие запросы на одобрение этого агента, а также любые завершённые за последние 24 часа. Используйте это при запуске сессии, когда пользователь упоминает предыдущее действие, или когда long-poll в use_platform завершился по таймауту и пользователь возвращается с вопросом о том, что произошло. Входные данные: отсутствуют. Возвращает: { pending: [{approval_id, platform_id, scope, created_at, expires_at}], recently_completed: [{approval_id, platform_id, scope, status, executed_at, result_summary, execution_error}] }. Аутентификация: Bearer JWT агента (отправляется автоматически).

list_platforms: Перечисляет платформы и области разрешений, к которым у этого агента есть доступ. Вызывайте его один раз на задачу, а не перед каждым вызовом. Входные данные: detail (необязательный: "compact" по умолчанию или "full"), platform (необязательный: platformId, возвращает эту одну платформу в полном виде). Возвращает (compact, по умолчанию): { detail: "compact", platforms: [{ platformId, platformName, scopes? (не-MCP: имена областей, которые нужно передать), scopeCount?, toolCount? и toolsEndpoint? (MCP: оттуда забираются список инструментов и схемы; область для инструмента - "<platformId>:<tool>", а имена инструментов в выводе compact идут без этого префикса), requireApproval? (только когда true), approvalScopes?, connections?, callStyle?, constraints?, connected?, health? }], version: "<hex>" }. connected: false значит, что платформа выдана, но за ней нет рабочих учётных данных, поэтому вызовы будут падать, пока владелец не переподключит её: скажите об этом пользователю, а не повторяйте попытки. health - последнее известное состояние подключения (active, reauth_needed, revoked, unknown). Используйте platform: "<id>", чтобы получить полный список областей одной платформы, unenforcedScopes, apiHints и lastProbeAt/lastSuccessAt; detail: "full" возвращает все платформы в полной форме { platforms: [{ platformId, platformName, scopes, requireApproval, approvalScopes?, connections?, callStyle?, apiHints? }], version }. Версия одна и та же, какой бы detail вы ни запросили. Платформа включает connections, когда у неё 2+ рабочих аккаунта или когда один аккаунт несёт контекст, который стоит знать; передайте выбранный connection_id в use_platform (пропустите, чтобы взять значение по умолчанию). Каждое подключение может нести identity (аккаунт, на который оно на самом деле указывает, например {email}) и hint (произвольный текст, который владелец написал для вас). Используйте их, чтобы разобрать инструкцию, где назван аккаунт, а не подключение: "send it from the aifirstpartner account" значит подключение, у которого совпадает identity.email или hint; если совпадений нет, спросите, а не угадывайте значение по умолчанию. Стиль вызова: callStyle присутствует только со значением "graphql" и говорит, как АДРЕСОВАТЬ…

read_platform: Читает данные с платформы, которую подключил владелец, через прокси AgentValet. Вызывает собственный публичный REST API платформы (например, GitHub REST API, Slack Web API, Stripe API); endpoint содержит путь в этом API, в точности как указано в его документации. Платформу, которую list_platforms указывает с callStyle 'graphql', этим инструментом прочитать вообще нельзя: она предоставляет ЕДИНЫЙ endpoint, который принимает только POST {query, variables}, поэтому отправляйте запрос на чтение через write_platform (или use_platform с методом POST), даже если это чтение. Запрос GET туда возвращает ошибку вышестоящего сервиса, которая не называет ни платформу, ни причину; это не вина брокера. Всегда выполняет GET: используйте write_platform для создания или обновления, а delete_platform для удаления. Входные данные: platform, endpoint, scope, connection_id (необязательно), reason (необязательно). Возвращает: тело ответа вышестоящего API. Аутентификация: Bearer JWT.

report_self_diagnostic: Отправляет самоотчёт (ошибка/предупреждение/информация) владельцу AgentValet. Используйте после того, как ошибка use_platform вернёт report_hint, ИЛИ заблаговременно, когда вы сталкиваетесь с проблемой, о которой пользователь должен знать. Входные параметры: severity (debug|info|warn|error|critical), message (строка, обязательный, макс. 4096 байт), code (строка, необязательный, макс. 128 символов), platform (строка, необязательный), endpoint (строка, необязательный), correlation_id (uuid строка, необязательный — скопируйте из report_hint от неудачного вызова, чтобы привязать этот отчёт к строке аудита на стороне брокера), context (объект, необязательный, JSON-сериализованный должен быть < 16 КиБ). Возвращает: { id, received_at } в случае успеха. Аутентификация: Bearer agent JWT (отправляется автоматически).

request_platform_access: Запрашивает у администратора организации доступ для этого агента к платформе, от которой он сейчас заблокирован. Вызывайте этот инструмент, когда use_platform возвращает ошибку доступа. Входные параметры: platform (строка, обязательный), scope (строка, опциональный: необходимый объём доступа), reason (строка, опциональный: причина запроса). Вызов ожидает решения администратора до ~50 секунд. Возвращает: { status: "approved"|"pending"|"denied", message }. При статусе "approved" повторите исходный вызов use_platform. При статусе "pending" запрос поставлен в очередь; повторите позже. Аутентификация: Bearer agent JWT (отправляется автоматически).

use_platform: Вызывает внешний API платформы (Airtable, GitHub, Slack, Metabase и т.д.) через прокси AgentValet. Входные данные: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), body (object, необязательно — тело JSON-запроса для POST/PUT/PATCH/DELETE). Возвращает: тело ответа вышестоящего API. Может занимать до 50 секунд, если для действия требуется одобрение владельца: вызов блокируется в ожидании, затем прозрачно возвращает одобренный результат. Если одобрение не приходит вовремя, возвращает обёртку pending_approval, а действие выполняется асинхронно; пользователь получает уведомление о завершении. Аутентификация: Bearer JWT. Примечание: старые клиенты, передающие data вместо body, всё ещё принимаются для обратной совместимости, но body — каноническое имя.

write_platform: Создаёт или обновляет данные на платформе, которую подключил владелец, через прокси AgentValet. Вызывает собственный публичный REST API платформы (например, GitHub REST API, Slack Web API, Stripe API); endpoint - это путь в этом API, точно такой, как он определён в документации. Для платформы с callStyle 'graphql' передайте "/" в качестве endpoint, а операцию поместите в body как {query, variables}: путь и HTTP-метод на такой платформе не имеют значения. Принимает только POST, PUT или PATCH: для GET используйте read_platform, а для DELETE - delete_platform. Может блокироваться до 50 секунд в ожидании одобрения владельца, затем возвращает одобренный результат; в противном случае возвращает обёртку pending_approval. Входные данные: platform, endpoint, scope, method (необязательно, по умолчанию POST), body (необязательно), connection_id (необязательно), reason (необязательно). Аутентификация: Bearer JWT.