[Objects](https://oods-foundry.com/objects) / Agent

# Agent

An AI agent that acts inside a product, for the people and organizations it is granted to act for.

alpha 5 traits · 7 contexts · 27 fields [Agent.object.yaml](#file) [How objects work](https://oods-foundry.com/guides/objects-and-traits)

Generated from @oods/foundry 0.18.0

This object is marked alpha.

## Screens

Every screen below was generated from this object by OODS Foundry 0.18.0, in React and Vue, and shows the calls that made it and its content hash. Each runs as its generated app runs, in this site's brand, Aquex, in the theme you choose, with the sample records this object's own file carries; the lists on its detail screens show related records from the shipped objects' samples, and a generated app copies the other objects' records among them when it is made. A value no record gives shows as a neutral one, such as an empty value or "Not recorded"; OODS Foundry invents none, though an editable choice with no empty option, such as a role, starts at its first choice.

[Agent detail screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/detail-react)

React app · sample records Maturity: alpha `sha256:77be62cd97aa…` [Open full size: Agent detail screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/detail-react)

Vue app · sample records Maturity: alpha `sha256:fa92beba404d…` [Open full size: Agent detail screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/detail-vue)

React app · sample records Maturity: alpha `sha256:00157aef0867…` [Open full size: Agent list screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/list-react)

Vue app · sample records Maturity: alpha `sha256:d76aa10510c6…` [Open full size: Agent list screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/list-vue)

React app · sample records Maturity: alpha `sha256:a58eb705b4aa…` [Open full size: Agent form screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/form-react)

Vue app · sample records Maturity: alpha `sha256:e78c95620171…` [Open full size: Agent form screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/form-vue)

React app · sample records Maturity: alpha `sha256:446133d22774…` [Open full size: Agent timeline screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/timeline-react)

Vue app · sample records Maturity: alpha `sha256:bdfe9ee2e43b…` [Open full size: Agent timeline screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/timeline-vue)

React app · sample records Maturity: alpha `sha256:30d23dd843b3…` [Open full size: Agent card screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/card-react)

Vue app · sample records Maturity: alpha `sha256:44f3a0c0df9a…` [Open full size: Agent card screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/card-vue)

React app · sample records Maturity: alpha `sha256:f20fd152dac8…` [Open full size: Agent inline screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/inline-react)

Vue app · sample records Maturity: alpha `sha256:81c093191bc4…` [Open full size: Agent inline screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/inline-vue)

React app · sample records Maturity: alpha `sha256:364efce86b71…` [Open full size: Agent workflow screen generated by OODS Foundry in React](https://oods-foundry.com/objects/agent/screens/workflow-react)

Vue app · sample records Maturity: alpha `sha256:9569c0d7d5f6…` [Open full size: Agent workflow screen generated by OODS Foundry in Vue](https://oods-foundry.com/objects/agent/screens/workflow-vue)

What `design_compose` reported for every screen here:

- `OODS-V121` Object 'Agent' has maturity 'alpha' — composed output may change.

The calls that made the Agent detail apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "detail",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-bc2ec0ef",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-bc2ec0ef",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:77be62cd97aacf90064dfab032b9d3c8115905e9779afdea340785dac5adeaf7`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:fa92beba404d427337fde843e816e79992f5f4b1d9eb8cb549f5eb14fbe2dc76`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

The calls that made the Agent list apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "list",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-1ae9c16a",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-1ae9c16a",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:00157aef0867d98a9fb2d9118c102bdf2d8e6ba439913310aa4de974a13b6354`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:d76aa10510c683ec860bae33308beec425af724dac5096cf496b152b89adde6d`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

The calls that made the Agent form apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "form",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-a458d571",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-a458d571",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:a58eb705b4aa7a76510c3efe06caeefc296c531aeb30d7f41d8ed4b211bd71bc`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:e78c95620171cbbca2dc762b3991377cede2265c5218e91a63915a80d28d8797`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

The calls that made the Agent timeline apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "timeline",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-6c1d88e6",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-6c1d88e6",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:446133d22774da04c9d05da130425960abab597619a4219ebeaaf42b37b952ee`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:bdfe9ee2e43bf3614b03a36a98bf13930b1b5fc4dd1764683d6521723f259c0f`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

The calls that made the Agent card apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "card",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-0002bc60",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-0002bc60",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:30d23dd843b3623766caa02ae53ece37049ddfbde0b96d68e75bb8b517101f61`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:44f3a0c0df9a711f6be6b140a7392076271673c40068429310250557d3b1bd11`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

For this screen it also reported:

- `OODS-V119` No view_extensions found for context "inline" in object "Agent". Available contexts: list, card, detail, form

The calls that made the Agent inline apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "inline",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-1f85a0ac",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-1f85a0ac",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:f20fd152dac8941c3720e0e55fae5acd6a7ecc6c64c6411085fc9dea3d21bdcc`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-aquex.css

The Vue app's content hash: `sha256:81c093191bc4cd3eadfb7815f9b4fc4c60068c55b54256021210025cf2b83a75`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-aquex.css

For this screen it also reported:

- `OODS-V121` as above, 4 times in all

The calls that made the Agent workflow apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Agent",
  "context": "workflow",
  "preferences": {
    "brand": "Aquex",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-863839e4",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-863839e4",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Aquex",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:364efce86b7179fec048eff91683c151d59a4b0672600c4d8e55c5f0a1dfc53c`. Its `src/` folder: App.tsx, actions.ts, app.css, application.ts, main.tsx, oods-brand-aquex.css, related-data.ts, sample-data.ts, screens/, ssr.tsx, store.ts

The Vue app's content hash: `sha256:9569c0d7d5f6ae35503d7639da5157b427bd6b3e46102e1ce4686413735d5698`. Its `src/` folder: App.vue, actions.ts, app.css, application.ts, main.ts, oods-brand-aquex.css, related-data.ts, sample-data.ts, screens/, ssr.ts, store.ts

## Fields

| Field | Type | Description |
| - | - | - |
| `status`required | string | Canonical lifecycle state derived from the states parameter.MoreThis is the single source of truth for the entity's current lifecycle position. Consumed by Colorized to resolve visual tokens, and by view extensions to render StatusBadge and StatusTimeline. |
| `state_history` | StateTransition\[] | Chronological log of state transitions.MoreEach entry records the before/after states, timestamp, and (when governance is enabled) the actor, reason, and transition metadata. Rendered by StatusTimeline in the detail and timeline views. Entry structure: - from: string (previous state) - to: string (new state) - timestamp: ISO 8601 datetime - actor_id: string (user/system who triggered the transition, optional) - reason: string (human-readable justification, required when requireTransitionReason is true) - transition_metadata: Record\<string, unknown> (arbitrary context, optional) Every recorded change can name who acted, who it acted for and who approved it. All optional, following Relationship's source_id/source_name pattern; only a \*\_name names a party, and an entry that names no one renders as it always has: - actor_name: string (who acted, as shown: "Billing Agent") - actor_kind: string (person, agent or system: the Actor trait's kinds) - on_behalf_of_name / on_behalf_of_id: string (the person or organization it acted for) - approved_by_name / approved_by_id: string (who approved the change, when someone did) StatusTimeline then reads "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi". A change someone approved can also say which approval it belongs to and what level of yes it was. Both optional; the id stays in the record's data, a pointer and not a link, and an entry without them renders as it always has: - approval_id: string (the Approval record the yes is kept in) - approval_level: string (the level of yes, one of the levels the product declares: "approval") StatusTimeline then reads "Billing Agent for Tidewater Co-op · approved by Ruth Adeyemi (level: Approval)". A change made as part of a task can also say which task it was. Both optional; the id stays in the record's data, a pointer and not a link, and an entry without them renders as it always has: - task_id: string (the Task record the change was made under) - task_name: string (the task, as shown: "Get INV-2026-0155 paid") StatusTimeline then reads "… · approved by Ruth Adeyemi (level: Approval) · task: Get INV-2026-0155 paid". A change made under a grant, the standing yes an actor acts under for a person or organization, can also say which grant it was. Both optional; the id stays in the record's data, a pointer and not a link, and an entry without them renders as it always has: - grant_id: string (the Grant record the change was made under) - grant_name: string (the grant, as shown: "Resend returned transfers") StatusTimeline names the grant after any approval and before the task: "Billing Agent for Tidewater Co-op · grant: Resend returned transfers". |
| `allowed_transitions` | string\[] | Materialized list of the next states the product allows from the current status, written by the product from the transitionRules parameter.MoreWhen transitionRules is null (open model), this contains all states except the current one. The detail page's StatusTimeline lists it when the record holds it. A generated StatusSelector reads transitionRules instead: it offers the current state and the moves the order allows (every state where no order is declared). |
| `owner_id`required | string | Identifier of the owning principal scoped by owner_type. |
| `owner_type`required | string | Categorical owner type sourced from the ownerTypes parameter. |
| `ownership_role` | string | Optional role name describing how the owner governs the entity. |
| `ownership_transferred_at` | datetime | Timestamp recording when ownership was last transferred. |
| `role_catalog`required | AuthzRoleDocument\[] | Canonical RBAC roles (R21.2 Part 4.2 TABLE 1). |
| `permission_catalog`required | AuthzPermissionDocument\[] | Atomic permissions following resource:action notation (TABLE 2). |
| `role_permissions`required | Record\<string, string\[]> | Junction map for role→permission edges (TABLE 3). |
| `membership_records`required | AuthzMembershipDocument\[] | SaaS membership triple (member, organization_id, role_id) with UNIQUE constraint (TABLE 4).MoreThe member is a user (user_id) or any other actor (actor_id with actor_kind, such as an agent), exactly one of the two. |
| `role_hierarchy_edges` | AuthzRoleHierarchyEdge\[] | Parent→child adjacency list for hierarchical RBAC (Part 3.1). |
| `session_roles` | string\[] | Materialized roles granted within the current session/token exchange. |
| `created_at`required | datetime | Timestamp recording when the entity was first created. |
| `updated_at` | datetime | Timestamp for the most recent modification, when available. |
| `last_event`required | string | Lifecycle event associated with the most recent timestamp mutation. |
| `last_event_at` | datetime | Timestamp for the lifecycle event captured in last_event. |
| `agent_id`required | uuid | Primary identifier for the agent. |
| `name`required | string | The name the agent is shown by, in its own record and in every history it appears in. |
| `description` | string | What the agent is for, in one line. |
| `provider`required | string | Who built or runs the agent. |
| `skills`required | string | What the agent can do, separated by "; " (Look up orders; Draft replies; Issue refunds). |
| `acts_for`required | string | Who the agent acts for, one phrase per party restating the grant it holds for that party (organization · scope · until), separated by "; ".MoreA standing yes inside a grant is covered by the grant it sits in and is not restated. |
| `allowed_actions`required | string | Actions the agent may take with no one's yes, under any grant that allows them, separated by "; "; None when there are none. |
| `asks_first_for`required | string | Actions that need a person's yes before the agent takes them, asked each time or given in advance by a standing yes under a grant, separated by "; "; None when there are none. |
| `never_allowed`required | string | Actions nothing permits the agent to take, separated by "; "; None when there are none. |
| `owner_name` | string | Display name of the person or team that sponsors the agent. |

## Traits

Each trait adds fields and behaviour. Every object with the trait gets the same.

- [Actor](https://oods-foundry.com/traits/actor)
- [Stateful as AgentLifecycle](https://oods-foundry.com/traits/stateful)
- [Ownerable as AgentSponsor](https://oods-foundry.com/traits/ownerable)
- [Authable as AgentRoles](https://oods-foundry.com/traits/authable)
- [Timestampable as AgentAuditTrail](https://oods-foundry.com/traits/timestampable)

## Relationships

This object declares no relationships with other object types. Its detail screens also list related records, declared on the object as related lists, apart from relationships.

## The object file

The Agent object definition in YAML: `objects/core/Agent.object.yaml`

```
object:
  name: Agent
  version: 1.1.1
  domain: core.identity
  description: An AI agent that acts inside a product, for the people and organizations it is granted to act for.
  tags:
    - universal
    - identity
    - core
    - agent

# s244-m02 (#2829): an agent is an actor, not a user. It is an object of its own and shares one trait with User, Actor: the
# ability to act. It answers to a sponsor (a person or team), holds roles, has a lifecycle of its own, and acts for others
# only under a grant (a Grant record from the person or organization to the agent, s248). Approval is a rule per action
# (allowed, ask first, never), never a property of the agent's identity; a grant can narrow it for one party, and a
# standing yes inside a grant can give an asks-first action's yes in advance. Every field is one line of text:
# a list is written as one string with its items separated by "; ", and "None" when it is empty.
traits:
  - name: core/Actor
    parameters:
      kind: agent
  - name: lifecycle/Stateful
    alias: AgentLifecycle
    parameters:
      states:
        - draft
        - active
        - paused
        - retired
      initialState: draft
  - name: structural/Ownerable
    alias: AgentSponsor
    parameters:
      ownerTypes:
        - user
        - team
      primaryOwnerType: user
      allowTransfer: true
  - name: core/Authable
    alias: AgentRoles
    parameters:
      hierarchyDepthLimit: 5
  - name: lifecycle/Timestampable
    alias: AgentAuditTrail
    parameters:
      recordedEvents:
        - created
        - activated
        - paused
        - retired
        - updated
      timezone: UTC

schema:
  agent_id:
    type: uuid
    required: true
    description: Primary identifier for the agent.
  name:
    type: string
    required: true
    description: The name the agent is shown by, in its own record and in every history it appears in.
    validation:
      minLength: 1
      maxLength: 80
  description:
    type: string
    required: false
    description: What the agent is for, in one line.
    validation:
      maxLength: 160
  provider:
    type: string
    required: true
    description: Who built or runs the agent.
  skills:
    type: string
    required: true
    description: What the agent can do, separated by "; " (Look up orders; Draft replies; Issue refunds).
  acts_for:
    type: string
    required: true
    description: Who the agent acts for, one phrase per party restating the grant it holds for that party (organization · scope · until), separated by "; ". A standing yes inside a grant is covered by the grant it sits in and is not restated.
  allowed_actions:
    type: string
    required: true
    description: Actions the agent may take with no one's yes, under any grant that allows them, separated by "; "; None when there are none.
  asks_first_for:
    type: string
    required: true
    description: Actions that need a person's yes before the agent takes them, asked each time or given in advance by a standing yes under a grant, separated by "; "; None when there are none.
  never_allowed:
    type: string
    required: true
    description: Actions nothing permits the agent to take, separated by "; "; None when there are none.
  owner_name:
    type: string
    required: false
    description: Display name of the person or team that sponsors the agent.

semantics:
  agent_id:
    semantic_type: identity.agent.id
    token_mapping: tokenMap(identity.id.primary)
  name:
    semantic_type: identity.agent.name
    token_mapping: tokenMap(identity.name.primary)
  # The one-line summary under the agent's name in lists.
  description:
    semantic_type: text.summary
    token_mapping: tokenMap(identity.description.summary)
  provider:
    semantic_type: identity.agent.provider
    token_mapping: tokenMap(text.body.*)
  skills:
    semantic_type: identity.agent.skills
    token_mapping: tokenMap(text.body.*)
  acts_for:
    semantic_type: identity.agent.acts_for
    token_mapping: tokenMap(text.body.*)
    ui_hints:
      valueLabels:
        None: No party listed
  allowed_actions:
    semantic_type: identity.agent.approval.allowed
    token_mapping: tokenMap(text.body.*)
  asks_first_for:
    semantic_type: identity.agent.approval.ask_first
    token_mapping: tokenMap(text.body.*)
  never_allowed:
    semantic_type: identity.agent.approval.never
    token_mapping: tokenMap(text.body.*)
  # structural/Ownerable's owner reference: the agent's sponsor, named by owner_name.
  owner_id:
    semantic_type: ownership.owner.id
    token_mapping: tokenMap(ownership.owner.id)
    ui_hints:
      component: OwnerReference
      ownerTypeField: owner_type
      displayLabelField: owner_name

tokens:
  identity.id.primary: "var(--text-strong)"
  identity.name.primary: "var(--text-strong)"
  identity.description.summary: "var(--text-subtle)"

metadata:
  owners:
    - Identity team
    - Platform team
  steward: Design team
  maturity: alpha
  changelog:
    - version: 1.1.1
      date: "2026-11-19"
      description: Lists the grants the agent holds and those under its standing grants. The Order Agent’s parties match its grant, and a stored None has an explanation on the page.
    - version: 1.1.0
      date: "2026-11-14"
      description: The four rule fields say what they mean beside a grant; acts_for restates the grant held for each party, and asks first means a yes, asked each time or given in advance.
    - version: 1.0.0
      date: "2026-11-07"
      description: Initial Agent object, the twelfth public reference object; an agent is an actor, not a user.
  # s249-m01: the lists this object's detail page shows of the records that point at one of its records, seat by seat,
  # declared here on the page that shows them (packages/mcp-server/src/objects/related-lists.ts says what each key means).
  # They read the registered objects' records by id only, never by name.
  # The agent's own acts_for stays a field: the product's words beside the record.
  relatedLists:
    - id: acts-for
      label: "Grants {name} holds"
      empty: "{name} holds no grant now."
      filtered: { one: "1 other grant to {name} is asked for or has ended.", other: "{count} other grants to {name} are asked for or have ended." }
      sources:
        - from: Grant
          via: granted_to_id
          when: { granted_to_kind: agent, within_id: null }
          states: [active, paused]
          inner: within_id
          row: { line: [granted_for_name, scope, last_use, { says: No uses counted, when: { uses: 0 } }], time: ends_note }
    - id: work
      label: "Work {name} did"
      empty: "No recorded change names {name} as the one who acted."
      sources:
        - { from: [Task, Approval, Transaction, Grant], via: "state_history[].actor_id" }
    # s250-m03 (next step 1888): only grants that hold a giver, since a request that expired unanswered was never held.
    - id: ended-grants
      label: "Ended grants {name} held"
      empty: "No grant {name} held has ended."
      collapsed: true
      sources:
        - from: Grant
          via: granted_to_id
          when: { granted_to_kind: agent, within_id: null, granted_by_id: { present: true } }
          states: [revoked, expired, replaced]
          inner: within_id
          row: { line: [granted_for_name, scope] }

# Seven authored sample agents, one at each of seven sample organizations, each sponsored by a person or team there. Six
# have held a grant to act for it, and each acts_for restates the grants its agent holds now, one phrase per party, or
# None. The Grant samples include each grant named here. Two agents whose grants ended hold none now:
# the Scheduling Agent's grant was revoked when
# Marlow Yoga closed, and the Support Agent's on 8 October, when its acts_for was restated as None. The Inventory Agent
# holds none: its one task is its sponsor's own, and its lines name no party. An agent is created as a draft
# (the lifecycle's initial state); each history ends in the agent's status, names who made each change, and its last
# event is the latest recorded change. A list is one line with its items separated by "; ", and None when it is empty.
samples:
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a01
    name: Billing Agent
    description: Matches payments to invoices for Tidewater Co-op
    provider: Built by Tidewater's finance team
    skills: Look up invoices; Match payments to invoices; Resend payments; Draft replies
    acts_for: Tidewater Co-op · invoices and payments · until 31 Dec 2026
    allowed_actions: Look up invoices; Match payments to invoices
    asks_first_for: Resend a payment; Dispute a charge
    never_allowed: Change bank details; Close the account
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d02
    owner_type: user
    ownership_role: Sponsor
    owner_name: Ruth Adeyemi
    session_roles: [Billing]
    status: active
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-08-20T21:00:00Z', reason: Set up to match bank transfers to invoices, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d02, actor_name: Ruth Adeyemi, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-09-01T21:00:00Z', reason: Approved after twelve days of supervised matching, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d02, actor_name: Ruth Adeyemi, actor_kind: person }
    created_at: '2026-08-20T21:00:00Z'
    updated_at: '2026-09-01T21:00:00Z'
    last_event: activated
    last_event_at: '2026-09-01T21:00:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a02
    name: Support Agent
    description: Answers order questions for Northwind Traders
    provider: Built by Northwind's support team
    skills: Answer order questions; Track shipments; Draft replies
    acts_for: None
    allowed_actions: Track shipments; Draft replies
    asks_first_for: Send a reply; Offer a discount code
    never_allowed: Cancel an order; Change a delivery address
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d01
    owner_type: user
    ownership_role: Sponsor
    owner_name: Dana Whitfield
    session_roles: [Support]
    status: active
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-03-02T15:00:00Z', reason: Set up for the spring order rush, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d01, actor_name: Dana Whitfield, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-03-09T15:00:00Z', reason: Replies reviewed and approved for customers, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d01, actor_name: Dana Whitfield, actor_kind: person }
    created_at: '2026-03-02T15:00:00Z'
    updated_at: '2026-10-08T16:00:00Z'
    last_event: updated
    last_event_at: '2026-10-08T16:00:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a03
    name: Order Agent
    description: Reserves stock for Summit Outfitters
    provider: Built by Summit's e-commerce team
    skills: Check stock; Reserve items; Update orders
    acts_for: Summit Outfitters · online orders · until 31 Mar 2027
    allowed_actions: Check stock; Reserve items for 24 hours
    asks_first_for: Split a shipment; Upgrade shipping
    never_allowed: Issue a refund; Delete an order
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d08
    owner_type: user
    ownership_role: Sponsor
    owner_name: Arjun Mehta
    session_roles: [Orders]
    status: active
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-05-04T16:00:00Z', reason: Set up for online orders, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d08, actor_name: Arjun Mehta, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-05-11T16:00:00Z', reason: Stock checks matched the warehouse counts, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d08, actor_name: Arjun Mehta, actor_kind: person }
      - { title: Paused, from: active, to: paused, at: '2026-06-30T17:59:00Z', reason: Paused while single sign-on was reset, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d08, actor_name: Arjun Mehta, actor_kind: person }
      - { title: Resumed, from: paused, to: active, at: '2026-07-01T15:00:00Z', reason: Single sign-on restored, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d08, actor_name: Arjun Mehta, actor_kind: person }
    created_at: '2026-05-04T16:00:00Z'
    updated_at: '2026-07-01T15:00:00Z'
    last_event: activated
    last_event_at: '2026-07-01T15:00:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a04
    name: Booking Agent
    description: Books and reschedules sessions for Blue Harbor Studio
    provider: Built by Blue Harbor Studio
    skills: Book sessions; Reschedule sessions; Send reminders
    acts_for: Blue Harbor Studio · session bookings · until 31 Jan 2027
    allowed_actions: Send reminders
    asks_first_for: Book a session; Reschedule a session
    never_allowed: Charge a card; Cancel a membership
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d03
    owner_type: user
    ownership_role: Sponsor
    owner_name: Priya Raman
    session_roles: [Bookings]
    status: paused
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-09-19T11:00:00Z', reason: Set up with the studio's trial, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d03, actor_name: Priya Raman, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-09-19T12:00:00Z', reason: Reminders tested on two sessions, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d03, actor_name: Priya Raman, actor_kind: person }
      - { title: Paused, from: active, to: paused, at: '2026-09-21T09:30:00Z', reason: Paused until the studio's new calendar is ready, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d03, actor_name: Priya Raman, actor_kind: person }
    created_at: '2026-09-19T11:00:00Z'
    updated_at: '2026-09-21T09:30:00Z'
    last_event: paused
    last_event_at: '2026-09-21T09:30:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a05
    name: Inventory Agent
    description: Counts flour and butter stock for Lindqvist Bakery
    provider: Built by Lindqvist Bakery
    skills: Count stock; Suggest supplier orders
    acts_for: None
    allowed_actions: Count stock
    asks_first_for: Place a supplier order
    never_allowed: Change prices
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d04
    owner_type: user
    ownership_role: Sponsor
    owner_name: Tomas Lindqvist
    session_roles: [Inventory]
    status: draft
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-10-05T07:00:00Z', reason: Drafted before the winter baking season, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d04, actor_name: Tomas Lindqvist, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-10-12T07:00:00Z', reason: Counts checked against a week of deliveries, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d04, actor_name: Tomas Lindqvist, actor_kind: person }
      - { title: Back to draft, from: active, to: draft, at: '2026-10-19T07:00:00Z', reason: Taken back to draft while its counting rules are rewritten, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d04, actor_name: Tomas Lindqvist, actor_kind: person }
    created_at: '2026-10-05T07:00:00Z'
    updated_at: '2026-10-19T07:00:00Z'
    last_event: updated
    last_event_at: '2026-10-19T07:00:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a06
    name: Collections Agent
    description: Sends payment reminders for Kestrel Print Co.
    provider: Built by Kestrel's accounts team
    skills: Send payment reminders; Record promises to pay
    acts_for: Kestrel Print Co. · overdue invoices · until 31 Dec 2026
    allowed_actions: Record a promise to pay
    asks_first_for: Send a payment reminder
    never_allowed: Pass an account to collections; Add a late fee
    owner_id: team_kestrel_accounts
    owner_type: team
    ownership_role: Sponsor
    owner_name: Accounts team
    session_roles: [Collections]
    status: paused
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-02-02T10:00:00Z', reason: Set up for overdue invoices, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d05, actor_name: Grace Okafor, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-02-09T10:00:00Z', reason: Reminder wording approved by the accounts team, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d05, actor_name: Grace Okafor, actor_kind: person }
      - { title: Paused, from: active, to: paused, at: '2026-09-23T16:00:00Z', reason: Paused while the reminders are rewritten, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d05, actor_name: Grace Okafor, actor_kind: person }
    created_at: '2026-02-02T10:00:00Z'
    updated_at: '2026-09-23T16:00:00Z'
    last_event: paused
    last_event_at: '2026-09-23T16:00:00Z'
  - agent_id: 6a1e2b3c-4d5e-4f60-8a7b-9c0d1e2f3a07
    name: Scheduling Agent
    description: Offered waitlist places for Marlow Yoga until it closed
    provider: Built by Marlow Yoga
    skills: Book classes; Send waitlist offers
    acts_for: None
    allowed_actions: Send waitlist offers
    asks_first_for: Book a class
    never_allowed: Charge a card
    owner_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d07
    owner_type: user
    ownership_role: Sponsor
    owner_name: Jonah Marlow
    session_roles: [Scheduling]
    status: retired
    state_history:
      - { title: Created, from: null, to: draft, at: '2026-01-12T10:00:00Z', reason: Set up for the class waitlist, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d07, actor_name: Jonah Marlow, actor_kind: person }
      - { title: Activated, from: draft, to: active, at: '2026-01-19T10:00:00Z', reason: Waitlist offers checked for a week, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d07, actor_name: Jonah Marlow, actor_kind: person }
      - { title: Retired, from: active, to: retired, at: '2026-07-10T08:59:00Z', reason: Studio closed; its grant was revoked, actor_id: 8b2e4d6f-1a3c-4e5b-9d7f-2c4e6a8b0d07, actor_name: Jonah Marlow, actor_kind: person }
    created_at: '2026-01-12T10:00:00Z'
    updated_at: '2026-07-10T08:59:00Z'
    last_event: retired
    last_event_at: '2026-07-10T08:59:00Z'
```
