Agents inside the product

Agents inside the product work for each Customer: as members of its org, workers on its queue, or the client of record. Each acts under a mandate, through the same gate as a person.

An agent's run, under its mandate

Filled: the run's states, which the Customer sees. Hollow: the mandate chain and the gate.

Capability families

An Agent API sells the agent, a Headless SaaS seats one beside each Customer's people, and a Service API takes one as its client. All three run on one family, offered again to every Customer. The agent belongs to that Customer's org, reads only its records and spends only its budget.

Family	What it gives every product
A runtime per Customer	Each Customer's agents run in its own space, pinned to the Version they started on, and paused, resumed or stopped by Verb
Agents as members	An agent joins a Customer's org with a Role, like a person: it sees what the Role sees, takes a seat where the plan counts seats, and is suspended or removed the same way
Tools from Verbs	An agent's tools are the product's own Verbs, the Customer's Sources and other products' Verbs, each called through the gate, priced and recorded. It has no other way to act
Memory	What an agent learns about one Customer stays in that Customer's space: readable, correctable and erased with the account
Skills	Instructions and examples shipped in the file, changed by a diff like any other line, and checked by evals at deploy
Leases and queues	An agent claims a task from its Role's queue under a lease, as a person does. A lapsed lease returns the task to the queue with its handoff packet
Brakes	Caps declared in the file on runs and spend, per Customer and period. A brake holds the run, braked, and asks the person its mandate names
Acts only a person makes	Verbs the file reserves to a person. An agent is refused each one, and a single-use link goes to its person
Proof	Every run's trace: each tool call, its decision, its price and its result, linked to the Action and the receipts it earned
Delegated sending	An agent sends from the Customer's own Domain, inbox or number under its mandate, in the case's conversation, with what each channel's rules require it to say
The client of record	A buyer's agent files a case, approves the quote, accepts or contests, and pays. The act the law reserves for a person goes to that person by a single-use link

The mandate chain, approvals and the one decision live in Identity, access and policy. An agent inside the product is the principal those rules were written for.

Lifecycles and states

Thing	States	What moves it
An agent, as a member	`invited`, `active`, `suspended`, `removed`	The Customer's admin; a revoked mandate suspends it; a removal is restorable
An agent's run	An Action: `pending` while it works (`Running`) or is braked (`AwaitingApproval`), then `done`, `failed` or `cancelled`	Its work, a brake and the person its mandate names, a cancel by Verb
A task it claims	`open`, `claimed`, `done`; or `released`, back to `open` for the next claim	The agent's claim and completion; a lease that lapses
A lease	`held`, `renewed`, then `released` or `lapsed`	The agent's progress; the clock
A brake	`armed`, `tripped`, `held`, then `released` or `reset`	A cap reached before a call runs; an approval, or the next period
A memory entry	`written`, `corrected`, `erased`	The agent; a member's correction; the Customer's erase
A reserved act	`sent`, then `made` or `expired`	The single-use link to the person, and its clock

A braked run holds its place: the move waits as a Pending Action with the reason AwaitingApproval, and an approval runs it once. Skills follow the Version they ship in.

What you declare, what the platform does

You declare	The platform does
An `agentic()` Verb with its tools	Runs it per Customer, offers only the tools named, sends each through the gate, and meters tokens and minutes
`as`: the Role the agent holds	Adds it to each Customer's org as a member, applies the Role to every read, and counts a seat if the plan does
`memory` and `skills`	Keeps memory in the Customer's space, ships skills with the Version, and refuses a deploy whose skill evals fail
`lease` on the agent's work	Leases each task, renews it while the run progresses, and requeues it on a lapse
`brakes` in `operate`: runs and spend per Customer per period	Holds the run at the cap, asks the mandate's person, and resumes once on approval
`agents.person`: the Verbs only a person makes	Refuses each to every agent, sends a single-use link to the person the mandate names, and records who made the act
Nothing else	Mandates, traces, delegated sending, the handoff packet, and the check that every agent can pay for what it calls

Example

meetings seats its agent in each Customer's org as an assistant. It leases each lead, stops at a daily brake, and leaves one Verb to a person.

definition.ts

24 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, crm and firms, as before
  roles: { assistant: { see: { Meeting: 'all' } } },
  Meeting: {
    with: 'string', company: 'string', at: 'date',
    book: agentic('Book a meeting with the next lead in {crm}', {
      as: 'assistant',                                  // a member of each Customer's org
      tools: ['inbox', 'crm', 'Meeting.create', 'firms.Company.research'],  // through the gate
      memory: 'customer', skills: ['./skills/booking.md'],
      lease: '30m',                                     // one lead per run at a time
      returns: { meeting: 'string' },
    }),
  },
  agents: { person: ['Meeting.cancel'] },               // only a person cancels a meeting
  on: { 'every Mon, Wed, Fri 09:00': 'Meeting.book' },
  offer: { … },                                         // by tokens, minutes and tool calls, as before
  operate: {
    brakes: { 'Meeting.book': { day: 5, spend: { day: 2 } } },  // per Customer; past it, a person
  },
})

The other way round, an agent is the client of record. Acme's agent orders a Filing for $25 and approves it, but signing the report is reserved to a person. The agent's call is refused, and the link goes to the person, never to the agent.

Response

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
X-Cost: price=0, currency="USD"
X-Request-Id: req_8d4f2a6e1b0c97e35a14

{
  "type": "https://filings.apis.dev/docs/errors#person_required",
  "title": "Forbidden",
  "status": 403,
  "detail": "Filing.sign is reserved to a person; a link went to dana@acme.com.",
  "code": "person_required",
  "sentTo": "dana@acme.com",
  "mandate": ["dana@acme.com", "org_acme", "agent_7"],
  "instance": "req_8d4f2a6e1b0c97e35a14"
}

The agent watches Filing.signed and carries on: the filing is filed, and the agent accepts or contests it under the Outcome contract.

Contracts with the other subsystems

Agents propose, and the Runtime's gate commits. An agent has no write path a person lacks, and none a person has that the agent's mandate does not name.

Subsystem	What agents take from it	What agents give it
Definition and compile	The agent, its tools, Role, brakes and lease, checked at deploy: a tool that is not a Verb or Source, or an agent that cannot pay for its tools, is refused	Skills shipped with the Version, changed by a diff
Identity, access and policy	The mandate chain, the Role, approvals, reserved acts and single-use links	Every call carrying its mandate, so the decision reads the whole chain
Model and records	The Customer's records, masked by the Role; memory kept as records	Records written only through Verbs
Data and Sources	The Customer's inbox, CRM and other Sources, read and written back under consent	Reads that respect each Source's licence terms
Runtime	The `agentic` Function kind, the model router, leases, clocks and `AwaitingApproval`	Each run as an Action, each tool call through the gate
Work	Tasks and queues, handoff packets, review of an agent's output, escalation to a person	Work done at the cheapest kind that meets the step's grade
Commerce	Tokens and minutes metered; the buy side's budget when an agent buys from other sellers	Spend per agent, task and seller, against each brake
Interfaces and distribution	MCP, the agent card, agent-to-agent tasks; the conversation an agent sends in	The affordance contract an agent reads before it moves
Trust and operations	Brakes, evals and runaway-spend detection	Traces of every run, and the evidence behind every brake

What Customers and their agents meet

An agent in the member list. A Customer's admin sees the agent beside its people, with its Role, mandate and spend, and suspends it with one Verb.
A brake, not a surprise. At a cap the run waits, braked, and the person its mandate names gets the approval. A grant runs the move once.
Its work, in the open. Every run's trace shows each tool call, what the gate decided and what it cost, beside the Action's price.
Memory the Customer owns. A member reads and corrects what the agent remembers; an erase removes it with the account.
A buyer's agent as client. It files the case, approves the quote, accepts or contests, and pays within its budget. The act reserved for a person reaches that person by a single-use link.
One queue for agents and people. A task whose lease lapses returns to the queue with its handoff packet. A person picks it up where the agent stopped.

An agent acts only through the Verbs a person has, under a mandate a person gave, so its work is as checkable as theirs.

Capability familiesCopy Anchor Link

Lifecycles and statesCopy Anchor Link

What you declare, what the platform doesCopy Anchor Link

ExampleCopy Anchor Link

Contracts with the other subsystemsCopy Anchor Link

What Customers and their agents meetCopy Anchor Link