An agent record is a catalog resource created automatically when an agent spawns. You do not author agent records — the platform writes them at spawn time and updates them when the agent terminates. Each record captures the agent’s identity, authorization grants, session location, and purpose.
The agent kind is hidden from schema discovery (murmur describe does not list it), but agent records are readable via murmur get agent.
This is a runtime record, not a user-authored resource. To configure how agents behave, use agent personas. Fields
| Name | Type | Required | Description |
|---|
agent_id | object | yes | Canonical agent identity. See agent_id fields below. |
grants | Grant[] | no | Authorization grants evaluated on every permission check scoped to this agent. See 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 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. 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 used at spawn time. Empty for developer-profile agents. |
tags | string[] | no | Names of the tags attached to this agent, 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 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) or service profile name (for service-profile agents). |
workspace | string | yes | Workspace this agent belongs to. Scopes the agent’s repos, environment, and base branches. |
agent | string[] | yes | Agent path — the hierarchy from root to leaf. A root agent has one element (e.g. ["fix-bug"]). A child has two (e.g. ["fix-bug", "api"]). |
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.
| 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
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
murmur get agent "github_oauth/acme-dev/w/default/fix-bug"
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"
The catalog name includes slashes. Quote the name when passing it to shell commands.
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 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 record. You can only modify your own. |
