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

22 сентября 2026 г.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, если мы хотим понять радиус поражения при изменении общего SDK, мы можем спросить: какие репозитории в этой организации зависят от общего модуля backend 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. Те же модели, те же вопросы, те же репозитории, те же инструменты, тот же зафиксированный коммит, та же температура. Единственное отличие заключалось в том, что система сначала выполняла один запрос к графу и добавляла ответ в промпт.

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

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

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

Граф предоставлял зацепку, а не ответ.

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

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

Граф оставался под контролем времени.

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

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

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

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

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

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

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

Возьмем связи вызовов во время выполнения — вопрос, стоящий за большинством серьезных инцидентов. Когда один сервис вызывает другой во время выполнения, ни один репозиторий не фиксирует это, потому что цель — это 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-вызовы во время выполнения — это другое. Не существует файла в масштабах всей организации, перечисляющего каждый сервис, который вызывает эндпоинт. Эти связи распределены по коду приложения, сгенерированным клиентам, конфигурации, механизмам обнаружения сервисов, шлюзам и «живому» трафику.

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

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

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

Нельзя прийти к факту путем рассуждений, если у вас нет данных

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

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

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

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

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

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

Все типизировано, у каждого ребра есть источник

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

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

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

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

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

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

Начните сборку

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

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

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

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

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

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

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

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

Читайте документацию здесь.

Ресурсы

Платформа Postman

• Каталог API

• Spec Hub

• Рабочие пространства Postman

• Мониторинг API

• Управление API

• Сеть API Postman

• Отчет о состоянии API

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

• Об API Catalog

• Подключение источников к API Catalog

• Обнаружение кода

• Исследование ваших сервисов

• Интеграция GitHub с Postman

• Обзор спецификаций API

• Обзор коллекций

• Обзор мониторов

• Обзор режима агента

• Postman API

Из блога Postman

• Дрейф спецификаций API: почему контекст важнее кода

• APIFlow-Bench: тест на выживаемость корпоративных AI-агентов

• Четыре уровня инфраструктуры, необходимые каждому производственному AI-агенту

• Новый Postman: AI-native и созданный для эры агентов

• Карты показателей состояния API в каталоге API Postman

• От git push до соответствия API: CI линтинг спецификаций с помощью API Catalog

• Почему программы управления API терпят неудачу

• Новое в Postman API v1.39: эндпоинты API Catalog и Spec Hub

• AsyncAPI 3.0, потоковая передача производительности и сервисные аккаунты

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

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

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

• W3C Trace Context