Context engineering for AI agents: What actually works

The context bottleneck

Your team has invested considerable time and budget into AI agents. You're running the latest LLM models. You've built MCPs. Then your team starts asking agents to do real work, and that's when the frustration hits.

Agents either take forever to respond, give wrong answers, or burn 100,000 tokens on a simple task. The problem isn't volume. It's that your context is fractured.

When data lives in GitHub, Jira, and PagerDuty separately, agents don't know what's real. They spend tokens reasoning through contradictions: calling GitHub for owners, Jira for tickets, PagerDuty for incidents, reconciling naming mismatches. Not only does this generate thousands of expensive tokens, it means the agent relies on "probabilistic similarities": it spots two pieces of data that look related statistically, but they aren't. This delivers inaccurate results at high cost.

Accurate context cuts costs

Pre-integrated context fixes both problems. When your data is already joined - service to team to on-call schedule - a single query surfaces everything the agent needs, all in real time. No chained calls. No reasoning about relationships. Accurate context. Faster decisions.

Teams using a unified, relational context layer saw a 40% improvement in agent accuracy and up to a 70% reduction in token consumption compared to teams using MCP and RAG alone. - Gartner® 2026

Why other approaches fall short

MCPs: delegation, not architecture

Connect an MCP for each tool in your stack and your agent has real-time access to everything. Sounds good. The problem: your agent now has to figure out the relationships between all those tools at runtime. It doesn't know which GitHub repos map to the service, which Slack channel it belongs to, what policies apply, who the owner is. So it calls one MCP, figures out what's relevant, calls another, then another. Every task starts cold with discovery. Token cost compounds with every context hop.

MCPs are the right mechanism for giving agents reach. They're not a context layer on their own.

RAG: search without relationships

RAG finds content that matches your question. The problem is that RAG searches by vector similarity, not by how things connect. Ask "what do I need for this service?" and you'll get chunks similar to that query. But you won't find the team that owns the service unless team ownership shows up in similar language. You won't connect incidents with the same root cause unless they're written the same way. Every structural relationship your agent needs still requires reasoning. It either guesses, asks a human, or misses the information entirely.

File systems: scale kills them

Some teams build a repository of markdown files: AGENTS.md, skill files, runbooks, decision logs. At small scale, this works. At enterprise scale - 500 services, each with its own runbook, plus monitoring files, incident templates, org charts, architecture diagrams - you have 5,000 files with no structure to determine which ones matter.

No dynamic updates as your stack changes. The moment you need context to reflect reality, you're building a context lake in markdown and JSON, manually tagging every file, and rebuilding them every time your organization moves. When a team restructures, when on-call rotations change, or when you sunset a service, those files go stale. Your agent now has context from five weeks ago.

Files don't scale. Databases do.

What actually works: the Context Lake

A context lake is a queryable graph of your organization's data. Not a data warehouse. Not a vector store. A relational graph where services, teams, incidents, deployments, runbooks, workflows, and decisions are typed nodes with explicit relationships.

An agent enters the graph with a task and retrieves everything it needs, structured and validated, ready to act. One query instead of five MCP calls. Structured data instead of raw material. Relationships are explicit in the model instead of hidden in a prompt.

What you need

A relational data model built for agents

Your agent shouldn't make five separate API calls to five different systems to find out who owns a service, where incidents are discussed, who's on call, and the incident history. Instead of encoding these relationships in your prompt ("First find the team, then look up their Slack channel"), model your entire engineering system as connected pieces. The relationships are baked into the model itself.

When your on-call process changes or you want to track a new relationship, you update the structure once. Every agent and person using it immediately sees the change. You're not hunting through a dozen prompts to update the same rule.

The model must support both agent and human collaboration from the start. It's an ever-evolving structure, iteratively refined to add or improve use cases.

A comprehensive sync and mapping layer

A data model only works if it reflects reality. You need a sync layer that pulls from your entire stack - well-known tools or internal ones. Mapping incoming data to your model automatically ensures it aligns with your semantics. Reconciliation keeps it up to date.

API calls, rate limits, live events, incremental syncing, mapping systems - this is unglamorous work, but it's what makes the graph trustworthy. An agent that can't trust its context won't act on it. A graph that falls out of sync is worse than no graph at all.

One shared layer

This is what makes the context lake reusable. You need:

• A production-ready REST or GraphQL API
• MCP server tools for agent access
• Clear query patterns so agents know what to ask for

One shared layer, many consumers. An agent accessing the graph looks identical to an internal tool querying it for a dashboard. The infrastructure doesn't care who's asking.

A comprehensive graph query API

Agents need to ask questions like "which services depend on this one?" or "show me all incidents owned by this team in the last 30 days with their post-mortems" or "what workflows touch this service?" Your query API should support relationships in any direction, filters by property or type or time, aggregations like count incidents by team, and recommendations. The query language should be expressive enough that agents can ask any reasonable question without falling back to raw MCP endpoints or RAG.

Self-building loops

A context lake maintained entirely by hand is costly and doesn't scale. Auto-discovery should continuously scan your stack, detect new services, infer relationships, and propose additions to the model. Humans review and approve. Agents can propose and act. Self-building doesn't mean autonomous - it means working with the graph to reduce manual effort. Automation proposes. Humans decide. The graph keeps up with your organization as it grows.

Skills and MCP in the right places

Skills are reusable instruction packages attached to nodes: approval workflows, remediation steps, deployment procedures. Attach skills directly to the things they describe. An agent navigating a service node sees the attached runbook and incident response skill. Skills stay with the graph, not scattered across prompts. Every agent that touches a service sees the update immediately. You maintain a single version of skills.

Connected to events, changes, and decisions

Every decision made by an agent or human should be recorded as a structured event: what was decided, when, by whom, on which entities, with what outcome. Before your agent reasons about a new incident, it should look back at the last five similar ones. What was tried? What did the post-mortem conclude? Was a proposed fix already attempted? Without that history, every incident starts cold.

Built for scale and production readiness

Observability is essential: see what agents are querying, how often, where queries are slow, and what queries fail. You're building infrastructure, not a feature.

Built for governance

As agents act on your graph, they need boundaries. A CI/CD orchestration agent shouldn't query the on-call graph. An incident response agent shouldn't mutate your service model. Every query, mutation, and proposed change should be logged. When an agent made a decision that affected production, you need to know what information it had when it decided. You'll need a just-in-time permission policy system to control it.

Take a deep dive into the Context Lake

 Nine components from first principles require significant infrastructure investment across data modeling, integrations, APIs, and governance. Port provides production-ready implementations of all of them. Here's where to learn about each:

What's next

The context lake is continuously evolving. Follow Port's changelog for updates and suggest improvements in the roadmap. We're just getting started.