{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mobilerun-ai/json-schema/mobilerun-ai-agent-schema.json",
  "title": "Agent",
  "description": "An Agent of the owner: its lifecycle state, profile and runtime.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mobilerun-ai-openapi.json#/components/schemas/Agent",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "pending",
        "failed",
        "archived",
        "disabled"
      ],
      "description": "`pending`: created but not provisioned yet, it takes no turns. `active`: ready for turns. `failed`: provisioning gave up (see `errorCode`); the Agent is archived. `archived`: read-only. `disabled`: switched off by the owner or because the plan grants fewer Agent slots; it takes no turns and holds no slot, and the owner can enable it again while a slot is free."
    },
    "threadSessionId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Active chat on the active machine, pinned first, then session lastActiveAt DESC, id DESC. Null for pending/archived Agents or no thread."
    },
    "welcomePending": {
      "type": "boolean",
      "description": "Whether this active primary Agent is still due its one-time greeting: the welcome-back for an adopted primary, or the onboarding greeting for a primary whose chat never had a message."
    },
    "threadPreview": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "excerpt": {
          "type": [
            "string",
            "null"
          ]
        },
        "awaitsInput": {
          "type": "boolean"
        },
        "timestamp": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "excerpt",
        "awaitsInput",
        "timestamp"
      ],
      "description": "Newest thread excerpt (90 characters), awaits-input and timestamp, from at most 20 newest rows. Null when the thread has no rows."
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the owner's primary Agent, the one a chat session uses when it names no `agentId`."
    },
    "profile": {
      "$ref": "#/$defs/AgentProfile"
    },
    "createdAt": {
      "type": "string"
    },
    "provisionedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When provisioning of the Agent completed (ISO 8601); null while a newly created Agent is still pending and after its provisioning failed."
    },
    "archivedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "disabledReason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "owner",
        "over-limit",
        null
      ],
      "description": "Why a `disabled` Agent is disabled: `owner` chose it, `over-limit` the plan grants fewer Agent slots than the owner had enabled. Null while the Agent is not disabled."
    },
    "errorCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why provisioning failed, null otherwise. An open set: new codes can appear. Codes written today: `provision_timeout`, `agent_limit_reached`, `provision_failed`; a code the harness reports for a failed start is passed through."
    },
    "runtime": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "awake",
        "sleeping",
        "waking",
        null
      ],
      "description": "Whether the Agent is running right now, derived from stored state only. `waking`: an active start, its machine is provisioning or a restart/rehydrate is pending and changed within the last 10 minutes (a timed-out or stalled start reads `sleeping`). `awake`: the machine is running and this Agent has been started in the current run. `sleeping`: everything else (stopped or parked machine, an Agent the running harness has not started yet, or an Agent that is not active). `awake` can lag a machine stop until the reconciler converges."
    },
    "lastActiveAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "Latest activity of the Agent (newest chat session activity or live turn heartbeat), ISO 8601; null when it has never been active."
    }
  },
  "required": [
    "id",
    "status",
    "threadSessionId",
    "welcomePending",
    "threadPreview",
    "primary",
    "profile",
    "createdAt",
    "provisionedAt",
    "archivedAt",
    "disabledReason",
    "errorCode"
  ],
  "$defs": {
    "AgentAvatarConfig": {
      "type": "object",
      "properties": {
        "seed": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 4294967295
            }
          ]
        },
        "color": {
          "type": "string",
          "enum": [
            "slate",
            "red",
            "orange",
            "amber",
            "lime",
            "green",
            "teal",
            "cyan",
            "blue",
            "indigo",
            "violet",
            "pink"
          ]
        }
      },
      "additionalProperties": false,
      "description": "Configuration of a `blob` avatar: its seed and optional user-chosen palette color. A color-only config retains the default seed fallback."
    },
    "AgentPersona": {
      "type": "object",
      "properties": {
        "displayName": {
          "type": [
            "string",
            "null"
          ]
        },
        "avatarKind": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "blob"
          ]
        },
        "avatarConfig": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentAvatarConfig"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "displayName",
        "avatarKind",
        "avatarConfig"
      ]
    },
    "AgentProfile": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentPersona"
        },
        {
          "type": "object",
          "properties": {
            "instructions": {
              "type": [
                "string",
                "null"
              ]
            },
            "modelProfile": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "instructions",
            "modelProfile"
          ]
        }
      ],
      "description": "Persona of the Agent plus its individual instructions passage; `instructions` is null when none is set."
    }
  }
}