Prepared Execution

prepareExecutionWithResponse() は、モデル呼び出しの前に Vela の状態確認と認可を行います。結果は3種類です。

outcome	HTTP目安	意味	次の処理
blocked	400	delegationやconnectionなど、実行前の設定状態で止まった	setup / onboarding UIへ返す
deny	403	policy、model、spend limitなどでVelaが拒否した	Velaのreason messageを保って返す
allow	200相当	relay accessが発行された	初めてprovider/model runtimeを呼ぶ

Web route では Response helper を使う

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

declare const client: import("@vel4ai/sdk").VelaClient;
declare const executionScope: import("@vel4ai/sdk").VelaExecutionScope;

export async function prepareForWebRoute() {
  const vela = createVelaIntegration({ client, executionScope });
  const prepared = await vela.prepareExecutionWithResponse({
    estimatedCostUsd: 0.05,
  });

  if (prepared.outcome !== "allow") {
    return prepared.response;
  }

  return Response.json({
    model: prepared.openAiCompatibleModel,
    relayBaseUrl: prepared.openAiCompatibleClientOptions.baseURL,
  });
}

Web Responseを返せないruntime

Web Response objectを返せないruntimeでは prepareExecutionWithFailure() と HTTP descriptor helperを使います。

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

declare const client: import("@vel4ai/sdk").VelaClient;

export async function prepareForRpc(input: import("@vel4ai/sdk").VelaClientPrepareExecutionInput) {
  const prepared = await client.prepareExecutionWithFailure(input);

  if (prepared.outcome !== "allow") {
    return createPreparedExecutionFailureHttpResponse(prepared);
  }

  return {
    status: 200,
    body: { model: prepared.openAiCompatibleModel },
  };
}

重要な境界

allow 前にmodel runtimeを呼ばないでください。setup / deny pathのテストでAI SDKやprovider SDKを読み込ませたくない場合も、この境界を守ると実装とテストが分離できます。