Software Agents Can Actually Use

What the term actually means

Two definitions are circulating, and the useful thing is that they don't contradict each other. They describe a floor and a ceiling.

The floor comes from Builder.io: agent-native software is built so humans and AI agents operate the same product through shared actions, data, permissions, and context. The discipline is a single action model. You define an action once, archive an email, create a dashboard, schedule a meeting, and from that one definition the UI can call it, the agent can see it as a tool, an API client can hit it, and another agent can route to it. The agent is part of how the app is built. It is not glued on afterward.

The ceiling comes from Dan Shipper's guide at Every, written with Claude, where the agent isn't just a first-class operator but the core of the thing. Features stop being code you write and become prompts that name an outcome, which an agent achieves by looping over atomic tools until it's done. His phrase for this is "Claude Code in a trenchcoat," and it's the right image. Five principles hold it up: parity (the agent can do anything the user can), granularity (tools are primitives, features are prompts), composability (new features are new prompts), emergent capability (the agent handles requests you never designed for), and improvement over time (you ship better prompts, not just more code).

I find the floor version is what most teams should actually build, and the ceiling version is what they should borrow from. The ceiling trades away determinism, latency, and predictable cost for malleability, and that's a real trade, not a free lunch. But its principles, especially parity and atomic tools, are how you get the floor right in the first place.

So here's the definition I'd write on the whiteboard: agent-native software exposes every outcome a human user can reach as a contract an agent can discover, call, and compose, with permission and audit enforced at the action layer rather than the interface. Two clauses, and you need both. The first clause without the second is a security incident waiting to be scheduled. The second without the first is just tidy API design.

A reference architecture

Strip away the diagrams and agent-native architecture is one commitment enforced everywhere: there is exactly one definition of each action, and everybody, the human, the agent, the API client, goes through it. Here is how the layers stack.

Operator surfaces        Web/mobile UI · embedded agent · CLI · external agents (Claude,
(interchangeable)        Codex, OpenClaw) · other services
        │
        │  HTTP · MCP (tools/resources/prompts) · A2A (for agent-to-agent)
        ▼
Action / capability      One definition per action: name, schema, description, risk tier,
layer                    idempotency key, dry-run mode, typed errors, pagination
        │
        ▼
Policy plane             Delegated identity (user X via agent Y) · least-privilege scopes
                         per session · risk-tiered approval gates · rate limits · egress
                         allowlists
        │
        ▼
Domain services          Business logic · database (volume, queries) · shared workspace
+ state                  (files a human can open) · agent session state (checkpoints)
        │
        ▼
Execution +              Durable long-running work (submit → poll → resume) · retries with
observability            idempotency · one trace per session · immutable audit log · evals

The parts that people skip, and then regret skipping:

The policy plane sits below the surfaces and above the services. If you attach permissions to UI routes, the agent can't see them and doesn't obey them. Attach them to actions and every caller is governed identically. And the agent authenticates as this user, delegated to this agent, never as a god-mode service account. That one decision is the difference between a scoped blast radius and an unscoped one.

Approvals are a real object, not a modal. An approval is a persisted, resumable state of a task, pending, then approved or denied, then executed, and it can show up in whatever client the human happens to be in. The current MCP spec gives this a protocol shape through elicitation and the Tasks extension.

The workspace is shared. Agent and human read and write the same artifacts. Shipper's guide makes the case that files are the most battle-tested agent interface there is, since models trained on bash already know cat, grep, and mv, and a human can open a folder and understand it. Keep the database for volume and indexed queries. Keep files for anything a person should be able to inspect.

The craft nobody warns you about: tool contracts

This is where agent-native projects live or die, and it's the best-documented corner of the field because Anthropic wrote an entire engineering piece on it. The mental model that unlocks everything: a tool is a contract between a deterministic system and a non-deterministic caller. The agent might hallucinate an argument, misread the purpose, or call the thing at the wrong moment. Your tool has to survive that.

A few rules earn their keep every time.

Names carry weight. Namespace them by service and resource, invoices_list, customers_search, so an agent picking among forty tools picks the right one. Vague names measurably degrade selection.

Descriptions are prompts, not documentation. They get loaded straight into the model's context, which means every word steers behavior. Write them the way you'd brief a new hire on their first day: spell out the query format, define the niche term, say when to use the tool and, just as important, when not to. I've watched a one-sentence description change flip an agent from reliable to useless and back.

Schemas should be strict and unambiguous. Not user, but user_id. Not date, but start_date: ISO YYYY-MM-DD, required. Declare an output schema too, so results come back typed.

Budget your tokens like they're money, because they are. Every tool result competes with the actual task for context. Paginate, filter, and truncate by default; Claude Code caps tool responses at 25,000 tokens. When you truncate, tell the agent what you dropped and how to get more. A single unpaginated list endpoint can quietly become your biggest line item.

Errors are steering text. "date must be YYYY-MM-DD, you sent 6/14/2026" turns a failed call into a self-correcting retry. An opaque stack trace burns an iteration and teaches the model nothing.

The meta-lesson underneath all of these: build the tool, write five realistic test tasks, run the agent, then read the transcripts. You'll learn more from one bad transcript than from an afternoon of speculation. The larger the effect of a change, the smaller the sample you need to see it. Most tool quality comes from this loop, not from getting it right on paper.

The interface stack, and when to reach for each

There's a small zoo of standards now, and the confusion is understandable because they answer different questions. Here's the map I use.

One thing you should know if you're touching MCP this quarter: the stable spec is 2025-11-25, but the 2026-07-28 revision publishes on July 28 and its own maintainers call it the largest change since launch. The protocol goes stateless, the session handshake and session header disappear, capabilities move into per-request metadata, and MCP servers become formal OAuth 2.1 resource servers with mandatory discovery. If you run remote MCP servers behind a load balancer, the removal of session affinity is your migration, and it's worth reading the changelog now rather than in August.

Security, or how not to build an exfiltration machine

Here is the uncomfortable part. The entire premise of agent-native software, a capable machine operator with broad reach, is also a beautiful attack surface, and you cannot prompt your way out of it.

Simon Willison named the core problem the lethal trifecta: give an agent access to private data, exposure to untrusted content, and a way to send data out, all in the same session, and it is reliably exploitable by indirect prompt injection. No jailbreak required. The attack just needs the model to follow instructions, which is the one thing it's guaranteed to do. This isn't theoretical. GitHub's MCP server leaked private-repo data through a prompt-injected public issue. The Supabase Cursor setup paired broad database access with untrusted support tickets. Writer.com exfiltrated document contents through an invisible image URL. Moltbook, the agent social network, shipped with automatic instruction execution that its own docs now flag as a prompt-injection risk.

The defense is architectural, and I want to be blunt about this because engineers keep looking for the sanitization function that doesn't exist. You break the trifecta by design, per session. An agent reading untrusted inbound email gets no egress. An agent with egress touches only data cleared for that destination. You enforce it with network-level egress allowlists, not with a polite instruction in the system prompt.

Everything else is the boring, load-bearing hygiene:

Delegated, short-lived, task-scoped identity, never a shared credential. Least privilege attached to actions, read-only by default. Approvals gated by stakes and reversibility, so the reversible and cheap auto-applies and the irreversible or expensive (payments, deletions, external sends) waits for a human. Idempotency keys on every mutation, because agents retry. Deterministic guardrails, spending caps, recipient allowlists, in code where no prompt can waive them. An immutable audit log that records the model version, because a model upgrade is a breaking change with no changelog entry, and one day you'll need to prove which version did what.

What good engineers still get wrong

I'll be honest about the ones that surprised me, because they're the ones that trip up people who are otherwise excellent.

Your defensive-programming instincts partially invert. Strict enums and validation at every layer, virtues everywhere else, strangle the exact composability that justifies this architecture. The skill is separating constraints that protect data integrity, which you keep, from constraints on judgment, which belong in the prompt.

English becomes load-bearing. Tool names, descriptions, and error strings are executable in the way that matters. They need review, version control, and regression tests, and a one-word change can swing your eval numbers.

Determinism is gone, and unit tests go with it. The same input produces different tool sequences on different runs. You test with eval pass rates over many trials and transcript review, and if you skip building that, a model-version bump will regress you and you won't be able to measure it.

Silent success reads as failure. An agent that does the right thing invisibly still loses the user's trust. Stream the thinking, show the current tool, reflect changes immediately. Visibility is a feature, not polish.

And the roadmap inverts. You stop guessing which features to build and start watching what people ask the agent to do. The requests that succeed are features you never had to design. The requests that fail are your parity gaps, pointing at exactly what to build next. Teams that keep planning spec-first throw away the strongest signal the architecture hands them.

The test that settles it

Shipper's guide ends with a test I keep coming back to, and I'll borrow it because nothing I've written beats it. Describe an outcome to your agent that lives inside your product's domain but that you never built a feature for. "Figure out which customers always pay within three days of a reminder and stop double-sending them." If the agent can compose its tools and its judgment and just do it, looping until it's done, you built something agent-native. If it can't, your architecture is too constrained, and you have a punch list.

That's the bar. Not whether you shipped a chat box. Whether an agent can accomplish what a person can, safely, through the same door.

Sources

• Dan Shipper and Claude, Agent-native Architectures, Every, Jan 2026 (updated Apr 2026)
• Builder.io, Agent-Native: The Next Architecture for Software
• Anthropic, Writing effective tools for agents - with agents
• Anthropic, Effective context engineering for AI agents
• Model Context Protocol maintainers, The 2026-07-28 MCP Specification Release Candidate
• Simon Willison, The lethal trifecta / Supabase MCP
• Oso, Understanding the Lethal Trifecta of AI Agents (incident survey)
• Linux Foundation, A2A Protocol surpasses 150 organizations, Apr 2026
• OpenAI, Codex and Custom instructions with AGENTS.md
• Time via AOL, Moltbook Is a Social Network for AI Bots