Agent · StartupBuilder

It acts from a Role seat, under that Role’s Permissions and its own Mandates.

Properties

Property	Type	Required	Description
`instructions`	`text`	required	What the Agent does and how.
`model`	`string`	required	The model the Agent runs on.
`tools`	`string[]`		The tools the Agent may call.
`skills`	list of Skill		The Skills it loads.
`memory`	`string`		One of `tenant` (one Memory per Customer Tenant) or `startup` (one Memory for the Startup).
`maxSteps`	`integer`		The most steps one Task may take.
`budget`	`money`		The most one Task may spend; the Mandate’s Limits apply as well.
`handoffs`	list of Role		The Roles it hands work to.
`status`	`string`	required	One of `standby`, `seated`, `paused` or `retired`: whether it fills a Role and is working.

Object

JSON

{
  "$id": "https://api.sb/shiftnote.app/agents/agent_1",
  "$type": "Agent",
  "instructions": "Example instructions",
  "model": "Example model",
  "tools": [
    "Example tools"
  ],
  "skills": [
    "skill_1"
  ],
  "memory": "tenant",
  "maxSteps": 1,
  "budget": {
    "amount": 79,
    "currency": "USD"
  },
  "handoffs": [
    "role_1"
  ],
  "status": "standby"
}

Relationships

An Agent is employed by many Startups: an Agent holds a seat in the Startup and acts within the authority it grants; one Agent can hold seats in many Startups. employedBy, inverse employs.
An Agent has many Mandates: a Mandate lets an Agent act without asking each time, within its Permissions and Limits, until it expires or is revoked. mandates, inverse authorizes.

Lifecycle

State	Meaning	Moves to
`standby` (first)	It fills no Role, so it performs no Verbs.	`seated` on `Role.staffed` when the Worker who fills the Role is this Agent
`seated`	It fills at least one Role and performs that Role’s Verbs under its Permissions.	`standby` on `Role.staffed` when another Worker fills the last Role this Agent held; `paused` by Agent.pause; `retired` by Agent.retire
`paused`	It keeps its seats, Memory, Mandates and Limits, and starts no new Action until it resumes.	`seated` by Agent.resume; `retired` by Agent.retire
`retired`	It holds no seat in the Startup again; its Actions, Memory and Mailbox history stay on the record.	None: it ends here.

Verbs

createCreates an Agent.
POST /{namespace}/agentsdoAgent.created
getReturns one Agent by id.
GET /{namespace}/agents/{id}readNo Event
listReturns Agents, newest first, one page at a time.
GET /{namespace}/agentsreadNo Event
updateChanges the given properties of an Agent.
PATCH /{namespace}/agents/{id}doAgent.updated
deleteDeletes an Agent; its history is kept.
DELETE /{namespace}/agents/{id}doAgent.deleted
mintMint creates an Agent in a Customer’s Tenant from an Agent Product the Customer bought.
POST /{namespace}/agents/mintdoAgent.minted
pausePause stops one Agent, every Agent on a Team, or every customer-facing Agent from starting new Actions in a Startup.
POST /{namespace}/agents/pausedoAgent.paused
resumeResume restarts a paused Agent in every seat it holds, with its Memory, Mandates and Limits unchanged.
POST /{namespace}/agents/{agent}/resumedoAgent.resumed
retireRetire removes an Agent from every seat in a Startup for good and keeps its Actions, Memory and Mailbox history on the record.
POST /{namespace}/agents/{agent}/retiredoAgent.retired

Permissions

Which Access level may call each Verb. One-way Verbs wait their delay window.

Operation	`owner`	`admin`	`member`	`viewer`
`Agent.create`	Yes	Yes	Yes	No
`Agent.get`	Yes	Yes	Yes	Yes
`Agent.list`	Yes	Yes	Yes	Yes
`Agent.update`	Yes	Yes	Yes	No
`Agent.delete`	Yes	Yes	Yes	No
`Agent.mint`	Yes	Yes	Yes	No
`Agent.pause`	Yes	Yes	Yes	No
`Agent.resume`	Yes	Yes	Yes	No
`Agent.retire`	Yes	No	No	No

Call it

Text

Mint the latest agent with a tenant and a product.

A support Agent fills the Customer Lead Role at a tutoring marketplace. Its instructions say to answer from the help center and hand billing questions to a Human; its tools read tickets and post replies.

PropertiesCopy Anchor Link

ObjectCopy Anchor Link

RelationshipsCopy Anchor Link

LifecycleCopy Anchor Link

VerbsCopy Anchor Link

PermissionsCopy Anchor Link

Call itCopy Anchor Link

ExampleCopy Anchor Link