A developer can notice that an environment request looks stuck and ask the platform team what happened. An agent may submit it again. Put that difference at the center of the interface design: the platform must explain what it accepted, what it created and what the caller is allowed to do next.
Define the request
Use a fictional test-environment service as the design exercise. Its request identifies the project, template version, owner and intended lifetime. The result contains an operation identifier and a state. “Request accepted” and “environment ready” are different responses because provisioning may continue after the initial call returns.
Give the caller a way to look up that operation. If the connection drops, the next step should be to establish its state. A second create call should have documented duplicate behavior. Otherwise, a short interruption can become two environments with different owners and nobody certain which one to use.
Enforce access in the service
The portal might restrict a dropdown to approved templates. An agent does not need to visit that dropdown. The operation itself must check the template, project, identity and resource limits before it acts. Both interfaces can use the same service without sharing an unrestricted service account.
Lakmal Warusawithana’s July 2026 CNCF member post describes platforms serving engineers and agents under a common governance model. The implication for this example is concrete: adding a machine interface should expose an existing controlled capability, with an identity and an outcome that can be traced.
Source: Lakmal Warusawithana, CNCF member post · July 21, 2026.
Test requests before expanding
Exercise the contract with deliberately fictional project data. Inspect the resulting resources as well as the response. A clear error is useful, but it is the absence of an unauthorized environment that proves the denial worked.
- An allowed request creates one environment with the stated owner.
- A request for another team’s project is rejected by the service.
- A repeated request produces the documented duplicate result.
- A timeout can be resolved through the operation identifier.
Make results easy to interpret
An agent should not need to translate a progress paragraph into a guess about whether it can deploy. Return explicit states and valid follow-up actions. Reserve explanations for helping the caller understand a decision, rather than using prose as the only interface contract.
This also improves the human route. The same operation record can tell a developer what exists, which policy stopped a request and who owns the unresolved state. Agent support is a useful test of whether the platform’s promises were explicit in the first place.