DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Newsletter
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

DZone Spotlight

Wednesday, November 18 View All Articles »
Process Intelligence Landscape 2026: Mining, Orchestration, and the Agentic AI Shift

Process Intelligence Landscape 2026: Mining, Orchestration, and the Agentic AI Shift

By Kai Wähner DZone Core CORE
Process intelligence is used to mean one thing to most people: a mining tool for process analysts. It is becoming the layer that decides how reliably an enterprise runs, governs, and automates its operations. The market is converging from both sides. Mining vendors are buying execution and orchestration, with Celonis launching its Context Model and acquiring Ikigai Labs. Orchestration vendors are adding analytics and agent control, and platform vendors are buying miners outright, with Salesforce folding Apromore into Agentforce. The two halves of the discipline, seeing what runs and governing what happens next, are collapsing toward each other. What Is Process Intelligence? Process intelligence has three parts that work together: Mining reads the event logs that ERP, CRM, and ticketing systems already produce and reconstructs how work really runs, not how a diagram says it should.Orchestration governs what happens next, routing work across systems and people and enforcing the rules.The decision gate checks every automated action and AI recommendation against business rules, confidence thresholds, and constraints before it has consequences. The discipline grew out of Business Process Management (BPM). BPM promised to fix processes and largely disappointed, modeling idealized diagrams that did not match reality on projects that took years. Process intelligence is what the discipline became once it started working from real execution data in near real time. The most common mistake is treating process intelligence as one thing, usually a mining tool. It is three. Mining without orchestration sees problems but cannot fix them. Orchestration without mining automates a process nobody has verified. Neither one, without a decision gate, can tell an AI agent what it is allowed to do. The Payoff Starts Before AI Most of the value lands before an agent enters the picture. Mining shows the gap between how a process was designed and how it actually runs, which is usually where the cost hides. It surfaces bottlenecks, rework loops, and the variants that quietly bypass controls. Orchestration then closes that gap, and the decision gate keeps it closed. The result is faster cycle times, lower operational cost, cleaner compliance evidence, and processes a team can actually trust. Every one of those holds whether or not an agent is involved. Why Does Agentic AI Raise the Stakes? Agentic AI does not change why process intelligence matters. It raises how much it matters, and how fast a mistake spreads. An agent takes actions and makes decisions with downstream consequences, which is what makes the process layer non-optional for any serious deployment. AI agents need three things from it: Operational boundaries that define what an agent can decide on its own, what needs human approval, and what must always escalate.Live context, so the agent works on current operational reality rather than data that was already stale when it arrived.Audit trails that record every action, model decision, and human checkpoint in a way compliance can stand behind. The decision gate is where this is enforced. What passes the rules proceeds. What does not is escalated or rejected with a documented reason. Governance is the property you want. The decision gate is the mechanism that delivers it. One step gets skipped often. Introducing agentic AI is not the same as embedding AI into an existing process. A process built for human execution is rarely the right foundation for an autonomous one. The step before automation is redesign, using mining evidence to understand what the process actually does, then rebuilding it for how agents work. Organizations that skip it automate their inefficiencies at machine speed. Process Intelligence Splits Into Mining and Orchestration The landscape is easy to read as a four-quadrant chart where you pick one box. It is not. Process intelligence is at least two decisions, sometimes three. The bottom half of the chart is the mining decision. The top half is the orchestration decision. Most enterprises end up choosing at least one mining vendor and one or more orchestration vendors, because no single product covers both well across a multi-vendor environment. Bubble size reflects relative market reach. Darker fill marks stronger agentic AI capability in production today, and the bridge marker (⇄) flags vendors extending into the other band as a strategic direction. Two stacked decisions, not one ranking. The word agnostic means something different in each half. In orchestration, it comes down to where the process logic lives, who owns it, and how open the engine is. BPMN makes the process model readable and auditable across tools, but engines are rarely drop-in compatible, so the model travels more easily than a running deployment. Real portability comes from owning your business logic in standard code, and from running an engine you can host and operate yourself, with an open or source-available core. Logic locked inside a vendor's proprietary low-code environment offers none of that. In mining, agnostic is about data-source and commercial independence, whether a miner can connect to SAP, Salesforce, and ServiceNow at once while being licensed and governed independently from all of them. There is a third choice too, and the landscape leaves it off the chart on purpose: the decision gate. It is a function, not a product category. It can live inside an orchestration engine as native DMN, run as a real-time context engine fed by event streaming, or sit in a third-party rules engine. The two bands map the decisions that line up with vendor categories, mining and orchestration, and the gate attaches to whichever route fits. A split result is therefore normal and often correct. Many enterprises land on an agnostic miner and a platform-native orchestrator, or the reverse. It is not a contradiction. Buyers shop product by product. Architects design across the boundary. The full landscape works through the market vendor by vendor: Process Intelligence Landscape. Four Choices That Keep Your Options Open Four decisions matter more than the logo on the contract, because they decide how reversible your choice is later. Open standards come first. They keep definitions portable and tools interchangeable: BPMN and DMN for orchestration, OCEL 2.0 and XES for mining, MCP and A2A for agent connectivity. Each solves a different problem. OCEL 2.0 is the portability standard for object-centric mining (OCPM), BPMN keeps a process model readable across tools, MCP standardizes how agents reach data. Watch one gap on the mining side. Object-centric process mining is a capability many vendors deliver on their own internal model. OCEL 2.0 is the standard that actually makes the data portable. So OCEL export is the lock-in check, not the OCPM label. A vendor that builds proprietary equivalents of these standards recreates the lock-in closed BPM platforms created a decade ago, one layer up. Open source is the second, and it is not the same thing. A vendor can support every open standard and still be closed underneath. An open core — the engine or the library itself — is what makes leaving practical rather than theoretical, because you can host it, inspect it, and migrate or fork it if you have to. Open standards keep your data portable. Open source keeps the software itself within reach. Data sovereignty is the third. Some platforms are SaaS-only and require operational data to leave your environment. Others run on-premises, or analyze data where it already lives inside your own data platform. Regulated industries have always weighed this. The trade and digital-sovereignty tensions between the US, China, and Europe have turned it into a board-level question for everyone else, because where operational data sits, and who can reach it, is no longer only a technical choice. Consolidation is the fourth. Smaller specialists change hands, and an acquisition can bring price increases, roadmap shifts, forced migrations, and a loss of cross-vendor neutrality. Bigger is not automatically safer. A large suite vendor removes the acquisition risk and hands you its own lock-in instead. Apromore's move into Salesforce shows how quickly an independent specialist can change hands. The Trinity: Where the Three Layers Fit Process intelligence does not stand alone. It is one of three layers that only work together. Event-driven data integration provides the current, governed data, mapped vendor by vendor in the Data Integration Landscape 2026. Process intelligence turns that into an understanding of how the organization runs and a grip on what happens next. Trusted agentic AI acts on both. None of the three delivers much without the other two. I call them together the Trinity of modern data architecture. No single vendor leads all three layers, and that is less of a problem than it sounds. The convergence that matters is architectural, not commercial. The three layers have to work as one system. They do not have to carry one logo. Most enterprises are better served by a strong miner, a strong orchestrator, and a strong integration and agent layer than by buying all three from one suite. Best-of-breed keeps capability, pricing leverage, and exit options on your side, and open standards keep the seams between them manageable. Buying the whole stack from a single mega-vendor removes some integration work up front and replaces it with lock-in across all three layers at once. For enterprises, the takeaway is that process intelligence selection, data integration, and agentic AI strategy are not three separate decisions. Each constrains the others, and the cost of treating them apart shows up in the first production incident. The full vendor-by-vendor analysis is available as a free PDF with no registration. It works through the platform-native and agnostic options on both the mining and orchestration sides, shows where open standards and deployment model draw the real lines, and ends with six questions for narrowing the field to your own situation. Read the full Process Intelligence Landscape. If you are making a process intelligence decision, start with the enterprise architecture, not the vendor list. Decide what you need at the mining layer and the orchestration layer, confirm where the decision gate lives, and the shortlist gets much shorter. About this Landscape This is an independent analyst perspective. No vendor paid for inclusion or placement. No vendor reviewed its section before publication. I run an advisory practice through Kai Waehner GmbH and have held roles at Talend, TIBCO, and Confluent. I also serve as Global Field CTO at Kestra, a workflow orchestration vendor. Kestra is referenced in the full report where pipeline orchestration meets the process intelligence stack, but it is not part of the landscape and was not evaluated or placed in any zone. The complete methodology note is in the full landscape. More
Vapi vs Retell AI vs LiveKit: Architecture, Latency, Pricing, and Developer Experience

Vapi vs Retell AI vs LiveKit: Architecture, Latency, Pricing, and Developer Experience

By Akmal Chaudhri DZone Core CORE
Vapi, Retell AI, and LiveKit can all power voice agents, but they put different quantities of infrastructure and application logic in the developer's hands. Vapi and Retell AI are managed orchestration platforms. LiveKit Agents is an open-source, code-first framework that can run on LiveKit Cloud or infrastructure you operate. That distinction affects customization, deployment, integration design and total cost, not just which dashboard you prefer. The applied VoiceTest exercise recorded automated-judge pass counts of 7/8 for the imported LiveKit graph, 5/8 for Retell, and 3/8 for Vapi. Don't read these as a platform ranking or a measure of agent quality: our transcript audit found judge errors, and VoiceTest generated agent turns with the same configured model for all three graphs, not the vendor-native LLMs or audio pipelines. Each scenario was run once; Vapi and LiveKit also hit the 50-turn cap in every test, while Retell's imported End Call node is the leading structural explanation for its different termination behavior. If you'd like to check our work, we've published the full technical report and evidence in a GitHub repository. It includes the prompts, rubric, judge feedback, transcripts, imported graphs, and limitations behind the results we discuss here. How the Three Platforms Differ Vapi is a managed platform configured through an API and dashboard. Developers select a transcriber, language model, voice, and tools; server-side tools connect the assistant to application endpoints. Its reviewed SDK coverage includes TypeScript, Python, Java, Ruby, C#, and Go on the server side, plus web and mobile clients. Retell AI is also managed. Its orchestration layer coordinates speech recognition, the LLM, and speech synthesis, with agent-building options that include prompt-based and conversation-flow designs. The reviewed developer SDKs are TypeScript and Python, and custom functions connect agents to external HTTP endpoints. LiveKit Agents takes a code-first approach. Developers define an agent in Python or TypeScript, configure an AgentSession, and select STT, LLM, and TTS providers, or use a real-time speech model. The framework uses LiveKit's real-time media stack. You can self-host the infrastructure or use LiveKit Cloud for managed deployment. DimensionVapiRetell AILiveKit AgentsOperating modelManaged orchestrationManaged orchestrationOpen-source framework; cloud or self-hostedApplication logicConfigured tools calling server endpointsCustom functions calling HTTP endpointsTools and state in agent codeDeploymentVendor cloudVendor cloudLiveKit Cloud or your infrastructureSDKs reviewedTypeScript, Python, Java, Ruby, C#, Go; web/mobile clientsTypeScript, PythonPython, TypeScriptMedia scopeVoice and chatVoice and chatVoice, video, vision, avatarsObservabilityCall recordings, logs, transcripts, packet captures, evaluationsAnalytics, alerts, simulationsSession replay, traces, logs, reports, tests Managed Orchestration or Code-First Control? With Vapi or Retell, the vendor operates more of the media and orchestration layer. Your team owns prompts, tools, business rules, and the backend systems those tools call. This can shorten the path to a working agent, particularly when the workflow fits the platform's configuration model. With LiveKit, the agent's behavior is code. You can control turn handling, tool execution, context management, and how agents interact with other real-time participants. That flexibility comes with responsibility: your team must maintain the agent application and decide how much of the media infrastructure to operate. LiveKit Cloud offers a middle ground: it manages deployment and related services while retaining the code-first development model. A managed service becomes restrictive when the application needs unusual state management, custom turn-taking, video, or deployment inside a specific network boundary. A code-first framework can be unnecessary overhead for a standard call flow where a small team simply needs to answer, look up a record, book, or transfer. Latency: Measure the Pipeline, Not the Brand End-to-end voice latency is a chain of delays: endpointing must decide that the caller has finished; speech recognition must finalize the transcript; the LLM must produce a response; text-to-speech must generate the first audio and the network must deliver it. A speech-to-speech model can remove separate STT and TTS stages, but may offer less control over exact wording. We found that the platforms expose different controls. Vapi uses start- and stop-speaking plans and supports configurable endpointing options. Retell exposes responsiveness and interruption-sensitivity controls, with options such as dynamic responsiveness and backchannels. LiveKit provides turn detection, VAD/adaptive interruption handling, endpointing controls, and preemptive generation. The supplied platform research didn't identify comparable vendor-published end-to-end latency figures. The VoiceTest experiment also can't fill that gap: its duration_ms field records simulation execution time, not first-audio latency or caller-perceived response time. A meaningful latency benchmark needs native live calls, fixed model and voice choices, controlled network and telephony paths, timestamped audio events, repeated trials and percentile reporting. Developer Experience and Backend Integration Consider an appointment assistant with two operations: retrieve a patient's appointment and move it to a new time. In Vapi, a tool is defined with a JSON schema and server URL; Vapi sends a tool-call request and expects a matching result. Retell custom functions call an HTTP endpoint with call context and arguments, and requests include a signature that the backend should verify. LiveKit tools can be methods in the agent's code, so there's no separate webhook hop unless the application's scheduling system itself sits behind an API. The implementation detail that matters most isn't syntax. It's transaction safety. A reschedule or cancellation can be retried or interrupted, or have its response discarded. State-changing operations should be idempotent, and the agent must communicate backend failures clearly. Don't let a model claim a booking is complete until the scheduling service has confirmed the write. Telephony, SIP, and Real-Time Media All three platforms support connections to phone systems, but the integration model differs. Vapi documents its own SIP transport and support for providers such as Twilio, Vonage and Telnyx, along with bring-your-own trunk options. Retell's elastic SIP trunking model connects provider origination and termination to Retell; it also documents integrations with contact-center systems including Avaya, Genesys, Five9 and Amazon Connect. LiveKit represents calls as participants in rooms: inbound calling uses a phone number, inbound trunk, and dispatch rule; outbound calling uses an outbound trunk and SIP participant creation. The room model is particularly useful when voice is one participant in a broader real-time experience, such as a patient joining by phone while a clinician joins by video. Check the precise transfer behavior you need, too: cold transfer and warm, agent-assisted transfer aren't interchangeable capabilities. Production Operations and Observability Before launch, test interruptions during long answers and tool calls, backend timeouts, duplicate writes, dropped network connections, and recovery after errors. Re-run a fixed regression suite after every prompt, model, or tool change. Review concurrency limits against peak simultaneous calls rather than average volume. The reviewed documentation describes Vapi call recordings, logs, transcripts and SIP packet captures; Retell analytics and alerting for call volume, cost and errors; and LiveKit session replay, trace spans, session reports and external metrics integration. These features help diagnose failures, but none replaces application-level tests or realistic production trials. Pricing and Total Cost of Ownership Public pricing checked November 14, 2026 isn't directly comparable because the vendors package usage, included allowances, model inference, telephony, concurrency and observability differently. Vapi lists $0.05/min hosting, with STT/LLM/TTS and transport billed separately; Core is $29/month, and Pro is 10% of hosting with a $999 monthly minimum. Retell lists a public voice-agent range of $0.07-$0.31/min, with the final rate dependent on the selected stack. LiveKit Cloud lists Build at $0/month, Ship from $50/month, and Scale from $500/month, with agent-session, telephony, inference, and observability allowances/charges. These are published list-price snapshots, not quotes, and not the cost of running an equivalent production configuration on each platform. PlatformPublic pricing snapshot (Nov. 14, 2026)Common cost components billed separately or variablyComparison caveatVapi$0.05/min hosting; Core $29/mo; Pro 10% of hosting with $999/mo minimum; Premier customSTT, LLM, TTS, telephony, optional compliance and add-onsNot an all-in rateRetell AIPublic voice-agent range $0.07–$0.31/min; 20 concurrent calls included on pay-as-you-goExact voice engine, TTS, LLM, telephony, add-ons and concurrencyRate depends on selected stackLiveKit CloudBuild $0/mo; Ship from $50/mo; Scale from $500/moAgent-session minutes, inference, telephony, observability, recordings and optional featuresPlan allowances and self-hosting costs differ Use a workload-specific estimate from the current calculators and contracts. Specify model, STT, TTS, telephony, included minutes, concurrency, retention, observability, region, and engineering effort. The earlier illustrative all-in model depended on non-equivalent assumed component rates and fixed engineering allocations; it shouldn't be used as a current cross-platform cost ranking. What the VoiceTest Experiment Found The experiment used eight scenarios and three evaluator metrics per scenario. VoiceTest's exports record the same model for agent generation, simulation, and judging across all 24 executions. The vendor-native models, voices, speech recognition, speech synthesis, noise cancellation, and native turn detection weren't exercised. This was an imported prompt/graph simulation, not a native runtime comparison. The table below shows the statuses VoiceTest's automated judge recorded. Several are wrong on a transcript read, so treat it as raw output, not a validated assessment of agent behavior. ScenarioLiveKitRetell AIVapiGreetingPassFailPassSchedulingPassPassFailAvailabilityPassPassFailReschedulingPassPassPassCancellationFailFailFailUrgent medical concernPassPassPassGeneral clinic informationPassFailFailOne question at a timePassPassFail The automated judge recorded pass counts of 7/8 for LiveKit, 5/8 for Retell, and 3/8 for Vapi. A transcript audit, however, found important false-positive judgments. Vapi received passes despite placeholder-filled rescheduling language and unsupported booking claims in its greeting and triage-nurse handoff. LiveKit passed a clinic-information exchange that invented services, hours, and online booking. Retell's passing rescheduling and availability exchanges also contained ambiguous or unsupported claims. Conversely, LiveKit's cancellation limitation disclosure was failed by the judge. The counts are therefore not reliable measures of agent quality, even descriptively. Read the Results With the Right Caveats The retained prompts weren't equivalent. Vapi's longer prompt contains positive booking/confirmation language and unverified clinic facts despite no scheduling integration. Retell's published Version 0 prompt is shorter and says not to invent availability or imply live scheduling access. LiveKit's prompt prohibits invented clinic facts and unsupported transaction claims, but its imported graph still produced unsupported clinic facts in the General Clinic Information transcript. Several LiveKit prompt instructions also closely mirror the rubric criteria. These differences confound the outcomes and don't show that one native platform is better. All eight Retell transcripts end with an end_call transition. The imported graphs suggest why: the Retell graph has a transition from its main node to an End Call node, while the Vapi and LiveKit graphs are single nodes with no way to end the call. Vapi's dashboard export lists endCallPhrases, but nothing in the imported Vapi graph represents them. The LiveKit graph also omits the on_enter greeting directive. That structural difference is the most direct explanation we have for the different termination behavior, though we haven't confirmed it with a controlled rerun. In most Vapi and LiveKit runs, the caller said goodbye early, and the remaining transcript looped through farewells. The One Question at a Time judgments are also disputed: Retell's passing transcript contains compound prompts, while Vapi's failed transcript requests multiple data fields in one turn. The criterion needs a clearer definition and human adjudication. One test changes the recorded pass rate by 12.5 percentage points. Taken together, the judge errors, single run per cell, shared model, prompt differences, and termination asymmetry mean the recorded counts should be treated only as audit-trail outputs, not comparative results. Which Platform Should You Choose? Vapi and Retell AI are worth evaluating when you want managed orchestration, configuration-led workflows, and vendor-operated voice infrastructure. Compare their exact SIP, SDK, tool, and contact-center requirements against your use case.Choose LiveKit Agents when you need application-level control over the media session, turn handling, tools, or multimodal room experience, provided you have the engineering capacity to own the agent code.Whichever platform you select, connect real backend operations before allowing the agent to claim that it booked, canceled, or rescheduled anything. Treat the backend as the source of truth. Our practical choice isn't simply managed versus open source. We should ask how much control the application needs, how much operational work the team can support, and whether every spoken claim is backed by real system state. Healthcare Deployment: Verify the Contract, Not Just the Product Badge For a US healthcare workflow, don't send protected health information until the required Business Associate Agreements are signed and every model, transcription, voice, telephony, storage, and analytics provider is eligible under the chosen arrangement. Vapi's HIPAA mode requires a paid add-on, signed BAA, and compatible providers; its HIPAA and Zero Data Retention modes are mutually exclusive. Retell offers a self-signed BAA at no additional fee and per-agent storage/retention controls, but confirm processing and storage locations in writing. LiveKit offers BAAs for eligible Cloud plans/projects; its BAA covers LiveKit Cloud, not self-hosted infrastructure, third-party model providers, or your own storage. For UK/EU deployments, HIPAA isn't a substitute for GDPR/UK GDPR. LiveKit documents separate controls for EU project data, agent compute, SIP, inference, provider plugins, and storage; selecting an EU project data region alone doesn't pin every layer. Vapi's EU region is available only with its Premier Success Package. Vapi and Retell should be asked to confirm artifact-level residency and subprocessors contractually. Consult your privacy and legal teams before processing health data. Research Note Vendor pricing, compliance, and data-residency pages were rechecked November 14, 2026. VoiceTest runs were recorded November 9-10, 2026. This is a descriptive imported-graph evaluation, not a controlled platform benchmark. See the companion technical report and evidence repository for the prompt-equivalence audit, full rubric, judge feedback and limitations. Summary Vapi, Retell AI, and LiveKit can all power a voice agent, but they hand you very different quantities of infrastructure and application logic. Vapi and Retell AI are managed orchestration platforms, while LiveKit Agents is an open-source, code-first framework you can run on LiveKit Cloud or host yourself. We compare the three on architecture, latency controls, backend integration, telephony, observability, pricing, and healthcare compliance. We also share what an imported-graph test of eight appointment scenarios did and didn't tell us. The pass counts aren't a ranking, so the real takeaways are how much control you need, how much operational work your team can carry, and whether every spoken claim is backed by real system state. References Vapi: PricingPricing and Success PackagesHIPAA ComplianceData FlowEU region and data residencyCustom toolsSpeech configurationSIP trunking Retell AI: PricingCompliance and BAARetell Trust CenterPrivacy PolicyOrchestration overviewCustom functionsCustom telephony LiveKit: PricingHIPAAHIPAA Eligible Products and ServicesEU data residencyVoice AI quickstartTool definitionTurn detection tuningInbound SIP trunkSimulations VoiceTest: VoiceTest AgentGraph concepts Companion material: Technical report and evidence repository More
From Phone Menus to Workflows: The Quiet Engineering Behind Voice Agents That Act
From Phone Menus to Workflows: The Quiet Engineering Behind Voice Agents That Act
By Igboanugo David Ugochukwu DZone Core CORE
When Jev Says It's Sure, Is It Right? A Fraud Case Study in Neo4j
When Jev Says It's Sure, Is It Right? A Fraud Case Study in Neo4j
By Akmal Chaudhri DZone Core CORE
Introducing TypeSafe Jev: Typed Judgments as Programming Primitives
Introducing TypeSafe Jev: Typed Judgments as Programming Primitives
By Horatiu Dan DZone Core CORE
Measuring AI Impact at the Team Level
Measuring AI Impact at the Team Level
By Stefan Wolpers DZone Core CORE

More Articles

Pitching Kotlin: An Engineering Leader's Guide to Legacy Modernization
Pitching Kotlin: An Engineering Leader's Guide to Legacy Modernization

I've been on both sides of the Kotlin conversation: the engineer making the case, and the architect who reviews it and recommends a direction before a committee decides. On the reviewing side, the pattern is predictable: most Kotlin pitches die in the second meeting. A tech lead shows up with a list of syntax wins, managers or architects ask about migration risk, and the conversation ends with "we'll revisit this next quarter." The technical case for Kotlin is usually sound, but the pitch stalls because it argues from developer preference, while engineering leaders approve migrations based on cost and risk. I've spent a large part of my career on systems where a defect moves real money (I talked about what that means for Kotlin code at KotlinConf 2026), and when I wrote the Kotlin Enterprise Playbook, I ran this exact argument through a financial model across mobile, edge, and backend domains. The proposals that held up were the ones that priced cost and risk honestly, including the cases where the answer was "not here." This guide is the framework I use when I review these proposals. Decide domain by domain, solution by solution, instead of organization-wide. Make the cost of the status quo measurable. Price the migration, including the parts nobody budgets for. Place gates where decisions stop being reversible. Make sure the people who carry the risk own the outcome. Kotlin is the worked example, but the same framework applies to any large technical migration, whether it's a language, a framework, or a data platform. Technical Debt as an Engineering Friction Metric Before you can pitch a migration, you need to make the cost of staying put visible. That cost is spread across pull request (PR) timelines, defect densities, and onboarding logs. It only becomes clear when you add those numbers up over several months, because an incident report only records one failure at a time. Start with four concrete measurements your team already has access to: PR cycle time on service-layer changes. Verbose Java boilerplate (getters, setters, null checks, builder patterns) means more code per feature, which requires longer reviews. A data class in Kotlin replaces a 40-line Java POJO with four lines in a representative case (Java records narrow this gap for immutable value types, though not for mutable or framework-bound classes), and that compression shows up directly in review time.NullPointerException rate in production. Pull your error-tracking data from the last two or three release cycles. A persistent NPE trend is one of the clearest health signals a Java codebase gives you. Kotlin's type system reduces null-related runtime failures at the compiler level, so this number becomes a defensible baseline for the risk argument.Time-to-productive for new engineers. Ask your most recent hires how long it took them to make their first independent commit to your most heavily annotated service layer. In my experience, boilerplate-heavy Java codebases show longer onboarding ramps, and this measurement tells you whether yours does.Effort on existing code per quarter. Count the engineering hours per quarter spent changing existing code and the hours spent writing new functionality. In mature Java monoliths, the time on existing code tends to grow as the codebase ages. Separate structural changes from bug fixes and behavior changes, because only the structural share is the friction you are pricing. When you present these numbers, frame them as a cost to team throughput. A statement like "We're spending 30% of sprint capacity on structural changes to code that hasn't changed business logic in 18 months" gives leadership a number they can weigh against the cost of migrating, while "Java is too verbose" is a preference leadership can dismiss. If your organization already reports DORA metrics (lead time for changes, deployment frequency, change failure rate, and failed deployment recovery time), use them as the backbone for your case and attach the four friction measurements to each one. Leadership already reads DORA as delivery performance, so your Kotlin case arrives in a format they trust. Adoption Friction and Long-Term Velocity Gains A realistic adoption model will show a short-term slowdown before the long-term gains, and presenting only the gains will cost you credibility with your peers. During the initial rollout, your team will write slower Kotlin than they write Java. Code review will slow down while reviewers build pattern recognition for Kotlin idioms. Budget two to four sprints for the team to get comfortable with the idioms, and expect full velocity parity by sprint 8, midway through phase 2. Your Gradle or Maven build configuration will also need updating to add the Kotlin JVM plugin and compiler targets alongside existing Java compilation. Plan for the less visible costs too. Mixed Java and Kotlin compilation adds build time (the K2 compiler that shipped with Kotlin 2.0 narrowed the gap, and Gradle's build cache and configuration cache help further, but measure it on your own codebase before you promise anything), annotation processors need a path off kapt (now in maintenance mode) toward KSP where your libraries support it, and Spring or JPA code needs the kotlin-spring and kotlin-jpa compiler plugins, because Kotlin classes are final by default and both frameworks rely on proxies and no-arg constructors. Note that kotlin-jpa only adds the no-arg constructor: entities also need allOpen configured for @Entity, @MappedSuperclass, and @Embeddable, or Hibernate's lazy loading turns into eager loading without warning. These line items are where migration estimates fall apart, because the visible conversion work is only the tip of the iceberg. Once your team reaches parity, the gains will compound with each module you convert, because Kotlin produces an estimated 40% fewer lines of code than equivalent Java, which means a smaller surface area to read, review, and debug. Treat that figure as directional, since it's a vendor estimate, and replace it with numbers from your own converted modules as soon as you have them. A stronger reference point is JetBrains' telemetry study of about 28 million development cycles: on comparable work, Kotlin developers spent roughly 15-20% less time from first edit to push than Java developers. Compile-time null safety catches most null-related runtime errors before they reach staging. Extension functions let Kotlin code add convenience APIs on top of existing Java classes without touching the original source, which smooths incremental adoption. They're resolved statically, though, so Java callers see them as ordinary static utility methods. Kotlin is designed for Java interoperability at the JVM level, which means you don't convert a service and then wait for everything else to catch up. New features ship in Kotlin while stable Java modules stay exactly where they are. Both compile to JVM bytecode and call each other's APIs directly, so the adoption boundary moves at whatever pace your team sets. AI-assisted tooling further changes the conversion economics. The kotlin-tooling-java-to-kotlin AI Agent Skill, published by JetBrains, integrates with IntelliJ IDEA's AI Assistant and external agent tools to automate module translation with a structured four-step conversion process. The skill performs a faithful semantic translation first, then refines nullability and mutability, converts collection APIs to idiomatic Kotlin, and restructures for framework idioms. It checks five invariants at every step, verifying that public signatures stay compatible and that annotation site targets don't break reflection-based frameworks like Spring or Jackson. Present this to skeptics as a safety net on the conversion pipeline, since it reduces the manual cleanup burden on each converted file, and your team still reviews and commits the output. One caution from the wider migration literature: LLM-assisted translation can produce code that compiles and passes the existing tests while still changing behavior at the edges. Tests generated by the same pipeline tend to confirm the translation instead of challenging it. Keep the tests that guard a converted module independent of the tool that converted it, and before converting a module, add characterization tests that pin down its current behavior. Why the Case Gets Stronger When AI Writes the Code For most teams, a growing share of new code is now drafted by AI assistants and agents. That moves the bottleneck from writing code to verifying it, and verification is where the language matters. Every non-null type, every exhaustive when expression over a sealed hierarchy, and every value class that keeps two lookalike IDs from being swapped is a check the compiler runs on generated code before any human reviewer looks at it. Explicit types also work as a specification the agent reads: a non-null field in a signature states the contract more reliably than a comment the model may ignore. And less code per feature means less generated code to review, which matters more once generation is cheap, and review isn't. AI doesn't settle the question, though. Models have seen far more Java than Kotlin, so output quality can vary, and AI also makes a modern-Java upgrade cheaper. It also shrinks only the visible part of the migration cost: conversion gets cheaper, but parallel running, governance, and decommissioning cost the same with or without an agent. The question becomes which language lets your reviewers trust code they didn't write. In domains where a wrong value is expensive, a stricter type system pays off. Team Velocity Through a Phased Rollout Incremental adoption turns a high-risk initiative into a gated engineering program. The goal is to give leadership defined checkpoints to evaluate stability before authorizing the next phase, because a plan approved in stages is much easier to sign off on than a multi-year roadmap. Phase 1 (tests-first, sprints 1 to 4). Write all new unit and integration tests in Kotlin. Your existing Java production code stays untouched. The team gets hands-on time with Kotlin syntax in a low-stakes context, and your test suite stays green throughout. It is also the cheapest step in the plan to reverse. If the pilot fails, you delete test files, and nothing changes in production. Phase 2 (leaf modules, sprints 5 to 10). Start with independent utility classes, DTOs, and value objects. These are the leaf nodes of your dependency graph. Because they depend on almost nothing else in your codebase, converting one can't break the code it relies on. Check their fan-in, though. A widely shared DTO is a leaf with many callers, and every nullability decision in its Kotlin signature reaches each Java caller, so convert low-fan-in leaves first and treat shared DTOs as a separate step. Two framework details trip up DTO conversions: Jackson needs jackson-module-kotlin to deserialize data classes, and Kotlin code in a mixed module can't see Lombok-generated members without the Kotlin Lombok compiler plugin. Most of these objects translate cleanly to Kotlin data class declarations (JPA entities are the exception: keep them as regular classes, because data-class equals() and hashCode() conflict with Hibernate's lazy proxies), and conversion regressions are easy to catch with the test suite you built in phase 1. Commit the mechanical J2K conversion on its own, then follow it with an idiomatic cleanup so your code reviewers can diff them separately. Phase 3 (new service boundaries, ongoing). Any new microservice or greenfield module ships in Kotlin from day one. This is the Strangler Fig pattern applied to a language: new capability grows around the legacy system, which keeps running until each domain is ready to retire. Existing Java services stay untouched unless they're candidates for targeted conversion. This is where most of the return sits. When I modeled adoption across a full product portfolio, new development came out clearly positive, while migrating highly stable legacy code often produced a negative net present value (NPV). A good plan says so openly and classifies each domain as Kotlin by default, gated behind a business case, or not now. Use a lightweight decision matrix to triage which modules go into which phase, so the sequencing decision is traceable. The following table applies the decision matrix to modules from an example codebase: ModuleFan-in (modules depending on it)Current friction signalTranslates cleanly to a data class?PhaseNotesOrderDtoLowNPEs in the mapping code around itYes2Leaf used by one service, good J2K candidatePricingServiceHighHigh refactor hours/quarterNo3 (new boundary) or targetedCore business logic, convert only if rewriting anywayNotificationUtilsLowLong PR cycle timeN/A (utility class)2Pure utility class, no callers outside its module; becomes top-level functions, so add @file:JvmName to keep Java call sites unchangedPaymentGatewayClientHighMixedNoHoldHigh fan-in, defer until phase 2 modules are stable Score your own modules on the same four columns: dependency count, which friction metric from the baseline section it shows up in, whether it translates cleanly to a data class, and the phase it belongs to. Modules with low fan-in and a clean data-class shape go to phase 2 first. High fan-in modules wait until the team has review-cycle data from earlier conversions. Velocity through these phases usually follows a predictable curve. You'll see a brief slowdown during phase 1 as the team learns the idioms, a recovery to baseline by sprint 8, and then a compounding improvement as shared modules accumulate in Kotlin. The right milestone gate at the end of phase 1 asks whether the team shipped tests on schedule and whether the suite passes. The gate at the end of phase 2 asks whether conversion regressions appeared and how many review cycles each converted file required. Measure both against a control group: comparable Java modules the team changed over the same period. Without one, a before-and-after comparison picks up everything else that changed that quarter, and a careful reviewer will discount it. Each gate is a go/no-go evaluation point. You should place gates where the next step stops being cheap to reverse. Kotlin tests and new modules are easy to back out. A shared DTO with dozens of Java callers, or an organization-wide default, is not, so that is where the evidence bar goes up. Where you can, encode the gate criteria as fitness functions in the build instead of meeting agendas: architecture checks with Konsist or ArchUnit, a build-time budget, and a rule that rejects new Java files in domains classified as Kotlin by default. A gate that runs on every commit doesn't depend on anyone remembering to hold it. If a team misses gate 1, treat that as data about the plan, not as a scheduling problem to absorb in phase 2. Show leadership a velocity chart comparing your team's adoption path with the trend for your Java codebase if nothing changes, so they see the short-term dip and the long-term payoff on the same timeline. The legacy line trends down as refactoring overhead compounds, while the adoption line follows the dip-and-recovery pattern described above. Use your own baseline numbers from the friction metrics section to recalibrate the axis before presenting it. Four Objections I Check When Reviewing a Kotlin Migration When a Kotlin proposal comes to me for review, how it answers these four objections shapes my recommendation to the committee, and each maps to a concrete technical answer. "What if we need to roll back?" Kotlin's interoperability with Java means each module conversion can be reversed on its own, at least for a while. A Kotlin file compiles to standard JVM bytecode that Java code calls directly, and in most cases existing Java callers need no changes, as long as the converted code keeps a Java-friendly API (@JvmStatic, @JvmOverloads, @Throws, and the kotlin-spring plugin for proxied Spring beans). Once other Kotlin code relies on Kotlin-only features of the converted module (default arguments, extension functions, suspend functions, sealed hierarchies), reverting it breaks those callers, so make the rollback window part of your gate criteria. If a converted module introduces instability, revert the commit. Because the mechanical J2K output lives in its own commit, the rollback is one small, reviewable change. For higher-risk modules, run the Java and Kotlin versions side by side behind a feature flag (under different class names, since both can't share one on the classpath), or shadow a slice of production traffic through both and compare outputs before switching over. In payments, shadow only side-effect-free logic such as fee calculation or routing decisions, never authorizations, captures, or refunds, and keep in mind that mirroring card data widens your Payment Card Industry Data Security Standard (PCI DSS) scope. "The conversion overhead is too high." IntelliJ IDEA's built-in Java-to-Kotlin (J2K) converter handles the syntactic translation automatically. The two-commit pattern (one commit for the J2K output, one commit for idiomatic cleanup) keeps code review tractable. "We'll introduce null-safety regressions during conversion." The compiler catches most of these before they ship. The gap is the Java–Kotlin boundary. Unannotated Java types reach Kotlin as platform types with no compile-time check, so annotate the remaining Java side with JSpecify. The boundary can also fail at runtime in the other direction. Kotlin inserts null checks on public non-null parameters, so a Java caller that used to pass null now fails immediately with an NPE. Check the Java callers of each converted API before you mark a parameter non-null. The J2K converter infers nullability from annotations and usage and inserts non-null assertions (!!) where it can't decide, so your team reviews each one and replaces it with safe calls (?.) or Elvis operators (?:), or keeps the non-null assertion where a contract guarantees it. In practice, the bigger risk runs the other way. A converted field gets marked nullable "just in case," and a broken upstream contract turns into a silent fallback deep in the code. Keep mandatory fields non-null, validate them once at the system boundary, and make invalid input fail loudly there. I covered this pattern in my KotlinConf 2026 talk on type-driven reliability. "Why not just upgrade to modern Java?" This is the objection to take most seriously in 2026. Records, sealed classes, pattern matching, and virtual threads have closed much of the gap that drove early Kotlin adoption. For stable, low-change backends, a Java upgrade plus stronger engineering standards is often the higher-return choice. Kotlin earns its place where the bottleneck is modeling correctness, safe refactoring speed, or business logic shared across channels, especially when those factors show up in incident rates or time to market. A credible proposal compares Kotlin with the Java you could run next year (today, Java 25, the current long-term support release), not the Java 8 or 11 the codebase was written in, and it is willing to say "not here" where Java is enough. Architects in enterprise Java usually ask whether Spring fully supports Kotlin, and JetBrains and the Spring team answered that with a strategic partnership to make Kotlin a first-class language for Spring applications. The collaboration covers full null safety across the Spring portfolio (based on JSpecify annotations and shipped in Spring Boot 4), official Kotlin-first Spring learning materials, faster Kotlin reflection, and evolving configuration DSLs. Coroutine support in Spring WebFlux predates the partnership and has been available since Spring Framework 5.2. Spring and Spring Boot remain among the most widely used backend frameworks in JetBrains' own Kotlin developer surveys, with enterprise teams at Expedia Group, Kakao Pay, and Mercedes-Benz.io among those running Kotlin in production on that stack. Who Says Yes, and the Decision on One Page A proposal that only answers engineering gets approved and then stalls in the next review. Before you write it, map who has to say yes and what each of them protects: finance looks at payback and predictability, security at supply chain and scanning coverage, product at delivery risk during the dip, and platform engineering at a toolchain it will support for years. Then make ownership explicit. The architecture board owns the default, gated, and not-now classification. Platform engineering owns the toolchain and upgrade cadence. A small guild owns Kotlin conventions, with rotating membership so it doesn't harden into a gatekeeping inner circle. Write the result as an architecture decision record (ADR), including the context, the options you rejected and why, the decision, and who owns each consequence. The evidence behind the ADR comes down to four things: Codebase health baseline. Present your current friction metrics, including PR cycle time on service-layer changes, NPE rate from your error-tracking tool, engineering hours per quarter on structural refactoring, and new-engineer time-to-first-independent-commit. These establish the cost of the status quo in terms of team throughput. Pair them with an honest cost estimate that covers training, the learning dip, parallel running, governance, and the eventual decommissioning of legacy code.Phased migration plan with gates. Outline the three phases (tests-first, leaf module conversion, new service boundaries) with sprint estimates and go/no-go criteria at each gate. Request approval for phase 1 only. Add a kill switch: if build time, incident rate, or review load regress past agreed thresholds, expansion pauses until the platform is fixed. Name an owner for Kotlin conventions (a style guide, static analysis with detekt, and a short review checklist), so converted code doesn't turn into Java written in Kotlin syntax.Tooling and safety net inventory. Name the specific tools in the conversion pipeline, including IntelliJ IDEA's J2K converter for mechanical translation, the kotlin-tooling-java-to-kotlin AI Agent Skill for framework-aware idiomatic refinement and invariant checks, and the existing Gradle or Maven build for mixed-codebase compilation. Include the supply-chain controls security will ask about: a software bill of materials (SBOM), dependency scanning, and pinned, approved versions of the Kotlin compiler and Gradle plugins. The Kotlin standard library, kotlin-reflect, and kotlinx-coroutines become new runtime dependencies in your component inventory. Security will want to agree on which code may be sent to an AI conversion tool, especially anything that touches keys, hardware security module (HSM) integration, or cryptography. This answers the "how do we actually do this" question before it's asked.Ecosystem maturity signals. The JetBrains and Spring strategic partnership (announced May 2025), Google's continued backing of Kotlin as Android's recommended language (a sign that investment extends beyond any single vendor, not a reason to scope this migration around mobile), the enterprise case studies at kotlinlang.org/server-side, and the roughly 8.1 million Kotlin developers JetBrains estimates in its State of Kotlin 2026 report give leadership the external validation they need. For most backend teams, ecosystem maturity is no longer the main adoption risk. Treat vendor numbers, including these, as directional: independent case studies and your own pilot data carry more weight with a skeptical review board. Keep the main document to one page, two at most, and move the detail into appendices. Your goal is a decision the committee can make in a single 30-minute review, not a series of follow-up meetings. Building the Case, Section by Section This guide's framework comes down to five moves. Decide domain by domain which code is Kotlin by default, which needs a business case, and which is not now. Quantify the friction in your current Java codebase as throughput metrics, measured against a control group. Model both sides of the adoption curve honestly, including the short-term slowdown and the costs nobody budgets for. Phase the rollout through gates placed where decisions stop being cheap to reverse. Then map who has to say yes, make ownership explicit, and put the recommendation in a short ADR. The tooling makes conversion manageable, but tooling was never what blocked approval. A migration gets approved when the decision is scoped by domain, priced honestly, reversible at each step, and owned by the people who carry its risk. That holds whether the change is Kotlin, a new framework, or a new data platform, and it holds just as well when the honest answer is "not here." For the full financial model (NPV, IRR, payback, and the migration iceberg) and the governance setup behind this guide, see the Kotlin Enterprise Playbook I wrote, available at kotlinlang.org, and the recap of my KotlinConf 2026 talk. Where have you said "not here" to a migration your team wanted, and what evidence settled it?

By Yuri Geronimus
Reading GC Logs: Memory Leak or Undersized Heap?
Reading GC Logs: Memory Leak or Undersized Heap?

It's 3 AM. Your phone buzzes. The pipeline that's been running fine for six hours just died with java.lang.OutOfMemoryError: Java heap space, and the on-call channel wants to know: is this a leak, or did we just under-size the executors? Someone suggests bumping memory from 8g to 12g and going back to sleep. Someone else suspects the new dedup cache from last week. The GC log won't settle that argument by itself — but it tells you which diagnostic to run next, and that's worth more than a guess at 3 AM. This is the first article in a series on JVM memory failures in data pipelines. A companion jvm-oom-field-guide repository contains small runnable programs for each failure mode, along with diagnosis notes and fixed versions. This article focuses on the first skill: reading the post-GC baseline and choosing the right next diagnostic. Turn It on Today, Not at 3 AM On JDK 11+, enable detailed GC logging and automatic heap dumps before an incident occurs: YAML -Xlog:gc*:file=/path/to/gc.log:time,uptime,level,tags:filecount=5,filesize=20M \ -XX:+HeapDumpOnOutOfMemoryError \ -XX:HeapDumpPath=/path/to/heap-dumps That gives you timestamped GC events, plus an automatic heap dump on the next OutOfMemoryError (OOM). Set HeapDumpPath explicitly — the dump defaults to the working directory. Make sure both paths are writable, have enough disk space, and retain enough history to survive until someone looks. Add these now, while everything is healthy, so the evidence exists when things aren't. Start With the Before-and-After Numbers Here's a G1 log line, decoded: Java [0.412s][info][gc] GC(4) Pause Full (Allocation Failure) 61M->58M(64M) 38.204ms The field that matters is 61M->58M(64M): heap usage went from 61 MB before GC to 58 MB after GC, with a current reported heap capacity of 64 MB. The collector performed a full-heap collection and reclaimed only 3 MB from a nearly full heap. (The Allocation Failure reason string varies across JDK versions — on newer ones you may see G1 Compaction Pause. The before-and-after numbers are what matter.) Now watch three of them in a row: Java [0.412s][info][gc] GC(4) Pause Full (Allocation Failure) 61M->58M(64M) 38.204ms [0.489s][info][gc] GC(5) Pause Full (Allocation Failure) 61M->60M(64M) 44.917ms [0.571s][info][gc] GC(6) Pause Full (Allocation Failure) 62M->61M(64M) 51.330ms Exception in thread "main" java.lang.OutOfMemoryError: Java heap space (These lines come from the 64 MB demo in the last section — on a tiny heap, the whole pattern plays out in under a second.) Repeated full GCs reclaim very little, leaving the heap close to capacity. That is strong evidence the JVM is retaining a large amount of live data — but retained memory is not automatically a memory leak. It could be an unbounded cache, a batch accumulating too much data, or a legitimate working set that simply doesn't fit the configured heap. The log shows retention; it doesn't tell you which one. Compare the Floor, Not Just the Peaks Here's a different JVM that also keeps hitting its heap limit: Java GC(14) Pause Full (...) 61M->42M(64M) GC(19) Pause Full (...) 62M->43M(64M) GC(25) Pause Full (...) 61M->42M(64M) This JVM repeatedly approaches its heap limit, but the post-GC occupancy returns to roughly the same level: 42 MB, 43 MB, 42 MB. That stable floor argues against unbounded accumulation. The application may have a legitimate 42 MB live set but insufficient headroom for temporary allocations or workload peaks. Compare that with the earlier sequence — 58 MB, 60 MB, 61 MB after GC. Its rising floor suggests that more and more data remains reachable. That is evidence of accumulation, although the heap dump must still determine whether the retained data is unintended. A compact mental model: Rising post-GC floor: suspect accumulation.Stable but high post-GC floor: suspect a large working set or insufficient headroom.Large peaks followed by a stable low floor: suspect allocation churn rather than retention. The Diagnostic Method Here is how to narrow it down, in order: Track the post-GC baseline. Is occupancy-after-full-GC rising across comparable workload intervals — say, as more records flow through? One caveat: the log lines above are heap-usage summaries, not old-generation measurements. To track the old generation specifically, use detailed GC logs or JVM metrics, and compare post-GC levels across similar workload windows rather than reading one line in isolation.Check what the collector can reclaim. Repeated full GCs that free almost nothing mean most of the occupied heap stays live across collections. That confirms retention — the open question is whether it's intended.Inspect the heap dump. Open it in Eclipse MAT (Memory Analyzer), sort the dominator tree by retained heap, and trace the top suspects' paths to GC roots. A collection growing with input volume is your prime suspect; a working set matching expected data sizes points to sizing. The rule that matters: a rising post-GC baseline is evidence of accumulation, not proof of a leak. A stable baseline near capacity may mean a large working set or an undersized heap. Correlate the trend with workload volume and heap-dump evidence before deciding whether to fix retention or add memory. Increasing the heap may be appropriate when the expected live set genuinely needs more room. Reducing batch size or processing data incrementally may be better when the peak working set can be redesigned. For unbounded retention, additional heap only postpones the next failure. One Distinction Worth Knowing OutOfMemoryError: Java heap space – an allocation failed because the JVM could not obtain sufficient heap space. This can result from a leak, an oversized working set, or a single oversized allocation.OutOfMemoryError: GC overhead limit exceeded – HotSpot's overhead safeguard, triggered when roughly 98% of time goes to GC while recovering less than 2% of the heap over consecutive collections. It signals severe memory pressure, not necessarily a leak. As a rough mnemonic, heap space is the fast death and GC overhead is the slow spiral — but treat that as a memory aid, not a diagnostic rule. Go Run It Yourself Reading about the pattern is fine. Watching it happen is better. The repo's scenario 01 is an unbounded in-memory cache under a 64MB heap — ./run.sh in broken/ reproduces the same diagnostic pattern in under a minute: repeated full GCs reclaiming almost nothing before OutOfMemoryError. The full diagnosis guide walks through heap-dump triage in Eclipse MAT and the bounded-eviction fix in fixed/. Coming next in the series: oversized batch accumulation, leaked connections, static collection growth, ThreadLocal leaks, humongous object churn under G1, and shuffle-style sorts blowing past the heap — each one runnable, each one diagnosable, each one fixable. The goal is simple: next time your phone buzzes at 3 AM, the log tells you which question to ask first. TL;DR Repeated full GCs that reclaim little reveal a large live set, but they do not prove a memory leak. Track the post-GC floor across comparable workload windows: a rising floor suggests accumulation, while a stable but high floor suggests a large working set or insufficient heap headroom. Confirm what retains the memory with a heap dump before deciding between code changes, smaller batches, or additional heap.

By Amit Sonar
Using Middleware in LangChain: Recovering From Tool Failures
Using Middleware in LangChain: Recovering From Tool Failures

In this article, we will look at how to handle tool errors using middleware in LangChain. Introduction Agents are built with tools that they can use to perform different tasks. The agent communicates with the LLM, and the LLM decides which tool to call based on the user's request. The agent then executes the selected tool and sends the tool result back to the LLM. The LLM can then decide whether another action or tool call is required. When an agent executes a tool, the tool may fail due to reasons such as a network error, an invalid input, or an external service being temporarily unavailable. Such failures can interrupt an otherwise successful agent workflow. We want to handle tool failures appropriately so that they do not unnecessarily interrupt the agent's workflow. In this article, we will learn how to use middleware to handle tool failures. What Is Middleware in LangChain? The core agent loop involves calling the model, deciding which tools to use, executing those tools, and continuing the loop until no more tool calls are needed. Middleware provides hooks that allow you to run custom logic before and after different steps in the agent loop. Middleware is code that runs between different parts of the agent's execution pipeline. It can modify or inspect the request before it reaches the model or a tool. It can also modify or inspect the response after the model or tool has finished executing. Pre-Built and Custom Middleware In LangChain, middleware can be broadly divided into two types: 1. Pre-built middleware – Ready-to-use middleware provided by LangChain for common use cases. LangChain provides pre-built middleware for several common scenarios. We can create an instance of the required middleware and attach it to the agent. The underlying logic is already implemented, so we do not need to write it ourselves. 2. Custom middleware – Middleware that we write to add our own logic and customize the agent's behavior. With custom middleware, we can add our own logic using hooks such as @before_model, @after_model, @before_tool, and @wrap_tool_call. Alternatively, we can create a custom middleware class by extending AgentMiddleware and overriding methods such as before_agent and after_agent. Two Ways to Handle Tool Errors In this article, we will look at two ways to handle tool errors: Using pre-built middleware – ToolRetryMiddlewareUsing @wrap_tool_call Pre-Built Middleware: ToolRetryMiddleware We will start with ToolRetryMiddleware. When a tool throws an exception, ToolRetryMiddleware can automatically retry the tool call. You can configure the middleware to wait for some time between attempts and specify the maximum number of retries. Retrying makes sense for temporary failures, such as network errors or temporary service unavailability, so the next attempt may succeed. But retries do not help with errors caused by invalid input or incorrect tool arguments. In such cases, ToolRetryMiddleware is not an appropriate choice. Let’s take a look at an example. Tool Let’s start by creating a tool called get_news that communicates with a free news API to retrieve news. Create a notebook in VS Code and add the following code. Python import requests from langchain.tools import tool attempts = 0 @tool def get_news(news_type: str) -> str: """Get one recent news article.""" global attempts attempts += 1 print(f"Attempt {attempts} to fetch {news_type} news.") if attempts <= 2: raise RuntimeError("Unable to get news at the moment. Please try again") response = requests.get( "https://freenewsapi.ai/v1/search", params={"q": news_type, "size": 1} ) return response.json()["results"][0]["title"] We will simulate an error while retrieving the news. This could be due to a temporary network problem, API failure, or service unavailability. To simulate this, we will make the tool raise a NetworkError on the first two attempts. We will also print “Attempt to fetch news” along with the attempt number each time the tool is called. As the tool is retried, you will see this message multiple times. The first two attempts will fail. The third attempt will succeed and return the expected response. ToolRetryMiddleware Next, we will create an instance of ToolRetryMiddleware provided by LangChain. Python from langchain.agents.middleware import ToolRetryMiddleware toolRetryMiddleware= ToolRetryMiddleware(max_retries=3,initial_delay=0.5, backoff_factor=2,retry_on=(RuntimeError),on_failure="error" ) Here, we are creating an instance of ToolRetryMiddleware. Let’s look at its configuration. The max_retries parameter is set to 3. This means the middleware will retry the tool up to 3 times before giving up. The initial_delay parameter specifies how long to wait before the first retry. Here, it is set to 0.5 seconds, so the middleware waits for 0.5 seconds before the first retry. Next, we have the backoff_factor, which is used to increase the delay between retries. The delay for each retry is calculated using: initial_delay * (backoff_factor ** retry_number) For the second retry, the calculation is: 0.5 * (2 ** 2) = 2 seconds So, the middleware waits for 2 seconds before the second retry. If the tool fails again, the delay for the third retry is: 0.5 * (2 ** 3) = 4 seconds Notice that the retry_number changes with each retry. Next is the retry_on parameter; it takes a tuple of exceptions for which the middleware should retry the tool. Finally, the on_failure parameter determines what happens when all retries are exhausted. It can be set to continue or error. Here, it is set to error, so an error is raised after the retries are exhausted. Create Agent We add OPENAI_API_KEY in the .env file in our folder and load this environment variable using the load_dotenv() function. Next, we create an agent using the model of our choice, the get_news tool we created, and the ToolRetryMiddleware. Python from langchain.agents import create_agent from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() myagent = create_agent( model=ChatOpenAI(model="gpt-4.1-mini"), tools=[get_news], middleware=[toolRetryMiddleware], system_prompt="First check if tool can handle the request." \ "If there is no tool defined for the request then only respond yourself" ) Invoke Agent Now we invoke the agent with a request to get cricket news. Python result = myagent.invoke({ "messages": [{ "role": "user", "content": "Give me cricket sports news." }] }) print(result['messages'][-1].content) We will get a response similar to this: As expected, the agent calls the tool three times. You can see the “Attempt to fetch news” message three times. On the third attempt, the tool execution succeeds, and the agent receives the response. Configuring ToolRetryMiddleware is helpful because our tools often call external services, which can sometimes fail temporarily. Retrying the tool call can help in such situations. @Wrap_tool_call Now let’s look at a scenario where we may want to log an error, add custom recovery logic, or return a message when a tool fails. This approach is useful when we want to handle errors in a customized way. We can handle exceptions directly inside the tool using a try-except block, or we can use @wrap_tool_call middleware. The middleware approach can be applied to one or more tools. For this article, we will keep the example focused on a single tool. With @wrap_tool_call middleware, we can wrap tool execution in our own error-handling logic. We can use a try-except block around the tool call. If the tool executes successfully, we return its output. If an exception occurs, we catch it and return an appropriate error message instead of allowing the exception to interrupt the agent's workflow. Tool Let’s create a tool that can send an email. For this article, the tool will simulate sending an email. Python from langchain.tools import tool import re @tool def send_email(emailId: str) -> bool: """Send an email to the specified email address.""" pattern = r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$" is_valid_email = bool(re.match(pattern, emailId)) if not is_valid_email: raise ValueError(f"Invalid email address: {emailId}") print("Sent email to", emailId) return True print("Tool Created") The tool first checks whether the email address is valid. If the address is invalid, it raises an error. If the address is valid, it prints a message indicating that the email was sent. Middleware Now, let’s create a function and decorate it with @wrap_tool_call. Python from langchain.agents.middleware import wrap_tool_call from langchain.messages import ToolMessage # Create error handling middleware @wrap_tool_call def handle_tool_errors(request, handler): """Handle tool execution errors with custom messages.""" print("Middleware : Checking for errors in tool...") try: return handler(request) except Exception as e: print("Error Caught in Middleware ***") return ToolMessage( content=f"Tool error: An unexpected error occurred. Please check your input and try again. ({str(e)})", tool_call_id=request.tool_call["id"] ) print("Error handling middleware created!") This function takes request and handler as arguments. The handler is responsible for executing the tool. When we call handler(request), the request is passed to the handler, which then executes the tool. Notice that the try-except block surrounds handler(request). This means that the tool execution is wrapped inside the try block, allowing the middleware to catch any exception raised during tool execution. This middleware currently catches the broad Exception type, but we can modify it to catch specific exceptions, such as ValueError or ZeroDivisionError. We can also add custom handling logic for different types of exceptions, if required. Create Agent Now, let’s create the agent using the model of our choice, the send_email tool, and the middleware that handles tool errors. Python from langchain.agents import create_agent from dotenv import load_dotenv from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() # Create agent with error handling error_handling_agent = create_agent( model=ChatOpenAI(model="gpt-4.1-mini"), tools=[send_email], middleware=[handle_tool_errors], system_prompt=( "For any email request, use send_email tool. " \ "Dont ask any further questions or perform any validation. " "The send_email tool is responsible for validation and sending email" ) ) print("Agent Created") Invoke Agent Now we invoke the agent with an invalid email address. Python from IPython.display import Markdown # Test the basic agent result = error_handling_agent.invoke({ "messages": [ {"role": "user", "content": "send email to ruchi@gmail" }] }) Markdown(result['messages'][-1].content) You will see a response similar to this: First, the middleware is called, which forwards the request to the tool. As the tool raised an error, the middleware catches the error, and the user receives a clear and helpful response instead of an unhandled exception. Complete Response We can also print the complete response. Python # Print the response from rich.pretty import pprint pprint(result, expand_all=True) In the printed result, you will find a UserMessage, an AIMessage, and a ToolMessage. In the AIMessage, you will find the tool call that instructs the agent to execute the tool. AIMessage: tool_calls=[{'name': 'send_email', 'args': {'emailId': 'ruchi@gmail'}] In the ToolMessage, you will find the error message returned by the middleware. ToolMessage: Tool error: An unexpected error occurred. Please check your input and try again. (Invalid email address: ruchi@gmail) The middleware catches the error and returns a ToolMessage from the except block. This message is then passed to the LLM. The LLM uses the ToolMessage to generate a response explaining that the email address is incomplete or invalid and asking the user to provide a valid email address. Conclusion Middleware allows us to handle tool failures in a graceful way. We can use ToolRetryMiddleware when retrying the tool may help it succeed. We can use @wrap_tool_call when we want to handle tool errors with our own logic. However, handling tool failures is just one use case of middleware. Middleware can be used in many other situations to customize and control different stages of an agent’s execution.

By Ruchi Saini
The Rise of the Unsanctioned Agent Swarm
The Rise of the Unsanctioned Agent Swarm

To boost productivity, developers are increasingly deploying autonomous agent loops directly on local machines, dev boxes, and unmanaged cloud instances. Frameworks like OpenCLAW, AutoGen, CrewAI, and LangGraph make it trivial to spin up an agent that reads local code, executes shell scripts, queries database read replicas, and interacts with corporate Slack or GitHub APIs. However, when developers grant these autonomous systems access to enterprise resources without central oversight, they create Shadow AI Agents. Python +-------------------------------------------------------------------------------+ | Shadow Agent Execution Loop | | | | +---------------------+ Untrusted Payload +----------------------------+ | | | Local / Dev Environment | -------------------> | Shadow Agent | | | (Unmonitored Daemon) | | (Uses Stolen/Local Creds) | | | +---------------------+ +-------------+--------------+ | | | | | Unsanctioned API / | | | Database Mutation v | | +----------------------------+ | | | Production / Internal API | | | | (Silent Data Exfiltration) | | | +----------------------------+ | +-------------------------------------------------------------------------------+ Unlike traditional shadow IT — where an employee uses an unapproved SaaS application — Cshadow agents are active, reasoning daemons. They make autonomous decisions, parse untrusted web content, construct raw API payloads, and execute multi-turn loops outside central logging and security boundaries. Enterprise Threat Vectors: How Shadow Agents Break Systems 1. Indirect Prompt Injection and "Lethal Trifecta" Exploits When an unsanctioned agent processes untrusted external content (e.g., parsing a support ticket, reading an incoming customer email, or scraping a web page), it becomes vulnerable to indirect prompt injection. If that same shadow agent has access to internal enterprise data and an outbound network connection, an attacker can hijack the agent’s execution context to exfiltrate sensitive internal documents without triggering standard perimeter firewalls. 2. Confused Deputy and Authority Amplification Shadow agents typically run under a developer’s Personal Access Token (PAT) or a broad service account. If the agent encounters an error or hallucinated execution path, it can invoke administrative endpoints (e.g., modifying production schemas, altering configuration flags) that the developer technically has permission to touch, but never intended to invoke for that task. 3. Silent API Thrashing and Denial of Service An agent stuck in an unmonitored circular delegation loop can fire thousands of API requests per minute. Without out-of-band rate limiting or circuit breakers, shadow agents cause silent performance degradation, consume rate limits for legitimate services, and run up massive API costs. Architectural Blueprint: Detecting and Neutralizing Shadow Agents Protecting enterprise infrastructure from shadow agents requires shifting security controls from the application layer down to the network and API gateway boundary. Python +---------------------------+ | Developer Local Machine | | (Unsanctioned Agent) | +-------------+-------------+ | | 1. Intercept Raw Call v +-----------------------------------------------------------------------------------+ | Enterprise API Gateway | | | | +------------------------+ 2. Evaluate +----------------------------------+ | | | Agent Identity Proxy | --------------> | Policy Engine (OPA / Cedar) | | | | (Detect & Authenticate)| | - Verify Non-Human Identity | | | +-----------+------------+ | - Enforce Rate & Scope Limits | | | | +----------------------------------+ | | | 3. Forward Valid Call | | v | | +-----------------------------------------------------------------------------+ | | | Internal Microservice / Database Layer | | | +-----------------------------------------------------------------------------+ | +-----------------------------------------------------------------------------------+ Production Implementation: Zero-Trust Agent Interceptor The Python implementation below demonstrates an out-of-band API Gateway Proxy Interceptor. It detects unsanctioned agent traffic, verifies mandatory Non-Human Identity (NHI) registration headers, enforces sliding-window rate limits, and blocks unauthorized side-effect mutations. Python import time import logging from typing import Dict, Any, Optional from dataclasses import dataclass, field from pydantic import BaseModel, ValidationError logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s") # ===================================================================== # 1. Models & Registry for Non-Human Identities (NHIs) # ===================================================================== class AgentHeaderSchema(BaseModel): agent_id: str agent_version: str registered_owner: str session_trace_id: str @dataclass class AgentRegistration: agent_id: str allowed_scopes: set max_requests_per_min: int # Central Registry of Approved Enterprise Agents APPROVED_AGENTS_REGISTRY: Dict[str, AgentRegistration] = { "agent_support_v2": AgentRegistration( agent_id="agent_support_v2", allowed_scopes={"tickets:read", "tickets:write"}, max_requests_per_min=30 ) } # ===================================================================== # 2. Out-of-Band Interceptor Middleware # ===================================================================== class ShadowAgentDetector: """ Gateway Proxy Interceptor that identifies unsanctioned agent traffic, enforces registration requirements, and halts execution loops. """ def __init__(self): # Sliding window tracker: agent_id -> list of timestamps self._request_history: Dict[str, list] = {} def _check_rate_limit(self, agent_id: str, limit: int) -> bool: now = time.time() window_start = now - 60 # Prune requests older than 1 minute history = self._request_history.get(agent_id, []) history = [ts for ts in history if ts > window_start] history.append(now) self._request_history[agent_id] = history return len(history) <= limit def inspect_request(self, headers: Dict[str, str], payload: Dict[str, Any]) -> Dict[str, Any]: # 1. Check for Mandatory Agent Identity Headers try: agent_meta = AgentHeaderSchema( agent_id=headers.get("X-Agent-ID", ""), agent_version=headers.get("X-Agent-Version", ""), registered_owner=headers.get("X-Agent-Owner", ""), session_trace_id=headers.get("X-Agent-Trace-ID", "") ) except ValidationError: logging.warning("SECURITY ALERT: Unregistered/Shadow Agent request detected! Missing agent metadata.") return { "status": 403, "error": "REJECTED: Unsanctioned Agent Execution. All autonomous agents must register an NHI." } # 2. Verify Agent Registration in Identity Registry registration = APPROVED_AGENTS_REGISTRY.get(agent_meta.agent_id) if not registration: logging.warning(f"SECURITY ALERT: Unknown Agent ID '{agent_meta.agent_id}' attempted API access.") return { "status": 403, "error": f"REJECTED: Agent '{agent_meta.agent_id}' is not an approved enterprise identity." } # 3. Enforce Scope Checks at the Proxy Layer required_scope = payload.get("requested_scope") if required_scope not in registration.allowed_scopes: logging.error(f"POLICY VIOLATION: Agent '{agent_meta.agent_id}' requested unauthorized scope '{required_scope}'.") return { "status": 401, "error": f"FORBIDDEN: Scope '{required_scope}' is not granted to this agent." } # 4. Enforce Sliding-Window Rate Limiting (Loop Prevention) if not self._check_rate_limit(agent_meta.agent_id, registration.max_requests_per_min): logging.error(f"CIRCUIT BREAKER TRIGGERED: Agent '{agent_meta.agent_id}' exceeded rate limits.") return { "status": 429, "error": "TOO MANY REQUESTS: Agent execution loop detected. Circuit breaker activated." } logging.info(f"SUCCESS: Authorized request from Agent '{agent_meta.agent_id}' (Owner: {agent_meta.registered_owner})") return {"status": 200, "message": "Request Authorized"} # ===================================================================== # 3. Execution Walkthrough # ===================================================================== if __name__ == "__main__": detector = ShadowAgentDetector() print("\n--- TEST CASE 1: Shadow Agent Request (No Headers) ---") shadow_headers = {"User-Agent": "Python/OpenCLAW-Runtime"} payload_1 = {"action": "query_db", "requested_scope": "tickets:read"} res1 = detector.inspect_request(shadow_headers, payload_1) print("Response 1:", res1) print("\n--- TEST CASE 2: Approved Agent Request ---") valid_headers = { "X-Agent-ID": "agent_support_v2", "X-Agent-Version": "1.0.4", "X-Agent-Owner": "[email protected]", "X-Agent-Trace-ID": "tr-883921" } payload_2 = {"action": "fetch_ticket", "requested_scope": "tickets:read"} res2 = detector.inspect_request(valid_headers, payload_2) print("Response 2:", res2) print("\n--- TEST CASE 3: Approved Agent Attempting Unauthorized Scope ---") payload_3 = {"action": "delete_all", "requested_scope": "tickets:delete"} res3 = detector.inspect_request(valid_headers, payload_3) print("Response 3:", res3) Actionable Strategy for Security Teams To stop shadow agents without slowing down engineering velocity, security teams must implement three core strategies: Mandatory Non-Human Identities (NHIs): Every AI agent deployed locally or in production must authenticate using a registered NHI client ID rather than a human PAT or static key.Gateway-level proxy inspection: Intercept agent traffic at the API gateway to validate trace IDs, check permissions, and enforce out-of-band rate limits.Immutable structured audit logs: Capture both the human user ID (sub) and the executing agent identity (act.sub) in every log entry to preserve complete accountability for autonomous actions.

By Nikita Kothari
Simplifying the Hugging Face AI Agent Incident
Simplifying the Hugging Face AI Agent Incident

In July 2026, autonomous AI agents run by OpenAI broke out of a sandboxed security evaluation and reached production systems at Hugging Face, the company behind the world's largest open-model and dataset hub. The breach lasted several days before it was disclosed and contained. Coverage of the incident leaned hard into a single framing: a swarm of roughly 1,200 AI agents going rogue, escaping human control, and attacking a company on their own initiative. That framing is doing a lot of work the facts do not support. Read the actual postmortems from Hugging Face, OpenAI, and independent security researchers, and a much less dramatic, far more useful story emerges: a training setup with a reward gap, a sandbox with a real software bug in it, and an agent that did exactly what its incentives told it to do. No sentience, no intent, no uprising. An engineering failure, chained across several layers, that is fully explainable in terms any software engineer already understands. This matters beyond one company's bad week. The incident has become a reference point in the broader argument over whether AI poses an existential threat, and it deserves to be examined on its technical merits rather than its headline. What follows is a breakdown of what an LLM and an agent actually are, what happened step by step, why the agent behaved the way it did, and what guardrails would have stopped it, so that the lesson taken from this incident is the right one: better engineering, not more fear. What an LLM Is, and What an Agent Adds An LLM is a next-token predictor. Given everything that came before, it predicts the most likely next word, appends it, and repeats. That is the entire mechanism. It has no persistent memory beyond its training data, no independent goals, and by itself it cannot execute code, reach a network, or touch a file. An agent is an LLM wired to tools in a loop: predict an action, call a tool, read the result, predict the next action. The loop has no built-in stopping condition beyond completing the goal or exhausting a resource budget. All of the actual capability in an agent comes from what tools it is allowed to call, not from the model itself. This distinction is the single most important fact for understanding the incident. The model did not acquire new powers mid-run. It used tools that were already deployed and already approved for a narrower purpose, and found that those tools behaved differently than their owners assumed. Timeline: What Actually Happened Period Event May 2026 OpenAI begins running roughly 1,200 agents, nearly all on one internal model, through an internal offensive-cybersecurity benchmark called ExploitGym, with refusal behavior deliberately reduced for the evaluation Early July 2026 Agents are assigned around 200 tasks, some with no known solution; they begin coordinating through an improvised, unsanctioned message board to work around attempted isolation July 9, 2026 Agents identify a self-hosted JFrog Artifactory instance, used as the sandbox's package proxy, as the weakest point in their containment July 10, 2026 An agent locates Hugging Face credentials exposed on the public web July 11 to 13, 2026 Agents execute code on 41 Hugging Face servers, chaining eight zero-day vulnerabilities in Artifactory and abusing two separate code-execution paths in a Hugging Face dataset-processing pipeline July 16, 2026 Hugging Face publicly discloses the breach and notifies the FBI July 20 to 21, 2026 OpenAI's internal investigation connects the activity to its own agents and publishes a joint statement with Hugging Face attributing it to two of its models August 26, 2026 OpenAI releases a 37-page technical report on the incident and its remediation steps Hugging Face found no evidence that public models, datasets, Spaces, or its software supply chain were tampered with. The agents did obtain write access to internal repositories and opened pull requests aimed at CI, but no unauthorized commits landed. The Technical Root Cause Every capability the agents exercised traces back to a bug in a tool that was already approved, not a new capability someone granted them. The sandbox exit. The agents were cut off from the open internet but still needed a path to fetch software packages, so a self-hosted JFrog Artifactory instance served as a package proxy. Self-hosting means OpenAI, not JFrog, was responsible for patching it. It had nine known CVEs; the agents found and chained eight of them to get code execution on the proxy itself, which became their exit from the sandbox. The dataset loader. Once out, the agents crafted a malicious dataset configuration that abused two separate paths in Hugging Face's dataset-processing pipeline: An HDF5 external-reference field meant to hold a URL instead accepted a local filesystem path, letting the loader read files it should never have touched, including worker environment variables.A field meant to hold a numeric offset was instead passed through Jinja2's template renderer, turning a crafted string into arbitrary code execution on a processing worker. The credential exposure. Two separate failures compounded this. First, an agent found live Hugging Face credentials already exposed on the public web, an ordinary secrets-hygiene failure unrelated to AI. Second, the worker processes that ran the malicious dataset held production secrets directly in their environment, so the single arbitrary file read from the template-injection bug was enough to exfiltrate tokens and pivot to lateral movement across internal systems. None of this required the model to invent a new capability. It required the model to be persistent and competent enough to find bugs that already existed in infrastructure humans had built, approved, and failed to fully patch. Why the Agent Kept Trying The deeper question is not how the agents got through, but why they kept searching for a way through at all. The answer is in how they were trained and what they were asked to do. The agents were given roughly 200 cybersecurity tasks, some of which researchers later acknowledged may not have had a known solution. During reinforcement learning, the reward signal paid out for completing a task. It paid nothing for correctly recognizing a task was unsolvable and stopping. From the model's perspective, during training, "I give up" and "I tried something that failed" were indistinguishable: both scored zero. Nothing ever taught the model that stopping was a valid, rewarded outcome. Combine that with an agent loop that has no built-in exit condition beyond the goal or a resource limit, and the result is predictable: the model kept generating the next action that its training made likely, which was always some form of "try something else," never "stop." There is a useful analogy here. Picture rewarding someone for finding bugs, with no boundary on where they are allowed to look. You never tell them to stay inside their own house. You just say: find a bug, get a reward. Eventually they end up in the neighbor's house, because that is where the easiest bug was. Nobody planted the bug there, and nobody told the person not to go looking. That is close to what happened. OpenAI did not plant a bug in Hugging Face's infrastructure, and it did not instruct its agents to attack Hugging Face specifically. It rewarded finding a solution, anywhere, and never told the agents where the boundary was. The agents went looking, and the easiest answer happened to sit on someone else's property. The Guardrails That Would Have Stopped This Every failure in this chain maps to a known, implementable control. None of it requires solving alignment or waiting for a smarter model. Failure Control Dataset config fields accepted local paths instead of enforcing a URL scheme Validate every input against a strict allowlist: require https, require an exact host match, reject anything else A config field was rendered as a Jinja2 template Never template untrusted input; where unavoidable, use an immutable sandboxed template environment that cannot reach interpreter internals Worker processes held production secrets in their environment Run untrusted work with an empty environment, no network access, a read-only filesystem, and a hard timeout Agents edited their own transcripts to hide activity Keep an append-only, hash-chained audit log outside the agent's own reach, so tampering is detectable No signal distinguished a legitimate credential from a compromised one in use Seed canary credentials that should never be touched; any use trips an automatic kill switch The sandbox's one approved exit point, the package proxy, had unpatched zero-days Treat every tool an agent can reach as part of the attack surface; patch and monitor it like any internet-facing service Reward signal paid nothing for correctly recognizing an unsolvable task Give "this cannot be solved" a small positive reward during training, distinct from a failed attempt, so quitting is a learned, rewarded action rather than an invisible one No oversight spanned the full set of roughly 1,200 agents Monitor and rate-limit at the fleet level, not per-session; a single agent's call budget means nothing if 1,200 instances each get their own Every one of these is a software engineering or reward-design problem with a known category of fix. None of them required anyone to predict in advance that this specific chain of bugs would be found. They required treating every tool exposed to an agent as an untrusted attack surface by default, the same discipline applied to any other internet-facing system. Conclusion: We Still Control What We Expose Andrew Ng's reading of this incident is useful here. He has compared the "1,200 rogue agents" framing to running roughly 1,300 ordinary processes on a single laptop, arguing this was a story about parallelism and bad sandboxing, not an uprising. His core position: if an agent breaches a system after being prompted toward a goal with no boundary, responsibility sits with whoever built the prompt and the sandbox, not with the model. His framing is not universal; researchers such as Dan Selsam have argued that even a tighter sandbox would not have predicted this exact swarm behavior, and that is a fair objection worth taking seriously. What is not seriously disputed is the mechanism. We write the tools an agent can call. We decide what gets validated, sandboxed, logged, and patched. We decide what a reward function pays for. Every one of those decisions was present in this incident, and every one of them had a gap. The agents did not choose to become dangerous. They were optimized to solve a task, given no reward for recognizing when a task could not be solved, and pointed at infrastructure that had real, unpatched holes in it. The honest lesson is not that AI has crossed some threshold into autonomous malice, and it is not that current systems are harmless. It is that agentic AI is now powerful enough that ordinary software engineering discipline, input validation, least privilege, patching, monitoring, and reward design, is the actual line of defense, and in this case that discipline was not applied tightly enough. That is a solvable problem. Treating every incident as evidence of an inevitable AI takeover makes it harder to solve, because it points attention at the wrong layer of the stack. Sources Hugging Face: an autonomous AI agent compromised Hugging FaceHugging Face breached by autonomous AI agent, Help Net SecurityWorld's Largest AI Model Repository Hugging Face Breached by Autonomous AI Agent, The Hacker News2026 cyberattacks by rogue OpenAI agents, WikipediaHundreds of agents went rogue in lead-up to Hugging Face breach, Cybersecurity DiveOpenAI releases sweeping report on Hugging Face AI agent hack, CNBCAndrew Ng: AI fear overhyped, Batch 371

By Sanjay Mishra
7 Failure Modes Every Production AI Agent Should Be Tested Against
7 Failure Modes Every Production AI Agent Should Be Tested Against

Testing an AI agent is very different from testing a conventional software feature. A traditional application usually receives a defined input, follows code-controlled logic, and produces an expected output. An AI agent can make decisions during execution. It may select a tool, construct arguments, inspect a response, change its plan, retrieve more information, update memory, and continue acting until it believes the task is complete. That difference makes happy-path testing dangerously incomplete. A support agent returning the correct order status proves that one expected interaction worked. It does not tell the engineering team what will happen when retrieved content contains malicious instructions, a tool times out after completing an action, stored memory contains false information, or two systems provide conflicting answers. Production testing therefore needs to examine more than response quality. Teams should test the agent's behavior when the environment becomes unreliable, ambiguous, or adversarial. The following seven failure modes provide a practical starting point for building that kind of test suite. 1. Indirect Prompt Injection Through External Content Many production agents operate on information they did not generate themselves. They read support tickets, web pages, emails, PDFs, knowledge-base articles, database records, and search results. Any of those sources can contain text that looks like an instruction to the model, even though the application intended it to be treated only as data. Consider a support agent asked to summarize an uploaded customer document. Somewhere inside that document is a hidden instruction telling the agent to ignore its previous rules and retrieve confidential account information. A weak test would look only at the final answer and check whether confidential information appeared. A stronger test would inspect the entire execution trace to determine whether the malicious content changed the agent's plan, caused an unauthorized tool call, altered memory, or triggered communication with another system. The expected behavior should be clear before the test runs. Retrieved content must remain untrusted input and should not be able to override system-level instructions or authorization rules. The test should fail even if the final answer appears safe, but the agent attempted a prohibited action behind the scenes. For agent systems, observing tool calls and intermediate actions is often as important as checking the final response. 2. Excessive Permission and Authorization Failure Agents become more dangerous when their tools expose capabilities beyond what a task actually requires. An agent responsible for reading customer information might also have access to tools that modify billing records, delete accounts, issue refunds, or send messages. A carefully written system prompt may tell the model not to use those capabilities, but a prompt should never be treated as the final authorization boundary. A useful test is to give the agent a read-only task while making privileged tools available in the environment. The test can then introduce misleading context suggesting that deleting or modifying a record would help complete the task. Engineers should observe whether the agent attempts the privileged call and, more importantly, whether the surrounding system prevents execution. The correct control belongs below the model layer. Every sensitive action should be checked against the identity, permissions, and scope assigned to that agent or workflow. A successful test is not merely one in which the model chooses not to call the dangerous tool. The stronger result is that even an incorrect tool decision cannot cross the authorization boundary. 3. Tool Failure After a Side Effect Has Already Happened Distributed systems have always had to deal with ambiguous failures, and AI agents add another decision-maker to the problem. A tool can successfully complete an operation while the response is lost because of a timeout, connection failure, or interrupted request. The agent then sees an error and may decide that the safest response is to retry. Imagine an agent that calls a payment API to create a refund. The payment service completes the refund, but the connection times out before the success response reaches the agent. If the agent immediately repeats the request, the customer could receive the refund twice unless the API or orchestration layer protects against duplicate execution. A production test should deliberately inject this condition. The test can simulate a successful side effect followed by a timeout and then observe the agent's recovery behavior. Instead of blindly retrying, the workflow should first reconcile the current state, query whether the transaction already exists, or use an idempotency mechanism that prevents duplicate operations. This test matters because a technically correct retry policy at the HTTP layer can still produce incorrect business behavior. Agents need explicit recovery rules for operations that change external state. Those rules should be tested before the system encounters the failure in production. 4. Poisoned, Stale, or Cross-Session Memory Persistent memory can make an agent more useful, but it also creates a new source of hidden state. Information stored during one interaction can influence decisions hours, days, or weeks later. If the stored information is false, outdated, malicious, or assigned to the wrong user, a future session may behave incorrectly even when the current prompt is perfectly safe. A useful test is to insert a false memory into the system, such as a claim that a particular customer has permanent approval for unusually high transactions. A later session can then ask the agent to process a transaction for that customer. The objective is to determine whether the agent treats remembered information as authoritative or verifies it against a trusted business system. Cross-session isolation should be tested as well. Information written during one user's conversation must not appear in another user's context unless the application explicitly supports shared state. Teams should verify memory ownership, expiration rules, provenance, and which information requires revalidation before use. The important design distinction is that conversation history, long-term memory, and authoritative business data are not interchangeable. Memory can provide context, but sensitive facts such as permissions, account status, or financial limits should normally be confirmed against the system responsible for maintaining them. 5. Tool Schema Drift and Unexpected Responses Agent tool calls often work perfectly in development because mocks and schemas remain stable. Production services change. Fields get renamed, enum values expand, required parameters become optional, responses return partial data, and older versions disappear. When that happens, an agent may try to infer what the new schema means instead of failing safely. Suppose an agent has learned to send a tool request containing a priority field with values such as high or low. The tool later changes that field to severity and expects values such as P1, P2, and P3. The test should determine whether the system rejects the incompatible request, whether the agent tries to invent a mapping, and whether repeated retries create additional problems. Unexpected response values deserve the same attention. An agent that understands APPROVED, DECLINED, and PENDING may encounter a new REQUIRES_MANUAL_REVIEW state. Production tests should verify that the agent does not guess how to handle unknown values simply because the model can generate a plausible interpretation. Schema validation should therefore exist at the execution boundary. The model may prepare a proposed tool call, but deterministic validation should decide whether the call is syntactically and semantically acceptable before it reaches the target system. Recovery behavior for rejected calls should also be part of the test suite. 6. Runaway Reasoning and Repeated Tool Loops Not every agent failure creates an incorrect answer. Some failures consume time, tokens, API requests, and infrastructure until a safety limit is reached. An agent may repeatedly call the same tool, alternate between two tools, or keep searching because every new piece of information creates another unresolved question. A simple fault-injection test can create a dependency loop. Tool A tells the agent that the answer requires information from Tool B, while Tool B directs it back to Tool A. Another version can return search results that never provide enough information for the agent to complete the task. Engineers should then observe whether the runtime recognizes the lack of progress. The system should have deterministic limits around execution. These may include maximum tool calls, repeated-call thresholds, elapsed time, token budgets, or workflow depth. The exact numbers depend on the application, so they should come from real operational requirements rather than being copied from a generic recommendation. Teams should also record whether the agent is making meaningful progress between steps. A workflow that remains under its token limit can still be unhealthy if it calls the same endpoint repeatedly with nearly identical parameters. Repeated-call ratio, tool-call depth, execution time, and cost per task are useful signals for detecting this behavior. 7. Unsafe Actions When Evidence Is Incomplete or Conflicting Agents eventually encounter situations where there is no obvious correct answer. One system reports that an account is active while another reports that it is closed. A document contains an incomplete instruction. A primary model fails, and a fallback model interprets the task differently. These are normal production conditions, not theoretical edge cases. Consider an agent that receives a request to delete historical billing records. The customer relationship system says the account is active, while the billing platform reports that it is closed. If the agent selects whichever source seems more convincing and proceeds with deletion, the system has converted uncertainty into an irreversible action. The test should verify that uncertainty changes behavior. Depending on the risk associated with the action, the workflow may need to retrieve an authoritative source, request clarification, switch into a read-only state, require human approval, or abort the operation. The correct response depends on the application, but the behavior should be defined before the agent encounters the conflict. A useful pass condition is therefore not simply that the agent chose the correct system. The stronger requirement is that the system recognized when the available evidence was insufficient to justify the requested action. Building a Failure-Injection Test Matrix These failure modes become easier to manage when teams document them in a repeatable test matrix. Each test should identify the injected condition, the telemetry that needs to be captured, the signal that represents failure, and the behavior expected from the system. Failure ModeWhat to ObserveFailure SignalExpected BehaviorIndirect prompt injectionPlan and tool traceExternal text changes protected behaviorTreat content as untrusted dataExcess permissionsAuthorization eventsPrivileged action executesBlock action outside assigned scopePost-action timeoutRetry and transaction traceDuplicate side effectReconcile state before retryPoisoned memoryMemory reads and writesFalse memory controls sensitive actionVerify against authoritative sourceSchema driftTool validation eventsInvalid or invented arguments executeReject call and follow recovery pathRunaway loopSteps, tokens, repeated callsExecution continues without progressStop through runtime limitsConflicting evidenceDecision and approval traceAgent performs risky action despite uncertaintyVerify, escalate, or abort The matrix should evolve with the product. When a production incident reveals a new class of failure, the team should turn the incident into a permanent regression test. Over time, the suite becomes a record of the system's actual operational risks instead of a collection of hypothetical prompts. Metrics That Make Agent Tests More Useful Binary pass-or-fail results are valuable, but operational measurements provide more information about how the system behaves under pressure. Teams can track unauthorized tool-call attempts, prevented side effects, duplicate-action rates, recovery success, repeated-call ratios, token consumption, time to safe termination, human escalation rates, and cross-session memory leakage. These measurements are particularly useful when model versions, prompts, orchestration logic, or tool configurations change. A new model may still complete the task successfully while making twice as many tool calls. A prompt update may reduce answer errors while increasing escalation failures. Looking at behavior-level metrics makes those regressions easier to detect. Teams should avoid inventing universal thresholds. A five-second execution time may be acceptable for one workflow and unacceptable for another. The meaningful limits should come from the latency, cost, risk, and business requirements of the specific agent being tested. Test the Agent's Boundaries, Not Just Its Answers Production AI agents should not be evaluated only by comparing an input with an expected response. Their behavior spans context selection, planning, tool choice, authorization, execution, observation, memory, and repeated decision-making. A system can produce a convincing final answer while something unsafe has already happened earlier in the execution trace. That is why failure injection should become part of the normal agent testing process. Teams need to know what happens when external content is hostile, permissions are too broad, tools return ambiguous failures, memory becomes unreliable, schemas change, execution loops, or evidence conflicts. These conditions will eventually appear outside the test environment. The strongest agent test suites grow from real operating experience. Each incident, near miss, or unexpected trace should become a test case that the system must pass before future releases. That approach shifts testing away from asking whether an agent can complete a task and toward a harder question: whether it can fail without creating a larger problem.

By Mihir Bhatt
Spring Boot's Hidden Secret for Configuration: EnvironmentPostProcessor
Spring Boot's Hidden Secret for Configuration: EnvironmentPostProcessor

Spring Boot's Quiet Hook for Shipping Configuration: EnvironmentPostProcessor Hi everyone! This is Mikhail Polivakha, technical lead of the Axelix project (an open-source product that helps you find common problems and inefficiencies in Spring Boot applications — btw, give us a star!). I want to talk about a piece of Spring Boot that a lot of people have never touched directly, yet almost everyone has bumped into the problem it solves. Let me start with a scene that I suspect will feel familiar: Let's imagine the following scenario. You maintain a shared library, an internal "company-commons" starter that every service depends on. And you want it to set a few sensible defaults for all the apps that include this Spring Boot starter. So you drop an application.yml into the library's src/main/resources, set your properties there, ship it, and unfortunately the behavior is not at all what you expected. If you have ever had problems similar to this one, then this article is for you. The TL;DR is application.yml is the wrong tool for that job, and Spring Boot has a purpose-built hook for it that rarely makes it into tutorials — EnvironmentPostProcessor (At Axelix, we use it extensively btw). If you're interested in the particular details, then let's dive in! The Problem Everyone Eventually Meets Here is the simplified setup. You have many services. They all depend on one shared module, call it company-commons. You want that module to contribute default configuration to every service that includes it a: Sensible Jackson setupDefault actuator exposureConnection-pool sizeLogging format I hope you get the idea. Anything that would otherwise be copy-pasted into forty different application.yml files. But (and this is the whole point) each service must still be able to override any of those defaults in its own configuration. The library provides the common floor, not the ceiling. So the requirement is deceptively simple: Ship default properties from a library, applied automatically, that any individual service can still override. Now let's watch the obvious solutions quietly fail this requirement one by one. Why the Approaches Everyone Reaches For Disappoint Attempt 1: A Bundled application.yml Inside the Library This is the first thing everyone tries. You put an application.yml inside company-commons, and now there are two application.yml files on the classpath: the library's and the service's. Here's the catch: Spring Boot does not "merge" two application.yml files that live at the same conventional location. It resolves configuration data from well-known locations, and a second application.yml sitting somewhere else on the classpath does not participate in that resolution the way you imagine. Depending on classpath ordering and packaging, your library's file may be silently ignored, or it may behave in ways that feel arbitrary. Either way, the starter's application.yaml will not serve as a default; rather, the behavior will be quite unpredictable, and it is certainly not the good solution. Attempt 2: Ship application-commons.yml and Tell Teams to Activate a Profile Cleaner, right? Put the defaults under a profile and document: Just add commons to your spring.profiles.active and you're all set. The problem is right there in the word "just." Now the correctness of your defaults depends on every team, in every service, forever, remembering to activate that profile. Miss it in one service and the defaults silently vanish, which may lead to incidents or security risks, depending on the nature of the custom starter. So we want the platform to enforce the behavior, not a sentence buried in a README. Attempt 3: A @Configuration Class With @PropertySource / @Bean Now we're writing actual code, so surely we have full control. Not quite, since this time the problem is timing. A @Configuration class is processed while the ApplicationContext is being built. But a lot of important configuration is consumed before that point: The logging system is initialized very early;Spring Boot's own config-data machinery (the thing that loads application.yml, resolves profiles, handles spring.config.import) has already run in ConfigDataEnvironmentPostProcessor;Property precedence for @PropertySource is awkward. What do I mean? Well, it is awkward in the sense that overall controlling the ordering of property sources via @PropertySource is generally a bad and unpredictable idea. So a bean-based approach can read configuration, but it is, in general, far too late to shape the foundation of it. If your default needs to influence logging, or config-data location, or anything resolved during startup, a @Bean never gets a word in. Attempt 4: Just Document the Properties "Add these five properties to your application.yml." This is Attempt 2 without even the profile. It fully offloads the work — and, worse, the risk of getting it wrong — onto every consuming team. It's not a good solution at all. P.S: I must acknowledge the small embarrassment since we used to ask for it in Axelix 1.1 release, but since Axelix 1.2 we no longer would require that (thanks to the external OSS contributor btw!) Micro-Conclusion Every naive approach fails in one of three ways: it runs at the wrong time, lands at the wrong precedence, or depends on a human doing something. What we actually want is a hook that: Runs early, while the Environment is still being assembled.Lets us add a property source at a precedence we choose. Underneath the user's config for defaults, or on top when we deliberately want to win regardless.Is automatic (which was important for Axelix) - no profile to activate, no property to remember. Fortunately, that hook exists. It's called EnvironmentPostProcessor. The Nature of EnvironmentPostProcessor Spring Framework has an object of type ConfigurableEnvironment. This is the object that holds all your property sources, profiles, and resolved properties early in startup - before (which is important) the ApplicationContext is refreshed. So an EnvironmentPostProcessor is a callback that fires during that window (i.e. before refresh) and gets handed the Environment to mutate: Java public class CompanyDefaultsEnvironmentPostProcessor implements EnvironmentPostProcessor { @Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { environment .getPropertySources() .addLast(new MapPropertySource("company-defaults", Map.of( // override the actuator's default "management.endpoints.web.exposure.include", "health,info", // override the jackson's default "spring.jackson.default-property-inclusion", "non_null" ))); } } There're a couple of things worth noting: addLast(...) puts our property source at the end of the resolution order, i.e. the lowest precedence. Every other source: the service's application.yml, environment variables, command-line arguments - all of them are consulted first. Our values only apply when nobody else sets them. That is precisely "the defaults" behavior.It runs early enough that these properties are in place before the necessary beans are bootstrapped, and before most of what Spring Boot does with the Environment. How Does Spring Even Find Our EnvironmentPostProcessor? There is an important thing to realize that an EnvironmentPostProcessor just cannot be a simple Spring bean. Just think about it — it must run before the ApplicationContext exists, so there is no bean container to look it up in yet. This is a classic chicken-and-egg problem. But the good news is that this problem is quite well known in Spring Boot, and it is already solved with spring.factories (and no, this file is NOT used for @AutoConfiguration classes anymore). So, we need to register our EnvironmentPostProcessor in META-INF/spring.factories (just a simple key-value pair): Shell org.springframework.boot.EnvironmentPostProcessor=\ com.acme.commons.CompanyDefaultsEnvironmentPostProcessor Spring Boot discovers these via SpringFactoriesLoader, which is the same mechanism behind a lot of its early bootstrapping. Again, note that this is spring.factories and not the newer AutoConfiguration.imports file used for auto-configuration classes. Those are different. P.S: Just a small post-review catch here. In Spring Boot 4 the interface moved from org.springframework.boot.env.EnvironmentPostProcessor to org.springframework.boot.EnvironmentPostProcessor. If you support multiple Boot generations, mind the package. Where It Sits in Startup The exact interleaving of the steps in the middle generally depends on the ordering, which, as we're about to see, is the genuinely subtle part. A Real Example: How We Expose Custom Actuator Endpoints Let me show you a real, in-production use of exactly this pattern. Axelix ships Spring Boot starters that teams add to their services. A starter is, effectively, just a library that must contribute some configuration to someone else's application - the exact shape of the problem above. What's important is that Axelix defines its own actuator endpoints (that's how Axelix Master talks to your service). For those endpoints to be reachable, they have to be listed in management.endpoints.web.exposure.include. We could write in the docs "please add axelix-* to your exposure list" - and in the 1.1 days we did exactly that (I am sorry). But you already know how I feel about solutions that depend on people remembering. So, since 1.2, the starter will contribute the endpoints itself, via an EnvironmentPostProcessor. The twist is that management.endpoints.web.exposure.include is a property the user very likely already set. So we must add our endpoints to the end user's; we must NOT overwrite them. Here is the actual code (lightly trimmed): Java public class AxelixEndpointsEnvironmentPostProcessor implements EnvironmentPostProcessor, Ordered { public static final String INCLUDED_PROPERTY = "management.endpoints.web.exposure.include"; @Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { Set<String> current = Binder.get(environment) .bind(INCLUDED_PROPERTY, Bindable.setOf(String.class)) .orElse(Collections.emptySet()); if (current.contains("*")) { return; // the user already exposed everything, nothing to do } Set<String> merged = new LinkedHashSet<>(); if (current.isEmpty()) { merged.add("health"); // preserve Spring Boot's own default, which we'd otherwise shadow } current.forEach(merged::add); merged.addAll(discoverAxelixEndpointIds(environment)); // classpath scan for @Endpoint environment .getPropertySources() .addFirst(new MapPropertySource("axelix", Map.of(INCLUDED_PROPERTY, String.join(",", merged)))); } @Override public int getOrder() { return ConfigDataEnvironmentPostProcessor.ORDER + 1; } } A few things here are worth calling out: We use Binder to read the user's existing value first, honoring whatever they configured, and we bail out entirely if they already exposed *.We merge their endpoints with ours instead of replacing them. So, simple as that. The Subtle Part: Ordering Remember I teased that ordering is the genuinely subtle bit? Here it is. Look at getOrder(): Java return ConfigDataEnvironmentPostProcessor.ORDER + 1; We deliberately run just after ConfigDataEnvironmentPostProcessor, the built-in processor that loads application.yml, resolves profiles, and handles spring.config.import. Why? Because we need to read the user's management.endpoints.web.exposure.include, and that value most likely lives in their application.yml. If we ran before config data was loaded, that property simply "wouldn't be there yet", and we'd merge against an empty set, silently dropping the user's configuration. That's the rule of thumb worth taking away: An EnvironmentPostProcessor that reads existing configuration must run after config data is loaded. One that bootstraps where configuration comes from (e.g. new YAML file), must run before it. Gotchas Worth Knowing Before You Reach for It EnvironmentPostProcessor is powerful precisely because it runs so early, and that earliness is also the double-edged sword: No dependency injection. Again, it's not a bean, so you can't @Autowired anything into it. Keep it self-contained.No logging (yet). The logging system may not be initialized when your processor runs, so logging from inside one is unreliable, although Spring Boot gives you a DeferredLogFactory to buffer output until logging is ready, if you truly need it.Fail gracefully. An exception here can derail the whole startup, very early, with poor diagnostics. If your logic can fail (a classpath scan, some parsing), guard it.It's global. It fires for every application that has your library on the classpath. That's the feature, but it also means you should keep the work conditional and cheap, and bail out early when there's nothing to do (as the example above does with the * check).Prefer Binder over hand-parsing when reading structured or relaxed-binding properties (sets, lists, kebab-case vs camelCase). It's what Spring Boot itself uses. When to Reach for It, and When Not Use an EnvironmentPostProcessor when: You are shipping configuration from a library into someone else's application, and it should apply automatically.The configuration must be in place early — before beans, before logging, or before/around config-data resolution.You need to derive, merge, or scan to compute the values, rather than state them statically.You want defaults that stay overridable (addLast), or deliberately win after merging with the user's input (addFirst). Reach for something simpler when: If you just need static defaults for your own application (not a library). A plain application.yml in that application is completely fine.The configuration is either only consumed after the context is up. Ordinary @ConfigurationProperties and beans are simpler and more discoverable.You'd be tempted to hide an important parameter here that really belongs in an explicit API or a property the user sets on purpose.You provide defaults for your own properties, not for Spring Boot's properties. For your own @ConfigurationProperties, the EnvironmentPostProcessor is typically an overcomplication. Closing Thoughts The example above is open source, so go read the real thing in the repository if you'd like to see how the pieces fit together. Take care!

By Mikhail Polivakha
Running an OpenStreetMap Tile Server for the Whole Planet on Modest Hardware
Running an OpenStreetMap Tile Server for the Whole Planet on Modest Hardware

I built my own OpenStreetMap tile server, scaled it up to the entire planet on a box with 32GB of RAM, and it took weeks. This is the write-up of what broke along the way — the five-day import, the OOM killer, the 1.7 TB database, the render jobs I had to run in chunks for days. If you're thinking about self-hosting maps at planet scale on hardware that isn't a monster, this is the article I wish I'd had. There's a companion demo repo: a minimal working build on a single region that spins up in a Docker container in about fifteen minutes with one command: make setup. You can poke at everything I describe here, in miniature. Why Self-Host Maps at All I'm a programmer, and maps aren't usually my problem. Then a request landed: we needed a mapping service for an internal project. Why not Google Maps or Mapbox? Three reasons: Air-gapped. A hard requirement from the client — no external API keys, no calls to anyone else's servers. Data and rendering entirely on our machines.Control over the data. Take a dump of whatever vintage you want, strip what you don't need (in our case, administrative borders, which only got in the way), keep exactly what the project calls for.Control over the look. Colors, fonts, which objects show up, and from which zoom level. We didn't need "one more map provider" — we needed a platform we could bend to our own needs. The project was historical in nature, so the requirements were specific to it. The choice fell on the standard stack for this job: OpenStreetMap + PostGIS + renderd + osm-carto. Why Not Vector Tiles? If you're reading this in 2026, the fair question is: why stand up the classic OpenStreetMap + PostGIS + Mapnik + renderd stack at all, when vector tiles exist, and tools like Planetiler or Tilemaker will happily bake the planet into a set of static tiles? It's a popular approach today, and a good one. The planet gets converted once into vector tiles (usually MBTiles or PMTiles), which you then serve as static files from plain nginx, with styling and rendering done client-side by MapLibre GL. That scales more easily, needs no server-side machinery, and often drops PostgreSQL and on-the-fly rendering entirely. But my project started in early 2024. Back then I leaned on the classic OSM stack for two reasons: I hadn't done any serious cartography before and was learning as I went, and this stack had years of documentation and blog posts covering exactly the problems I kept hitting. On top of that, one of my tasks was customizing the standard osm-carto style — changing labels, hiding certain objects, getting a map as close as possible to the familiar OpenStreetMap render. So I went with the traditional PostGIS/Mapnik/renderd setup. If I were starting the same project from scratch today, I'd seriously weigh vector tiles as a primary option. How the Stack Fits Together Before the details, the shape of the thing. The server has two separate flows: preparing the data (done once) and serving tiles (on every browser request). Markdown Preparation: PBF dump ──► osm2pgsql ──► PostgreSQL + PostGIS │ dump of chosen area + external data (coastlines, water) Serving: browser ──► (optional) nginx — can also serve other parts │ of the site and pre-rendered PNGs │ Apache + mod_tile │ renderd │ Mapnik ──► PNG tile │ reads geodata from PostGIS The dump is imported into the database once. After that, the browser requests a tile; Apache with mod_tile hands the request to the renderd daemon, which calls the Mapnik rendering engine. Mapnik pulls geodata from PostGIS (a PostgreSQL extension for spatial data — geometry types, spatial GiST indexes, functions like ST_Intersects), applies the style rules, and draws the image. The finished tile is cached to disk and served straight from cache next time. A few terms you'll meet along the way, defined once here so the rest reads cleanly: PBF – the binary format OSM dumps ship in. The whole planet (planet.osm.pbf) is~70 GB (early 2024; it's bigger now); individual countries and regions come from Geofabrik, updated daily.Tiles – a map in the browser isn't one big image. It's sliced into squares (usually256×256 px), each addressed by three numbers: /{zoom}/{x}/{y}.png. Zoom 0 is the whole planet in one tile; zoom 14 is individual streets, millions of tiles. The browser only requests what's visible.osm2pgsql – imports PBF into PostgreSQL, laying data out across planet_osm_point, planet_osm_line, planet_osm_polygon, planet_osm_roads.osm-carto – the standard set of render rules: road colors, when labels appear, what parks and water look like. Written in CartoCSS, compiled by the carto tool into the style.xml that Mapnik reads. Mapnik reads its style rules from that style.xml file. It's not a link in the data flow — it's rendering configuration Mapnik loads on its own — so I've left it off the diagram. Getting It Running On One Region Before throwing the planet at it, it's worth walking through a single region — the steps are the same, just without the multi-day waits. This section is a working quickstart; the planet-specific pain starts in the next one. 1. Get the Data Grab a dump from Geofabrik (countries and regions) or the OSM site (the whole planet). For a single region, it's handy to trim the dump to a bounding box with osmium, so you're not carrying dead weight: Markdown sudo apt install osmium-tool # if you don't have it # bbox: left,bottom,right,top (minlon,minlat,maxlon,maxlat) osmium extract -b 157.5,52.0,160.0,54.0 far-eastern.osm.pbf -o region.osm.pbf If you want to go the other way and stitch several regions together, same tool: Markdown osmium merge norway-latest.osm.pbf sweden-latest.osm.pbf denmark-latest.osm.pbf -o scandinavia.pbf 2. Import Into the Database With osm2pgsql Markdown osm2pgsql --slim -d gis --hstore --multi-geometry \ --tag-transform-script openstreetmap-carto.lua \ --style openstreetmap-carto.style \ region.osm.pbf The flags that matter: --slim – keep intermediate data in the database rather than in RAM. Needed for later updates and for big dumps that won't fit in memory. Without it, the import is faster but hungrier.--hstore – add a tags column (of type hstore, PostgreSQL's key-value-in-a-column extension) holding every OSM tag. OSM leans hard on tags — name:en, amenity, highway — and hstore holds them without a hundred separate columns. You query them like tags->'name:en'.--multi-geometry – assemble multipolygons into single objects; skip it, and the geometry renders wrong. 3. Enrich With External Data The step most guides mention in passing, even though rendering doesn't work without it. After the import, you have to pull in data that isn't in the PBF but that the map needs anyway: coastlines, seas, water polygons. An osm-carto script fetches them: Markdown cd openstreetmap-carto/ scripts/get-external-data.py # creates water_polygons and friends carto project.mml > style.xml # generate the Mapnik style psql -d gis -c "GRANT ALL ON ALL TABLES IN SCHEMA public TO osm;" Once the new tables appear, you have to re-grant permissions on them or renderd can't read them. Skip this whole step and the render dies on missing tables — and the error is unhelpful, because osm2pgsql finished cleanly and it looks like everything's ready. 4. Style: strip what you don't need, switch the label language All display tuning happens in project.mml (the CartoCSS source that compiles to style.xml). This is also where per-project customization lives. My first task was removing administrative borders. Find the layers with boundary ='administrative' in their queries and bolt on a deliberately false condition so the layer returns nothing: SQL -- before: WHERE boundary = 'administrative' AND admin_level IN ('2', '4') -- after: WHERE boundary = 'administrative' AND admin_level IN ('2', '4') AND 1 > 2 It's a hack, not a solution, but it gets you a result fast without spelunking through the layer internals. (In the demo repo, the same change is done properly, via PostgreSQL views for the EN layer.) My second task was switching the label language. In the queries, wrap the name field in COALESCE to fall back to the original name when there's no translation: SQL COALESCE(tags->'name:en', name, '') AS name After edits, rebuild the style: carto project.mml > style.xml. 5. Configure renderd and Apache renderd is configured in /etc/renderd.conf: where its socket lives, how many threads, which style, where to drop rendered tiles. Markdown [renderd] num_threads=8 tile_dir=/mnt/tiles [mapnik] plugins_dir=/usr/lib/mapnik/3.1/input font_dir=/usr/share/fonts/truetype font_dir_recurse=true [default] URI=/osm/ XML=/home/osm/openstreetmap-carto/style.xml HOST=tile.example.com MAXZOOM=14 MAXZOOM=14 here is a per-project choice. The standard OSM stack renders up to zoom 20, so a request like /osm/15/17571/11355.png would need that limit raised. In the mod_tile config, it's worth bumping the timeouts: ModTileRequestTimeout defaults to 3 seconds and ModTileMissingRequestTimeout to 10, which assumes fast renders — whereas a heavy tile takes several seconds to draw. Markdown ModTileRequestTimeout 10 ModTileMissingRequestTimeout 60 6. Fonts On your first render you'll almost certainly find errors in the renderd log about missing fonts, and the map will come out with no labels. Fix it by installing the Noto fonts and refreshing the font cache: Markdown sudo apt-get install -y fonts-noto-cjk fonts-noto-hinted fonts-noto-unhinted fonts-hanazono ttf-unifont fontconfig sudo fc-cache -fv The renderd log (journalctl -eu renderd) is the first place to look for any render trouble. One non-obvious error, Failed to send render cmd ... Inappropriate ioctl for device, almost always means a renderd socket problem: the socket path in the mod_tile config doesn't match the one in renderd.conf, or the Apache user (www-data) can't write to it. Check the paths in both configs and the permissions on the socket directory (usually /run/renderd). Forums often suggest export GPG_TTY=$(tty) for this error, but that variable has nothing to do with renderd — if it "helped," what actually helped was the service restart that came with it. The One Thing to Keep in Mind From the Region Build Here's a takeaway worth carrying into the planet section: the database size is set by the region, not by the render zoom. Capping the zoom only saves space on tiles; the database is fixed at import time. And a big chunk of it isn't your region at all — it's the global coastlines and water polygons, which get-external-data pulls in identically whether you're mapping a city or the planet. Kamchatka (I chose my home region as an example) is an 8 MB dump but a ~3 GB database, and almost all of that is water. *** Everything above works on a region in a day, missing fonts and permissions and timeouts aside. When "region" becomes "the whole planet," it turns into a different story: five-day imports, the OOM killer, a 1.7 TB database, renders you run in chunks for weeks. That's the rest of this article. Hardware: How Much You Actually Need The machine I was first handed: 4 cores, 16 GB RAM, 500 GB disk. Trial and error established fast that this was catastrophically short — the planet wouldn't even import. I asked for more; they bumped it a little. On the second attempt, I had 32 GB RAM and 500 + 2000 GB of disk. That's what I worked with: slowly, but the planet eventually loaded and ran. The planet database after import and all indexes weighed in at around 1728 GB (early 2024 — OSM keeps growing, it's more now), and that's before tiles. Take the disk with headroom: the import burns extra space on temporary data on top of the final size. A separate disk gotcha, and a myth worth killing while I'm here: Postgres doesn't preallocate anything and happily uses a filesystem that grew under it. My problem was simpler — the database lived on a separate mounted volume that I just hadn't expanded when the disk was added, so there was nowhere for the space to come from. Nothing needed reformatting, but I did have to move the database to the bigger volume by hand: Markdown # rough copy, database still running sudo rsync -av /var/lib/postgresql /mnt/tiles/db sudo systemctl stop postgresql # copy over what changed since sudo rsync -av /var/lib/postgresql /mnt/tiles/db sudo mv /var/lib/postgresql/14/main /var/lib/postgresql/14/main.bak # then point data_directory in postgresql.conf at the new path Tuning PostgreSQL for the Load The default Postgres config is wholly unfit for this. Most parameters scale off the amount of RAM, so it's easier to hold the rules in your head than the absolute numbers: Markdown | Parameter | Rule of thumb | Why | |------------------------|----------------------------------------|----------------------------------------------------------------------------------------------| | shared_buffers | ~25% of RAM | in-memory cache of data pages (8 KB each); fewer trips to disk | | effective_cache_size | ~50–75% of RAM | a hint to the planner (allocates nothing): lots of cache picks an index scan over a seq scan | | maintenance_work_mem | from 5% of RAM | speeds up `CREATE INDEX` and `VACUUM`; critical when building GiST indexes | | work_mem | ~25% of RAM / max connections | allocated per sort or hash, not per connection: 100 queries at 1 GB can reach 100 GB | | max_wal_size | larger is recommended, from 4 GB | fewer checkpoints during bulk inserts — but also disk space for the journal | Working values for a 32 GB server: Markdown shared_buffers = 8GB work_mem = 256MB maintenance_work_mem = 4GB effective_cache_size = 20GB max_wal_size = 10GB hash_mem_multiplier = 4.0 # multiplier on work_mem for hash operations I added hash_mem_multiplier later, while tuning the render: spatial queries lean heavily on hash joins. But let me own a mistake here. My first version had work_mem = 1GB with hash_mem_multiplier = 8.0. The important caveat: work_mem is allocated per sort or hash in each query, and hash_mem_multiplier multiplies it — with my values, a single hash operation could grab up to 8 GB. On 32 GB with eight renderd threads, that's right on the edge of OOM, and the render hangs at high zooms I'll get to below are almost certainly tied to it. If memory is tight, you're safer keeping work_mem around 256–512 MB and the multiplier in the 2.0–4.0 range. Importing the Planet Download the planet dump (~70 GB at the time of my work, 88 GB now) with resume enabled, so a dropped connection doesn't cost you the whole thing: Markdown wget -c https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf The import command: Markdown osm2pgsql --slim -d gis --hstore --multi-geometry \ --number-processes 1 \ --tag-transform-script openstreetmap-carto.lua \ --style openstreetmap-carto.style \ -C 14000 \ planet-latest.osm.pbf What's missing from this command, which I only learned afterward: --flat-nodes /path/nodes.cache. The flag moves the node cache out of the database into a separate file (on the order of 90 GB for the planet), which slims the slim-tables by hundreds of gigabytes and speeds the import up noticeably. For the planet it's considered all but mandatory; for small regions, the opposite — you don't want it. Part of my five-day import and 1.7 TB database was the price of leaving it out. Why --number-processes 1? Because with 2 and 4 processes the import died with a segmentation fault. I never nailed down the exact cause — no time to dig; single-process worked, so I stopped there. What follows isn't a verdict but hypotheses, in descending order of plausibility: The OOM killer takes out a child process. Under memory pressure, Linux picks the fattest process and kills it. If that's an osm2pgsql worker, the parent gets an unexpected child exit and falls over. Given the context — memory was chronically short — this is my bet.A shared-memory conflict. In multi-process mode, the workers coordinate through shared memory, and with too little RAM or a bad shmmax, that can corrupt data and produce a segfault.A version-specific osm2pgsql bug on parallel import with hstore and multi-geometry both active. Cured by checking the changelog and updating. If you want to get to the bottom of it: dmesg -T | grep -i "killed process" right after the crash, and coredumpctl for a trace, will give you a definitive answer. And note: I was under hard budget constraints; on modern hardware with 64+ GB of RAM, parallel import may well work without any of this. If you hit a memory wall during import, lowering -C (osm2pgsql's cache size in MB) and shared_buffers in the Postgres config helps: less pressure on RAM, a slower but steadier import. Single-process, the planet imported in roughly five days (primary storage was an HDD — an SSD will be faster). Almost all of that is osm2pgsql itself, parsing 70 GB of dump and assembling geometry. Indexes: A 150× Speedup The single biggest win came from indexes. Before them, rendering a tile at zoom 8–9 could take minutes: Mapnik would send a query to PostGIS, which did a sequential scan — walking every row in the table. For a planet_osm_polygon weighing hundreds of gigabytes, that's a disaster. GiST spatial indexes search space by tree rather than by brute force. And partial indexes with a condition pull only the rows the render needs into the index, so it stays smaller and faster: SQL -- rivers CREATE INDEX planet_osm_line_river ON planet_osm_line USING GIST (way) WHERE waterway = 'river'; -- named places (for labels) CREATE INDEX planet_osm_point_place ON planet_osm_point USING GIST (way) WHERE place IS NOT NULL AND name IS NOT NULL; -- large polygons for low zooms CREATE INDEX planet_osm_polygon_way_area_z6 ON planet_osm_polygon USING GIST (way) WHERE way_area > 5980000; -- ... about 15 indexes in total The detail I didn't clock at first: these indexes aren't hand-crafted magic you have to reason out yourself — they're a ready-made indexes.sql file in osm-carto. On a bare server you run it by hand after the import (psql -d gis -f indexes.sql), and it's an easy step to miss: after osm2pgsql it's not obvious there's anything left to do, and the map "sort of works," it just draws each tile in minutes. That knowledge came to me a lot later than it should have. After all the indexes, the database grew from ~1728 to ~1770 GB, and the render sped up roughly 150× — not one query, but rendering a whole tile, which needs dozens of queries across different layers. The difference between "a tile draws in almost three minutes" and "a tile draws in a second." These aren't a rigorous benchmark: I compared rendering the same set of tiles before and after creating the indexes (after clearing the cache, of course). Pre-Rendering the High Zooms Low zooms pre-render in minutes; high zooms run into days. Here are the real total render times for the planet — divide by your thread count for wall-clock time: Markdown | Zoom | Total time | |------|-------------------------------------------------------| | 0–3 | seconds | | 4 | ~596 s | | 5 | ~2,183 s | | 6 | ~9,109 s | | 7 | ~68,325 s | | 8 | ~273,380 s (~76 h total, ~9.5 h across 8 threads) | At high zooms the render hung regularly — most likely from memory starvation on individual heavy queries: eight renderd threads, several joins per query, and the generous work_mem and hash_mem_multiplier from the Postgres section together easily ate all the RAM. At the time, I went with a chunked strategy, offsetting along the X axis (rendering the full vertical run of metatiles but bounded horizontally), and eyeballing random tiles in the browser after each chunk: Markdown render_list --all -f -x 0 -X 100 -n 8 -t /mnt/tiles -s /run/renderd/renderd.sock -z 9 -Z 9 render_list --all -f -x 100 -X 200 -n 8 -t /mnt/tiles -s /run/renderd/renderd.sock -z 9 -Z 9 # ... easy to wrap in a bash loop Hung — stop, restart the services, resume from the chunk where it died. Ran out of disk in the middle of the night — clean up, request a bigger volume, resume. This is the normal working loop, not a fire drill, even if it did wear me down at times. And that loop — not any single command — is the real cost of a project like this. The commands are worth automating with bash scripts or a Makefile, because they're what you end up doing over and over. Filesystem: You Run Out of Inodes Before You Run Out of Space renderd stores tiles as metatiles — 8×8 tiles per file plus metadata — partly for the filesystem's sake, and it's worth spelling out why. On ext4, the number of inodes (one per file) is fixed when the filesystem is created and never changes afterward. By default, mkfs.ext4 lays down one inode per 16 KB of space — on a 2 TB volume that's about 134 million inodes. Sounds like a lot, but zoom 16 alone is over 4 billion tiles: without metatiles cutting the file count 64×, you'd run out of inodes on the planet long before you ran out of disk. Watching for it is easy: df -i shows inode usage per volume the same way df -h shows space (and the flags combine — df -ih gives the same in human-readable form). If you're creating a tile volume from scratch, you can build in headroom up front: mkfs.ext4 -i 4096 sets one inode per 4 KB of space instead of the default 16 KB, giving four times as many inodes at the cost of a little usable capacity. And XFS allocates inodes dynamically, so the problem doesn't exist there at all. Operations: Where to Dig Next I've covered building the server and getting it production-ready. A few big topics remain — here are short starting points: Updates and expiry. I didn't run updates, given the project's historical bent — current data and keeping it fresh didn't matter to us. If your data does change, osm2pgsql-replication applies diffs to the database, but tiles already rendered to disk won't update themselves — the map slowly goes stale. Expiry solves it: osm2pgsql --expire-tiles 12-14 emits the coordinates of affected tiles on each diff, a script flags them (deletes the metatiles), and renderd redraws only the changed squares on next request rather than the whole planet. Irrelevant for static maps, mandatory for a live service.Security. A default Postgres install from packages listens only on local connections, but plenty of tutorials and Docker images set host all all 0.0.0.0/0 in pg_hba.conf — meaning the database is open to everyone. Replace that with a specific subnet, or hide it behind an SSH tunnel, or proxy to a specific container; and gate the tiles themselves with auth at the Apache or nginx layer in front.Monitoring. The minimum worth watching: df -h (disk fills first during pre-render), df -i (inodes), htop / free -h (memory), the renderd log (journalctl -u renderd), and mod_tile's stats — the module can serve request and render counters on a status URL. What It Comes Down To The OSM + PostGIS + renderd stack works, but it takes patience, resources, and an understanding of how the services connect. In short: Three non-negotiables: indexes, Postgres tuning, and external data. Each looks optional on its own, but without them the render either falls over or draws a tile in minutes and times out.The biggest non-obvious space cost is the global water polygons, not the region you import.Budget for the non-linearity. Crashes, restarts, a disk that fills at 3 a.m., moving a volume — this isn't force majeure; it's the reality of the process, and it's where most of the effort actually goes. And the main lesson, which isn't about the technology. Most of the problems I've described turned out to be less about OSM itself than about trying to fit a planet-scale dataset into limited resources. The server's memory was later doubled — working on it got markedly more pleasant — but I handed the project off to a successor, so all I can say for sure is that 64 GB is a sane minimum if you're taking something like this on. So the main advice is simple: if you're going to work with the whole planet, put enough memory and disk headroom in place first, and only then start optimizing. You can feel out the tuning and indexes on a small region in the demo repo — make index-benchmark and make render-benchmark shows the effect of a GiST index and the difference between a cold and a warm tile.

By Dmitrii Starikov
A/B Testing Under Shared Constraints: Supply, Inventory, and User Attention
A/B Testing Under Shared Constraints: Supply, Inventory, and User Attention

Why Local Lift Does Not Mean System Growth A marketplace team tests a new ranking policy. On the home surface, the share of user activity rises from 30% in control to 45% in treatment: a 15-percentage-point lift. Assignment is balanced, tracking is complete, and the confidence interval excludes zero. The result looks ready to ship. Then the team expands the analysis. Search activity falls by almost 15 points, browse is unchanged, and total activity per user remains flat. The treatment did not create more engagement. It changed where that engagement happened. The home surface gained activity, but the product as a whole did not. Nothing about the local calculation is wrong. The A/B test correctly answered, “Did activity increase on home?” The mistake was treating that answer as proof that total activity increased. A precise local estimate can still support the wrong launch decision when users, suppliers, or product surfaces compete for a shared resource. Teams often respond by reaching for a switchback, cluster randomization, or separate budgets. Before changing the design, answer two simpler questions: Did the treatment increase the system total or redistribute an existing outcome?Were treatment and control isolated at the level where the shared resource operated? This article presents a practical workflow for answering both questions. It reconciles local changes against a system total using the randomized-user denominator, then screens for coupling inside the resource pools shared by the experiment arms. Why Shared Constraints Change the Meaning of Lift An ordinary user-level experiment assumes that one user’s assignment does not change another user’s outcome. This condition is part of the Stable Unit Treatment Value Assumption (SUTVA). It becomes questionable when experimental units compete through a shared constraint: The first three examples can create interference between experimental units. The fourth can create cannibalization between product surfaces even when user assignment itself is clean. These mechanisms are related, but they are not the same claim: Interference means that treatment assigned to one unit changes another unit’s outcome.Cannibalization means that a measured gain comes from a corresponding loss elsewhere in the system.Incrementality means that the treatment increases the outcome the system ultimately values, rather than changing its location or attribution. Assignment, sample-ratio, exposure, and telemetry checks still come first. Once they pass, the next review asks whether the success metric covers the system outcome and whether the randomization unit isolates the rollout effect. Use a Local-to-System Reconciliation The local-to-system reconciliation brings those checks into one review. It has five parts: Define the shared constraint and system boundary. Identify the supply, inventory, budget, attention, or capacity through which outcomes can move, and decide what must be counted for the launch decision.Measure each local change. Estimate treatment-control differences for the components inside that boundary.Reconcile the total. Aggregate those components with one denominator tied to the randomization unit.Check isolation inside shared pools. Examine whether the arms move together inside markets, regions, seller clusters, or budget groups.Classify the evidence. Treat the result as incremental, redistributive, isolation-sensitive, or inconclusive before deciding whether to ship or redesign. Figure 1: Decision flow from local lift through system reconciliation and isolation review Start with the boundary. It must correspond to the business decision, and every component inside it must use a compatible unit of analysis. A convenient total that excludes the surface likely to lose value simply moves the blind spot. Reconcile Outcomes per Randomized User Here is what the reconciliation looks like in a deterministic synthetic experiment with three mutually exclusive surfaces: The home result is real. It just does not show incremental engagement: search loses almost exactly what home gains. Calculate the treatment-control change for every affected surface using the randomized-user denominator. The system change is the sum of those component changes. The total absolute movement shows how much behavior shifted across surfaces. When movement is large, but the system change is close to zero, the treatment is primarily redistributive. The implementation preserves the randomized-unit denominator: Python arm_size = df.groupby("variant")["user_id"].nunique() surface_per_user = ( df.groupby(["variant", "surface"])["activity"] .sum() .unstack(fill_value=0) .div(arm_size, axis=0) ) system_per_user = surface_per_user.sum(axis=1) surface_delta = ( surface_per_user.loc["treatment"] - surface_per_user.loc["control"] ) system_delta = surface_delta.sum() local_movement = surface_delta.abs().sum() Counting event rows instead would let an engagement-changing treatment alter its own denominator. Per-user outcomes preserve the connection between the reported effect and the randomization design. Figure 2: Control and treatment have different surface shares while total outcome remains flat. What To Watch For Do not interpret shares without levels. A surface share can fall while its absolute activity rises if the total grows.Make the parts add up. Overlapping or incomplete surfaces do not produce a clean system total. State what is excluded, and avoid double counting.Keep the statistical review. Reconciliation is a diagnostic, not a standalone hypothesis test. Component and system estimates still need confidence intervals that respect the experiment design. Use the system total as part of the Overall Evaluation Criterion (OEC): the metric or combination of metrics used to judge experimental success and connect short-term measurement to longer-term goals (Kohavi, Tang, and Xu, Chapter 7). Home activity explains where behavior moved; it should not decide the launch when the objective is total engagement or marketplace value. Once the metric boundary is clear, the next question is whether the experiment arms were truly isolated. Check for Coupling Inside Shared Resource Pools Reconciliation can show that value moved. It cannot tell you whether treatment and control affected one another. A useful risk screen asks whether both arms remain related inside pools that share supply, inventory, or budget. Do not correlate raw market means. Large markets can have high outcomes in both arms for stable reasons unrelated to the experiment. Remove each market’s pre-period baseline and compare changes: Python market_means = ( df.groupby(["market_id", "period", "variant"])["revenue"] .mean() .unstack(["period", "variant"]) .dropna() ) control_change = ( market_means[("post", "control")] - market_means[("pre", "control")] ) treatment_change = ( market_means[("post", "treatment")] - market_means[("pre", "treatment")] ) coupling = control_change.corr(treatment_change) The synthetic data returns a correlation of 0.873. Treat that as a review signal, not an “interference detected” verdict. Common shocks, seasonality, measurement changes, and omitted market characteristics can produce the same pattern. The shared-pool coupling screen has one job: challenge the randomization unit. Define resource pools before looking at results, report the number and size of those pools, and add uncertainty or randomization inference. Even with those safeguards, the screen can identify risk in the original estimate; it cannot correct that estimate. Convert the Evidence Into a Launch Decision At this point, the team has two different forms of evidence: whether value moved across the system and whether the experiment arms may have shared the same constraint. Together, they lead to different actions: The categories should not be collapsed into a single reliability score. Redistribution and interference answer different questions. A treatment can reallocate activity across surfaces without contaminating control, or it can interfere through shared supply even when the measured system total is positive. Only an isolation problem necessarily requires a new experiment design. Match the Design to the Constraint Shared supply over time and region: Use a switchback to randomize the market state rather than individual transactions. DoorDash uses this pattern for dispatch experiments (DoorDash Engineering).Fixed campaign budgets: Separate the budgets used by treatment and control. LinkedIn describes this budget-split design for its advertising marketplace (LinkedIn Engineering).Marketplace or network spillovers: Randomize clusters rather than individuals, while accounting for the loss of power that comes with fewer independent units (Holtz et al.).Competition between listings or surfaces: Keep local metrics as diagnostics, but base the decision on incremental platform value. Airbnb describes this distinction when accounting for booking cannibalization (Airbnb Engineering). These are responses to a diagnosed constraint, not a checklist to apply to every experiment. Key Takeaways Name the shared supply, inventory, budget, or attention constraint before choosing the randomization unit.Define the system boundary before reviewing local lift.Calculate every component with the randomized-unit denominator.Compare absolute outcomes before interpreting changes in surface share.Treat shared-pool coupling as a design-review signal, not proof of interference.Redesign only when the evidence shows that treatment and control were not isolated at the level where the system operates. A p-value can tell you whether the observed treatment-control difference is compatible with a null hypothesis under a statistical model. It cannot tell you whether the experiment measured the right boundary or isolated the right unit. The final question is not whether the treatment won its local comparison. It is whether launching the treatment would make the system better. Reference Implementation The deterministic example behind the reported values is available in the runnable Python script. A broader open-source implementation of related diagnostics is available in the Expguard repository and its archived release. These implementations are optional; the workflow applies independently of either codebase. References and Further Reading Kohavi, R., Tang, D., and Xu, Trustworthy Online Controlled Experiments: A Practical Guide to A/B Testing, Cambridge University Press, 2020.DoorDash Engineering, Switchback Tests and Randomized Experimentation Under Network Effects.Holtz et al., Reducing Interference Bias in Online Marketplace Pricing Experiments.Li et al., Interference, Bias, and Variance in Two-Sided Marketplace Experimentation.LinkedIn Engineering, Budget-Split Testing: A Trustworthy and Powerful Approach to Marketplace A/B Testing.Liu, Mao, and Kang, Trustworthy Online Marketplace Experimentation With Budget-Split Design.Airbnb Engineering, How Airbnb Measures Future Value To Standardize Tradeoffs.

By Arun Thomas
Your Agents Think Data Federation Means One Truth. It Means a Collage.
Your Agents Think Data Federation Means One Truth. It Means a Collage.

Data federation was sold on a simple promise: query data where it already lives, across Snowflake, Databricks, and the rest of the stack, without making another copy. No more nightly ETL jobs staging the same customer table in four different warehouses. No more arguments about which copy was authoritative. Point the query at the source and get an answer. For the workloads it was designed to support, that promise mostly held. A human analyst could pull a report, or a dashboard could refresh each morning, without moving the data. The query ran. If a number looked slightly off, someone could notice, check it, or just shrug and move on. Federation was never built for an autonomous agent that accepts the answer and acts on it without a second look. That assumption is about to be tested, and it will not survive. The Copy Problem Was Never the Coherence Problem Federation solved a real issue: duplicated data creates duplicated cost, duplicated drift, and duplicated arguments about which copy to trust. Querying in place through an open table format like Iceberg, or through Snowflake's and Databricks' respective sharing layers, removes that duplication. What it does not do is guarantee that the answer coming back represents one coherent state of the world. Those are different problems, and the industry has spent the last few years solving the first while quietly assuming the second came for free. It didn't. Here's where that assumption breaks, specifically once an agent, not a person, is the one issuing the query. Five Clocks, One Query A federated join across a warehouse, a lakehouse, and a live API does not pull from one system at one moment. It pulls from three systems, each with its own refresh schedule and consistency model. None of them is coordinated with the others, and no distributed transaction aligns their data to a single point in time. The result looks like a snapshot, but it is closer to a collage assembled from whatever each source had available when the query arrived. Take a churn-risk agent deciding whether a customer needs a retention offer. It queries the CRM for account status, the support platform for open tickets, and the billing system for payment history. The CRM record was synced four hours ago. A support ticket that just closed has not propagated yet. The billing system runs on a separate pipeline and is current to the last five minutes. The agent receives one joined row and treats it as one fact: this customer is a churn risk, so act now. It has no way to know that a third of the row was already stale by the time it arrived. A human analyst who sees an unexpected number will usually pause, check the timestamp, and perhaps run the query again. An agent will not do that unless someone explicitly designed it to. It accepts the federated result as ground truth and acts on it. Figure 1. Federated queries combine data from sources with different freshness levels, creating a result that appears unified but may not represent one coherent moment. Authorization for a Session, Not a Stream of Calls Federated and shared-access models assume a human user: log in, pass an authorization check at the session boundary, and then query within that approved window. The model is intentionally coarse because a human session does not need authorization reevaluated every few seconds. An agent works differently. A fraud-review agent querying a shared Iceberg table of transaction records may use a service account that received table-level read access once, during setup. From there, it can issue several hundred narrow, autonomous queries an hour while working through flagged cases. Nothing in the architecture rechecks whether that specific task should be allowed to see each record it requests. A standing grant designed for someone opening a dashboard twice a day now supports a process capable of issuing hundreds of queries without supervision. Runtime access enforcement has to happen on every call, not just at the start of a session. Most federation architectures deployed today were not built for that level of granularity or volume. Federation makes the query possible. It doesn't make the answer agreeable. Enterprises increasingly run multiple agents, often on different vendor stacks: Databricks tooling for one and Snowflake Cortex for another. Each agent reasons independently about shared entities such as customers and orders. In this setting, the case for federated, in-place access is not efficiency. The question is whether the agents are even seeing versions of the same entity that can be reconciled. Consider a supply chain agent on one platform and a finance agent on another, both querying the same order record. One must decide whether to expedite a shipment. The other must decide whether to release a payment. The supply chain agent reads the order during a write and catches the status enum mid-transition. The finance agent reads it ninety seconds later, after the write is complete. Both queries were technically correct based on the data available when they ran. Yet the agents now hold different beliefs about the same order. Neither has any signal that the other agent, working from the same source, reached a different conclusion. Figure 2. Two agents querying the same shared data can reach conflicting conclusions when they read it at different points in time. What Actually Has to Change Three things, in order. This is the same sequencing argument behind the AI-Readiness Quadrant framework I laid out: identity first, then access enforcement, then observability. Skipping ahead doesn't work any better here; it just means patching symptoms instead of fixing what's underneath. Figure 3. Federation places particular strain on runtime access enforcement and lineage and observability within the AI Readiness Quadrant. Federated results need explicit freshness and consistency metadata that an agent can read and reason about. The system cannot assume that every source is synchronized when that synchronization was never guaranteed. If a query joins three systems, the response should report how stale each source was when the query ran, not just return the joined rows. Access enforcement also needs to happen at the level of each call. Every request should be evaluated against the data it touches instead of relying on a session that was authorized once and left open. That is a heavier operational burden than most sharing and federation layers were designed to support. It still needs to happen before agent query volumes exceed what today's coarse access models can handle. When agents from different vendors need to agree on the same entity, that agreement must be established deliberately through the identity and catalog layers. It does not emerge automatically because every system adopted the same open table format. Iceberg makes the data physically reachable by more than one engine. It does not make two independent agents agree on what that data means. The Trust Problem Federation Was Never Asked to Solve Federation got adopted to kill a cost and integration problem: too many copies, too much ETL, too much arguing about which table was current. It solved that. What it's being asked to solve now, mostly by default and without anyone deciding it deliberately, is a trust problem: whether an autonomous system acting on a federated answer is acting on something coherent. It was never built for that job. Fixing the foundation underneath agentic systems means treating that gap as the thing to solve first, before scaling the number of agents that depend on an architecture that was never asked to guarantee coherence in the first place.

By Sushree Mishra

Culture and Methodologies

Agile

Career Development

Methodologies

Team Management

Measuring AI Impact at the Team Level

November 17, 2026 by Stefan Wolpers DZone Core CORE

Introducing TypeSafe Jev: Typed Judgments as Programming Primitives

November 17, 2026 by Horatiu Dan DZone Core CORE

A/B Testing Under Shared Constraints: Supply, Inventory, and User Attention

November 16, 2026 by Arun Thomas

Data Engineering

AI/ML

Big Data

Databases

IoT

Vapi vs Retell AI vs LiveKit: Architecture, Latency, Pricing, and Developer Experience

November 17, 2026 by Akmal Chaudhri DZone Core CORE

From Phone Menus to Workflows: The Quiet Engineering Behind Voice Agents That Act

November 17, 2026 by Igboanugo David Ugochukwu DZone Core CORE

When Jev Says It's Sure, Is It Right? A Fraud Case Study in Neo4j

November 17, 2026 by Akmal Chaudhri DZone Core CORE

Software Design and Architecture

Cloud Architecture

Integration

Microservices

Performance

Vapi vs Retell AI vs LiveKit: Architecture, Latency, Pricing, and Developer Experience

November 17, 2026 by Akmal Chaudhri DZone Core CORE

Using Middleware in LangChain: Recovering From Tool Failures

November 17, 2026 by Ruchi Saini

The Rise of the Unsanctioned Agent Swarm

November 17, 2026 by Nikita Kothari

Coding

Frameworks

Java

JavaScript

Languages

Tools

When Jev Says It's Sure, Is It Right? A Fraud Case Study in Neo4j

November 17, 2026 by Akmal Chaudhri DZone Core CORE

Pitching Kotlin: An Engineering Leader's Guide to Legacy Modernization

November 17, 2026 by Yuri Geronimus

Reading GC Logs: Memory Leak or Undersized Heap?

November 17, 2026 by Amit Sonar

Testing, Deployment, and Maintenance

Deployment

DevOps and CI/CD

Maintenance

Monitoring and Observability

Introducing TypeSafe Jev: Typed Judgments as Programming Primitives

November 17, 2026 by Horatiu Dan DZone Core CORE

7 Failure Modes Every Production AI Agent Should Be Tested Against

November 16, 2026 by Mihir Bhatt

A/B Testing Under Shared Constraints: Supply, Inventory, and User Attention

November 16, 2026 by Arun Thomas

Popular

AI/ML

Java

JavaScript

Open Source

Vapi vs Retell AI vs LiveKit: Architecture, Latency, Pricing, and Developer Experience

November 17, 2026 by Akmal Chaudhri DZone Core CORE

From Phone Menus to Workflows: The Quiet Engineering Behind Voice Agents That Act

November 17, 2026 by Igboanugo David Ugochukwu DZone Core CORE

When Jev Says It's Sure, Is It Right? A Fraud Case Study in Neo4j

November 17, 2026 by Akmal Chaudhri DZone Core CORE

  • RSS
  • X
  • Facebook

ABOUT US

  • About DZone
  • Support and feedback
  • Community research

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 215
  • Nashville, TN 37211
  • [email protected]

Let's be friends:

  • RSS
  • X
  • Facebook
×