Skip to main content

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.

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

NameTypeRequiredDescription
agent_idobjectyesCanonical agent identity. See agent_id fields below.
grantsGrant[]noAuthorization grants evaluated on every permission check scoped to this agent. See grant fields below.
created_attimestampyesWhen the record was first created (first spawn of this slug). Immutable across resurrections — only reset by --force-new.
terminated_attimestampnoWhen the agent last terminated. Zero while running. Cleared on resurrection.
session_urlstringyesLocation of the session blob. The session is the durability layer that makes resurrection possible.
purposestringnoOne-sentence goal for this agent. Displayed in the dashboard. Not interpreted by the system. Set at spawn time and preserved across resurrections.
descriptionstringnoHuman-readable description shown in the dashboard. Maximum 1024 bytes.
service_profilestringnoName of the service profile used at spawn time. Empty for developer-profile agents.

​
agent_id fields

The agent_id object identifies the agent uniquely within the tenant.
NameTypeRequiredDescription
tenantobjectyesIdentity namespace — contains provider and org.
owner_providerstringyesDistinguishes identity provider types (e.g. GitHub OAuth, GitHub App, service profile).
accountstringyesOwner’s username (for developer agents) or service profile name (for service-profile agents).
workspacestringyesWorkspace this agent belongs to. Scopes the agent’s repos, environment, and base branches.
agentstring[]yesAgent 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"]).
The catalog name for an agent 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.
NameTypeRequiredDescription
groupsstring[]conditionalGroup names in the same tenant. At least one of groups or users is required.
usersstring[]conditionalGitHub logins. At least one of groups or users is required.
inlineobjectconditionalInline permission list. Exactly one of inline or role must be set.
rolestringconditionalNamed role reference resolved at evaluation time. Exactly one of inline or role must be set.
name_patternstringnoGlob pattern restricting which resources the grant applies to. Supports ${provider} and ${username} variable substitution.

​
Examples

​
Listing agent records

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

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

CodeMeaningWhat to do
INVALID_ARGUMENTagent_id is requiredThe record is missing the agent_id field. This indicates a platform error — agent records are written automatically.
INVALID_ARGUMENTagent_id must have tenant, workspace, and agent fieldsThe agent_id is incomplete. Same as above — this is a platform-side validation.
INVALID_ARGUMENTsession_url is requiredThe record is missing the session URL. Platform-side validation.
INVALID_ARGUMENTdescription exceeds 1024 byte limit (<n> bytes)The description is too long. Shorten it to 1024 bytes or fewer.
INVALID_ARGUMENTgrants[<n>]: grant must specify at least one group or userA grant has neither groups nor users. Add at least one.
INVALID_ARGUMENTgrants[<n>]: grant must specify inline permissions or a role referenceA grant has neither inline nor role. Set exactly one.
INVALID_ARGUMENTgrants[<n>]: grant role reference must be non-emptyThe role field is set but empty. Provide a valid role name.
PERMISSION_DENIEDcannot modify agent record for account "<owner>" (caller is "<caller>")You attempted to modify another developer’s agent record. You can only modify your own.