Agent

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/derive-to/json-schema/derive-to-agent-schema.json",
  "title": "Agent",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/derive-to-openapi.json#/components/schemas/Agent",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "role": {
      "type": "string",
      "enum": [
        "viewer",
        "commenter",
        "editor",
        "owner"
      ],
      "description": "Permission level; commenter comments only, editor can write, owner never allowed. Defaults to editor, capped at the creator's seat."
    },
    "managed": {
      "type": "boolean",
      "description": "Made automatically for one imported paper, not named by a person. Never listed over MCP, asked, or used as a workflow step."
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "The user who registered the agent — who it publishes and bills on behalf of."
    },
    "created_at": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "One line: what this agent does."
    },
    "instructions_short_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The artifact it reads before every job. Null for a connected tool."
    },
    "machine": {
      "type": "string",
      "enum": [
        "owner",
        "derive"
      ],
      "description": "Where its jobs run: the owner's runner or MCP session, or a Derive sandbox."
    },
    "provider": {
      "type": "string",
      "enum": [
        "claude-code",
        "codex"
      ],
      "description": "Which coding agent runs its jobs."
    },
    "runtime": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "ortam",
            "boat"
          ]
        },
        "reason": {
          "type": [
            "string",
            "null"
          ]
        },
        "phase": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "creating",
            "provisioning",
            "stopping",
            "ready",
            "busy",
            "deleting",
            "failed",
            null
          ]
        }
      },
      "required": [
        "provider",
        "phase"
      ],
      "description": "Cloud sandbox availability and progress. No credentials."
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "effort": {
      "type": [
        "string",
        "null"
      ],
      "description": "Harness reasoning level. Null is its default."
    },
    "sandbox": {
      "$ref": "#/$defs/AgentSandbox"
    },
    "ask_policy": {
      "type": "string",
      "enum": [
        "workspace",
        "invited"
      ]
    },
    "spend_policy": {
      "type": "string",
      "enum": [
        "asker",
        "creator"
      ],
      "description": "asker: each job runs on its asker's model account and secrets. creator: on its creator's, lent to everyone who may ask."
    },
    "write_policy": {
      "type": "string",
      "enum": [
        "publish",
        "review"
      ],
      "description": "publish: its writes go live like a person's. review: they still go live, and every new version it writes to an existing page opens a review round for the person it acts for."
    },
    "paused": {
      "type": "boolean"
    },
    "seen_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When its runner last pulled work."
    },
    "max_run_ms": {
      "type": [
        "number",
        "null"
      ]
    },
    "max_concurrency": {
      "type": "number"
    },
    "connection_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sources it can reach."
    },
    "repository": {
      "type": [
        "string",
        "null"
      ],
      "description": "Where its tasks work when an ask names no repository."
    },
    "environment": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Environment variables its jobs get: NAME → the id of a saved secret. Never values."
    },
    "environment_names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Environment variable names bound to credentials. Never values."
    },
    "sources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentSource"
      },
      "description": "Every source and secret it is bound to, by name: connection_ids and the secrets behind environment. Never values."
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "role",
    "managed",
    "created_by",
    "created_at",
    "description",
    "instructions_short_id",
    "machine",
    "provider",
    "model",
    "effort",
    "sandbox",
    "ask_policy",
    "spend_policy",
    "write_policy",
    "paused",
    "seen_at",
    "max_run_ms",
    "max_concurrency",
    "connection_ids",
    "repository",
    "environment",
    "environment_names",
    "sources",
    "account_id"
  ],
  "$defs": {
    "AgentSandbox": {
      "type": "object",
      "properties": {
        "snapshot": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{1,120}$",
          "description": "A prepared provider image, such as a Boat named snapshot."
        },
        "environment": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{1,120}$",
          "description": "A provider environment to attach, with its repositories and secrets. Absent: none of the account's secrets."
        },
        "size": {
          "type": "string",
          "enum": [
            "small",
            "default",
            "large",
            "xlarge"
          ],
          "description": "Machine size."
        },
        "fresh": {
          "type": "boolean",
          "description": "Build a new machine from the snapshot for every task instead of resuming."
        },
        "check": {
          "type": "string",
          "maxLength": 2000,
          "description": "Shell command run before the harness starts. A nonzero exit ends the task with its output and spends no model tokens."
        }
      },
      "description": "The machine its Derive jobs run on. Empty uses the workspace default."
    },
    "AgentSource": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "description": "The source's name, or a secret's label. Never a value."
        },
        "kind": {
          "type": "string",
          "enum": [
            "oauth",
            "secret",
            "github_app",
            "slack",
            "mcp",
            "runtime"
          ]
        },
        "scope": {
          "type": "string",
          "enum": [
            "personal",
            "workspace"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "pending",
            "revoked"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "kind",
        "scope",
        "status"
      ]
    }
  }
}