ИИ-инструменты

Инструменты дают ИИ-ассистенту возможности, опирающиеся на код вашего расширения. Объявление находится в contributes.tools — имя, описание и схема входа, реализацию предоставляет sdk.ai.

Объявление

| Поле | Обязательно | Описание | | --- | --- | --- | | id | да | Короткий идентификатор инструмента — тот же, что вы передаёте в registerTool. | | name | да | Человекочитаемое имя. | | description | да | Когда и как ассистенту использовать инструмент. | | inputSchema | да | JSON схема входа инструмента. | | needsApproval | | Помечает инструмент как требующий подтверждения пользователя перед запуском. |

Ассистенту предлагаются только инструменты, объявленные в манифесте, поэтому обработчик, зарегистрированный для незадекларированного id, никогда не вызывается.

{
  "contributes": {
    "tools": [
      {
        "id": "getWeather",
        "name": "Get weather",
        "description": "Возвращает текущую погоду для города.",
        "inputSchema": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ]
  }
}

registerTool

registerTool(id: string, handler: (input: unknown) => unknown | Promise<unknown>): IDisposable

Зарегистрируйте обработчик с тем же id, что и в манифесте — Fragmenta добавит к нему id вашего расширения, таким образом полный id инструмента — <publisher>.<name>.<id>.

• Обработчик получает только input — аргументы, которые ассистент сформировал по вашей inputSchema. Сигнала отмены или контекста вызова нет. input имеет тип unknown: приведите его к форме схемы или валидируйте, если не можете полагаться на то, что ассистент следует схеме.
• Всё, что возвращает обработчик или значение, в которое разрешается его промис, передаётся обратно ассистенту как результат инструмента.
• Если обработчик выбрасывает исключение или отклоняется, ассистент получает ошибку инструмента с message этой ошибки.
• input и результат пересекают границу хоста расширения, поэтому должны быть сериализуемыми: простые объекты, массивы, строки, числа, логические значения и null.
• Если у задекларированного инструмента нет зарегистрированного обработчика — например, после освобождения регистрации, — вызов завершается ошибкой инструмента.
• Регистрации удаляются при деактивации расширения.

export function activate(context: ExtensionContext) {
  context.subscriptions.push(
    sdk.ai.registerTool('getWeather', async (input) => {
      const { city } = input as { city: string }
      return fetchWeather(city)
    }),
  )
}