Представляем Context Graph API: единая карта вашей экосистемы API

С вами когда-нибудь случалось такое? Вы беретесь за то, что кажется простой задачей по написанию кода: обновить API, запустить тесты, открыть PR и двигаться дальше. А через несколько ночей вас вызывают из-за инцидента, связанного с этим изменением. Обновление сработало именно так, как ожидалось, в вашем сервисе, но оно молчаливо сломало дюжину зависимых потребителей, о существовании которых вы даже не подозревали.

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

Именно поэтому мы запускаем Context Graph API: частный аутентифицированный граф знаний, который предоставляет агентам машиночитаемую модель всей вашей экосистемы API.

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

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

Другими словами, агент наконец-то может ответить на вопрос, который задает каждый старший инженер перед тем, как прикасаться к критически важному API:

Если мы изменим это, что сломается?

Используйте собственную модель

Если вы похожи на меня, вы, вероятно, думаете: сколько из моего существующего стека мне придется заменить, чтобы использовать контекстный граф API? Ответ: ничего.

Context Graph API разработан таким образом, чтобы органично вписаться в ваш текущий стек. Вы один раз подключаете существующие источники через Postman UI. Контекстный граф принимает данные, сопоставляет сущности в этих системах и строит связи, которые превращают набор разрозненных записей в граф, доступный для запросов. После этого граф обновляется каждую ночь по мере изменения вашей экосистемы API. Теперь каждый раз, когда появляется новый сервис, развертывание переносится в другую среду или ownership переходит в другую команду, граф подхватывает эти обновления при следующем обновлении, предоставляя каждому агенту актуальное представление вашей экосистемы API.

Без общего слоя контекста каждое из этих изменений делает понимание системы агентом все менее актуальным. Вскоре он будет рассуждать об архитектуре, которая была у вас полгода назад, а не о той, которая в данный момент работает в продакшене.

Context Graph поддерживает эту оперативную картину в актуальном состоянии, не требуя от вас изменения рабочих процессов вашей команды. Вам не нужно переходить на новую IDE, внедрять нашего агента по кодингу или переписывать уже созданного агента. API вписывается в ту модель, которую вы уже используете. Это не еще одно место для работы разработчиков. Это общий слой контекста для систем, которые уже выполняют работу.

Один эндпоинт, один вопрос

Использовать API просто. Вам не нужно изучать новый язык запросов или оркестрировать дюжину эндпоинтов. Вы отправляете один вопрос на адрес /asks.

Например, если мы хотим понять масштаб последствий изменения общего SDK, мы можем спросить: Какие репозитории в этой организации зависят от общего модуля бэкенд SDK?

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

Первоначальный POST возвращает ответ 202 Accepted с идентификатором задания и статусом:

Затем опрашивайте тот же путь, пока статус не перестанет быть pending, queued, running или in_progress:

Как только задание переходит в статус completed, ответ содержит текстовый ответ и структурированные данные, лежащие в его основе. Агент может использовать ответ напрямую или изучить отдельные результаты перед принятием решения о том, какой код нужно изменить.

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

В этом заключается важное отличие: нам не нужно знать полный масштаб перед тем, как задать вопрос. Если бы мы уже знали каждый затронутый репозиторий, сервис и команду, нам бы вообще не понадобился Context Graph. Нам нужно определить лишь то, что мы меняем — эндпоинт, схему, сервис или общий модуль. Граф обнаруживает окружающий его масштаб.

Он также может возвращать репозитории, которые не проверены локально, поскольку он выполняет запрос к общему для всей организации индексу, а не только к текущему рабочему пространству. Именно этого контекста не хватало агенту по кодингу во время первоначального инцидента.

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

До 74% меньше токенов, на 52% меньше вызовов инструментов и на 72% ниже стоимость

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

Поэтому мы создали контролируемый тест. Мы предоставили трем передовым моделям доступ к базе из 468 репозиториев и задали каждой из них по восемь вопросов:

• Каковы зависимости во время выполнения между сервисами?
• Перечислите каждый сервис и производимые им логи, метрики и трейсы.
• Какие сервисы мы действительно развертываем и как развертывается каждый из них?
• Какие сервисы обслуживают HTTP-эндпоинты и какие пути обслуживает каждый из них?
• Какие сервисы считывают данные из шины сообщений и какие топики они читают?
• Какие сервисы вызывают HTTP API платформы?
• Какие сервисы объявляют машиночитаемый контракт данных или API?
• От чего зависит каждый сервис во время выполнения?

Это именно те вопросы, на которые мы хотели бы получить ответы перед изменением общей инфраструктуры.

В качестве базового уровня модель получила код и набор инструментов поиска только для чтения. Ей пришлось самостоятельно искать репозитории и восстанавливать связи. Ей даже не сказали о существовании Context Graph.

Затем мы запустили тот же бенчмарк с использованием Context Graph API. Те же модели, те же вопросы, те же репозитории, те же закрепленные коммиты, та же температура. Единственным отличием было то, что обвязка (harness) сначала выполняла один запрос к графу и добавляла ответ в промпт.

Модели все равно приходилось изучать код и доказывать свой ответ. Она просто начинала с готовой карты вместо того, чтобы искать по 468 репозиториям с нуля. К моменту завершения индексации эта карта содержала 6712 узлов: 4828 эндпоинтов, 1424 API и сервиса, 309 внешних систем, 139 схем баз данных и 11 конфигураций телеметрии.

Мы запускали каждый вопрос трижды в обеих конфигурациях — всего 144 теста (ячейки). Нам нужно было выяснить простую вещь: помогает ли лучший контекст модели работать эффективнее без снижения стандартов правильного ответа?

Чтобы быть честными с самими собой, мы добавили три контрольных критерия.

Граф давал наводку, а не готовый ответ.

Мы относились к списку кандидатов так же, как к подсказке от другого инженера: полезно, но требует проверки. Агенту все равно приходилось открывать репозитории, изучать код и цитировать реальные файлы.

Мы проверяли, нашел ли он известные зависимости, процитировал ли по крайней мере три пути, существовавших в закрепленном коммите, и не выдумал ли более 20% цитат. Мы также наказывали за ложноположительные результаты, поэтому граф не мог повысить свою полноту (recall), просто возвращая каждый репозиторий в организации.

Граф работал на время.

Мы учитывали общую задержку каждого запроса /ask, включая повторные попытки, когда первый ответ был пустым. Запрос к графу обычно добавлял от 20 до 45 секунд. Если у графа не было полезного контекста для вопроса, запуск с использованием графа все равно нес эти затраты.

Модель не могла оценивать свою собственную работу.

Позволить модели оценивать собственный ответ — это все равно что позволить инженеру самому утверждать свой собственный PR: можно дважды не заметить одни и те же проблемы. Мы создали ответы-эталоны на основе реальных мест вызовов и файлов go.mod, проверили каждую цитату по закрепленному коммиту и поручили отдельной модели сравнить анонимизированные ответы. Таким образом, оценка отражала то, что реально находилось в коде, а не то, насколько убедительным казался ответ.

Одно предостережение: это не было идеальным сравнением в равных условиях. Базовый вариант выполнял поиск по точной версии кода, в то время как Context Graph выполнял поиск по более широкому индексу организации, который мог быть чуть новее или старше.

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

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

Меньшее количество токенов не имело бы особого значения, если бы ответы стали хуже, поэтому вот что произошло с точностью. Для трех моделей и семи оцененных промптов Context Graph API улучшил показатели в 18 из 21 пары «промпт-модель».

Возьмем отношения времени выполнения (runtime), которые стоят за большинством серьезных инцидентов. Когда один сервис вызывает другой во время выполнения, ни один репозиторий это не фиксирует, потому что целевой объект — это URL, собираемый из конфигурации при запуске. Там нет строки для поиска через grep. Вот как Opus и Astra справились с этим единственным вопросом:

Количество правильных сервисов для Opus выросло с 5 до 15, а для Astra — с 10 до 20, причем обе модели потратили меньше ресурсов на достижение этого результата.

Это возвращает нас к исходному изменению API. Если агент начинает с 468 репозиториев, ему приходится открывать для себя связи по одной за каждый поиск. Если он начинает с короткого списка вероятных потребителей, он может сразу перейти к верификации. Каждый пропущенный им шаг экономит время и токены.

Вопрос, на который grep не может ответить

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

Какие сервисы вызывают HTTP API платформы?

Какие сервисы вызывают HTTP API платформы?

Если мы спросим, какие репозитории импортируют библиотеку, ответ обычно где-то записан. В Go мы можем изучить go.mod. В других экосистемах мы бы посмотрели на package.json, pom.xml или requirements.txt. Имя файла меняется, но суть проста: разобрать манифесты зависимостей и пройти по объявленным связям.

Вызовы API во время выполнения — это другое. Не существует файла в масштабе всей организации, в котором перечислен каждый сервис, вызывающий эндпоинт. Эти связи распределены по коду приложений, сгенерированным клиентам, конфигурации, средствам обнаружения сервисов (service discovery), шлюзам и живому трафику.

В протестированной инфраструктуре было ровно 13 сервисов, которые действительно вызывали API. Мы проверили каждый из них вручную. Некоторые использовали сгенерированные клиентские библиотеки, поэтому буквальный путь /api/... никогда не появлялся в их исходном коде. Нельзя найти с помощью grep то, чего там нет. Агент может усерднее искать и читать больше файлов, но недостающая связь все равно не появится в репозитории. Это также тот вопрос, на который владельцам API приходится отвечать вручную, обычно в Slack, в условиях дефицита времени, прямо перед выпуском критического обновления.

Мы дали каждой модели одинаковые промпт и код, а затем запустили ее три раза только с инструментами репозитория и три раза — с предварительным запросом к графу контекста.

Каждая модель улучшила свои показатели с Context Graph API. Sonnet более чем в два раза увеличила число найденных реальных вызывающих объектов, Opus достиг 12 из 13, а Astra улучшила результат, даже несмотря на то, что уже была близка к полному ответу. Граф предоставил каждой модели более надежную отправную точку, помог обнаружить больше сервисов, которые действительно вызывают API, и при этом не загромождать ответ лишними предположениями.

Нельзя логически прийти к факту, которого у вас нет

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

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

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

Именно здесь на помощь приходит Context Graph API. Он дает агенту доступ к этим связям еще до того, как тот начнет вносить изменения. Агенту по-прежнему необходимо изучать код и проверять найденное, но ему больше не нужно восстанавливать всю архитектуру с нуля по тем репозиториям, которые случайно оказались открыты.

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

Возможно, модель была не слишком маленькой. Возможно, ее представление о системе было таковым.

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

Граф представляет собой граф свойств, состоящий из типизированных узлов: API, развертываний, баз данных, внешних служб, команд и телеметрии.

База данных — это узел, к которому можно перейти. То же самое относится к кластеру, на котором работает служба, и к команде, которая ею владеет. Именно это позволяет ответить на вопрос вроде «какие команды владеют чем-то, что считывает данные из этой базы данных» за один переход вместо трех бесед.

Затем идут типизированные ребра, каждое из которых имеет фиксированное значение:

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

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

Сопоставление этих трех источников — основа графа контекста. Спецификация в рабочей области утверждает, что эндпоинт существует. Код говорит, что он вызывается из репозитория, о котором в спецификации нет ни слова. New Relic сообщает, что он обрабатывает сорок тысяч запросов в день от развертывания, о котором никто не писал. Ваши агенты не могут разрешить эти конфликты, и до сих пор ничего другое в вашем стеке тоже не могло.

Начало работы

Каждый агент, развертываемый для работы с вашим набором API, делает ставку на то, чего он не видит. API графа контекста (Context Graph API) — это способ перестать делать такие ставки.

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

Чтобы начать загрузку данных в граф контекста, выберите Agent Context в выпадающем меню Домашней страницы (Home Menu).

Затем нажмите Connect More, после чего вы попадете на страницу индексации. Postman индексируется по умолчанию.

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

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

HTTP-эндпоинт — это не единственный способ доступа. Мы также добавляем API графа контекста в протокол Model Context Protocol (MCP), поэтому любой клиент MCP, который вы уже используете — ваш редактор, фреймворк для агентов или собственный инструмент — может отправлять запросы к графу в качестве инструмента без написания запросов или обработки опросов. Тот же граф, те же данные на каждом ребре и на одну интеграцию для поддержки меньше. Скоро это станет доступно. Эндпоинт выше работает уже сегодня, и все, что вы создаете с его помощью сейчас, не пропадет зря, когда появится MCP-сервер.

Используйте Context Graph API уже сегодня. Используйте модель, к которой вы привыкли.

Читайте документацию here.

Ресурсы

Платформа Postman

• Каталог API
• Центр спецификаций
• Рабочие пространства Postman
• Мониторинг API
• Управление API
• Сеть API Postman
• Отчет о состоянии API

Документация Postman

• Обзор каталога API
• Подключение источников к каталогу API
• Обнаружение кода
• Изучение ваших служб
• Интеграция GitHub с Postman
• Обзор спецификаций API
• Обзор коллекций
• Обзор мониторов
• Обзор режима агента
• API Postman

Из блога Postman

• Отклонение спецификаций API: почему контекст важнее только лишь кода
• APIFlow-Bench: тест на выживание для ИИ-агентов на уровне предприятия
• Четыре уровня инфраструктуры, которые необходимы каждому рабочему ИИ-агенту
• Новый Postman: создан на базе ИИ и для эпохи агентов
• Оценка состояния API в каталоге API Postman
• От git push до соответствия API: проверка спецификаций в CI с помощью каталога API
• Почему программы управления API дают сбой
• Новое в Postman API v1.39: эндпоинты каталога API и центра спецификаций
• AsyncAPI 3.0, потоковая передача производительности и служебные аккаунты

Спецификации

• Спецификация OpenAPI
• Спецификация AsyncAPI