---
title: "Manifest の説明"
description: "manifest.yaml はアプリと SotaAgents 間の宣言的 contract です。Identity、contribution、backend、load 可能な native module、platform compatibility を記述します。Server が再検証するため、client manifest は authority で…"
url: "https://sotaagents.ai/ja/manual/developer-guide/manifest-explained"
generated_by: "sotaagents-ldp"
docs_index: "https://sotaagents.ai/manual/llms.txt"
locale: "ja"
---

# 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
```

> [!WARNING]
> 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](/manual/assets/developer/app-surface-overview.webp)
_Exact artifact に宣言された tool、skill、UI slot、prompt、grant だけが公開されます。_