> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# agent

> Catalog record automatically created when an agent spawns. Captures identity, authorization grants, session location, and termination state.

An [agent](/concepts/agents) record is a catalog resource created automatically when an [agent](/concepts/agents) spawns. You do not author [agent](/concepts/agents) records — the platform writes them at spawn time and updates them when the [agent](/concepts/agents) terminates. Each record captures the [agent's](/concepts/agents) identity, authorization grants, session location, and purpose.

The [agent](/concepts/agents) kind is hidden from schema discovery (`murmur describe` does not list it), but [agent](/concepts/agents) records are readable via `murmur get agent`.

<Note>
  This is a runtime record, not a user-authored resource. To configure how [agents](/concepts/agents) behave, use [agent personas](/concepts/agent-personas).
</Note>

## Fields

| Name              | Type      | Required | Description                                                                                                                                                                                                                                               |
| ----------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`        | object    | yes      | Canonical [agent](/concepts/agents) identity. See [agent\_id fields](#agent_id-fields) below.                                                                                                                                                             |
| `grants`          | Grant\[]  | no       | Authorization grants evaluated on every permission check scoped to this [agent](/concepts/agents). See [grant fields](#grant-fields) below.                                                                                                               |
| `created_at`      | timestamp | yes      | When the record was first created (first spawn of this slug). Immutable across resurrections — only reset by `--force-new`.                                                                                                                               |
| `terminated_at`   | timestamp | no       | When the [agent](/concepts/agents) last terminated. Zero while running. Cleared on resurrection.                                                                                                                                                          |
| `session_url`     | string    | yes      | Location of the session blob. The session is the durability layer that makes resurrection possible.                                                                                                                                                       |
| `purpose`         | string    | no       | One-sentence goal for this [agent](/concepts/agents). Displayed in the dashboard. Not interpreted by the system. Set at spawn time and preserved across resurrections.                                                                                    |
| `description`     | string    | no       | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                                                                                                                                                                    |
| `service_profile` | string    | no       | Name of the [service profile](/concepts/secrets) used at spawn time. Empty for developer-profile [agents](/concepts/agents).                                                                                                                              |
| `tags`            | string\[] | no       | Names of the [tags](/catalog/tag) attached to this [agent](/concepts/agents), referencing the tenant tag registry. Max 8, unique within the set. Set at spawn and editable via `murmur set agent`. Preserved across resurrection; reset by `--force-new`. |

## agent\_id fields

The `agent_id` object identifies the [agent](/concepts/agents) uniquely within the tenant.

| Name             | Type      | Required | Description                                                                                                                                                                           |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tenant`         | object    | yes      | Identity namespace — contains `provider` and `org`.                                                                                                                                   |
| `owner_provider` | string    | yes      | Distinguishes identity provider types (e.g. GitHub OAuth, GitHub App, service profile).                                                                                               |
| `account`        | string    | yes      | Owner's username (for developer [agents](/concepts/agents)) or [service profile](/concepts/secrets) name (for service-profile [agents](/concepts/agents)).                            |
| `workspace`      | string    | yes      | [Workspace](/concepts/workspaces) this [agent](/concepts/agents) belongs to. Scopes the [agent's](/concepts/agents) repos, environment, and base branches.                            |
| `agent`          | string\[] | yes      | [Agent](/concepts/agents) path — the hierarchy from root to leaf. A root [agent](/concepts/agents) has one element (e.g. `["fix-bug"]`). A child has two (e.g. `["fix-bug", "api"]`). |

The catalog name for an [agent](/concepts/agents) record is derived from the `agent_id`: `{owner_provider}/{account}/w/{workspace}/{slug}[/{slug}...]`. The `owner_provider` segment uses a lowercase form of the enum (for example, `PROVIDER_GITHUB_OAUTH` becomes `github_oauth`).

## Grant fields

Each grant in the `grants` array controls what actions specific users or groups can perform on this [agent](/concepts/agents).

| Name           | Type      | Required    | Description                                                                                                                    |
| -------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `groups`       | string\[] | conditional | Group names in the same tenant. At least one of `groups` or `users` is required.                                               |
| `users`        | string\[] | conditional | GitHub logins. At least one of `groups` or `users` is required.                                                                |
| `inline`       | object    | conditional | Inline permission list. Exactly one of `inline` or `role` must be set.                                                         |
| `role`         | string    | conditional | Named role reference resolved at evaluation time. Exactly one of `inline` or `role` must be set.                               |
| `name_pattern` | string    | no          | Glob pattern restricting which resources the grant applies to. Supports `${provider}` and `${username}` variable substitution. |

## Examples

### Listing agent records

```bash theme={null}
murmur get agent
```

```
github_oauth/acme-dev/w/default/fix-bug
github_oauth/acme-dev/w/default/refactor-api
github_app/acme-org/w/default/issue-triage
```

### Reading a single agent record

```bash theme={null}
murmur get agent "github_oauth/acme-dev/w/default/fix-bug"
```

```yaml theme={null}
agent_id:
  tenant:
    provider: PROVIDER_GITHUB_OAUTH
    org: acme-dev
  owner_provider: PROVIDER_GITHUB_OAUTH
  account: acme-dev
  workspace: default
  agent:
    - fix-bug
created_at: "2026-05-14T10:30:00Z"
session_url: "gs://murmur-sessions/github_oauth/acme-dev/w/default/fix-bug/session.jsonl"
purpose: "Fix the login timeout bug in the auth middleware"
```

<Note>
  The catalog name includes slashes. Quote the name when passing it to shell commands.
</Note>

## Errors

| Code                | Meaning                                                                   | What to do                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `INVALID_ARGUMENT`  | `agent_id is required`                                                    | The record is missing the `agent_id` field. This indicates a platform error — [agent](/concepts/agents) records are written automatically. |
| `INVALID_ARGUMENT`  | `agent_id must have tenant, workspace, and agent fields`                  | The `agent_id` is incomplete. Same as above — this is a platform-side validation.                                                          |
| `INVALID_ARGUMENT`  | `session_url is required`                                                 | The record is missing the session URL. Platform-side validation.                                                                           |
| `INVALID_ARGUMENT`  | `description exceeds 1024 byte limit (<n> bytes)`                         | The description is too long. Shorten it to 1024 bytes or fewer.                                                                            |
| `INVALID_ARGUMENT`  | `grants[<n>]: grant must specify at least one group or user`              | A grant has neither `groups` nor `users`. Add at least one.                                                                                |
| `INVALID_ARGUMENT`  | `grants[<n>]: grant must specify inline permissions or a role reference`  | A grant has neither `inline` nor `role`. Set exactly one.                                                                                  |
| `INVALID_ARGUMENT`  | `grants[<n>]: grant role reference must be non-empty`                     | The `role` field is set but empty. Provide a valid role name.                                                                              |
| `PERMISSION_DENIED` | `cannot modify agent record for account "<owner>" (caller is "<caller>")` | You attempted to modify another developer's [agent](/concepts/agents) record. You can only modify your own.                                |

## Related

* [Agents](/concepts/agents) — concept overview
* [Agent personas](/concepts/agent-personas) — reusable templates that configure [agent](/concepts/agents) behavior
* [Workspaces](/concepts/workspaces) — the resource that scopes an [agent's](/concepts/agents) repos, environment, and branches
* [Profiles and secrets](/concepts/secrets) — developer profiles and service profiles
* [`murmur get`](/cli/get) — CLI command for reading catalog resources
* [`murmur spawn`](/cli/spawn) — CLI command that creates [agent](/concepts/agents) records
* [`murmur ls`](/cli/status) — list running [agents](/concepts/agents)