Execution Scope

execution scope は、どの顧客のどの委任で実行するかを表す最小の入力です。

field	説明
customerTenantId	Vela上の顧客tenant。アプリ側のworkspaceやaccountに紐付けて保存します。
delegationId	Hosted Connectで作成または再利用された委任。
requestedModel	互換用の任意model input。新規実装では modelSlot や modelRequirement を優先します。

Hosted Connect return URL

Hosted Connectから戻るURLには velaCustomerTenantId、velaDelegationId、任意の velaRequestedModel が付与されます。手書きparseではなく resolveVelaExecutionScopeFromUrl() を使います。

import { resolveVelaExecutionScopeFromUrl } from "@vel4ai/sdk";

export function readScopeFromReturnUrl(href: string) {
  const scope = resolveVelaExecutionScopeFromUrl(href);

  if (!scope) {
    throw new Error("Hosted Connect return URL に execution scope がありません。");
  }

  return scope;
}

保存済みobject

DB、session、localStorage、request bodyから復元する場合は resolveVelaExecutionScope() で正規化します。不完全な値では null を返します。

import { resolveVelaExecutionScope } from "@vel4ai/sdk";

export function readScopeFromRequestBody(body: unknown) {
  const scope = resolveVelaExecutionScope(body);

  if (!scope) {
    return Response.json(
      { error: "Vela execution scope がありません。" },
      { status: 400 },
    );
  }

  return scope;
}

VelaIntegration にbindする

scopeを解決した後は、毎回 customerTenantId / delegationId をspreadせず、createVelaIntegration() にbindします。

import { createVelaClientFromEnvironment, createVelaIntegration } from "@vel4ai/sdk";

declare const process: { env: Record<string, string | undefined> };
declare const executionScope: import("@vel4ai/sdk").VelaExecutionScope;

export const vela = createVelaIntegration({
  client: createVelaClientFromEnvironment({ env: process.env }),
  executionScope,
});