agent

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"]`).

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.

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

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

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.

Agents — concept overview
Agent personas — reusable templates that configure agent behavior
Workspaces — the resource that scopes an agent’s repos, environment, and branches
Profiles and secrets — developer profiles and service profiles
murmur get — CLI command for reading catalog resources
murmur spawn — CLI command that creates agent records
murmur ls — list running agents

Getting Started

Core Concepts

Guides

Fields

agent_id fields

Grant fields

Examples

Listing agent records

Reading a single agent record

Errors

​Fields

​agent_id fields

​Grant fields

​Examples

​Listing agent records

​Reading a single agent record

​Errors

​Related

Fields

agent_id fields

Grant fields

Examples

Listing agent records

Reading a single agent record

Errors

Related