Manifest の説明

manifest.yaml はアプリと SotaAgents 間の宣言的 contract です。Identity、contribution、backend、load 可能な native module、platform compatibility を記述します。Server が再検証するため、client manifest は authority ではありません。未知の property は即座に拒否されます。正確な JSON Schema は sota manifest schema、個々の field の解説は sota manifest explain contributes.tools で確認してください。

Root field のうち manifestSchemaVersion、appId、version、publisher、contributes の 5 つが必須で、それ以外はすべて任意です。

YAML

manifestSchemaVersion: 3
appId: my-first-project-demo
version: 1.0.0
displayName: "My First Project Demo"
description: "SotaAgent app."
publisher:
  id: local-dev
  displayName: "Local Dev"
  contact: dev@local-dev.example

contributes:
  skills:
    - name: example
      description: Example content-backed skill.
      appendsTo: system
      content: src/skills/example
      timeoutMs: 3000
      failure_mode: skip
  tools:
    - name: example
      description: Example tool that echoes its input and verified tenant context.
      route: POST /tools/example
      inputSchema: src/schemas/tool-input.schema.json
      outputSchema: src/schemas/tool-output.schema.json
      timeoutMs: 15000
      failure_mode: abort
  ui:
    - id: admin-screen
      kind: nativeModule
      surface: page
      slot: admin.workspace.tab
      sectionId: my-first-project-demo
      label: Admin screen
      route: /admin/*
      module:
        entry: dist/ui/app.js
        export: AdminScreen
        styles: dist/ui/app.css

service:
  baseUrl: https://my-first-project-demo.example.com
health:
  url: https://my-first-project-demo.example.com/health
  intervalSeconds: 60
platform: ^1.2.0
locales:
  default: en
  files:
    en: src/locales/en.json

Identity は安定値です。appId を永続的な public identifier として扱います。
Version は artifact ごとに immutable です。Bytes を変更したら version を上げます。
Contribution だけが platform に公開可能です。
Environment overlay は local、stg、prod という任意の override です。Root service が hosted default、local は sota dev 用です。Global --origin は SotaAgents deployment を選び、各 command の -e は保存済み profile／overlay を選択します。

各 native UI surface と public runtime API は、この manifest reference の後に専用 page として説明します。

YAML

service:
  baseUrl: https://my-app.example.com
health:
  url: https://my-app.example.com/health
  intervalSeconds: 60

environments:
  local:
    service:
      baseUrl: http://127.0.0.1:8787
    health:
      url: http://127.0.0.1:8787/health
  stg:
    service:
      baseUrl: https://stg.my-app.example.com
  prod:
    service:
      baseUrl: https://my-app.example.com

Localhost は environments.local にだけ書けます。

Base manifest は deploy 可能なアプリを記述するものです。Root の service に 127.0.0.1 を書くと拒否されます。また deploy 用 base URL が .invalid のままなら、実際の host 済み backend が未設定ということです。

Tool を宣言する#

Tool は、アシスタントが backend に到達するための入口です。contributes.tools に一度宣言すれば、model に何が提示されるか、request がどう route されるか、どう認証されるか、どれだけ時間を使えるか——その他すべてを platform がその宣言から導きます。Schema は閉じているため、宣言にない key は validation で失敗します。

Field	必須	規則
`name`	必須	安定した public identifier。先頭は小文字、以降は英数字とハイフン。ドットで区切ることもでき（例：`documents.query`）、各セグメントは最大 64 文字。Release 後は変更しないでください。Prompt、renderer、保存済み conversation がこの名前を参照します。
`description`	必須	空不可。tool を呼ぶかどうかを model が判断するときに読むテキストそのものです。いつ使うか、backend が何をするか、何が返るか、前提条件は何かを書いてください。名前の言い換えでは不十分です。
`route`	必須	`METHOD /path` 形式。method は `GET`、`POST`、`PUT`、`PATCH`、`DELETE` のいずれかで、path は `/` 始まり。Path は有効な environment の `service.baseUrl` に対して解決され、その origin の外には出られません。`POST` を宣言してください。アシスタントの呼び出し経路は arguments を JSON body で送り、scaffold も各 system app も `POST /tools/<name>` を使います。
`inputSchema`	必須	アプリ内の JSON Schema ファイルへの path、または inline の schema object。明示的な `required`、`additionalProperties: false`、上限のある string／array、既知の mode には enum を推奨します。
`outputSchema`	必須	Input schema と同じ形式。結果が単純でも必須です。backend が守るべき contract を文書化します。
`timeoutMs`	任意	正の整数。Artifact 生成時に最大 30,000 ms へ clamp されます。必ず宣言してください。未宣言の tool は host 済み backend では wall-clock の上限を持たず、Development tunnel でのみ 10 分に制限されます。
`failure_mode`	任意	`abort` または `skip`。Tool の既定は `abort` です。失敗を失敗として報告すべき場合は `abort`、その contribution が本当に任意で、無くてもアシスタントが誠実に回答できる場合にだけ `skip` を選びます。失敗した書き込みや重要な照会を、体裁の良い応答で隠さないでください。
`searchHint`	任意	Tool を見つけやすくする追加キーワード。空不可。
`undoable`	任意	Boolean。取り消し可能な action であることを示します。
`configGate`	任意	App config の key。その config key が存在する場合にのみ tool が提示されます。

宣言が指す schema ファイルは通常の JSON Schema です。Compiler がそれらを解決して artifact に inline するため、参照されたファイルは build／deploy より前に存在している必要があります。Local の smoke test でその route を通らない場合でも同様です。

JSON

// src/schemas/tool-input.schema.json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Message for the example tool to echo."
    }
  },
  "required": ["message"]
}

Tool を一つでも宣言すると service が必須になります。Platform が送信先を知る必要があるためです。Tool 名は一つの manifest 内で一意でなければならず、surface: tool-view の UI contribution は contributes.tools に実在する名前を toolNames に列挙する必要があります。宣言していない tool に紐づく renderer は validator が拒否します。またインストール済みの 2 つのアプリが同じ tool 名の renderer を主張することはできず、後から入ったアプリが競合した名前を失います。

Platform がこの宣言をその後どう扱うか——model が見る名前、signed request、response の contract——は Architecture philosophy を参照してください。

Resolved surface overview を表示する Staging app detail — Exact artifact に宣言された tool、skill、UI slot、prompt、grant だけが公開されます。