Mapeamos 115 microsserviços para nossos agentes de programação — Kamalakannan Nandagopal, Postman

Autoria: AI Engineer · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: We Mapped 115 Microservices for Our Coding Agents — Kamalakannan Nandagopal, Postman · Canal: AI Engineer · 17:15 · Assistir no YouTube

Tópicos: Agentes de IA, Avaliação e benchmarks de IA, Engenharia de software com IA, Ferramentas de desenvolvimento com IA

Resumo

Kamalakannan Nandagopal, engenheiro da Postman, apresenta um grafo de contexto de APIs criado para ajudar agentes de programação a trabalhar em uma arquitetura distribuída com centenas de serviços e repositórios. O grafo conecta APIs, implementações no código, consumidores, dependências e dados de produção, com cada informação fundamentada em código ou telemetria. Em avaliações, esse contexto ajudou agentes a descobrir APIs, analisar mudanças e entender o impacto em serviços dependentes, embora os resultados dependam de manter o grafo atualizado. A equipe também usou o grafo para gerar uma análise ampla da arquitetura e aponta como próximos passos conectar contexto técnico e semântico de negócio.

Pontos-chave

Em sistemas distribuídos, APIs podem servir como uma camada de contexto que revela responsabilidades dos serviços e workflows entre sistemas.
O grafo de contexto da Postman relaciona microsserviços, endpoints, código de implementação, consumidores, bancos de dados, caches e aplicações.
Cada informação do grafo deve estar fundamentada em código-fonte ou em traces de telemetria de produção.
As avaliações compararam o agente da Postman, Claude Code, busca de código e uma skill com acesso ao grafo, medindo qualidade e uso de tokens.
O contexto do grafo foi especialmente útil para identificar APIs adequadas, analisar formatos de entrada e avaliar impactos de mudanças.
Um grafo desatualizado pode causar respostas incorretas e reduzir a confiança e o uso pelos desenvolvedores.
Uma análise gerada pelo agente identificou ciclos de dependência, migrações longas, pontos únicos de falha e lacunas de telemetria.
A equipe pretende conectar informações sobre o negócio e ampliar o raciocínio sobre domínios, modelos de dados e escolhas entre APIs.

Capítulos

Início	Capítulo	Resumo
00:12	Agentes de programação em sistemas distribuídos	O palestrante apresenta a arquitetura da Postman e explica por que agentes que funcionam bem em um único projeto enfrentam desafios em sistemas distribuídos.
03:53	Construção do grafo de contexto de APIs	A equipe mapeia serviços, endpoints, implementações, consumidores e dados, exigindo que cada informação tenha fundamento verificável.
06:33	Avaliações e comparação entre agentes	A equipe cria avaliações a partir de PRs e decisões reais e compara qualidade e uso de tokens entre diferentes abordagens.
08:08	Descoberta de APIs e análise de mudanças	Exemplos de uso mostram como o contexto ajuda a escolher APIs, entender formatos de entrada e estimar o impacto de alterações.
11:55	Impacto, falhas e atualização do grafo	O grafo ajuda a avaliar dependências, mas informações desatualizadas podem causar falhas e abalar a confiança dos desenvolvedores.
14:01	Análise da arquitetura e próximos passos	O agente gera um relatório amplo sobre a arquitetura, e a palestra encerra com aprendizados e planos para adicionar contexto semântico de negócio.

Citações

Em uma arquitetura de sistemas distribuídos e microsserviços, as APIs são sua camada de contexto. — 03:53

Cada dado que chegava ao grafo de contexto precisava estar fundamentado em uma verdade verificável. — 05:27

Atrasos na sincronização do grafo de contexto com a verdade de referência criam lacunas nos resultados. — 13:00

O grafo de contexto de APIs serve como camada de contexto para agentes de programação em sistemas distribuídos do mundo real. — 15:40

Conceitos e entidades

API context graph (conceito): Grafo que relaciona APIs, serviços, implementações, consumidores e dependências para fornecer contexto técnico aos agentes de programação.
Postman (empresa): Plataforma de APIs cuja arquitetura de microsserviços é o caso apresentado na palestra.
Kamalakannan Nandagopal (pessoa): Engenheiro da Postman que apresenta a experiência da empresa com agentes de programação e contexto de APIs.
Claude Code (ferramenta): Agente de programação usado como comparação nas avaliações descritas na palestra.
MCP (conceito): Alternativa mencionada para fornecer contexto aos agentes, cuja eficácia depende do contexto disponível.
skill (conceito): Forma usada na comparação para disponibilizar o grafo de contexto a um agente de programação.
evals (conceito): Avaliações baseadas em tarefas reais, decisões de engenharia e resultados esperados para comparar agentes.

Tradução completa (pt-BR)

00:12 Hoje vou falar sobre como levar seus coding agents além da geração de código e sobre como o contexto de API pode ser a resposta para isso. Sou Kamal. Sou engenheiro sênior na Postman. Como talvez você saiba, a Postman é uma plataforma de API de ponta a ponta. Mas, além do aplicativo para desktop, que permite testar suas APIs REST e criar APIs, a Postman também tem muitos recursos na nuvem. Uma extensa arquitetura de microsserviços dá suporte a todos esses recursos na nuvem. Temos mais de 150 microsserviços e milhares de endpoints de API REST

00:45 Então, vou usar nossos casos de uso e workflows reais de engenharia, além das experiências com nossos coding agents e do que aprendemos com elas, para mostrar como temos aprimorado a experiência e a eficácia dos nossos coding agents com o grafo de contexto de API. Nossa jornada com os coding agents começou de forma parecida com a de muitos de vocês. Primeiro, veio a conclusão automática no nível de linhas e funções: a era do Copilot. Depois, vieram as refatorações de bases de código completas e as implementações de uma só vez

01:17 e as correções feitas de uma só vez: as eras do Composer e do Cloud Code. Agora, estamos avançando para workflows de coding agents totalmente autônomos. Temos agents que iniciam o workflow de ponta a ponta, fazem as alterações, verificam as alterações, enviam pull requests e até verificam pull requests. O que vemos os coding agents fazerem muito bem são projetos greenfield ou correções e melhorias no contexto de um único projeto. Mas os sistemas de produção tendem a ser um pouco mais complexos. Eles tendem a ser

01:48 sistemas distribuídos, divididos em vários microsserviços. Muitas vezes, são implantados em vários ambientes, com várias versões diferentes em cada um deles. Temos diversos aplicativos — frontend, CLI e API — que se comunicam com nossa infraestrutura de backend, e tudo isso está distribuído por centenas de repos, com o código espalhado entre eles. Quando pensamos em melhorar o desempenho dos coding agents, a primeira área que começamos a analisar é a documentação. A documentação é um ótimo ponto de partida, mas, como todos nós, desenvolvedores, sabemos, nós

02:19 odiamos escrever e manter documentação. É uma sobrecarga adicional. Custa tempo e fica difícil mantê-la ao longo do tempo. Mas, se você deixar os LLMs escreverem e manterem a documentação sozinhos, pesquisas apontam que a documentação escrita e mantida exclusivamente por LLMs tende a se degradar exponencialmente com o tempo. É definitivamente necessária algum tipo de curadoria humana para torná-la mais eficaz. Skills e MCPs são uma alternativa muito boa, mas todos sabemos que skills e MCPs só são tão bons quanto o contexto que recebem. A memória do agent é, na verdade, uma ótima solução para esse

02:51 cenário. Em termos de experiências no mundo real, boa parte desse conhecimento provavelmente já existe como conhecimento tácito na cabeça das pessoas e agora está sendo convertido em memória do agent no harness do coding agent. A maior limitação que vemos é que a memória do agent ainda é muito restrita a um usuário individual, e ainda não surgiram padrões comuns para compartilhar memórias de agents entre equipes mais amplas ou por toda a organização de engenharia. Enquanto tentávamos resolver esse problema para os coding agents na área de engenharia, nossas equipes de go-to-market

03:22 também estavam criando business agents para casos de uso executivos de ponta a ponta das equipes de go-to-market. Elas têm criado agents personalizados, criados especificamente para esse fim e alimentados com dados de clientes provenientes de várias fontes de dados. Também fizeram várias iterações para organizar todos esses dados não estruturados vindos de todas essas fontes em dados estruturados, sobre os quais esses agents operam. O resultado foi um pipeline de RAG mais grafo realmente otimizado, que funciona como uma camada centralizada de contexto e faz com que todos esses business agents individuais funcionem muito bem e

03:53 resolvam o problema para todos eles. Então, começamos a analisar o que poderíamos aprender com isso e o que poderíamos fazer para melhorar de verdade o desempenho dos coding agents. Ao analisarmos a questão, percebemos que, em uma arquitetura de sistemas distribuídos e microsserviços, as APIs são a camada de contexto. Arquiteturas de engenharia complexas costumam ser divididas em domínios e modelos, e cada microsserviço é responsável por uma única responsabilidade, de acordo com um modelo ou domínio. As APIs definem qual é essa responsabilidade. E as chamadas de API

04:23 entre sistemas geralmente são como identificamos workflows e jornadas de usuário que abrangem vários sistemas. Os agents só são tão bons quanto o contexto que recebem. Por isso, começamos uma jornada para criar a melhor camada de contexto para os agents. Começamos então a criar um grafo de contexto de API que representasse a arquitetura de engenharia da Postman. A jornada começou com a identificação e catalogação de todos os microsserviços em produção. Em seguida, identificamos todos os endpoints expostos por cada um desses serviços de API REST e registramos como cada

04:56 um deles é implementado, até a linha exata de código em que foi implementado. Também mapeamos como cada serviço se comunica com os outros e como cada endpoint se conecta a todos os demais endpoints. Acompanhamos também como os dados percorrem toda a stack, incluindo bancos de dados e caches, por toda a stack. Também identificamos como aplicativos como frontends, CLIs e APIs interagem com toda a arquitetura e infraestrutura de backend.

05:27 Fornecemos todos esses dados e os indexamos usando um LLM para produzir uma camada centralizada e eficaz de grafo de contexto. Mas sempre tivemos em mente um princípio fundamental: cada dado que entrasse no grafo de contexto precisava estar fundamentado em uma verdade concreta. Essa verdade concreta podia ser uma linha de código implementada na base de código ou um trace exato proveniente da telemetria de produção. Com isso em prática, começamos a preencher nosso grafo de contexto. Este é um retrato de como é nossa

05:58 arquitetura de engenharia. Começam a surgir alguns padrões bastante comuns que você esperaria encontrar. Vemos um cluster central de serviços essenciais, com APIs e serviços muito interligados e altamente dependentes uns dos outros. Encontramos um ou dois serviços muito inchados nas bordas externas desses sistemas. Os que ficam no centro são normalmente classificados como serviços de tier zero ou tier um. Agora que temos o grafo de contexto, começamos a analisar como medir as melhorias que ele proporciona aos coding agents. Então,

06:33 pegamos exemplos reais dos repos Git da organização da Postman. Pegamos PRs reais enviados aos repos do GitHub e, para cada um deles, identificamos o que o desenvolvedor estava tentando fazer e qual foi o resultado efetivo ao final do PR. Também consideramos projetos importantes e as principais decisões de design e conclusões discutidas nas conversas sobre design. Mapeamos cada um deles para um eval e registramos qual decisão foi realmente tomada, em retrospecto, como a verdade de referência que queríamos que os evals confirmassem.

07:06 Para executar as validações, conseguimos conectar o AI agent da Postman ao grafo de contexto de API e validar tudo isso também com o AI agent da Postman. Mas, para manter a comparação justa, também validamos os casos com um coding agent genérico — neste caso, Claude Code — e tentamos verificá-los usando apenas uma busca direta de código no GitHub. Também pegamos o mesmo grafo de contexto, disponibilizamos como uma skill e comparamos com o coding agent genérico, neste caso

07:37 Claude Code. Então, vocês vão ver os resultados em um gráfico como este. Atribuímos uma pontuação de zero a cinco para cada eval e também medimos a quantidade exata de tokens usada em cada uma dessas execuções. Se algo aparecer no canto superior direito, significa que o agent fez um bom trabalho. Ele conseguiu uma pontuação alta na avaliação, mas gastou muitos tokens para isso. Se estiver no canto superior esquerdo, fez um ótimo trabalho: não só obteve uma pontuação alta, como também fez isso com muito mais eficiência. Se algo ficar abaixo da linha tracejada, simplesmente não atingiu o nível esperado para uma boa pontuação

08:08 nessa avaliação. Então, agrupamos alguns dos casos de uso e cenários comuns que encontramos no desenvolvimento do dia a dia e analisamos em que categoria eles se encaixam. Um cenário importante que sempre observamos é a descoberta de APIs. Qualquer desenvolvedor que esteja fazendo uma alteração no frontend ou no backend, integrando-se a outros sistemas, precisa saber: qual é a API certa para chamar? Em sistemas reais, provavelmente há centenas de APIs diferentes e, muito provavelmente, várias APIs que fazem a mesma coisa. Neste caso, um exemplo simplificado que usei é: qual é a

08:41 API certa a chamar para obter o nome do perfil de um usuário específico? Nesta avaliação, trata-se de um caso de uso puramente de busca, e os resultados são os esperados. Com o context graph, o agent obteve uma pontuação muito boa em comparação com a busca puramente no código, na qual os agents não se saem muito bem. Há uma pequena diferença entre o Postman e o Claude, mas ela não é grande o suficiente para nos aprofundarmos nisso. O segundo caso de uso é onde a coisa fica realmente interessante. É o que chamamos de cenários de design e redesign de APIs. Nesse cenário, vamos considerar um

09:12 desenvolvedor que está criando um novo recurso e, para desenvolvê-lo, projetou uma nova API e o schema para os dados de entrada da requisição. Definiu a implementação. Fez os testes do seu lado e, então, integrou o recurso ao produto. Está satisfeito com o produto e pronto para lançá-lo. No último minuto, uma das equipes dependentes o procura e diz: “Ei, seria bom se eu pudesse passar mais uma propriedade para a API, que gostaria de usar mais adiante.” Então, o desenvolvedor pensa: “Talvez não tenhamos tempo suficiente para avaliar todas as diferentes maneiras de fazer isso.

09:44 Qual é o schema certo para isso?” Então, ele simplesmente adiciona esse contexto, que é um objeto JSON de formato livre, e inclui uma tarefa pendente no código dizendo: “Revisitar isso e adicionar um schema daqui a duas semanas.” O recurso é lançado em produção. Todo mundo fica feliz. Duas semanas depois, o desenvolvedor volta e descobre que aquela propriedade específica, que deveria enviar um atributo, agora tem 15 atributos, e está sendo enviada por um serviço, ou talvez por cinco serviços, ou talvez por dez serviços. Agora, o desenvolvedor não tem ideia de qual é exatamente o formato da requisição enviada à API nem de todas as diferentes maneiras pelas quais

10:17 cada consumidor tem enviado dados. Isso pode ser… É o que chamo de análise do formato de entrada de cada API e dos motivos pelos quais ela é usada dessa maneira. Isso pode ser difícil por vários motivos. Primeiro, rastrear cada consumidor da sua API pode ser impraticável em cenários reais. Mesmo que você tenha dependências entre serviços e mapas de serviços, descobrir o formato exato da entrada usado por cada consumidor pode ser muito complicado. Muitas vezes, os engenheiros não têm informações detalhadas o bastante nos logs de produção e, por motivos de privacidade, talvez elas nem estejam

10:50 disponíveis. Mesmo que os formatos sejam identificados, descobrir exatamente por que o consumidor decidiu enviar os dados dessa maneira é um problema muito, muito complicado. Mas, neste cenário, quando pegamos essa avaliação e a executamos com o agent do Postman, o surpreendente foi que ele quase acertou tudo. O que ajudou nesse caso foi, em primeiro lugar, o context graph ter conhecimento de cada consumidor de uma API. Mas não só isso: ele também permitiu investigar em detalhes e chegar à fonte da verdade sobre onde exatamente cada uma dessas APIs foi implementada no código. E o contexto ao redor desse código ajudou o agent a entender por que a alteração foi feita.

11:22 Muito rapidamente, ele conseguiu descobrir os formatos específicos de cada consumidor que chamava essa API, e foi possível fazer as alterações com bastante confiabilidade e segurança. Dá para ver que a busca puramente no código não se sai muito bem, mas, com o Claude e a skill, o resultado é um pouco melhor. Ainda assim, ele tende a desistir depois de um número suficiente de turnos e aguardar que o usuário confirme o que fazer em seguida. Outro caso de uso muito comum que começamos a observar é a avaliação de impacto.

11:55 Como descobrir o impacto de uma alteração específica? Se eu mudar esta API, quais são os possíveis casos de uso? Ou talvez já exista uma API V2 e eu queira introduzir uma API V3. Como entender primeiro como a API V2 é usada, para que eu possa projetar uma API V3 melhor? Esse é um cenário em que vemos o context graph realmente se destacar. Dá para ver que o Postman Agent não só produz resultados de alta qualidade, como também consegue fazer isso usando quase metade, ou até um terço, dos tokens necessários em comparação com a busca puramente no código.

12:28 Mas nem sempre tudo corre bem. Às vezes, encontramos falhas. Neste caso, um dos casos de uso que testamos foi descobrir o impacto de uma alteração em um PR específico, que introduziu uma mudança em um endpoint, e identificar todos os serviços downstream afetados por esse endpoint. Começamos a observar uma falha, e dá para ver que o gráfico ficou quase invertido. O Postman não só teve uma pontuação baixa, como também consumiu muitos tokens. Quando investigamos e tentamos entender por que estava falhando, percebemos que

13:00 havia novos consumidores entre o momento em que a eval foi escrita e o momento em que a avaliação foi executada. Portanto, não basta preencher o context graph: é igualmente importante mantê-lo atualizado. Qualquer atraso na sincronização do context graph com a fonte da verdade cria uma lacuna nos resultados. E, se houver uma lacuna nos resultados, isso leva imediatamente à perda de confiança do desenvolvedor, o que se traduz em falta de uso. Detectar novas APIs e novas dependências é importante, mas detectar remoções de APIs e de dependências é igualmente

13:31 importante e também pode causar confusão e problemas. Talvez vocês pensem que esses casos de uso sejam ou não comuns no seu caso, mas, quando analisamos retrospectivamente todos os PRs abertos nos dez principais repos, percebemos que quase 75% dos PRs tinham algum efeito sobre as APIs. Ou essas alterações modificavam a superfície externa de uma API, ou introduziam a integração com uma nova API. Ambas podem ter um impacto realmente cascata nos sistemas downstream.

14:01 Esses casos de uso nos permitiram fazer uma comparação direta entre antes e depois, com e sem o context graph. Mas, assim que obtivemos essas informações, conseguimos fazer perguntas que antes não podíamos fazer. Essas perguntas nos permitiram usar o Postman agent e dizer: “Ei, faça uma análise completa de engenharia e uma revisão arquitetural de ponta a ponta de todo o nosso ecossistema.” Foi aí que tivemos aquele momento de revelação. Quando pedimos ao Postman agent que fizesse isso, ele produziu um relatório de engenharia de 21 páginas, examinando cada ponto fraco e

14:34 pontos de vulnerabilidade. Ele encontrou insights interessantes para nós, incluindo ciclos de dependências, que podem ser realmente problemáticos em caso de incidente; migrações longas e arriscadas, que são sinais de dívida técnica; e pontos únicos de falha, que podem ser realmente problemáticos ou problemas prestes a acontecer; pontos cegos na telemetria, em que coisas presentes na implementação não aparecem na telemetria; e, então, apresentou itens de ação claros sobre o que o CEO, o CTO e os engenheiros de equipe talvez precisem fazer. Além de todas essas coisas, quando analisamos o que podemos fazer para melhorias futuras

15:07 uma das áreas que se destaca é trazer a camada semântica — o que a sua empresa faz — e conectá-la à camada de contexto que os seus agentes de programação recebem como entrada para seus workflows. Outra área de melhoria que estamos explorando é como podemos aprimorar e acrescentar raciocínio sobre por que um modelo de dados existe. Por que o domínio está mapeado dessa forma? Por que esta API existe em vez de outras APIs? Por que, por que você deveria usar uma API em vez de outra? Tudo isso ajuda nas decisões subsequentes de programação e se traduz em resultados realmente eficazes quando vocês as usam

15:40 nos workflows de desenvolvimento do dia a dia. Então, os aprendizados e as conclusões. Percebemos que o grafo de contexto de API serve como camada de contexto para agentes de programação em sistemas distribuídos do mundo real. Ele oferece uma visão de alto nível que ajuda a responder a perguntas sobre a arquitetura de engenharia que não era possível responder no contexto de um único repo ou de um único microsserviço. Ele reduz o tempo necessário para encontrar a maneira certa de resolver determinado problema. E tudo isso significa que fazer esse trabalho com a qualidade adequada ou com muito mais eficiência se torna possível.

16:11 Então, eficiência se traduz em economia de custos, mas, da forma como vemos, se conseguimos realizar uma tarefa específica com muito mais eficiência, isso significa que podemos realizá-la com mais frequência. Isso nos permite fazer as mesmas avaliações com muito mais frequência, inclusive levá-las ao nível do PR ou até diretamente à máquina de desenvolvimento ou ao ambiente de desenvolvimento em que o engenheiro está trabalhando. Portanto, quanto mais cedo conseguirmos antecipar as decisões e detectar problemas no ciclo de vida, acreditamos que os agentes que estão gerando código podem trazer tranquilidade para o

16:43 desenvolvedor e ajudá-lo a enviar alterações para produção com muito mais confiança daqui para a frente. Então, é tudo da minha parte. Todas essas funcionalidades estão disponíveis na plataforma Postman. Também estão disponíveis para uso como acesso antecipado. Estarei ali fora logo após a palestra, caso tenham perguntas ou queiram conversar mais. Também temos um estande, o S32, bem em frente, do outro lado do corredor. É tudo da minha parte. Muito obrigado.

17:15 Uhu! [música]

Transcrição original

[00:12] Today I’m going to talk about how you can take your coding agents beyond code generation and how API context might be the answer for that. I’m Kamal. I’m a staff engineer at Postman. And Postman, as you might know, is the end-to-end API platform. But beyond the desktop app that allows you to test your REST APIs and build your APIs, uh Postman also has uh a lot of cloud features. Empowering all of those cloud features is an extensive microservices architecture. We have more than 150 microservices and thousands of uh REST

[00:45] API endpoints. Uh so, I’m going to be using our real uh engineering use cases and workflows and on top of our coding agent experiences and what we learned from it and how we’ve been improving the experience and the effectiveness of our coding agents with API context graph. So, our journey with the coding agents started similar to how many of you might have gone through the same journey as well. Starting with line and function level auto completion, this is the Copilot uh days eras. Uh moving on to full code base uh refactors and one-shot

[01:17] implementations and one-shot fixes, uh this is your composer eras and cloud code eras. Now, moving on to fully autonomous coding agent workflows. Uh we have agents that end-to-end start the workflow and then make the changes, verify the changes, send pull requests, and even verify pull requests as well. What we see as the coding agents excelling really well at are greenfield projects or fixes and improvements within the context of a single project. But production systems tend to be slightly more complex. They tend to be

[01:48] distributed systems split across multiple microservices. They’re often deployed across multiple environments, even multiple different versions in each of these environments. We have several applications, front end, CLI, API, all of them talking to our back end infrastructure, and all of this is spread across hundreds of repos where the code is distributed across all of them. When we think about improving coding agent performance, the first area that we start looking into is documentation. Documentation is a great place to start, uh but as we all know, developers, we

[02:19] hate writing and maintaining documentation. It’s an added overhead. It costs time, and it becomes tricky to go and maintain over time. But if you offload documentation purely to LLMs to author and maintain, research points out that purely LLM maintained and written documentation tends to degrade exponentially over time. Some sort of human curation is definitely needed to make it more effective. Skills and MCPs are a really good alternative to look at, but we all know skills and MCPs are only as good as the context that they’re provided to. Agent memory is actually a really good solution for uh this

[02:51] scenario. Um in terms of real-world uh experiences, most of this knowledge is probably already tribal knowledge in people’s heads, and now it’s getting translated into agent memory within the coding agent are the harness. The biggest limitation factor that we see with this is agent memory is still very limited to an individual user, and no standard patterns have now emerged yet in terms of sharing agent memories across your broader teams or across your entire engineering organization. While we were trying to solve this problem for the coding agents on the engineering side, our go-to-market teams

[03:22] were also building business agents for go-to-market agents for their end-to-end executive use cases. So, they’ve been building uh custom agents that are purpose-built with customer data that is brought in from multiple data sources, and they’ve done several iterations to streamline all of this unstructured data coming in from all of these data sources into a structured data on top of which these agents operate. What they have ended up with is a really optimized like rack plus graph rack pipeline that serves as a centralized context layer that makes all of these individual uh business agents work really well and

[03:53] solve the problem for all of them. So, we started looking at how can we learn from this and what can we do to make the coding agent performance really better? And when we looked at this, what we realized is in a distributed systems and microservices architecture, APIs are the context layer for you. Complex engineering architecture is often broken down into domains and models, and each microservice is responsible for owning one single responsibility as per a model or a domain, and APIs are what defines what that responsibility is. And API

[04:23] calls between systems is usually how you identify workflows and user journeys that span across multiple systems. So, agents are only as good as the context that they’re given. So, we set out on a journey to build the best context layer for the agents. So, we went out to start building an API context graph for what Postman’s engineering architecture looks like. The journey started by identifying and cataloging every single microservice that was on production. And then we identified every endpoint that is exposed by each of these REST API services, and then we captured how each

[04:56] and every one of them is implemented right down to the exact line of code where it was implemented. And we also mapped how each and every service talks to each other, and how each endpoint connects to each each and every other endpoint. We also tracked how the data goes all the way down across the stack, including databases and caches, and all the way down in the entire stack. We also identified how applications like front ends, CLIs, APIs, how they interact with the whole back end architecture and back end infrastructure.

[05:27] We get give all of this data and we index all of this data using LLM to produce a centralized and effective context graph layer. But one key principle that we had in mind always was every single data point that landed on the context graph always had to be grounded down in a hard truth, and that hard truth is either a line of code that is implemented in your code base, or it could be a an exact trace that is coming from a production telemetry. With this in place, we set out on a journey to populate our context graph, and this is a snapshot of what our

[05:58] engineering architecture kind of looks like. So, it is some of the very common patterns that you would expect start to emerge. You start to see a central cluster of core services, of very tightly intertwined intertwined APIs and services that are tightly dependent on each other. You find one or two heavily bloated services that are on the outer edges of these systems. The ones at the center is typically what you would classify as tier zero or tier one services. So, now that we have the context graph, when we start looking at how does how do we measure what does it add in terms of improvements to the coding agents? So,

[06:33] we took real examples from the Postman Git organized from our organization’s Git repos. We took real PRs that were raised to the GitHub repos, and for each and every one of them, we identified what the developer was trying to do, and what the actual outcome was at the end of the PR. We also took like important projects, and what were the key design decisions and takeaways that were being discussed in those design discussions. We mapped each and every one of them into an eval, and we mapped what the actual decision that was taken in retrospect as the ground truth that we wanted the evals to confirm into.

[07:06] To to run the validations, we were able to get the Postman’s AI agent connects to the API context graph, and we were able to validate all of these against the Postman AI agent as well. But to keep the comparison fair, we also validated this against a generic coding agent, in this case Claude code, and we tried to verify these use cases simply by like a straightforward GitHub code search. We also took the same context graph, and we made it available as a skill, and also compared that against the generic coding agent, in this case

[07:37] Claude code. So, you’re going to see the results of of in a graph plotted like this. So, we scored every eval on zero to five scale and we also measured the exact amount of tokens it took for each of these runs. So, what you will see if something shows up on the top right, it means that the agent did a good job. It was able to score high on the evaluation, but it spent a lot of tokens doing so. If it’s on the top left, it did a great job not only scoring high, but it also did it much more efficiently. If something goes beyond the dash line, it just did not meet the bar of what a good score should

[08:08] be on that evaluation. So, then we bucketed like come up some of the common use cases and scenarios that we see in day-to-day development and where do they fall under? One key scenario that we always notice is API discovery. Any developer who is making a change either to the front end or back end integrating with other systems, what is the right API to call? And in real-world systems, you probably have hundreds of different of the hundreds of different APIs and most likely you have multiple APIs that probably do the same thing. So, in this case, uh a simplified example that I’ve taken is what is the

[08:41] right API to to call to get the profile name for a particular user. So, in this evaluation, this is a pure search use case and the results are what you would expect. Like with the context graph, the agent scored really well as compared to like pure code search where the agents don’t do really well. And there’s a slight deviation between like Postman and Claude, but the deviation is not that big enough uh for us to be uh diving deeper into. The second second use case is where it gets really uh interesting. So, this is what we call API design and redesign scenarios. So, in this scenario, let’s take a

[09:12] developer who’s building a new feature and to build that feature out, they’ve designed a new API and they’ve designed the schema for the request input. They have defined the uh implementation of it. They have tested it out from their side and then they go integrate it with the product and they’re happy with the product and they’re ready to ship. At the last minute, one of the dependencies comes to them and then say, “Hey, would it be nice if I just had this one additional property that I would like to pass to to API that I would like to use at a later point in time. So, the developer is like, “Maybe we don’t have enough time to evaluate all the different ways in which it can be done.

[09:44] What is the right schema to do this?” So, they just add this one additional context, which is a free-form JSON object, and they add a to-do in the code saying, “Revisit this and add a schema 2 weeks later.” The feature ships to production. Everybody’s happy. 2 weeks later, the developer comes back and finds out that that one particular property which is supposed to send one attribute now has 15 attributes, and it’s being passed by one service or it might be five services. It might be 10 services. Now, the developer has no idea what exactly is the shape in which the request is being passed down uh to the API, and what are all the different ways in which

[10:17] every single consumer has been passing data down to. So, it can be uh So, this is what I call like analysis of a shape of input for each and every API, and why they are used like that. So, this can be hard for a bunch of reasons. First, tracking down every single consumer of your API can be impractical in real-world scenarios. Even if you had service dependencies and service maps, finding out the exact shape of input used by each and every consumer can get really tricky. Engineers often lack the detail or depth of information in production logs, and for privacy reasons, it may not even be

[10:50] available at a lot of times. Even if the shapes are identified, finding out exactly why the consumer decided to pass it down like this is a very, very tricky problem. But, in this scenario, when we took this evaluation and then ran it with the Postman agent, what was surprising was the Postman agent almost got it really well. And the thing that helped in this case is, first of all, the context graph having an awareness of every single consumer of an API, but not just that, but having the drill down or the ground truth of where exactly each of these APIs were implemented in code, and the

[11:22] context surrounding that code helped the agent understand why the change was done. And very quickly, it was able to figure out exact unique shapes for every consumer that was calling this API, and you could be able to make the changes uh quite reliably and confidently. And you can see that the pure code search does not do really well, but with Claude and the skill, it does slightly better, but it tends to give up like after it’s done like enough number of turns and waiting for the user to kind of confirm what to do next. So the other very common use cases that we start to see is impact assessment.

[11:55] How do you figure out what is the impact of one particular change? So if I change this API, what are the potential use cases? Or maybe there’s an existing API, there’s a V2 API, and I’m interested in introducing a V3 API. How do I understand how the V2 is API V2 API is used first so that I can design a better V3 API. So this is one scenario where we see the context graph really shine well, and you can see that like Postman Agent not only does really well in terms of the quality of the output, but also it’s able to do it with almost like half or even 1/3 when compared to pure code search.

[12:28] But this is not smooth sailing all the time. Sometimes we see failures, and in this case, one of the use cases that we threw at it was find out the impact of a change in one particular PR where it introduce a change to an endpoint and figure out all the all the downstream services that are affected by that endpoint, and we started seeing a failure, and you can see the graph like almost inverted. We see Postman not only scoring down, but also like consuming a lot of tokens while it did that. And when we investigated in and into it and then tried to understand why it was failing, what we realized was that

[13:00] uh there were new consumers between the time where the eval was written and the time it the evaluation was run. So the context graph is not only important to populate, but it’s equally important that you keep it up to date, and any delays in syncing your context graph with the ground truth uh creates gap in the result. And if there’s a gap in the result, it immediately leads to a loss of trust by the developer, and that translates into lack of usage. Not only detecting new APIs and new dependencies, detecting removals of APIs and removal of dependencies is equally

[13:31] important and that can also lead to confusions and problems. So, you might think that these use cases may or may not be common to you, but when we went back and retrospected on all the PRs that were raised in the top 10 repos, we noticed that almost 75% of the PRs had some effect on the APIs. So, either these changes are introducing a change to the external surface area of an API or they’re introducing an integration of a new API and both of them have can have like really cascading impact downstream.

[14:01] So, these use cases were clear for us to do like a before and after comparison with the context graph and without the context graph, but as soon as we had this information, we were able to ask questions that we were previously not able to ask. And these questions asked allowed us to be able to take the Postman agent and say, “Hey, do a complete engineering analysis and an end-to-end architecture review of our entire ecosystem.” So, this is where the light bulb moment happened for us. When we asked the Postman agent to do this, it produced a 21-page engineering report going through every single weakness and

[14:34] points of vulnerability. It found out interesting insights for us including cycles of dependencies, which can be really problematic in terms of an incident, risky long-running migrations, which are signals of technical debt, and then single points of failure, which can be really problematic or issues that are waiting to happen, blind spots and telemetry, where stuff that is in the implementation does not reflect in telemetry, and then it came out with clear action items for hey, this is what your CEO, this is what your CTO, and this is what your staff engineers might need to do. On top of all of these things, when we look at what we can do for further

[15:07] improvements, one of the areas that stands out is bringing in the semantic layer of what does your business do and connecting it into the context layer of what your coding agents take as input for their workflows. Another layer of improvement that we’re looking into is how can we improve and add additional reasoning of why does a data model exist? Why does the domain map like this? Why does this API exist versus other APIs? Why Why should you use one API over the other API? And all of these helps in subsequent coding decisions and all of that translates into really effective output when you’re using them

[15:40] in your day-to-day development workflows. So, takeaways and learnings. We’ve realized that API context graph serves as the context layer for coding agents in a real-world distributed systems. Gives a high-level view that helps you answer questions about your engineering architecture that you were not able to answer in the context of a single repo or a single microservice. It shortens the time to find the right way to do a particular problem. And all of this means that do the doing this either with the right amount of quality or being much more efficient in being able to do this.

[16:11] So, efficiency translates either into your cost savings, but the way that we see it is if we can do one particular task a lot more efficiently, it means that we can do it more often and this allows us to do the same evaluations at a lot more frequency including bringing it down at the PR level or even bringing it down right down to the development machine or in the development environment where the where the engineer is working on. So, the sooner we can move the decisions and catch problems earlier in the life cycle, we believe that the agents who are generating code can translate into peace of mind for the

[16:43] developer and help them ship changes to production with a lot more confidence going forward. So, that’s everything from my side. All of these capabilities are available within the Postman as a platform. These are also available to use as early access. I will be around outside right after the talk if you have any questions or follow-ups. We also have a booth S32 right across the hall from here. That’s everything from my side. Thank you so much.

[17:15] >> Woo! >> [music]