---
title: "Agent API"
url: /patterns/agent-api
---

# Agent API

> Sell a worker who does the job, billed by consumption.

**One run of `Meeting.book`, metered once.**

- The schedule starts a run at 09:00 in the Customer's timezone, and the run reserves its $2 ceiling.
- The run thinks and acts, counting tokens and minutes, and every tool call passes the gate.
- A call that would pass the Customer's brake waits, braked, until a person approves it.
- When the job is done, the run is metered once: $0.484.

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](/workflow.md#the-lifecycle) that carries what it consumed.

```ts title="definition.ts"
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`](/patterns/function-api.md). For an unknown company, the agent buys `Company.research` at $0.50 and bills the run $0.60, a margin deploy prints.

## Runs and what they consume
| Family | What it does |
| --- | --- |
| The agent per Customer | One worker per Customer, in their [Namespace](/reference/platform.md#namespace): their records, their [Sources](/patterns/dataset-api.md#how-a-field-is-filled), 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](/reference/platform.md#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](/reference/platform.md#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: reading the CRM, sending from the inbox or buying research 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, made under the run's own mandate. 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. The first that fails answers, and nothing past it is spent.

1. **The Customer's mandate,** when an agent hired the worker: its budget, sellers and Verbs, from the [buy side](/commerce/buy-side.md).
2. **The plan's limits,** the [Entitlement](/reference/platform.md#entitlement) the hire runs under.
3. **The call's `Max-Cost`** on the hire, or the Customer's spend ceiling on the [Key](/reference/platform.md#key).
4. **Your ceiling, `maxPerRun`,** printed on the offer card: no run of `Meeting.book` bills more than $2.
5. **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 its spend so far, and an approval resumes it once.

```http title="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
Everything above is in the file: the prompt and `tools`, `memory: 'customer'`, the `on` schedule, the rates per unit, `maxPerRun` and the brakes. Leases, handoffs, traces and the agent card need nothing declared.

An Agent API draws on every subsystem:

- **Definition and compile** checks that tools resolve and every unit has a price.
- **Identity, access and policy** gives the mandate chain and the approver a brake asks.
- **Model and records** keeps the Customer's records and the agent's memory, with history and erasure.
- **Data and Sources** connects each Customer's inbox and CRM as [Integrations](/patterns/headless-saas.md#integrations), and other products as Sources.
- **Runtime** runs each run as an Action, through the model router, with effects sent once.
- **Work** gives leases, handoffs to a person and the brake's approval, from [Agents inside the product](/work/agents.md).
- **Commerce** meters consumption, holds the ceiling, signs a receipt per run, and pays the products it buys from.
- **Interfaces and distribution** gives the agent card, agent-to-agent tasks, and `usage` on every [Interface](/every-product.md)'s Action.
- **Trust and operations** runs brakes, evals and traces, and judges success and latency from outside.

## What Customers and their agents meet
A person sees every run itemised: tokens, minutes, priced tool calls and the total, with a signed receipt.

An agent hires the worker with no UI:

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

| Pattern | Noun: the shape you promise | Verb: what can be done to it | Source: where its data comes from | Trigger: what reacts to a change | Offer: the price |
| --- | --- | --- | --- | --- | --- |
| [Agent API](/patterns/agent-api.md): Sell a worker who does the job, billed by consumption. An agent writes it. | 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 |