---
title: "Agents inside the product"
url: /work/agents
---

# Agents inside the product

> An agent per Customer, three ways: a member of its org, a worker on its queue, and the client of record under a mandate, each through the same gate as a person.

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.**

- A person mandates an org, and the org mandates an agent; each link is narrower.
- The agent claims an `open` task under a lease and works it. Each tool call is a Verb through the gate, and an allowed one commits.
- At a brake the run waits, braked, until the person its mandate names approves; then the move runs once.
- If the lease lapses, the task returns to the queue, `open` for the next claim.

## Capability families
An [Agent API](/patterns/agent-api.md) sells the agent, a [Headless SaaS](/patterns/headless-saas.md) seats one beside each Customer's people, and a [Service API](/patterns/service-api.md) 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](/reference/platform.md#version) they started on, and paused, resumed or stopped by Verb |
| Agents as members | An agent joins a Customer's org with a [Role](/reference/platform.md#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](/patterns/dataset-api.md#how-a-field-is-filled) 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](/workflow.md#the-lifecycle) 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](/identity.md). 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](/workflow.md#the-lifecycle) with the reason `AwaitingApproval`, and an approval runs it once.

## What you declare, what the platform does
An `agentic()` Verb names its tools, and `as` names the Role the agent holds in each Customer's org. `memory`, `skills` and `lease` sit on the agent, `brakes` in `operate`, and `agents.person` lists the Verbs only a person makes.

Deploy refuses a tool that is not a Verb or Source, a skill that fails its evals, and an agent that cannot pay its way. Mandates, traces, delegated sending and the handoff packet need nothing declared.

### 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.

```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
  },
  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
    '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
  },
})
```

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

```http title="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
An agent has no write path a person lacks, and none a person has that the agent's mandate does not name.

- **Definition and compile** checks the agent, its tools, Role, brakes and lease at deploy.
- **Identity, access and policy** gives the mandate chain, approvals and reserved acts, and every call carries its mandate for the decision to read.
- **Model and records** masks the Customer's records by Role, keeps memory as records, and takes writes only through Verbs.
- **Data and Sources** opens the Customer's inbox, CRM and other Sources under consent and their licence terms.
- **Runtime** gives the `agentic` [Function](/patterns/function-api.md) kind, the model router, leases and clocks, and sends every tool call through the gate.
- **Work** gives queues, handoff packets, review and escalation to a person.
- **Commerce** meters tokens and minutes, pays for purchases from other sellers out of the buy side's budget, and counts spend against each brake.
- **Interfaces and distribution** gives MCP, the agent card, agent-to-agent tasks and the [affordance contract](/interfaces/ui-contracts.md) an agent reads before it moves.
- **Trust and operations** runs evals and runaway-spend detection, and keeps every run's trace.

## 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, and the person its mandate names gets the approval.
- **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.

---

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