Building an internal developer platform (IDP) that works seamlessly with AI agents requires more than just connecting tools - it demands thoughtful architecture. As AI agents move from experiment to production reality, the platforms you build today will either amplify or constrain what your engineering organization can achieve tomorrow.

Main insights

• The right IDP architecture uses three layers - developer experience, platform contract, and platform engine - with the middle layer being critical for agent readiness
• Agents play a dual role as both workloads running on your platform and users of your platform, requiring identity management, sandboxing, and proper abstractions
• More abstractions mean fewer tokens and tighter guardrails - exposing high-level intents to agents rather than low-level infrastructure reduces blast radius and improves safety
• Open source platforms like OpenChoreo can provide a 75% head start, letting you focus on customization rather than building from scratch

Sameera Jayasoma and Lakmal Warusawithana are both VP and Distinguished Engineers at WSO2 and co-maintainers of OpenChoreo, a CNCF sandbox project focused on building agent-ready internal developer platforms. Together, they bring six years of hands-on experience designing platforms that balance developer productivity, security, and operational control - now extended to meet the demands of AI-augmented engineering.

You can watch the full discussion here if you missed it.

The highest goal: Maximizing return on engineering investment

Every IDP decision ultimately comes down to one metric: increasing the ROI of your engineering investment. Developer productivity, security, and agent readiness all serve this goal. But there are three common ways organizations lose that return:

• Having no platform at all
• Building a platform without proper architecture
• Having a platform that isn't agent-ready

As Sameera explains, "Nowadays if you don't have a platform, if you have a platform but if it's not agent ready, that's also another way to lose the return because now agents are amplifying the productivity of developers and the organization as a whole."

The challenge isn't about which tools you pick - the CNCF landscape offers excellent options. The real question is how you compose them. Just as in software engineering, it's never about the libraries you use, but how you combine them with sound architecture and design principles.

The three-layer architecture: Avoiding the messymiddle

A well-designed agent-ready IDP consists of three distinct layers:

Developer experience layer: This is where your users live - developers, SREs, and now agents. They interact through portals, CLIs, GitHub integrations, Slack, and increasingly through MCP (Model Context Protocol), an emerging standard for agent access to platform capabilities.

Platform contract layer: This middle layer is what most organizations miss. It abstracts away the platform engine from developers, providing proper developer experience. When a developer says "I want to create a component" or "I want to release my service to the dev environment," this layer orchestrates that intent and compiles it into a form that Kubernetes and underlying tools can act on.

Platform engine layer: This is where your tools live - Kubernetes, CI/CD, observability, gateways, and access control, all properly integrated.

The problem many organizations face is skipping the middle layer entirely. As Sameera demonstrates, "If you want to add a portal to your existing platform, you would do this kind of integrations to Backstage.io. You would configure Kubernetes plug-in, you would configure Github Actions, you will configure your observability stack into backstage."

This creates what they call the messy middle - a tangle of point-to-point integrations that becomes unmaintainable over time. When you add agents to this architecture, the situation gets significantly worse. Agents end up accessing tools directly, manipulating Kubernetes manifests and YAML files with no guardrails and a high blast radius.

Agents as workloads and actors

Agents play a dual role in your platform, and your architecture must account for both.

As workloads, agents are just like your web apps, services, jobs, and databases. They need identity, secrets, networking, and observability. But agents are special because they execute code generated by LLMs, which means you need sandbox execution environments. Two emerging open source projects address this:

• Agent Sandbox creates a one-to-one mapping where each agent becomes a pod, scheduled by Kubernetes like any other workload, but with sandboxing technologies providing isolation.
• Agent Substrate handles burst scenarios where you spin up hundreds of sub-agents quickly. It maintains a pool of pods and schedules agent workloads into them - similar to a virtual thread scheduler - with agents suspending and resuming as needed.

As actors, agents function as users of your platform. They can play different roles - developer, platform engineer, or SRE - each with different access policies and identities. As Lakmal notes, "Your IDP becomes the agents harness" - your platform governs everything agents can do, what policies apply, and how they're identified.

The abstraction advantage: Fewer tokens, tighter guardrails

One of the most actionable insights from this session is that more abstractions lead to fewer tokens and better safety. When agents work at the intent level - "promote this release to production" - they're constrained to what that intent can do. The platform contract layer governs their actions.

Compare this to exposing lower-level access where agents parse Kubernetes manifests and raw configuration to get the job done. Not only does this require processing significantly more context (and more tokens), but it also increases the blast radius when something goes wrong.

Sameera is direct on this point: "Until you get the abstractions properly, abstractions will leak, that's for sure. But the point is still you are letting them access underlying complexity via tighter guard rails."

Your architecture can support both paths - high-level intent for 95% of cases, with carefully governed escape hatches for advanced scenarios where agents might need read-only access to diagnose what's happening.

Six principles for agent-ready platforms

Sameera and Lakmal distill their architectural approach into six principles every platform team can apply:

1. Platform contract: Hide agents from your underlying tooling complexity through a well-defined contract layer
2. Return path: Let agents reason about system health and abstractions without accessing underlying observability APIs directly
3. Golden paths: Create paths that work equally well for humans and agents
4. Agent identity: Provide proper identity management so agents are distinguishable, auditable actors
5. Sandbox environment: Run agents in isolated, controlled environments to limit the impact of unexpected behavior
6. Governed access: Plan how agents access lower layers when necessary, with appropriate controls and audit trails

Building versus adopting: The OpenChoreo approach

Organizations face a practical choice: build from scratch or adopt an open source platform. Building from scratch gives you complete control but requires significant time and effort. Adopting a platform like OpenChoreo can give you a 75-80% head start, letting you focus on the last mile of customization rather than foundational plumbing.

OpenChoreo, a CNCF sandbox project, embodies these architectural principles. As Sameera explains, "Even though early in the sandbox, it's six years of learnings and experience we captured into OpenChoreo. It's production ready."

The platform organizes the engine layer into conceptual planes: a data plane where workloads run (you can have multiple data planes for different environments), an observability plane that connects to your data planes, and a control plane that contains abstractions as CRDs (Custom Resource Definitions), APIs, and orchestration logic.

During the live demo, Sameera showed how agents can interact with OpenChoreo through MCP servers - asking questions like "list all components in this deployment" without being exposed to underlying Kubernetes complexity. The platform also supports component types, which are templates where platform teams encode golden paths and organizational best practices that both humans and agents consume consistently.

​

If you enjoyed this, find more great insights and events from our Platform Engineering Community.

For more comprehensive guidance, check out the Platform Engineering Certified Architect Course and learn best practices from industry experts.

​

Key takeaways

​

• Architecture matters more than ever with agents: Humans can work around poor platform design through tribal knowledge and informal communication. Agents cannot. The three-layer architecture with a strong platform contract layer is essential for agent readiness - without it, you're exposing raw infrastructure to systems that will act on whatever access they're given.
• Design for agents as both workloads and users: Your platform must run agents as workloads with proper identity, secrets, and sandboxing, while also treating them as actors with role-based access. Your IDP becomes the harness that governs what agents can do and how their actions are audited.
• Expose intent, not infrastructure: Give agents access to high-level abstractions like "create a web app" or "promote to production" rather than direct access to Kubernetes and raw tooling. This reduces token usage, limits blast radius, and makes every action auditable - three outcomes that matter enormously at scale.
• Start from a solid foundation: Building from scratch is possible but time-consuming. Open source platforms like OpenChoreo can provide 75% of what you need, letting you focus on the last mile of customization for your organization's specific policies, golden paths, and operational practices.