#Интеграция с помощью ИИ-агента

Современный ИИ-агент способен написать бо́льшую часть интеграции со Smartica за один-два вечера. Эта статья — полное руководство: от «я никогда не кодил с ИИ» до проверенного результата.

Опытным разработчикам достаточно раздела с промптом — остальное можно пролистать.

#Что вы получите

К концу статьи у вас будет:

• рабочая связка «кнопка в карточке приёма → вход врача → возврат протокола»;
• тесты, которые проверяют идемпотентность и авторизацию;
• понимание, что именно проверить руками перед боевым запуском.

Чего вы не получите: интеграции, которую можно включить без единой проверки. ИИ отлично пишет обвязку, но регулярно ошибается в требованиях, которые нельзя вывести из кода. Ниже есть отдельный раздел с типичными ошибками — прочитайте его обязательно.

#Если вы никогда не работали с ИИ-агентом

Пропустите эту главу, если уже пользуетесь Cursor, Claude Code или похожим инструментом.

#Чем агент отличается от чата

Обычный чат вроде веб-версии ChatGPT работает вслепую: вы копируете туда кусок кода, получаете ответ, вставляете обратно руками. Модель не знает, как устроен ваш проект.

ИИ-агент работает внутри вашего репозитория. Он умеет:

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

Для нашей задачи это принципиально: агент сам найдёт, где у вас хранятся приёмы и врачи, как устроена авторизация и по какому шаблону пишутся тесты. Вам не придётся объяснять это словами.

#Что установить

Принципиальной разницы для этой задачи нет — промпт ниже работает в любом. Если выбираете впервые, берите Cursor: там нагляднее видно, какие файлы меняются.

Актуальные инструкции по установке смотрите на сайте выбранного инструмента — они меняются чаще, чем эта статья.

#Первый запуск, если выбрали Cursor

1. Установите Cursor и откройте в нём папку с репозиторием вашей МИС.
2. Откройте панель агента — обычно это Cmd+I на macOS или Ctrl+I на Windows.
3. Убедитесь, что включён именно агентский режим, а не простой чат: в агентском режиме инструмент может сам править файлы и запускать команды.
4. Вставьте промпт из этой статьи и отправьте.

Дальше агент начнёт читать проект и предлагать изменения. Каждое изменение видно как обычный diff — зелёные и красные строки. Ничего не применяется молча.

#Обязательный шаг: сделайте отдельную ветку

Это самое важное действие во всей статье.

git checkout -b smartica-integration

Агент меняет реальные файлы. Если что-то пойдёт не так — а на первых порах пойдёт, — вы должны иметь возможность откатить всё одной командой:

git checkout .

Никогда не запускайте агента на ветке, где лежит незакоммиченная работа. Сначала закоммитьте или спрячьте её:

git stash

#Что подготовить перед запуском

#1. Параметры подключения от Smartica

Без них запускать агента бессмысленно. Точный адрес SSO и ваш platform выдаёт Smartica при подключении — подобрать их нельзя. Если агент не получит эти значения, он придумает правдоподобные, и код молча не заработает: все запросы будут возвращать 404.

Как их получить — в статье Онбординг партнёра. Пока ждёте ответ, можно спокойно проходить остальные пункты.

#2. Знание своего проекта

Агент найдёт это сам, но если вы подскажете — результат будет заметно точнее:

• как называется модель или таблица приёма;
• как называется модель или таблица врача;
• где хранится текст протокола и его поля;
• как в проекте проверяется, что врач имеет доступ к приёму.

Если не знаете — не страшно. В промпте есть шаг, на котором агент сам изучит проект и задаст вопросы.

#3. Понимание контракта хотя бы в общих чертах

Прочитайте Обзор интеграции. Это пятнадцать минут, которые окупятся: вы должны понимать, что запросы идут в обе стороны, иначе не сможете оценить, правильно ли агент всё сделал.

#Правила безопасности

Их всего три, но нарушение любого — это инцидент.

Не вставляйте в промпт секреты. Ни API-ключей, ни паролей, ни строк подключения к базе. Передавайте только имена переменных окружения — агент напишет код, который читает значения оттуда. В промпте ниже это уже учтено.

Не вставляйте данные пациентов. Ни стенограмм, ни фрагментов реальных карт, ни ФИО. Для примеров используйте выдуманные данные.

Не давайте агенту доступ к боевой базе. Работайте на локальной или тестовой копии. Агент может выполнить команду, которую вы не ожидали.

Если ваша компания запрещает отправлять исходный код во внешние сервисы — уточните политику до начала работы. Агент отправляет содержимое файлов на серверы модели.

#Документация в машиночитаемом виде

Наши статьи доступны в формате, удобном для агентов:

• индекс всей базы знаний: https://smartica.ai/llms.txt;
• любая статья как сырой Markdown — добавьте .md к адресу, например https://smartica.ai/help/integrations/glossary.md.

Агенту лучше давать .md-версии: HTML-обёртка только зашумляет контекст. В промпте это уже прописано.

#Готовый скилл вместо промпта

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

Скилл — это файл с инструкциями, который лежит в вашем репозитории. Агент подхватывает его сам каждый раз, когда кто-то работает с кодом интеграции: сегодня — вы, через год — коллега, который эту статью не читал. Инварианты контракта при этом соблюдаются без чьего-либо участия.

Установка — одна команда в корне репозитория.

Каталог .agents/skills — общий стандарт: его читают и Cursor, и Codex. Начните с него.

mkdir -p .agents/skills/smartica-mis-integration && \
curl -fsSL -o .agents/skills/smartica-mis-integration/SKILL.md \
  https://smartica.ai/skills/smartica-mis-integration/SKILL.md

Claude Code этот каталог пока не читает — ему нужна отдельная копия:

mkdir -p .claude/skills/smartica-mis-integration && \
curl -fsSL -o .claude/skills/smartica-mis-integration/SKILL.md \
  https://smartica.ai/skills/smartica-mis-integration/SKILL.md

#Какой инструмент какой каталог читает

Единого каталога, который покрывал бы все три инструмента, сейчас нет. Отсюда практический вывод:

• если в команде только Cursor или Codex — достаточно .agents/skills;
• если кто-то работает в Claude Code — выполните обе команды, файл будет лежать в двух местах.

Частая ошибка — положить скилл для Codex в .codex/skills. Этот путь встречается в сторонних инструкциях, но Codex его не читает: скилл просто не загрузится, и никакой ошибки вы не увидите. Codex ищет .agents/skills во всех каталогах от текущего до корня репозитория. Проверить, что скилл виден, можно командой /skills; в Cursor — через Customize → Skills.

Файл везде один и тот же: SKILL.md — открытый стандарт, различаются только каталоги. Если пользуетесь другим инструментом, посмотрите в его документации, где он ищет скиллы.

Закоммитьте файл в репозиторий: тогда он появится у всей команды. При обновлении скилла просто выполните те же команды заново.

Посмотреть содержимое можно по прямой ссылке: smartica-mis-integration/SKILL.md. Внутри — инварианты контракта, лимиты, список типичных ошибок и указание останавливаться и спрашивать, если не выданы параметры подключения.

Скилл намеренно тонкий: он не дублирует контракт, а ссылается на наши статьи в машиночитаемом виде. При расхождении верна документация.

Скилл и промпт не конфликтуют. Удобный порядок: поставить скилл, затем запустить промпт — агент будет работать точнее, потому что часть требований уже в контексте.

#Заполните плейсхолдеры

В промпте есть значения в <угловых скобках>. Замените их все, иначе агент будет угадывать.

Если не знаете значение — напишите «не знаю, найди в проекте». Это лучше, чем оставить угловые скобки: увидев их, агент может решить, что так и надо, и оставить заглушку в коде.

#Главный промпт

Скопируйте кнопкой в правом верхнем углу блока, замените плейсхолдеры и отправьте агенту.

Ты работаешь в репозитории медицинской информационной системы:
- название: <MIS_NAME>
- стек и версии: <STACK_AND_VERSIONS>
- точный SSO endpoint Smartica: <SSO_ENDPOINT_FROM_SMARTICA>
- зарегистрированный platform: <PLATFORM_FROM_SMARTICA>
- модель/таблица приёма: <ENCOUNTER_MODEL_OR_TABLE>
- модель/таблица врача: <DOCTOR_MODEL_OR_TABLE>

Нужно реализовать интеграцию МИС со Smartica.

Сначала:
1. Открой https://smartica.ai/llms.txt — это канонический индекс документации.
2. Из секции «Интеграция с МИС» загрузи нужные статьи как Markdown
   (URL оканчиваются на .md). Не парси HTML-страницы /help, если доступен .md.
3. Обязательно прочитай:
   - https://smartica.ai/help/integrations/overview.md
   - https://smartica.ai/help/integrations/glossary.md
   - https://smartica.ai/help/integrations/test-environment.md
   - https://smartica.ai/help/integrations/launch.md
   - https://smartica.ai/help/integrations/launch-and-sso.md
   - https://smartica.ai/help/integrations/import.md
   - https://smartica.ai/help/integrations/mis-api-get-encounter.md
   - https://smartica.ai/help/integrations/mis-api-export-encounter.md
   - https://smartica.ai/help/integrations/authentication-and-errors.md
   - https://smartica.ai/help/integrations/limits.md
4. Изучи структуру проекта, существующие conventions, auth, валидацию,
   обработку ошибок и тесты.
5. Найди текущий способ проверки доступа врача к приёму.
6. Составь короткий план и перечисли недостающие обязательные данные.
7. Если неизвестны точный endpoint, схема хранения протокола или auth
   входящих запросов, остановись и задай вопросы. Не выдумывай контракт.

Реализуй:

1. Серверный запуск Smartica
- Добавь кнопку/действие «Smartica» в карточку приёма.
- Браузер передаёт бэкенду только ID текущего приёма.
- Бэкенд проверяет авторизацию врача и доступ к приёму.
- Бэкенд получает email и ФИО врача из доверенных данных МИС.
- Бэкенд вызывает точный SSO endpoint методом POST:
  Authorization: Bearer <значение переменной SMARTICA_SSO_KEY>
  Content-Type: application/json
  Accept: application/json
- JSON: user_email, user_full_name, encounter_id.
- encounter_id всегда передавай строкой.
- user_full_name передавай всегда, даже для существующего врача.
- Верни браузеру redirect на launch_url или безопасно открой его в новой вкладке.
- Не собирай launch_url самостоятельно и не сохраняй параметр t.

2. GET /api/for-smartica/encounters/{encounter_id}
- Защити endpoint проверкой заголовка Authorization: Bearer по HTTPS.
- Ожидаемый токен читай из SMARTICA_INBOUND_TOKEN.
- Сравнивай токен за постоянное время (timing-safe), а не оператором ==.
- Найди приём и проверь его доступность для интеграции.
- Верни 200 JSON:
  encounter_id, user_email, template,
  fields: [{ id, label }].
- fields[].id должны быть уникальными и стабильными.
- fields[].label должны быть человекочитаемыми: по ним Smartica
  определяет смысл поля.
- Для ошибок возвращай подходящий non-2xx и безопасный JSON message.

3. PUT /api/for-smartica/encounters/{encounter_id}
- Используй только PUT и ту же проверку Bearer-токена.
- Валидируй encounter_id, fields и transcript.
- Проверь совпадение ID в URL и JSON.
- В одной транзакции обнови переданные fields по id.
- Не очищай поля, отсутствующие в массиве.
- Пустой массив fields — валидный запрос: сохрани стенограмму.
- Замени сохранённую стенограмму полной версией transcript.
- Сохраняй многострочный текст и UTF-8 без потерь.
- Сделай обработку идемпотентной по encounter_id:
  повторный payload не создаёт новую карточку, протокол или вложение.
- Верни 200 JSON:
  { "encounter_id": "...", "status": "saved" }.
- Не возвращай 204, HTML или пустое тело.

4. Конфигурация и безопасность
- Базовый адрес Smartica вынеси в конфигурацию, не хардкодь домен из примеров:
  разработка идёт на тестовой площадке, боевой адрес подставляется при запуске.
- Секреты только в env/config; добавь placeholders в .env.example.
- Не помещай ключи, токены, launch_url или SSO token
  во frontend, логи и тексты ошибок.
- Не логируй медицинские данные целиком.
- Не ослабляй TLS и существующую авторизацию.
- Не меняй несвязанный код и зависимости без необходимости.

5. Тесты
- Успешная выдача контекста через GET.
- 401 для неверного или отсутствующего токена.
- 404 для неизвестного encounter_id.
- Успешный PUT с полями и transcript.
- Повторный одинаковый PUT не создаёт дубликат.
- Отсутствующие в PUT поля не очищаются.
- Пустой массив fields сохраняет стенограмму.
- Несовпадающие ID в URL и JSON отклоняются.
- SSO вызывается только сервером и передаёт user_full_name.
- Секреты отсутствуют в клиентском bundle и ответах.

После реализации:
1. Запусти formatter, линтер, целевые тесты и сборку frontend, если он менялся.
2. Исправь введённые тобой ошибки.
3. Покажи список изменённых файлов.
4. Кратко опиши принятые решения и команды проверки.
5. Отдельно перечисли всё, что требует параметров или подтверждения Smartica.

#Лучше разбить на несколько запусков

Один большой промпт работает, но у него есть минус: если агент ошибётся в начале, ошибка пройдёт через всю работу, и разбираться придётся в сотнях строк diff.

Надёжнее идти шагами и коммитить после каждого. Так вы всегда откатываетесь на один шаг, а не на всё сразу.

#Шаг 1. Разведка без изменений

Начните с того, чтобы агент ничего не менял, а только изучил проект. Это дёшево и сразу показывает, понял ли он задачу.

Пока ничего не меняй в коде.

Прочитай https://smartica.ai/llms.txt и статьи раздела «Интеграция с МИС»
как Markdown (URL с суффиксом .md).

Затем изучи этот репозиторий и ответь:
1. Где хранятся приёмы и как называется их идентификатор.
2. Где хранятся врачи, их email и ФИО.
3. Где хранится текст протокола и его поля.
4. Как в проекте проверяется доступ врача к приёму.
5. Как устроена авторизация входящих API-запросов.
6. По какому шаблону в проекте пишутся тесты.
7. Куда правильно добавить новый защищённый API-endpoint.

В конце составь план реализации интеграции и перечисли всё,
чего тебе не хватает для начала работы.

Прочитайте ответ внимательно. Если агент неверно понял структуру проекта — поправьте его сейчас, пока он не написал ни строчки.

#Шаг 2. Только приём результата

Начните с PUT: это единственный обязательный endpoint и самая ценная часть интеграции.

Реализуй только PUT /api/for-smartica/encounters/{encounter_id}
по контракту из
https://smartica.ai/help/integrations/mis-api-export-encounter.md

Требования:
- Проверка заголовка Authorization: Bearer, ожидаемый токен
  из SMARTICA_INBOUND_TOKEN, сравнение timing-safe.
- Проверь совпадение ID в URL и в теле, иначе 422.
- Обнови переданные fields по id в одной транзакции.
- Поля, отсутствующие в массиве, не очищай.
- Пустой массив fields — валидный запрос, стенограмму всё равно сохрани.
- Замени стенограмму полной версией из transcript.
- Сделай обработку идемпотентной по encounter_id.
- Верни 200 и JSON { "encounter_id": "...", "status": "saved" }.
- Не возвращай 204, пустое тело или HTML.

Напиши тесты, включая повторную отправку одинакового payload
и проверку того, что отсутствующие поля не затираются.

Больше ничего не трогай.

Прогоните тесты, закоммитьте.

#Шаг 3. Кнопка и вход врача

Реализуй серверный запуск Smartica по контракту из
https://smartica.ai/help/integrations/launch-and-sso.md

- Кнопка «Smartica» в карточке приёма.
- Браузер передаёт бэкенду только ID приёма.
- Бэкенд проверяет доступ врача к этому приёму.
- Email и ФИО врача берутся из сессии МИС, а не из тела запроса.
- POST на <SSO_ENDPOINT_FROM_SMARTICA> с Bearer из SMARTICA_SSO_KEY.
- Тело: user_email, user_full_name, encounter_id строкой.
- Ответ: редирект на launch_url без изменений.
- Ключ не должен попадать во frontend, логи и тексты ошибок.

Обработай ошибки 401, 403, 422, 429 и 5xx так, как описано в статье:
показывай понятное сообщение и не повторяй запрос автоматически
на 401 и 403.

Напиши тесты. Больше ничего не трогай.

#Шаг 4. Отдача контекста

Этот шаг можно пропустить: если вы передаёте название бланка и поля прямо в SSO-запросе, GET не нужен вообще. Решите заранее — см. Launch URL и SSO.

Реализуй GET /api/for-smartica/encounters/{encounter_id} по контракту из
https://smartica.ai/help/integrations/mis-api-get-encounter.md

- Та же проверка Bearer-токена, что в PUT.
- Верни 200 JSON: encounter_id, user_email, template, fields[{id,label}].
- encounter_id строкой, совпадает с URL.
- user_email — врач, ведущий этот приём.
- fields[].id уникальны и стабильны.
- fields[].label — человекочитаемые названия полей бланка.
- Ошибки: подходящий non-2xx и безопасный JSON message
  без стектрейсов и SQL.

Напиши тесты на успешный ответ, 401 и 404. Больше ничего не трогай.

#Как разговаривать с агентом

Для тех, кто делает это впервые.

#Агент задаёт вопросы — отвечайте

В промпте есть прямое указание остановиться и спросить, если чего-то не хватает. Это сделано намеренно. Если агент спрашивает «где хранится текст протокола?» — ответьте конкретно, а не «разберись сам». Каждый точный ответ убирает целый класс будущих ошибок.

#Не принимайте изменения не глядя

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

#Полезные фразы

#Если агент пошёл не туда

Не пытайтесь исправить всё в диалоге — это редко работает. Правильная последовательность:

1. Откатите изменения: git checkout .
2. Поймите, чего не хватало в постановке.
3. Сузьте задачу: попросите сделать только одну вещь.
4. Запустите заново с уточнённым промптом.

Один точный запуск с чистого состояния лучше, чем десять уточнений поверх запутанного кода.

#Если агент «зациклился»

Признак: он раз за разом правит одно и то же место, тесты продолжают падать, объяснения повторяются. Остановите его и попросите:

Остановись и не меняй код.

Опиши: какую ошибку ты видишь, какие три гипотезы у тебя есть
и как проверить каждую. Не предлагай исправление, пока не
подтвердишь гипотезу фактами из кода или из вывода теста.

#Типичные ошибки ИИ в этой интеграции

Это самая ценная часть статьи. Все перечисленные ошибки встречаются регулярно, компилируются без проблем и не находятся тестами, которые агент пишет сам.

Последний пункт стоит подчеркнуть. Если агент неправильно понял требование, он напишет тест, который проверяет неправильное поведение, и тест пройдёт. Зелёные тесты не означают, что контракт соблюдён.

#Проверка результата

#Автоматически

Проверь свою реализацию по чеклисту и честно отметь, что не выполнено.
Не исправляй ничего, пока я не подтвержу.

1. Секреты читаются из окружения, в коде их нет.
2. Ключ клиники отсутствует в клиентском бандле.
3. Email и ФИО врача берутся из сессии МИС.
4. Доступ врача к приёму реально проверяется.
5. encounter_id передаётся строкой.
6. launch_url не собирается вручную и не логируется.
7. PUT идемпотентен по encounter_id.
8. Отсутствующие в PUT поля не очищаются.
9. Пустой массив fields сохраняет стенограмму.
10. Успешные ответы — 200 с JSON, не 204 и не HTML.
11. Тексты ошибок не содержат стектрейсов, SQL и секретов.
12. Стенограммы не попадают в логи целиком.

Для каждого пункта укажи файл и строку, где это обеспечено.
Если пункт не выполнен — так и напиши.

Требование указывать файл и строку важно: без него агент склонен отвечать «всё выполнено» по всем пунктам.

#Руками

Автоматической проверки недостаточно. Пройдите этот список сами:

• Секреты читаются из окружения, а не зашиты в коде
• SSO вызывается с сервера, ключа нет в клиентском бандле
• Email и ФИО врача берутся из сессии, а не из тела запроса браузера
• Проверка доступа врача к приёму действительно выполняется
• Повторный PUT не создаёт дубликат — проверено курлом, а не тестом агента
• PUT с частичным набором полей не затирает остальные
• PUT с пустым fields сохраняет стенограмму
• Миграции корректны и обратимы
• В логи не попадают стенограммы и ссылки для входа
• Не появились лишние зависимости
• Изменения не задели несвязанный код

Проверку идемпотентности делайте именно курлом:

curl --fail-with-body --silent --show-error \
  --request PUT \
  --user 'LOGIN:PASSWORD' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "encounter_id": "12345",
    "fields": [{ "id": "complaints", "value": "Тестовые жалобы" }],
    "transcript": "Тестовая стенограмма..."
  }' \
  'https://mis.example.ru/api/for-smartica/encounters/12345'

Выполните дважды и убедитесь, что в МИС остался один приём.

#Живой прогон

ИИ не заменяет приёмочный прогон. Проведите настоящий тестовый приём: нажмите кнопку, запишите короткий разговор, дождитесь результата и посмотрите, что приехало в карту.

#Дополнительные промпты

#Ревью чужой или своей реализации

Проведи ревью интеграции со Smartica в этом репозитории.

Сверься с контрактом:
- https://smartica.ai/help/integrations/mis-api-export-encounter.md
- https://smartica.ai/help/integrations/launch-and-sso.md
- https://smartica.ai/help/integrations/authentication-and-errors.md
- https://smartica.ai/help/integrations/limits.md

Ищи в первую очередь:
- секреты в клиентском коде, логах и текстах ошибок;
- неидемпотентный PUT;
- очистку полей, отсутствующих в payload;
- encounter_id, переданный числом;
- ручную сборку launch_url;
- ответы 204, пустые тела и HTML;
- email врача, принятый от браузера без проверки.

Для каждой находки укажи файл, строку, риск и минимальное исправление.
Ничего не исправляй без моего подтверждения.

#Разбор ошибки от Smartica

При запросе к Smartica приходит такая ошибка:

<ВСТАВЬТЕ КОД ОТВЕТА И ТЕЛО, БЕЗ СЕКРЕТОВ>

Найди причину. Сверься с
https://smartica.ai/help/integrations/troubleshooting.md
и с нашим кодом.

Сначала объясни причину, потом предложи исправление.
Не меняй код, пока я не подтвержу.

#Дописать тесты

Проверь, что тесты интеграции покрывают все эти случаи,
и допиши недостающие:

- успешный GET контекста;
- 401 при неверных credentials;
- 404 для неизвестного encounter_id;
- успешный PUT с полями и стенограммой;
- повторный одинаковый PUT не создаёт дубликат;
- PUT с пустым массивом fields сохраняет стенограмму;
- PUT с частичным набором полей не затирает остальные;
- несовпадение ID в URL и теле даёт 422;
- SSO вызывается только с сервера и передаёт user_full_name.

Не меняй продакшн-код: только тесты. Если тест выявит
реальный баг — сообщи о нём, но не исправляй сам.

#Если ИИ-агента нет

Ничего страшного: интеграция небольшая. Идите по статье Быстрый старт — там пошаговая инструкция и готовый пример кода, который переносится на любой стек.

#Связанные статьи

• Обзор интеграции — как устроена интеграция
• Быстрый старт — ручная реализация по шагам
• Онбординг партнёра — как получить параметры подключения
• Лимиты и ограничения
• Диагностика: если что-то не работает