The Dual Interface Era: Designing for Humans and Agents

When I was working on SEO for a product, I kept running into the same tension: you have to write for humans and for search engines at the same time. If you only optimize for algorithms, the content feels robotic; if you only write for people, no one ever discovers it. Modern SEO best practice is explicitly about finding that balance: people-first content wrapped in structured clarity so crawlers can understand it too.

If AI agents are going to be first-class actors in our products, we are about to face the same design problem again, this time not just for content, but for entire applications.

That is the core idea behind SIA: Semantic Interface for Agents. It is a semantic layer for dual human and AI agent consumption, so we can design products that both humans and agents can understand, operate, and trust.

Check out the project: https://github.com/Douglasymlai/sia.

From SEO to Semantic Interfaces

SEO is essentially a contract between your content and two audiences: humans with intent and algorithms that need structure. You express meaning through language, layout, and UX for humans; you express structure through tags, schema, and sitemaps for crawlers.

In the data and analytics world, semantic layers have emerged as the equivalent contract for AI agents and BI tools: a shared model of business concepts, metrics, and rules that both humans and AI can use to interpret data safely and consistently.

SIA extends this idea from data to applications:

Instead of just describing tables and metrics, we describe screens, entities, actions, workflows, and constraints.
Instead of just being queryable by SQL or natural language, the manifest is callable by AI agents and legible to humans: designers, PMs, operators, and auditors.

Agents become a new stakeholder in your product, and at the same time a new representative of your product to end-users and other agents.

The Vision Behind SIA

SIA's vision is simple to state but ambitious to realize:

Every production application should expose a semantic manifest that describes what it can do, how it behaves, and what is safe, understandable to both humans and agents.

Practically, that means:

A machine-readable manifest of the product: entities, components, actions, parameters, preconditions, postconditions, and policies.
A human-readable layer on top of the same source: documentation, diagrams, and narratives that PMs, designers, and ops can work with.
A reusable component semantics catalog, so common patterns like forms, approvals, orders, shipments, and payments do not need to be re-described from scratch for every screen.

You can think of SIA as aiming to be an OpenAPI for product semantics: not an API spec for HTTP endpoints, but an operations spec for the behaviors of your product.

Architecture Principles for a Semantic Interface

To make this vision real in production environments, SIA is guided by a set of architectural principles. These are also the why behind the five opportunity areas I see for this project.

1. Product semantics as a contract, not a sidecar

In analytics, semantic layers are shifting from passive dictionaries to active translators that encode business meaning as first-class, executable semantics.

SIA applies the same principle to applications:

Treat the semantic layer as a contract that defines the product's vocabulary: entities (Order, Cart, Ticket), actions (approve, cancel, ship), and invariants (only managers can approve > GBP 10,000, inventory cannot go negative).
Design the system so that both humans and agents are expected to rely on this contract, not on reverse-engineering the UI or source code.

Architecturally, the semantic layer sits alongside your API and UI layers, not as a thin annotation, but as the shared definition of what operating the product correctly means.

2. Dual-consumption by default: humans and agents

Most current work on semantic layers for agents or semantic UI protocols is agent-first and developer-oriented. In contrast, SIA is explicitly dual-consumption:

For agents, the manifest is a machine-readable map of the product: what tools (actions) exist, what inputs they need, when they are valid, what they affect, and what safety constraints apply.
For humans, the same manifest is rendered as clear documentation and design artifacts: flows, components, policies, and guardrails.

This is the SEO analogy applied to product semantics: people-first experience, structure-first semantics, so agents can reliably interpret and operate the system without compromising human understanding.

3. Derived from reality, not hand-authored fantasy

One of the big challenges with semantic layers in the data world is that they often become yet another hand-maintained, out-of-date model.

SIA is designed around automatic or assisted generation:

Introspect existing systems: design systems, component libraries, routing, and API schemas are treated as input signals to derive semantics.
Capture runtime behavior: logs, events, and traces can be turned into candidate workflows and constraints (this action always follows that action, these parameters correlate with failure modes).
Standardize reusable patterns: instead of bespoke semantics per screen, SIA pushes toward reusable component semantics like approval steps, checkout steps, or shipment legs that can be reused across products.

The architecture should make it easier to keep the semantic interface in sync with the actual system than to ignore it.

4. Safety and governance as first-class citizens

Enterprise semantic layers are increasingly framed as necessary for safe, explainable AI agents because they encode business rules, access controls, and consistent definitions instead of leaving everything to LLM inference.

SIA brings that mindset to application operations:

Each action in the manifest carries preconditions, authorization rules, and risk levels.
The manifest can express hard constraints (never refund to a different card), soft policies (ask for human review above threshold), and audit hooks (where to log, what to attach).
Agents are expected to plan and act within this envelope, rather than do whatever the model thinks looks similar to past examples.

This is not bolt-on moderation. It is safety baked into the semantic layer that both humans and agents respect.

5. Protocol-agnostic and composable

There are already emerging protocols and frameworks for agent interaction with UIs and tools, and new ones will keep appearing. In the data world, semantic layers typically expose APIs and query languages that a variety of tools can speak.

SIA is designed to be:

Protocol-agnostic: the manifest is independent of any particular agent framework or transport (MCP, A2UI-like JSON protocols, UI-level semantic annotations, and so on).
Composable: the same core semantics can be projected into different surfaces:
- a tool catalog for agent frameworks
- a semantic annotation layer for web or native UIs
- internal documentation and modeling tools for humans

In other words, SIA aims to be the source of truth for product semantics, not a competing runtime protocol.

How SIA Fits into Real-World Production Stacks

So how does this look in an actual production environment?

Imagine a typical modern SaaS platform stack:

Backend services and APIs
A web or native frontend using a component library or design system
Some data layer with its own semantic model for analytics
Increasingly, internal and external AI agents that automate workflows, triage tickets, or act on behalf of users

SIA weaves into this stack roughly as follows:

1. Semantic extraction and modeling

A build-time and or runtime process analyzes your routes, components, and APIs to produce an initial semantic graph: entities, actions, dependencies, and constraints.
Product teams refine this graph where needed: naming, higher-level flow semantics, and risk annotations.

2. Manifest generation and versioning

The semantic graph is compiled into a versioned manifest in JSON, YAML, graph form, or similar, and becomes part of your deployment artifact.
This manifest is stored along with your code and config, so every release has a corresponding semantic interface.

3. Consumption by humans and agents

Human-facing tools like docs portals, internal consoles, and design tools render this manifest into UX-appropriate formats.
Agent frameworks ingest the manifest to build toolsets, policies, and planning constraints, instead of relying purely on prompt-hacked screenshots or reverse-engineered DOM.

4. Feedback loop and evolution

As agents operate and humans interact, logs feed back into the semantic layer to refine workflows, detect new patterns, and improve the safety envelope, mirroring how semantic layers for data are now used to continuously improve AI decision-making.

The goal is that adding SIA to your product feels like adding OpenAPI: once you plug it in, everything else, agents, docs, governance, gets easier to build on top.

Real-World Usage Scenarios

To make this concrete, here are some examples of how SIA could be used across domains when platform providers add this semantic layer.

E-commerce platforms: AI store managers and merchandisers

Imagine a multi-tenant e-commerce platform:

The platform exposes an SIA manifest that describes concepts like Product, Category, Inventory, Promotion, Order, and actions like createProduct, adjustPrice, launchCampaign, fulfillOrder, each with clear parameters, preconditions, and side-effects.
A merchant's AI store manager can safely:
- Create and update products within brand and compliance constraints
- Run price experiments within configured guardrails
- Launch marketing campaigns only targeting allowed segments
- Manage returns and refunds subject to policy encoded in the manifest

For the platform, SIA means:

They do not have to ship a bespoke SDK for every agent vendor. The manifest is the canonical contract any customer AI employee can plug into.
The platform owner, which might itself become an AI agent in some scenarios, can operate fleets of stores via the same semantics, without hard-coding each workflow.

Supply chain and logistics: autonomous coordinators

In a supply chain SaaS:

The SIA manifest encodes entities like Shipment, Warehouse, Route, Carrier, and actions like schedulePickup, rerouteShipment, splitOrder, allocateInventory, with built-in constraints like capacity, cut-off times, and regulatory rules.
A customer's AI logistics coordinator can:
- Simulate and schedule multi-leg shipments
- Proactively reroute around disruptions within allowed carrier and SLA rules
- Coordinate allocations between warehouses without violating reserve policies

Because the constraints are defined in the semantic layer, agents from different companies, a retailer's agent, a 3PL's agent, a carrier's agent, can interoperate through the platform without learning each other's private codebases.

B2B SaaS and back-office systems: AI executives

Consider a finance or back-office SaaS used by small businesses:

The SIA manifest exposes flows like closeBooks, approveExpense, generateInvoice, forecastCashflow, each with roles, thresholds, and sign-off requirements.
A small business whose CFO is an AI agent can:
- Operate the system directly via the semantics, without brittle UI scripting
- Demonstrate compliance, because every action the agent takes is defined and constrained in the manifest
- Integrate multiple tools like accounting, payroll, and invoicing via their respective semantic interfaces, composing higher-level workflows safely

Here, the company owner might itself be an agent, and the semantic interface is literally how that owner operates its own stack.

Prior Work and What Inspired SIA

Recent research and products have shown that semantic layers are becoming the backbone of enterprise-grade AI agents, particularly in analytics, where they bridge business language, technical metadata, and governance for safe autonomous decision-making. Work on semantic component interfaces and agent-oriented UI protocols is starting to do something similar at the UI level.

SIA is inspired by all of that, but also by something much more mundane: doing SEO. Balancing human experience and algorithmic clarity for content made me realize we need the same dual-audience mindset for products themselves. If agents are going to be our colleagues, customers, and even company owners, they deserve a first-class interface to our products, not a series of scraped heuristics. And if they are going to represent our products to the world, we need that interface to encode not just what is possible, but what is right.

The Dual Interface Era: Designing for Humans and Agents