Agent experience for AI agents: why APIs need a new design layer

At a glance

What this is: This article argues that AI agents require a distinct design layer, agent experience, because they consume products differently from humans and need explicit, structured, machine-readable interfaces.

Why it matters: It matters to IAM practitioners because agent-facing systems change how access, scope, reversibility, and accountability have to be governed across NHI, autonomous, and human workflows.

👉 Read WorkOS's article on designing products agents can actually use

Context

AI agent-facing products fail when they assume human interpretation. Agents do not resolve ambiguity, infer hidden state, or work around UI-only functionality, so products built around implicit cues create operational risk for automated consumers and the identity systems they rely on. In practice, agent experience becomes a governance problem for the machine identities that call APIs, not just a product design preference.

The author’s core claim is that agent-driven workflows are becoming a default consumption model for software, which means API structure, error handling, idempotency, and schema quality now shape how identities behave at runtime. That shifts attention from interface polish to whether an NHI or agent can execute safely, retry cleanly, and stay within scope without human translation.

This is atypical only in the sense that many teams still treat agent support as a niche developer concern. The article shows it is already an access and control issue whenever software is exposed to machine consumers.

Key questions

Q: How should security teams govern AI agents that use public APIs?

A: They should treat agent-facing API use as delegated execution, not ordinary application traffic. That means structured schemas, deterministic errors, idempotent operations, and scoped permissions are all part of governance. If the agent can retry, chain calls, or act at machine speed, access control must assume automation will amplify any ambiguity in the interface.

Q: Why do UI-only workflows create risk for machine identities?

A: Because machine identities cannot reliably operate through visual interfaces, UI-only steps often force teams into browser automation or uncontrolled workarounds. That creates brittle execution paths, weak auditability, and unclear boundaries around what the identity can actually do. If a task matters enough to automate, it also matters enough to expose programmatically.

Q: What do organisations get wrong about agentic retries and idempotency?

A: They often assume a failed request means nothing happened, which is unsafe in agent workflows. Agents retry aggressively, and without idempotency the same action can execute twice or more. The control question is not whether retries occur, but whether repeated calls produce the same safe result without duplicate side effects.

Q: How do you know an agent workflow is safe enough to delegate?

A: Look for three signals: the action is reversible, the scope is explicit, and the system is inspectable before completion. If users cannot see what the agent will change, cannot undo it, or cannot bound its access, delegation is premature. Safe delegation depends on legibility, not just model accuracy.

Technical breakdown

Why agent-facing APIs need explicit structure

AI agents operate as parsers and executors, not as context-aware users. They work best when APIs return stable object shapes, typed fields, documented limits, and machine-readable errors, because they cannot infer intent from layout or prose. The design problem is not cosmetic. If state is implicit, an agent has to guess; if errors are vague, it has to retry blindly; if the schema is incomplete, it will improvise. That is why structured responses, idempotent operations, and complete schema documents are operational controls for agent consumption, not just documentation quality.

Practical implication: expose every agent-consumable action through a structured, documented API and treat UI-only workflows as unsupported for machine identities.

Idempotency and retry safety in agent workflows

Agents retry aggressively because failures are normal in multi-step execution. Idempotency prevents retries from creating duplicate side effects when a request times out, a network call fails, or a workflow resumes midstream. The pattern depends on a caller-generated key that lets the server deduplicate logical operations within a window. Without that, a 10-step agent task can multiply records, messages, or transactions on every retry path. This is why idempotency is more than developer convenience. It is a boundary control for machine identities that may reissue the same action without noticing the previous result.

Practical implication: require idempotency keys on all side-effecting agent actions and test retry behavior as part of access and workflow assurance.

Autonomy, reversibility, and scoped action design

Agent-powered products change the identity problem from asking whether a user can do something to asking how much delegated action is safe before human review. The right control model is based on reversibility and blast radius. Reversible, narrow actions can proceed with minimal friction, but broad or irreversible actions need previews, confirmation, or explicit stop points. This is not a generic UX pattern. It is a governance model for delegated execution, especially when a software agent is acting with machine speed inside a human workflow.

Practical implication: classify agent actions by blast radius and reversibility, then gate only the irreversible or broad-scope operations.

Breaches seen in the wild

• Moltbook AI agent keys breach — Moltbook breach exposed 1.5M AI agent keys.
• AI LLM hijack breach — attackers used stolen AWS access keys to hijack Anthropic LLM models on Bedrock.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Agent experience is an identity control surface, not a design nicety. Once AI agents become primary consumers of software, the question is no longer whether the interface is pleasant for humans. The question is whether machine identities can safely interpret, retry, and complete actions without guessing. That makes structured output, explicit state, and idempotent execution part of access governance, because the agent is effectively the actor carrying privilege.

UI-only functionality creates hidden identity debt for machine consumers. If a capability exists only in the dashboard, the organisation has implicitly decided that the control cannot be exercised safely by an NHI or agent. That breaks parity between what the business thinks the product can do and what an automated identity can actually reach. The implication is not simply that teams need more APIs. It is that unsupported UI workflows are ungoverned execution paths.

Reversibility is the missing control concept in agent governance. Human IAM has long relied on confirmation, review, and exception handling to bound risk, but agent-driven workflows compress time and increase retry frequency. A control model built for slow human action fails when an identity can act, repeat, and chain decisions at machine speed. Practitioners should treat reversal, preview, and scoping as core access design properties, not post-launch usability choices.

Agentic scope drift should be understood as delegated execution beyond intended boundaries. The article shows how easy it is for an agent to keep going when the task is underspecified, the state is ambiguous, or the action model is not explicit. That is a governance failure because the system is not only using access, it is interpreting it. The implication is that approval models, lineage, and auditability need to be designed around machine-paced delegation, not human-paced supervision.

From our research:

• Only 44% of developers are reported to follow security best practices for secrets management, according to The State of Secrets in AppSec.
• Another finding from the same research shows organisations maintain an average of 6 distinct secrets manager instances, which fragments control.
• For a broader view of how machine identities and secret exposure interact, see AI LLM hijack breach.

What this signals

Agent experience will increasingly shape how identity teams evaluate product readiness. When interfaces become machine-consumed rather than human-consumed, governance questions move from usability to execution safety. The programmes that adapt fastest will be the ones that measure API parity, error discipline, and action reversibility as part of their control baseline.

AX debt is a useful term for the hidden operational cost of human-only design. If the product roadmap keeps expanding agent use without first-class machine-readable controls, teams inherit brittle automation, unclear scope, and weak audit trails. That creates a familiar identity problem in a new form: privilege without legibility.

With 43% of security professionals already concerned that AI systems can learn and reproduce sensitive information patterns from codebases, the boundary between product design and NHI governance is getting thinner. The practical response is to pair explicit schemas with published guidance such as the OWASP Agentic AI Top 10 so machine consumers do not become unmanaged execution paths.

For practitioners

• Map agent-facing actions to explicit API parity Inventory which product functions are only available in the UI and define API equivalents for each one that an agent may need to call. If a capability cannot be exposed programmatically, document it as unsupported for machine consumers so teams do not fall back to brittle browser automation.
• Require structured errors and typed responses Standardise error codes, response shapes, and field types so agent callers can branch deterministically instead of parsing free text or inferred status. Include documented edge cases for pagination, rate limits, empty states, and partial failures.
• Enforce idempotency on side-effecting workflows Use idempotency keys for create, send, modify, and delete actions that agents may retry. Test the full retry path so repeated execution does not create duplicates or unintended downstream changes.
• Gate agent actions by reversibility and blast radius Classify each delegated action as reversible or irreversible, then set confirmation, preview, or approval requirements based on the impact radius. Keep low-risk edits flowing, but stop before irreversible completion steps.
• Expose scope and schema to machine consumers Publish complete OpenAPI or GraphQL specifications, normalise field naming, and make state transitions explicit so agents do not have to infer meaning from prose or historical convention.

Key takeaways

• AI agents need machine-readable interfaces because human-oriented product design leaves them guessing at state, scope, and failure.
• Idempotency, explicit schemas, and reversible actions are governance controls when agents are the ones consuming your product.
• Teams that expose only UI workflows or vague error handling are creating AX debt that will surface as access and audit risk.

Key terms

• Agent Experience: The design layer that makes software usable by AI agents instead of only by humans. It focuses on machine-readable structure, explicit state, predictable errors, and safe retry behavior so agents can act without guessing. In identity terms, it governs how delegated machine consumers interpret and execute access safely.
• Idempotency: A property of an operation that produces the same safe result when repeated. For agent workflows, it prevents retries from causing duplicate side effects when requests time out or fail midstream. This is a core control for machine identities because autonomous retries can otherwise multiply impact.
• Blast Radius: The scope of impact an action can create if it goes wrong. In agent-powered systems, blast radius helps decide whether an action can run freely, needs preview, or must stop for explicit approval. It is especially useful when a machine identity can act faster and more repeatedly than a human operator.
• API Parity: The degree to which everything available in a user interface is also available through a programmatic interface. For agent consumption, parity matters because UI-only controls are effectively hidden from machine identities. When parity is incomplete, organisations create unmanaged execution paths outside normal governance.

Deepen your knowledge

Agent experience and delegated execution are practical topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are designing for machine consumers or agent-driven workflows, it is a useful place to build the governance foundation.

This post draws on content published by WorkOS: Agent experience: How to design products that agents can actually use. Read the original.