AiAgentView

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/picaos/main/json-schema/picaos-ai-agent-view-schema.json",
  "title": "AiAgentView",
  "description": "`Eq` is absent for the same reason as on the record: `guardrails` carries a\nfractional dollar amount.",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/picaos-api-openapi.json#/components/schemas/AiAgentView",
  "properties": {
    "active": {
      "type": "boolean"
    },
    "channels": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/AiAgentChannels"
        }
      ]
    },
    "createdAt": {
      "format": "date-time",
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "environment": {
      "$ref": "#/$defs/SecretKeyEnvironment"
    },
    "guardrails": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/AiAgentGuardrails"
        }
      ]
    },
    "id": {
      "format": "uuid",
      "type": "string"
    },
    "memory": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/AiAgentMemory"
        }
      ]
    },
    "model": {
      "$ref": "#/$defs/AiAgentModelType"
    },
    "modelId": {
      "type": [
        "string",
        "null"
      ]
    },
    "modelProvider": {
      "$ref": "#/$defs/AiModelProviderType"
    },
    "name": {
      "type": "string"
    },
    "organizationId": {
      "format": "uuid",
      "type": [
        "string",
        "null"
      ]
    },
    "projectId": {
      "format": "uuid",
      "type": [
        "string",
        "null"
      ]
    },
    "runnerStatus": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/PodStatusType",
          "description": "The state of this agent's runner, when it has one.\n\nThe agent's own lifecycle and its pod's are separate, and this field is\nwhat lets a caller see the second without conflating it into the first.\nAn agent that has never been run has no pod and reports `None`; one\nwhose pod was stopped - by the owner, or by a lapsed seat culling it -\nreports [`PodStatusType::Terminated`], which is what a console renders\nas paused.\n\nPopulated only by the read paths that opt in through\n[`ViewWithCtxExt::into_view_with_ctx`], so the write paths pay nothing\nfor it.\nAbsent from the wire rather than null when there is no runner, so a\nresponse for an agent that has never run is byte-identical to before."
        }
      ]
    },
    "runnerStopReason": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/PodStopReasonType",
          "description": "What stopped the runner, when it is stopped.\n\n`runnerStatus` alone cannot say: a pause the owner performed and a stop\nbilling performed both read `terminated`, which is the whole reason this\nexists. Absent while the runner is live, and on pods stopped before it\nwas recorded.\n\n**A cause, not a prediction.** It records the stop that happened and\nnothing re-derives it afterwards, so entitlement can move underneath it\nin both directions: an owner-paused agent stays `user_requested` when\nits seat later lapses, because the cull only counts what is running,\nyet `ensure` counts every undeleted agent and will refuse it; and a\nculled agent stays `seat_lapsed` after a replacement seat is bought,\nuntil a resume clears it. Use it to explain what happened - and ask\n`ensure` whether the agent can start, rather than guessing from\nthis."
        }
      ]
    },
    "runtime": {
      "$ref": "#/$defs/AiRuntimeType"
    },
    "status": {
      "$ref": "#/$defs/AiAgentStatusType"
    },
    "tags": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "tools": {
      "$ref": "#/$defs/AiAgentTools"
    },
    "trialSeat": {
      "description": "Whether this agent occupies the owner's free-trial seat.\n\nWorth surfacing because it decides what happens when the trial ends:\nthis is the agent stopped first, ahead of the least recently used. It\nis also the only way a caller learns whether a `useTrial` create took\neffect, since that flag is ignored rather than rejected when there is\nno live trial or another agent already holds the seat.\n\nAbsent from the wire rather than `false` on the paths that do not\nresolve it, so \"not on the trial seat\" is never confused with \"not\nasked\".",
      "type": [
        "boolean",
        "null"
      ]
    },
    "triggers": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/AiAgentTriggers"
        }
      ]
    },
    "updatedAt": {
      "format": "date-time",
      "type": "string"
    },
    "userId": {
      "format": "uuid",
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "volumeId": {
      "format": "uuid",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "userId",
    "name",
    "model",
    "status",
    "tools",
    "environment",
    "runtime",
    "modelProvider",
    "createdAt",
    "updatedAt",
    "version",
    "tags",
    "active"
  ],
  "type": "object",
  "$defs": {
    "AiAgentActionPolicy": {
      "description": "How much of an action surface an agent may exercise. The wire strings are\nkebab-case because that is how the console has always persisted them.",
      "enum": [
        "read-only",
        "read-write",
        "all"
      ],
      "type": "string"
    },
    "AiAgentApiChannel": {
      "description": "The agent's own HTTP surface. It carries no API key: that credential is\nissued and held elsewhere, never on the record.",
      "properties": {
        "enabled": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "rateLimit": {
          "default": null,
          "format": "int32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentChannels": {
      "description": "The messaging surfaces an agent answers on, and their settings.\n\nNo channel here carries a credential. Slack and Telegram bot tokens live in\nthe agent's pod secret (`channel-slack` / `channel-telegram`), encrypted at\nrest, so the fields do not exist on this type and serde drops them from\nwhatever a client sends. That is the guarantee, not a strip step a writer\nhas to remember.",
      "properties": {
        "api": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentApiChannel"
            }
          ]
        },
        "slack": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentSlackChannel"
            }
          ]
        },
        "telegram": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentTelegramChannel"
            }
          ]
        },
        "whatsapp": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentWhatsAppChannel"
            }
          ]
        },
        "widget": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentWidgetChannel"
            }
          ]
        }
      },
      "type": "object"
    },
    "AiAgentChatTrigger": {
      "properties": {
        "enabled": {
          "type": "boolean"
        }
      },
      "required": [
        "enabled"
      ],
      "type": "object"
    },
    "AiAgentConnections": {
      "description": "Which connections an agent may reach: every one its tenant holds, or a\nnamed list of connection keys.",
      "oneOf": [
        {
          "$ref": "#/$defs/EveryConnection"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    },
    "AiAgentCronSchedule": {
      "properties": {
        "deliverTo": {
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "expression": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "instructions": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "timezone": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "label",
        "enabled",
        "expression"
      ],
      "type": "object"
    },
    "AiAgentDmPolicy": {
      "description": "Who may open a direct conversation with the agent on a channel.",
      "enum": [
        "open",
        "allowlist"
      ],
      "type": "string"
    },
    "AiAgentGroupPolicy": {
      "description": "Whether the agent answers every message in a group, or only when named.",
      "enum": [
        "always",
        "mention"
      ],
      "type": "string"
    },
    "AiAgentGuardrails": {
      "description": "The limits applied to an agent's behaviour.",
      "properties": {
        "actionPolicy": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentActionPolicy"
            }
          ]
        },
        "blockedActions": {
          "default": null,
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "maxBudgetUsd": {
          "default": null,
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "maxTurns": {
          "default": null,
          "format": "int32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentHandScope": {
      "description": "How much of a platform's surface a framework agent's One \"hands\" may use.",
      "enum": [
        "read",
        "write"
      ],
      "type": "string"
    },
    "AiAgentMcpServer": {
      "description": "An MCP server the agent may call.\n\nIt carries no headers: a header map is where an MCP server's bearer token\nwould sit, and a credential does not belong on the record. One that a\nclient sends is dropped, the way the channel bot tokens are.",
      "properties": {
        "name": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "url": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentMemory": {
      "description": "The console's session settings for the agent.\n\n`runtime`, `model_provider` and `model_id` are the copies the console wrote\nbefore each became a column of its own. The typed columns are what core\nreads; these are kept so a console still writing them round-trips.",
      "properties": {
        "maxSessionMessages": {
          "default": null,
          "format": "int32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "mode": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentMemoryMode"
            }
          ]
        },
        "modelId": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "modelProvider": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiModelProviderType"
            }
          ]
        },
        "runtime": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiRuntimeType"
            }
          ]
        },
        "sessionTimeout": {
          "default": null,
          "format": "int32",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentMemoryMode": {
      "description": "How much of a conversation the agent carries between messages. The wire\nstrings are kebab-case because that is how the console has always persisted\nthem.",
      "enum": [
        "stateless",
        "per-session",
        "per-user"
      ],
      "type": "string"
    },
    "AiAgentModelType": {
      "enum": [
        "haiku",
        "sonnet",
        "opus",
        "fable"
      ],
      "type": "string"
    },
    "AiAgentSlackChannel": {
      "properties": {
        "channelPolicies": {
          "additionalProperties": {
            "$ref": "#/$defs/AiAgentGroupPolicy"
          },
          "default": null,
          "propertyNames": {
            "type": "string"
          },
          "type": [
            "object",
            "null"
          ]
        },
        "enabled": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "respondToMentions": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "workspaceName": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentStatusType": {
      "enum": [
        "active",
        "paused",
        "disabled"
      ],
      "type": "string"
    },
    "AiAgentSystemTools": {
      "description": "The runtime's own tools the agent may call.",
      "properties": {
        "bash": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "codeExecution": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "fileRead": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "fileWrite": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "webFetch": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "webSearch": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentTelegramChannel": {
      "properties": {
        "allowedChatIds": {
          "default": null,
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "botUsername": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "dmPolicy": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentDmPolicy"
            }
          ]
        },
        "enabled": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "groupPolicy": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentGroupPolicy"
            }
          ]
        }
      },
      "type": "object"
    },
    "AiAgentTools": {
      "description": "What the agent may reach: its connections, the actions and methods it is\nheld to on each, and the system tools it may call.\n\nEvery field is optional and the struct defaults, so a record written before\na field existed still reads back.",
      "properties": {
        "allowedActions": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "default": null,
          "propertyNames": {
            "type": "string"
          },
          "type": [
            "object",
            "null"
          ]
        },
        "allowedMethods": {
          "additionalProperties": {
            "items": {
              "$ref": "#/$defs/Method"
            },
            "type": "array"
          },
          "default": null,
          "propertyNames": {
            "type": "string"
          },
          "type": [
            "object",
            "null"
          ]
        },
        "connections": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentConnections"
            }
          ]
        },
        "handScopes": {
          "additionalProperties": {
            "$ref": "#/$defs/AiAgentHandScope"
          },
          "default": null,
          "propertyNames": {
            "type": "string"
          },
          "type": [
            "object",
            "null"
          ]
        },
        "mcpServers": {
          "default": null,
          "items": {
            "$ref": "#/$defs/AiAgentMcpServer"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "skillIds": {
          "default": null,
          "items": {
            "$ref": "#/$defs/AiSkillId"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "systemTools": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentSystemTools"
            }
          ]
        }
      },
      "type": "object"
    },
    "AiAgentTriggers": {
      "properties": {
        "chat": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentChatTrigger"
            }
          ]
        },
        "cronSchedules": {
          "items": {
            "$ref": "#/$defs/AiAgentCronSchedule"
          },
          "type": "array"
        },
        "webhookSubscriptions": {
          "items": {
            "$ref": "#/$defs/AiAgentWebhookSubscription"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "AiAgentWebhookSubscription": {
      "properties": {
        "actionId": {
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "enabled": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "id": {
          "type": [
            "string",
            "null"
          ]
        },
        "instructions": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": [
            "string",
            "null"
          ]
        },
        "relayId": {
          "type": [
            "string",
            "null"
          ]
        },
        "relayUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "thirdPartyWebhookId": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentWhatsAppChannel": {
      "properties": {
        "allowedNumbers": {
          "default": null,
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "dmPolicy": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentDmPolicy"
            }
          ]
        },
        "enabled": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "phoneNumber": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiAgentWidgetChannel": {
      "properties": {
        "allowedOrigins": {
          "default": null,
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "enabled": {
          "default": null,
          "type": [
            "boolean",
            "null"
          ]
        },
        "publicKey": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "theme": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentWidgetTheme"
            }
          ]
        }
      },
      "type": "object"
    },
    "AiAgentWidgetPosition": {
      "enum": [
        "bottom-right",
        "bottom-left"
      ],
      "type": "string"
    },
    "AiAgentWidgetTheme": {
      "properties": {
        "placeholder": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "position": {
          "default": null,
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/AiAgentWidgetPosition"
            }
          ]
        },
        "primaryColor": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        },
        "welcomeMessage": {
          "default": null,
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "AiModelProviderType": {
      "description": "The model provider powering a framework agent's brain. Values mirror the\nwire ids the console has always written into `memory.modelProvider`\n(`openai-api`, not `openai`) so the typed column and the historical\nmarker can never disagree. Stored as text (the `Role` pattern) — the\nclosed set lives here in Rust, so admitting a provider is a code change,\nnever a Postgres enum migration.",
      "enum": [
        "anthropic",
        "openai-api",
        "gemini"
      ],
      "type": "string"
    },
    "AiRuntimeType": {
      "enum": [
        "claude",
        "hermes",
        "openclaw",
        "clockwork"
      ],
      "type": "string"
    },
    "AiSkillId": {
      "description": "Prefixed ID with 'ai_skill' prefix (e.g., 'ai_skill_1C'), also accepts raw integer",
      "type": "string"
    },
    "EveryConnection": {
      "description": "The `\"*\"` the console writes when an agent is held to no particular\nconnection.",
      "enum": [
        "*"
      ],
      "type": "string"
    },
    "Method": {
      "enum": [
        "OPTIONS",
        "GET",
        "POST",
        "PUT",
        "DELETE",
        "HEAD",
        "TRACE",
        "CONNECT",
        "PATCH"
      ],
      "type": "string"
    },
    "PodStatusType": {
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed",
        "terminated"
      ],
      "type": "string"
    },
    "PodStopReasonType": {
      "description": "Why a pod was stopped. The same operation reached two ways, and the\ndifference matters after the fact: a user pausing their runner and billing\nculling it for a lapsed seat leave an identical `terminated` row, and mean\ncompletely different things to whoever is asking why an agent went quiet -\none is \"I did that\", the other is \"resume will not help until you pay\".\n\nNull on a pod that has not been stopped, and on rows written before this was\nrecorded.\n\nDeliberately has no `Default`. \"Why did this stop\" has no sensible fallback:\nthe column is nullable precisely because *unknown* is the honest answer for\na pod stopped before it existed, and any default would answer that question\nwith a guess. `user_requested` in particular is the one value that makes a\nconsole offer a restart.",
      "enum": [
        "user_requested",
        "seat_lapsed"
      ],
      "type": "string"
    },
    "SecretKeyEnvironment": {
      "enum": [
        "test",
        "live"
      ],
      "type": "string"
    }
  }
}