Agentes de código falham sem grafos de contexto da equipe

Engenharias sem nada em comum estão construindo a mesma estrutura, sob nomes diferentes: catálogo de serviços, registro de APIs, mapa de propriedade ou grafo de dependências. Para Talia Kohan, no blog da Postman, a convergência não é coincidência: agentes de código mudaram a economia do trabalho, e a diferença entre um agente em projeto pequeno e um em codebase real não está no modelo, e sim em quanto contexto da equipe ele alcança.

Em campo, ela viu agentes corrigir tickets em bases desconhecidas: leem o arquivo imediato, fazem grep, adivinham o formato da resposta e entregam mudanças plausíveis que citam endpoints aposentados ou duplicam serviços já existentes. O agente não é incompetente; opera sem o grafo que os humanos acumularam na cabeça. A informação útil fica espalhada em outros repositórios, contratos antigos, APIs sem catálogo e threads do Slack.

Por que janelas maiores não resolvem

A primeira resposta foi ampliar a janela de contexto. Ajuda nas margens, não no fundo: o estudo "context rot" (2025), da Chroma, testou 18 modelos frontier e todos degradam antes da janela encher; o "lost in the middle", de Stanford, mostrou queda de precisão de 30% ou mais para informação no meio de prompts longos. O modo de falha não é de raciocínio, e sim de recuperação e grounding - segundo o VentureBeat, agentes perdem contexto em bases grandes, geram refatorações instáveis e carecem de consciência operacional. O GraphRAG, da Microsoft, mostra que travessia de grafo sustenta raciocínio entre entidades que a busca vetorial perde; o CodexGraph (NAACL 2025) mostra que um LLM consultando o grafo do repositório navega e gera melhor que só com recuperação. Nenhuma é bala de prata; juntas apontam que o modelo é o lugar errado para o conhecimento que falta.

O que é um grafo de contexto

É um conjunto de entidades tipadas e relações tipadas - a ideia do RDF do W3C: sujeito, predicado, objeto. Importam repositórios e funções; serviços, endpoints e especificações OpenAPI; times e propriedade de código; ambientes, deployments e feature flags; governança, deprecações e aprovações; incidentes e postmortems. Com isso, o agente responde o que grep não responde: já existe um endpoint que faça isso? quem aprova a mudança? o que quebra se o formato da resposta mudar? qual time recebe o pull request?

A camada de API como grafo

Quem trabalha com APIs já tem parte disso: uma especificação OpenAPI é um conjunto de entidades e relações tipadas, e um workspace do Postman agrega fatos de runtime com Collections, Environments e monitors. O texto apresenta produtos da Postman como infraestrutura: Private API Network para descoberta, API Governance para regras verificáveis antes do pull request e Postman MCP Server para expor o grafo como ferramentas de consulta. Fornecedores como Stripe, Okta, Twilio e Salesforce geram os mesmos erros: sem saber que a aplicação usa a v2 do fornecedor, o agente escreve código para a versão errada, e o erro só aparece com rate limit ou cobrança. O Model Context Protocol (MCP) dá aos agentes acesso estruturado ao grafo, e a especificação Agentic Resource Discovery, recém-publicada pelo Google, leva o padrão à escala da internet.

Armadilhas e primeiros passos

Quatro advertências: o grafo fica obsoleto rápido - atualizações de propriedade devem entrar nos fluxos de revisão que já mesclam código; governança sem aplicação é pior que nenhuma - se o agente entrega contra endpoint descontinuado, ou ele não vê o fato ou a aplicação, geralmente no CI, está quebrada; cardinalidade pesa - modelar 20 serviços é fácil, mas 500 serviços e uma década de histórico criam duplicatas falsas; e descoberta é só metade do caminho - publicar collections e environments junto às especificações permite ao agente testar. Como começo, três passos baratos: publicar as APIs existentes no Private API Network com metadados de propriedade, ativar governança ao menos para deprecação e autenticação exigida e conectar um agente (Claude Code ou assistente interno) ao Postman MCP Server. Nada disso é projeto de pesquisa - é encanamento para tornar os agentes já existentes mais úteis.