Vela SDK Overview

Vela SDK は provider SDK ではありません。アプリが顧客の provider API key を保持せずに、委任、失効、利用状況、モデル解決、relay access、監査報告を Vela control plane に委ねるための server-side SDK です。

アプリは自分の tenant / workspace / session を持ち続けます。Vela は、その実行が今許可されているかを判定し、許可されたときだけ短命の OpenAI Compatible relay access を返します。

何を解決するか

領域	アプリが持つもの	Vela SDK が扱うもの
Identity	app user、workspace、session	Vela app credential、customerTenantId、delegationId
Consent	Hosted Connect 入口、returnUrl、保存先	connect session、delegation status、revoke
Execution	prompts、tools、UI state、retry	prepareExecution、policy deny、relay access
Provider	provider SDK 呼び出し形状	OpenAI Compatible relay configuration
Audit	app log、trace id	managed relay の completed / failed 記録、app-owned execution report

導入の標準順

1. Install & Environment で @vel4ai/sdk と VELA_APP_ID / VELA_APP_TOKEN を用意する。
2. Hosted Connect Session で顧客を Vela の委任へ接続する。
3. Execution Scope として customerTenantId / delegationId をアプリ側に保存する。
4. Protect Server Call でモデル呼び出し直前に prepareExecutionWithResponse() を呼ぶ。
5. allow のときだけ Relay Target を使ってモデルを呼ぶ。Vela-managed relay の結果は relay が記録し、app-owned execution だけ Reporting & Audit で結果を報告する。

最短で見る

Next.js + AI SDK の最短導入は Quickstart から始めてください。完成例は Next Basic Chat にあります。Python + OpenAI Agents の agentic demo は Python OpenAI Agents と Python Agentic Chat を参照してください。

実装で守る境界

• @vel4ai/sdk は framework 非依存です。AI SDK 固有の wiring は @vel4ai/ai-sdk に分けています。
• 本番アプリで VELA_CUSTOMER_TENANT_ID / VELA_DELEGATION_ID を必須 env にしません。execution scope はアプリのDB、session、Hosted Connect return URLなどから解決します。
• prepareExecutionWithResponse() が allow を返す前に model runtime を読み込まない構成にできます。
• Vela-managed relay を呼ぶrouteでは同じexecution sessionをapp側からreportしません。app-owned execution routeだけ createResultReporter() などのreport helperを使います。