Перейти к основному содержимому

Проектирование с помощником

API проектируются в разделе спецификации. Здесь чат с ИИ находится рядом с актуальным документом и его предпросмотром: вы описываете задачу обычным языком, сохраняя контроль над фактическими изменениями.

Цикл согласования​

Модель не изменяет документ напрямую. Процесс намеренно разделён на явные этапы:

you describe an intent
        |
the model reads current state and proposes operations
        |
the host validates the proposal
        |
you review a patch card and Apply or Reject
        |
the change is merged into the document

Это разделение — ключевое проектное решение. Модель понимает намерение и предлагает структуру; приложение детерминированно проверяет каждую операцию; вы одобряете каждое изменение. Предложение не считается применённым до вашего подтверждения.

Карточки изменений​

Карточка кратко описывает изменение и перечисляет точные операции, например добавление нового пути:

{
  "type": "patch",
  "summary": "Add GET /products endpoint",
  "ops": [
    { "op": "add", "path": ["paths", "/products"], "value": { "get": {} } }
  ],
  "affects": { "paths": ["/paths/~1products"], "resources": ["Product"] }
}

Сегменты пути передаются элементами массива, а не строкой JSON Pointer. Для нового пути используется ["paths", "/products"]; родительские контейнеры создаются автоматически.

Точечные изменения существующих операций​

При редактировании существующей операции помощник не отправляет её целиком заново: это удалило бы все неупомянутые поля. Вместо этого он формирует небольшие операции, затрагивающие только нужный фрагмент, в том числе глубоко вложенный:

  • Добавление параметра запроса:
{ "op": "add", "path": ["paths", "/products", "get", "parameters", "-"], "value": {} }
  • Расширение схемы ответа:
{ "op": "replace", "path": ["paths", "/products", "get", "responses", "200", "content", "application/json", "schema", "properties", "total"], "value": { "type": "integer" } }
  • Изменение одного поля:
{ "op": "replace", "path": ["paths", "/products", "get", "summary"], "value": "..." }

Элементы добавляются в массивы с помощью токена "-", без повторной отправки всего массива. Параметры определяются парой (in, name), что исключает дублирование существующего параметра. Приложение объединяет предложенное значение с текущей операцией и сохраняет всё, что не затронуто изменением.

Так последовательное уточнение остаётся надёжным: просьбы «добавь параметр limit» или «сделай имя обязательным» меняют только соответствующее поле, сохраняя остальную операцию.

Инструменты чтения дают основу для предложений​

Перед ответом модель может вызвать инструменты только для чтения, чтобы получить точное текущее состояние, а не угадывать его:

  • spec.overview: название, версия, протоколы, количества, теги, серверы и безопасность;
  • spec.listOperations: все операции в формате METHOD /path с кратким описанием и тегами;
  • spec.presentOperations: карточка со списком всех операций, доступная только для чтения;
  • spec.getOperation: полное определение операции и схемы, на которые она ссылается;
  • spec.getSchema: одна схема компонента, включая обязательные поля и описания.

Если полная структура операции не видна, модель должна прочитать её перед редактированием.

Объёмные задачи выполняются поэтапно​

При широкой задаче вроде «создай API интернет-магазина» помощник не выдаёт всё сразу:

  1. Сначала задаёт уточняющий вопрос о ключевых решениях;
  2. После ответа предлагает по одному точечному изменению за раз, от двух до пяти операций в карточке;
  3. Продолжает только пока ваш последний запрос остаётся в рамках этой цели.

Как только объём задачи понятен, помощник также формирует plan намеченных эндпоинтов, чтобы вы увидели структуру работы до появления изменений.

Как сохраняется направление работы​

Приложение применяет несколько правил:

  • Текущий документ — авторитетный источник состояния; модель не считает прошлое изменение применённым, если документ говорит об обратном;
  • В режиме точечного редактирования меняется только активный объект и явно указанные схемы компонентов, без попутных изменений соседних эндпоинтов;
  • Явное указание другого METHOD /path считается намеренным переходом к новой задаче;
  • Применённые и отклонённые предложения учитываются в истории; уже внесённое изменение не предлагается повторно.

Если необходимых сведений нет, помощник задаёт конкретный вопрос, а не выдумывает детали.

Другие карточки​

Не каждый ответ является предложением изменений:

  • Карточки вопросов предлагают выбрать один из вариантов;
  • Карточки проверки показывают результаты контроля качества: успешные проверки, предупреждения и ошибки;
  • Карточки действий предлагают конкретные шаги, например запуск сценария или открытие рабочей области;
  • Таблицы данных показывают примеры или тестовые строки для эндпоинта либо схемы.

См. также: Рабочая область запросов, Сценарное тестирование, ИИ и модели.

Агенты A2A​

Проектируйте и отлаживайте версионированные сообщения агентов, операции с задачами и обновления SSE с помощью x-protocol: a2a. Поля расширения и привязки JSON-RPC, REST и настольного gRPC описаны в разделе Агенты A2A.