Architecture philosophy

SotaAgents は platform control plane と app data plane を意図的に分離します。Platform は user、organization、workspace、installation、selected environment、exact artifact、capability を理解し、app backend は検索、CAD、専用 API、business rule など domain を理解します。

App に専用 backend が必要な理由#

• 独立 ownership：Core に domain code を追加せず独自 cadence で ship。
• Security boundary：Credential と integration を server-side に置き、signed context だけを受け入れる。
• Data boundary：Domain に合う database、retention、residency、scaling を選択。
• Operational isolation：他 app と分離して scale、fail、recover。

アシスタントはどのように tool を呼ぶのか#

Manifest への tool 宣言は物語の半分にすぎません。ここから先が、その宣言を runtime にプラットフォームがどう扱うか——アプリを単なる host 済み web service 以上のものにしている部分です。

Platform が送る request#

Body は envelope です。model の arguments は body.input に入れ子になっており、scaffold の route が request.body ではなく request.body.body.input を読むのはそのためです。

POST https://my-app.example.com/tools/example
content-type: application/json
authorization: Bearer <invocation JWT>
x-sota-core-token: <delegated Core token>   # アプリが Core tool grants を宣言した場合のみ

{
  "requestId": "01K...",
  "organizationId": "6a66...",
  "workspaceId": "6a66...",
  "appId": "my-first-project-demo",
  "hook": { "type": "tool", "name": "example" },
  "body": {
    "input":   { "message": "hello" },
    "context": { "organizationId": "…", "workspaceId": "…", "userId": "…",
                 "conversationId": "…", "agentId": "…", "toolCallId": "…", "config": {} }
  }
}

Invocation token#

Authorization header は、この 1 回の呼び出しのために発行された短命の EdDSA 署名 JWT を運びます。Backend は <core origin>/.well-known/jwks.json で公開される platform の公開鍵で検証します。アプリは Sota の秘密鍵を持たず、自ら token を発行することもありません。

各 route には最小の scope を要求してください。/tools/example の handler が求めるべきは tool:example であり、それより広い権限ではありません。Scaffold の src/backend/sota-auth.ts に、issuer・audience・algorithm・type・有効期限・tenant claim・scope という一連の検証が、再利用可能な middleware として揃っています。

Response の形#

通常の JSON HTTP response を返します。Sota 専用の wrapper を組み立てる必要はありません。

outputSchema は runtime の response に対しては検証されません。検証されるのは publish 時であり、そこで version 間の breaking change 検出に使われます。出力は境界で自分で検証してください。Schema は runtime の防御壁ではなく、consumer と renderer に対する約束としての contract です。

予約された 2 つの任意 key により、一つの結果が二つの読み手に対応できます。model 向けの簡潔な結論と renderer 向けの詳細 payload を同じ response に入れ、_sota.modelOutput で model にまったく別の射影を渡すか、_sota.modelProjection.omitKeys で renderer 専用 key を model の読む範囲から外します。model 可視の射影は約 32,000 文字で切り詰められるため、生の文書ではなく結論・ID・件数・citation に留めてください。