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. The generic catalog write commands (murmur set, murmur patch, murmur rm) reject the agent kind: agent records change only through dedicated commands such as murmur tag add and murmur delete.

This is a runtime record, not a user-authored resource. To configure how agents behave, use agent personas.

Fields

An agent’s grants inherit down its child tree and authorize direct access by name. They do not make it discoverable in listings. Discovery uses tenant, runtime, or containing workspace authority; see listing rules.

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.
`repo_restriction`	object	no	The repositories this agent may reach, present only for a confined agent: see Repository confinement. Server-authored and read-only: it is computed and pinned at spawn from the repositories the spawn involves, and `agent.edit` cannot add, change, or remove it.
`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 tag add` and `murmur tag rm`. 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"

generation: 1747218600123456
agentId:
  account: acme-dev
  agent:
  - fix-bug
  ownerProvider: PROVIDER_GITHUB_OAUTH
  tenant:
    org: acme-dev
    provider: PROVIDER_GITHUB_APP
  workspace: default
createdAt: "2026-05-14T10:30:00Z"
purpose: Fix the login timeout bug in the auth middleware
sessionUrl: gs://murmur-sessions/github_oauth/acme-dev/w/default/fix-bug/session.jsonl

murmur get prints the record as YAML with the JSON (camelCase) field names, keys sorted, after a leading generation: key.

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.
`FAILED_PRECONDITION`	`agent is a workflow record and cannot be set through generic catalog mutation; use its dedicated RPC`	`murmur set agent` and `murmur patch agent` are not supported. Use `murmur tag add` or `murmur tag rm` to change tags.
`FAILED_PRECONDITION`	`agent is a workflow record and cannot be deleted through generic catalog mutation; use its dedicated RPC`	`murmur rm agent` is not supported. Use `murmur delete` to delete an agent.

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