AI-agent-first primitives: designing for agents from day one

There is a difference between a product that supports AI agents and a product designed for AI agents. The difference is structural: it shows up in the data model, in the auth system, in the audit log, in the API surface. By the time you can see it in the UI, the decision has already been made — for or against — five layers down.

This piece is about those five layers. The five primitives that, if you build them in from day one, make every subsequent agentic feature cheap. And if you don't, every agentic feature you ship is fighting against the substrate.

The list:

1. Agent identity — every agent is a first-class user.
2. Principal attribution — every write records who (agent or human) and what kind.
3. Scoped, composable permissions — agents have less authority than their owners by default.
4. Consent gates — irreversible operations require a human-in-the-loop handshake.
5. Shape caps on writes — agents can't fill the disk by accident.

You can read this as a checklist for new products, or as a diagnostic for existing ones. If you're staring at an AI feature roadmap and wondering why each item costs three months, the answer is usually that one or more of these five is missing.

Primitive 1: Agent identity

The first decision is whether an agent is a separate entity in your system, or a process running inside a human user.

The lazy default is the latter: agent runs as user, agent uses user's credentials, agent's actions are recorded as the user's actions. Every product I've seen that started here regrets it. Within six months they ship a "service account" or a "bot user" feature and migrate. Within a year they ship "agent" as a distinct type. Within eighteen months they unify it with workspace membership.

You skip the migration if you start at the destination. The schema is straightforward:

User
  id
  email
  ...
  agent_owner_id   -- if non-null, this user is an agent owned by another user
  agent_kind       -- "human" | "agent"

The agent is a row in users. It has its own ID, its own credentials, its own audit trail. It has an agent_owner_id pointing at a human user, which gives you the accountability link. It has an agent_kind flag so you can distinguish humans from agents in queries that need to.

Once this is in place, "agent does X" can be recorded the same way "human does X" is recorded — same schema, same audit log, same auth flow. The only thing the agent needs that a human doesn't is the owner link, which exists for accountability and inheritance.

We covered the architectural shape in Why agents need their own identities. The point for this piece is that this is the foundational primitive. If your agent is a process inside a user, every other primitive on this list either doesn't fit your model or has to be retrofitted.

Primitive 2: Principal attribution

If agent identity says "agents are users," principal attribution says "every write knows who wrote it."

Most product schemas have a created_by column on important tables (workspaces, docs, rows, comments). What they often don't have is what kind of principal did the writing. Was that comment posted by a human via the UI? By an agent via the API? By a webhook on the user's behalf? In a chat-assistant world, it didn't matter — every write was effectively a human's. In an agent-first world, it matters constantly.

The schema change is small:

Comment
  id
  body
  ...
  created_by_principal_id
  created_by_principal_type   -- "user" | "agent" | "system"

Two columns: the ID, and the type. You don't bind to User.id directly because over time you'll want to attribute things to entities that aren't users (system jobs, third-party integrations, dead users whose attribution you want to preserve). You always store the pair.

The discipline is that every write records this pair. Every doc edit, every row insert, every comment, every API call that produces a side effect. The audit log becomes a faithful record of who-did-what, where "who" is a typed reference, not just an ID.

This costs you nothing if you build it in from day one. It costs you weeks of migrations and stale-data cleanup if you bolt it on later. We've shipped principal attribution across every write surface in our product (the principle is documented internally as reference_principal_attribution.md), and it pays back the moment you have to answer "did the agent do this or did the user?" — which, in an agent-first product, is every other support ticket.

Primitive 3: Scoped, composable permissions

Agents need less authority than their owners, by default. Always.

The temptation when shipping the first agent is to give it whatever the owner has. The owner is logged in, the owner has full read/write on their workspaces, the owner has access to billing — so the agent gets all of it. This is the path of least resistance and it's the wrong default.

The right default is: an agent has zero permissions outside the specific workspace it was attached to. To give it more, the owner has to explicitly extend its scope. This is asymmetric to the human case (humans have access to all their own workspaces by default) for a reason: humans have an embodied sense of what they're doing, and agents don't.

The mechanics, concretely:

• An agent is created in the context of an owner and an org.
• Without explicit grants, the agent has access to zero workspaces in the org.
• The owner grants access per workspace, with a role (viewer / editor).
• The agent inherits the owner's identity for accountability but never inherits the owner's permissions.

We documented the inheritance rule (a soft form of inheritance for reads in some cases, for ergonomics) in Signed-agent inheritance. The hard rule for writes is: explicit grants only.

This sounds restrictive. It is. The trade-off is that when an agent does something unexpected, the blast radius is bounded. The agent can't accidentally write to a workspace it shouldn't have access to, because it never had access. You can't lose data you can't reach.

The composability piece matters too. Permissions should be expressible as workspace-scoped roles, not as global flags on the agent. An agent that's an editor in workspace A and a viewer in workspace B should be the natural representation, not the exception. This means workspace membership is your permission model, and you grant agents into workspaces the same way you grant humans into workspaces.

Primitive 4: Consent gates for irreversible operations

Some operations should never run without human confirmation, no matter how confident the agent is. The pattern for handling this is the consent gate — a two-call handshake that turns a single dangerous call into propose-confirm-execute.

The shape:

1. Agent calls upgrade_plan(org=acme, plan=scale).
2. The handler doesn't execute. It returns { confirm_token: "tok_abc...", summary: "Upgrade Acme to Scale plan ($49/mo, charged immediately)" }.
3. The agent surfaces the summary to its human owner.
4. The human approves.
5. The agent calls upgrade_plan(org=acme, plan=scale, confirm_token="tok_abc...").
6. The handler validates the token (single-use, time-bound, bound to the exact org and operation), and executes.

The token is the protection. It's bound to the operation and parameters that were proposed. If the agent tries to use the same token for a different operation, it fails. If it tries to use a stale token, it fails. If it tries to skip the proposal step, the executing call has no token and fails.

The discipline question is which operations need a consent gate. The rule of thumb is: any operation that moves money, widens access, or can't be undone with a click. So:

• Plan upgrade / downgrade: yes.
• Adding an OrgMember with admin role: yes.
• Deleting a workspace: yes.
• Sending an email to the customer's email list: yes.
• Adding a row to a workspace: no (reversible).
• Reading a doc: no (no side effect).

The list grows as you add features. The discipline is that adding a feature in the dangerous category requires adding a consent gate as part of the feature, not later. We covered the mechanics in Consent gates for dangerous operations and the broader contract in the dangerous-ops docs.

The cost of building this in from day one is moderate. The cost of not building it in is your first six-figure mistake — an agent that, in a loop, did something it shouldn't have, and there was no gate.

Primitive 5: Shape caps on writes

The fifth primitive is the least sexy and the most important once you've shipped to a few thousand customers.

Agents can write a lot. They can write fast. They can, in a loop, write garbage fast — a doc that's 50 megabytes of nested JSON, a table with a million rows, a comment thread that recurses on itself. None of this is malicious; it's a side effect of the agent finding a path through your prompt where "write more" was the locally optimal move.

The protection is shape caps — hard limits on the size and structure of any write, enforced at the substrate, applied uniformly to humans and agents. The caps are dimensions like:

• Bytes: documents over N MB are rejected.
• Depth: nested structures over N levels are rejected.
• Node count: documents with more than N nodes are rejected.
• Row count: tables over N rows are rejected (or paginated).

These caps live below the API. They run inside the function that writes to the database, so they apply regardless of which surface called the write — REST, MCP, the live collaboration channel. Every write goes through the same gate.

The trick is choosing limits that real prose / real tables never trip. Real documents are well under 1 MB; real tables are well under tens of thousands of rows for the kinds of work humans do collaboratively. Setting limits at 10x typical usage gives you a safety net that real users never feel and that agents-in-a-loop hit immediately.

We documented our cap implementation in Shape caps on TipTap JSON. The pattern generalizes: every write surface gets a substrate-level cap, the cap is the same for humans and agents, real users don't notice, agents-in-a-loop fail safely.

How the five fit together

These five primitives compose. None of them is sufficient alone, and most of them require at least one of the others to work.

• Identity + attribution = a real audit log. You can answer "what did Argus do this week?" because Argus is a stable identity and every write records its principal.
• Identity + permissions = bounded blast radius. Argus has its own identity and its scope is less than its owner's, so a compromised Argus can't take down everything.
• Permissions + consent gates = safe authority. Argus has scoped access and the most dangerous operations require human confirmation, so the things Argus can do unilaterally are bounded.
• Consent gates + shape caps = safe failure. Even if Argus does something wrong, it can't move money without a token and it can't fill the disk on the way down.

Skip one and you create a class of bug that the other four can't catch. Skip identity and your audit log doesn't know who wrote what. Skip attribution and you can't isolate agent activity. Skip permissions and a single compromised agent can do everything its owner can. Skip consent gates and a buggy agent can charge customer cards in a loop. Skip shape caps and a buggy agent can fill your database.

The economic argument for building all five in from day one is that they pay back at every layer above. Every API endpoint you ship becomes a constrained API endpoint — one where you don't have to retrofit attribution, where you don't have to re-think who can call it, where you can apply a shape cap with one line. The features become cheap because the substrate carries the weight.

What to do if you skipped them

If you're reading this with a product that's already shipped and didn't build any of the five in, here's the order to add them:

1. Identity first. Add agent_kind and agent_owner_id to your user table. Backfill existing API-key users to agent_kind = "agent" with the appropriate owners. This unblocks everything else.
2. Attribution second. Add principal_id and principal_type to your write tables. Backfill from existing created_by columns. Update every write path to set both.
3. Permissions third. Move from "agent has owner's permissions" to "agent has explicit per-workspace grants." This is the painful one. Communicate aggressively with customers; offer a one-click "grant agent the same scope" migration path that customers can opt into.
4. Consent gates fourth. Wrap your dangerous operations. Start with the obvious ones (billing, member changes) and grow the list as you add features. Every new dangerous operation joins the list.
5. Shape caps last. Add hard limits to every write. Real users won't notice. Agents will start failing safely instead of unsafely.

The order matters because each step builds on the previous. You can't do attribution cleanly without identity. You can't do permissions cleanly without attribution. And so on. Doing them out of order means doing them twice.

The thesis, restated

A product designed for AI agents is one where these five primitives are baked into the substrate. A product that supports AI agents is one where some subset has been bolted on.

The difference is invisible from the outside until something goes wrong — a misattributed action, an over-scoped API key, an agent that runs away in a loop. Then the difference becomes the entire conversation.

The teams that build all five from day one don't have to have those conversations. The teams that retrofit will, eventually, have to do every one of these migrations. The work is the same; the only choice is whether to do it before you have customers or after.

If you're starting a product in 2026 that has any agentic component, build the five. If you're auditing one, audit for the five. If you're vendoring infrastructure, ask whether the vendor has the five, or whether you're going to be the one to add them.

Pillars and clusters in this series:

• The umbrella: Agent collaboration: a primer for 2026
• The positioning case: Why teams need an AI workspace, not an AI assistant
• Identity deep-dive: Why agents need their own identities
• Authorization deep-dive: Consent gates for dangerous operations
• Shape caps deep-dive: Shape caps on TipTap JSON

FAQ

What does it mean to design a product "AI-agent-first"?

It means treating AI agents as first-class entities at the substrate level — they are users in your user table, they have scoped permissions in your auth system, their actions are attributed in your audit log, dangerous operations are gated by consent flows, and writes are bounded by shape caps. These are not features layered on top; they are properties of the data and auth model.

What's the difference between agent-first and adding agent support to an existing product?

Agent-first products have identity, attribution, permissions, consent gates, and shape caps in the substrate. Products that bolt on agent support typically have one or two of these and missing the rest. The bolted-on version works for one agent; the agent-first version scales to many agents per workspace, multi-agent coordination, and audit-grade accountability.

Do I need all five primitives or just some?

You can ship with a subset, but each missing primitive creates a class of failure the others can't catch. Identity without attribution gives you actors but no record. Permissions without consent gates lets a buggy agent take destructive actions. The five compose, and the value is highest when all five are present.

How do consent gates fit into agent autonomy — don't they slow agents down?

Consent gates only fire on a small set of operations: ones that move money, widen access, or can't be undone. The vast majority of agent actions (reading docs, drafting content, adding rows, leaving comments) flow through with no gate. Consent gates are about catching the small set of operations where the cost of a mistake is high, not throttling the agent generally.

What's the migration path if my product has shipped without these primitives?

Start with identity (add agent_kind to your user table), then attribution (add principal type+id to writes), then per-workspace permissions, then consent gates on existing dangerous operations, then shape caps. The order matters because each step depends on the previous. Communicate the changes with customers, especially the permission change, which often requires explicit re-grants.

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "AI-agent-first primitives: designing for agents from day one",
  "description": "Five primitives that distinguish a product designed for AI agents from a product that bolted them on. Get them right at the substrate and every feature gets cheaper.",
  "datePublished": "2026-04-25",
  "author": {
    "@type": "Person",
    "name": "Govind"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Dock",
    "url": "https://trydock.ai"
  },
  "image": "https://trydock.ai/blog-mockups/style-d-dreamscape/ai-agent-first-primitives.webp",
  "mainEntityOfPage": "https://trydock.ai/blog/ai-agent-first-primitives"
}