Agent API

Meeting.book: one run, metered once

Hollow: the run's private work. Filled: what the Customer sees. The point marks the move that pays you.

An Agent API sells a worker, not an answer. It runs for each Customer in their own space, with their inbox and CRM as tools, on a schedule or when hired. Each run is an Action that carries what it consumed.

definition.ts

28 lines

import { define, agentic } from 'apis.dev'

/** An agent that books three meetings a week with each Customer's leads, in their own inbox and CRM. */
export default define({
  name: 'meetings', domain: 'meetings.apis.dev',
  sources: {
    inbox: { system: 'email', scope: 'customer' },                       // each Customer's own
    crm:   { system: 'crm',   scope: 'customer' },
    firms: { api: 'summaries.apis.dev', cost: { 'Company.research': 0.5 } },  // another product
  },
  Meeting: {
    with: 'string', company: 'string', at: 'date',
    book: agentic('Book a meeting with the next lead in {crm}', {
      tools: ['inbox', 'crm', 'Meeting.create', 'firms.Company.research'],  // each call passes the gate
      memory: 'customer',                                                // what it learns stays theirs
      returns: { meeting: 'string' },
    }),
  },
  on: { 'every Mon, Wed, Fri 09:00': 'Meeting.book' },                   // in each Customer's timezone
  offer: {
    'Meeting.book': { per1000Tokens: 0.01, perMinute: 0.05,
                      perTool: { 'firms.Company.research': 0.6 }, maxPerRun: 2 },
    'Meeting.get': 0, 'Meeting.list': 0,
  },
  operate: {
    brakes: { 'Meeting.book': { day: 5, spend: { day: 2 } } },           // per Customer; past it, a person
  },
})

meetings is built on summaries: when a lead's company is unknown, the agent buys Company.research for $0.50 and bills it to the run at $0.60. Deploy prints that margin beside the token and minute rates.

Runs and what they consume

Family	What it does
The agent per Customer	One worker per Customer, in their Namespace: their records, their Sources, their memory. Nothing one Customer's agent learns reaches another's
Runs	Each run is one Action, started by a schedule in the Customer's timezone, an Event, or a hire. It is pinned to its Version until it ends
Tools	Your Verbs, the Customer's Sources and other products' Verbs, each called through the gate under the run's mandate. Credentials stay with the platform and never enter a prompt
Memory and skills	What the agent keeps between runs, per Customer, readable and erasable by that Customer; skills are instructions you ship with the Version
Consumption metering	Tokens, minutes and priced tool calls, each counted once by the Meter and written on the Action as `usage` and `cost`
Budgets and brakes	A ceiling per run, a brake per Customer per day, the Customer's own `Max-Cost` and spend ceiling, and the mandate when the hirer is an agent
Handoffs and leases	A run holds its work under a lease; a run that stalls releases it, and a person or a fresh run takes it over with its context
Proof	A trace per run, the agent card, and success and latency judged from outside on the offer card

Thing	States	What moves it
A run	`pending` with its reason (`Running`, `AwaitingSource`, `AwaitingApproval` when braked), then `done`, `failed` or `cancelled`	Its work, a brake, a cancel, or its ceiling: a run that reaches it ends with what it finished
A tool call	`decided`, then `done` or `refused`; a priced one is `reserved`, then `captured`	The gate, as for any call; a refused tool call returns its cure to the agent, not to the Customer
A brake	`armed`, `tripped`, `held`, then `released` or `reset`	A call that would pass the cap; the person the mandate names; the next day
A lease	`held`, `renewed`, then `released` or `lapsed`	The run's progress renews it; a run that stalls lets it lapse, and its work returns to the queue
A memory entry	`written`, `corrected`, `erased`	The run writes it; the Customer corrects or erases it through the API

Tools and the Customer's space

A tool is a Verb. When the agent reads the Customer's CRM, sends from their inbox or buys research, the call passes the same gate as a call from outside.

The run carries a sub-mandate of the Customer's own, narrowed to the file's tools and the run's budget. The agent can do nothing its Customer could not.

A tool call to another product is a purchase. meetings pays summaries $0.50 under its own mandate, and the run shows one tool call at $0.60. A send from the inbox is a durable intent, sent once, so a retried run never books the same lead twice.

Budgets and brakes

Five limits hold a run, checked before each step in the gate's order: decide, then price, then guard. The first that fails answers, and nothing past it is spent.

The Customer's mandate, when an agent hired the worker: its budget, sellers and Verbs, from the buy side.
The plan's limits, the Entitlement the hire runs under.
The call's Max-Cost on the hire, or the Customer's spend ceiling on the Key.
Your ceiling, maxPerRun, printed on the offer card: no run of Meeting.book bills more than $2.
The brake and the rate limit, per Customer: five runs or $2 of spend a day, then a person.

A brake holds the run instead of failing it. The Action waits AwaitingApproval with what it has spent so far, and the approval resumes it once.

GET /actions/act_32, while it waits

HTTP/1.1 200 OK
X-Cost: price=0, currency="USD"
X-Request-Id: req_8d0f2b61a4c97e3510ab

{
  "id": "act_32",
  "verb": "Meeting.book",
  "status": "pending",
  "reason": "AwaitingApproval",
  "brake": "Meeting.book · spend 2 a day",
  "approval": "https://meetings.apis.dev/approvals/apr_4",
  "usage": { "tokens": 9100, "minutes": 3 },
  "cost": { "price": 0.241, "currency": "USD" }
}

A run is billed for what it consumed, up to the moment it ends. 9,100 tokens at $0.01 per 1,000 and 3 minutes at $0.05 make the $0.241 above. A declined approval or a cancel ends the run at that figure, and a run that fails bills nothing.

Contracts and the platform's part

You declare	The platform does
An agentic Verb, its prompt and its `tools`	Runs one agent per Customer in their space, with each tool behind the gate and its credentials held by the platform
`memory: 'customer'`	Keeps what the agent learns per Customer, and serves it to that Customer to read, correct and erase
A schedule or an Event in `on`	Starts one run per Customer, in that Customer's timezone, pinned to the Version it started on
Rates per 1,000 tokens, per minute and per tool call	Meters each unit once, writes `usage` and `cost` on the Action, and prints the margin over each tool's `cost`
`maxPerRun`	Reserves it before the run, stops the run at it, and prints it on the offer card
Brakes in `operate`	Checks them before each step, holds the run, asks the person the mandate names, and resumes on approval
Nothing else	Leases, handoffs, the trace of every step, the agent card, and the offer card's proof

Subsystem	What an Agent API takes from it
Definition and compile	Tools that resolve, a price for every unit, and the margin over each tool's `cost`
Identity, access and policy	The mandate chain: the Customer's mandate, the run's sub-mandate, and the approver a brake asks
Model and records	The Customer's records, memory as records, history and erasure
Data and Sources	Each Customer's inbox and CRM as Integrations, and other products as Sources
Runtime	Runs as Actions, schedules per timezone, the model router, effects sent once
Work	Leases, handoffs to a person, and the brake's approval; the family is Agents inside the product
Commerce	Consumption metering, the ceiling, the receipt per run, and payment to the products it buys from
Interfaces and distribution	The agent card, agent-to-agent tasks, and `usage` on every Interface's Action
Trust and operations	Brakes, evals, traces, and success and latency judged from outside

What Customers and their agents meet

The worst case first. The offer card prints each rate and the per-run ceiling, so a hire's most expensive run is known before it starts.
Every run, itemised. Each Action shows tokens, minutes, priced tool calls and the total, and each run has a signed receipt.
Limits on both sides. Their Max-Cost and spend ceiling stop a run at the cap. Your daily brake hands it to a person.
Their data stays theirs. The agent works in their space, and its memory is theirs to read, correct and erase.

An agent hires the worker with no UI:

It reads /.well-known/agents.json: the agent card, the rates, maxPerRun, and the proof.
It hires under a standing mandate from its person: three runs a week, $6 a week, meetings.apis.dev only.
It watches each run's Action, and reads usage and the receipt when it ends.
It approves or declines a braked run through its person, and revokes the mandate to stop the work.

Agent API: its five blocks
Nounthe shape you promise	Verbwhat can be done to it	Sourcewhere its data comes from	Triggerwhat reacts to a change	Offerthe price
your Customer's records, in their space	the job, done by an agent for them	your Customer's inbox and CRM	a schedule: three meetings a week	by consumption: tokens and minutes

Runs and what they consumeCopy Anchor Link

Tools and the Customer's spaceCopy Anchor Link

Budgets and brakesCopy Anchor Link

Contracts and the platform's partCopy Anchor Link

What Customers and their agents meetCopy Anchor Link

Runs and what they consume

Tools and the Customer's space

Budgets and brakes

Contracts and the platform's part

What Customers and their agents meet