How to Build an Agent App: Turn Your API Into an Agent-Native Tool

What "build an agent app" means

An agent app is not a new API. It's an adapter layer that makes an existing API agent-native: discoverable at runtime, typed (JSON in, JSON out), permission-scoped, and callable without a browser or bespoke glue code. Concretely, on Pilot Protocol an installed app is:

• Local. A small binary runs on the agent's own daemon; your actual backend — the database, the model, the service you already run — stays exactly where it is. The installed binary is a thin, stateless adapter that talks to it.
• Typed. Every method is a JSON request and response, not an HTML page or a bespoke SDK call.
• Signature-verified. The manifest pins the binary's hash and carries a signature; the daemon re-checks both every time it spawns the app.
• Grant-scoped. The manifest declares exactly what the app may touch — network, filesystem — and the operator accepts those grants at install time, not before.
• Runtime-discoverable. Every app exposes a <app>.help method that returns its own methods, parameters, and expected latency, so an agent learns the interface by calling it, not by reading your docs.

That last point is the difference that matters for adoption. A REST API with great docs still requires a human to read those docs and write the integration. An agent app answers "what can you do?" as a structured API call, so an agent can onboard itself.

Why this beats a bare API or an MCP server

If you already expose an MCP server, that's a real integration path — MCP gives one agent a standard way to reach your tool over a connection it manages itself. What it doesn't give you is distribution: every agent that wants to use your tool still has to know it exists, configure a connection to it, and manage that connection's lifecycle itself.

The app store is a distributed catalogue layered on top of that problem, running over the same overlay network that gives every agent its persistent address and trust model. Publish once, and any agent on the overlay can find your app in the catalogue, install it with one command, and start calling it — with the daemon handling verification, permission grants, and process supervision so neither you nor the agent's operator has to. These are complementary models, not competing ones: plenty of teams run an MCP server for direct integrations and also publish an agent app for overlay-wide discovery.

Compared to a bare REST API, the difference is what the agent has to do before the first successful call. Against a raw API, an agent (or its operator) needs the base URL, an API key, the request/response shapes, and error-handling conventions — usually assembled by a human reading docs. Against an installed agent app, the agent runs <app>.help and gets that shape back as data.

The loop every agent app supports: discover → install → call

Whatever your API does, once it's published as an agent app it fits the same three-step loop every other app on the store follows.

1. Discover

An agent (or its operator) browses the catalogue and inspects your app before installing it — description, vendor, the methods it exposes, and its declared permissions.

# See what's installable
pilotctl appstore catalogue

# Inspect one app before installing it
pilotctl appstore view io.pilot.yourapp

2. Install

One command. The daemon fetches the bundle, verifies its signature and hash against the manifest, requests the permissions it declares, and auto-spawns it — no manual start step, no separate service to babysit.

pilotctl appstore install io.pilot.yourapp
pilotctl appstore list   # confirm it's ready and see its methods

3. Call

The agent calls <app>.help to learn your methods and their parameters at runtime, then calls the method it needs.

# Learn the interface
pilotctl appstore call io.pilot.yourapp yourapp.help '{}'

# Call a method — JSON in, JSON out
pilotctl appstore call io.pilot.yourapp yourapp.search '{"q":"example"}'

That's the whole lifecycle from the agent's side. No SDK to import for your specific API, no key to provision by hand, no endpoint to memorize.

What you actually bring to the table

You don't rewrite your API and you don't hand over your source code. You describe your existing app or API's methods — what each one takes, what it returns, how auth is structured — through the publish flow, and Pilot generates and signs an agent-first adapter from that description. Your secrets stay yours: operators supply their own credentials at install time, not you at publish time.

Concretely, before you start the publish flow it helps to have on hand:

• A method list. Each endpoint you want exposed, with its inputs and outputs described plainly — this becomes the typed methods an agent calls.
• Auth shape. Whether calls need an API key, a header token, or nothing at all, and where that credential is supplied.
• A sense of latency. Which methods are fast lookups versus slower, multi-step operations — this feeds the <app>.help latency class an agent uses to pick the cheapest method that fits its task.
• A valid email. The publish flow verifies it with a one-time code before you can submit, and uses it to keep you posted on review status.

From there, the shape is: describe your app → verify your email → Pilot builds and signs the adapter → the team reviews it → it's live in the app store, one command away from every agent on the network.

Designing methods agents actually call well

A published app is only as useful as its methods are easy to call correctly on the first try. A few things that make a real difference:

• Name methods by intent, not by internal route. search, answer, lookup read clearly at runtime; an internal endpoint name your team uses internally usually doesn't.
• Group by latency honestly. If one method is a cheap cache read and another kicks off a multi-step job, say so — an agent choosing between methods via <app>.help should be able to pick the cheapest one that answers its actual question, the same way a developer would pick a lighter call over a heavier one.
• Keep parameters flat and typed. Every value passed through call arrives as JSON; simple, well-named fields are easier for an agent to construct correctly than deeply nested structures.
• Return structured errors, not prose. An agent that gets a clear error code back can decide whether to retry, adjust its call, or give up — much more useful than a string it has to parse.

These aren't arbitrary style preferences. They're the same considerations that make an app's <app>.help output actually useful as a runtime contract instead of just a list of names.

Why publish at all

The store grows by builders adding to it. Every app you publish is one more capability the agents already on the network — 243k+ of them — can pick up with a single install command, without you having to market it, write framework-specific SDKs, or answer integration questions one developer at a time. If your API is genuinely useful to autonomous agents, publishing it once reaches all of them; keeping it as a bare REST endpoint means each agent's operator has to do the integration work themselves, every time.