Vela SDK Docs Hosted Connect and relay integration
Reference

Find helpers, troubleshooting signals, and dogfood checks.

Use this page when you need to choose the right SDK helper, debug setup signals, or run the local dogfood validation surfaces.

API map

Use the highest-level helper that matches your app boundary. Drop down to lower-level APIs only when the app needs custom model selection, batched authorization, or a non-OpenAI relay shape.

Common SDK helpers and when to use them
Helper Use when Returns or changes
getVelaEnvironmentDiagnostics() Env-driven setup should show every missing Vela variable before creating the client. Non-secret diagnostics with missingRequiredVariables and a ready-to-return message.
createVelaEnvironmentDiagnosticsHttpResponse() / createVelaEnvironmentDiagnosticsResponse() Fetch API compatible route should return SDK setup diagnostics before creating the integration. Framework-neutral { status, body } or Web JSON Response with error and missingEnv.
createVelaClientFromEnvironment() Server route has VELA_APP_ID and VELA_APP_TOKEN; VELA_BASE_URL is only a local or preview override. A credentialed VelaClient.
createVelaIntegration() Database, session, or return URL already resolved execution scope. Scoped prepare helpers that do not need repeated ID spreading.
createVelaIntegrationFromEnvironment() Local demo or env-driven route owns both credentials and execution scope in env. Credentialed client plus scoped prepare helpers.
checkVelaIntegrationReadiness() / integration.checkReadiness() Settings or onboarding should verify delegation readiness without issuing authorization or relay access. ready, reasonCode, requestedModel, and a status snapshot.
createVelaIntegrationReadinessHttpResponse() / createVelaIntegrationReadinessResponse() App-resolved scope readiness route should return readiness with the SDK's status mapping. Framework-neutral { status, body } or Web JSON Response with status 200 or 400.
createVelaIntegrationReadinessResponseFromEnvironment() Env-driven readiness route should combine missing env diagnostics, readiness, and unexpected errors. Web JSON Response with ready, missingEnv, reasonCode, or error.
resolveVelaExecutionScope() Saved JSON, DB payload, or localStorage value needs validation. VelaExecutionScope or null.
resolveVelaExecutionScopeFromUrl() Hosted Connect returned to the app with Vela query parameters. customerTenantId, delegationId, optional model.
prepareExecutionWithResponse() Fetch API compatible route can return Web Response. Allowed relay target or ready-to-return non-allow response.
createOpenAiCompatibleUsageReportInput() Raw fetch receives OpenAI-compatible usage. Usage input for tryReportCompletedWithUsage().
createResultReporter() Streaming callbacks can call success and failure reporting paths. Idempotent reporting methods with non-throwing variants.
createVelaErrorHttpResponse() / createVelaErrorResponse() Unexpected route errors should return the same normalized { error } body. Framework-neutral descriptor or Web JSON Response with a fallback message.
@vela/ai-sdk prepareVelaStreamTextWithResponse() AI SDK route has a Vela integration and Web Response boundary. Ready-to-return non-allow response or allowed result with createStreamTextInput().
@vela/ai-sdk createVelaStreamTextInput() AI SDK streamText() route should merge app-owned fields with Vela-controlled model and callbacks. A single streamText() input with messages, system, tools, model, onAbort, onError, and onFinish.
@vela/ai-sdk createVelaStreamTextOptions() AI SDK route wants model and callbacks separate from app-owned streamText() fields. AI SDK chat model plus onAbort / onError / onFinish callbacks.
@vela/ai-sdk createVelaOpenAI() AI SDK route wants model creation separate from report callbacks. AI SDK OpenAI-compatible provider, chat model, and model ID.
@vela/ai-sdk createVelaStreamTextCallbacks() AI SDK streamText() should report finish, error, and abort results. onAbort / onError / onFinish callbacks wired to Vela audit reporting.
@vela/ai-sdk createVelaStreamCallbacks() App code already created an ExecutionResultReporter. The same AI SDK onAbort / onError / onFinish callbacks without recreating the reporter.

Troubleshooting

The fastest debug path is to keep the SDK signals intact. Return missingEnv, ready, outcome, reasonCode, and requestedModel from server routes before adding app-specific copy around them.

Common integration signals and the next action
Signal What it means Next action
missingEnv getVelaEnvironmentDiagnostics() found setup gaps before creating the client. Set the listed App credential env vars. VELA_BASE_URL is only a local or preview override; execution scope is resolved outside required env.
ready: false integration.checkReadiness() found a delegation or API Clip issue without authorizing execution. Show the readiness reasonCode, reopen Hosted Connect, or ask the app to choose an allowed requestedModel.
outcome: "blocked" The execution setup is not usable, such as inactive delegation or missing connection state. Return prepared.response, keep the model uncalled, and route the user back to connection setup.
outcome: "deny" Vela policy denied an otherwise reachable delegation, for example model, spend, request, or ZDR policy. Return the SDK response with reasonCode; let the user select an allowed model or update policy.
onReportError The model path completed or failed, but the audit report API had its own error. Keep the model result primary, send telemetry, and rely on tryReport... methods to avoid replacing the original route result.
AI runtime loads on setup path A route imported @vela/ai-sdk or ai before knowing the execution was allowed. Use core prepareExecutionWithResponse() first, then dynamically import both packages only after allow.

Integration checklist

A Vela integration is complete when the app proves every model execution passes through the delegated, revocable, audited path.

Application responsibilities

  • Register an app in Developer Console and keep the App token server-side.
  • Open Hosted Connect from the app settings or onboarding flow.
  • Persist customerTenantId and delegationId in the app source of truth.
  • Expose a readiness check before users send chat messages. Use createVelaIntegrationReadinessResponseFromEnvironment() for env-driven routes, or integration.checkReadiness() when the app has already resolved scope.
  • Preserve missingEnv, ready, outcome, reasonCode, and requestedModel in supportable API responses.
  • Call prepareExecution... before every model request.
  • Only call the relay when prepared execution is allow.
  • Report completed usage or failure for audit.

Dogfood references in this repo

  • examples/next-basic-chat/app/api/chat/route.ts: thin Next.js route entrypoint.
  • examples/next-basic-chat/app/api/chat/handler.ts: AI SDK route logic with core prepare and allow-only createVelaStreamTextInput().
  • examples/next-basic-chat/app/api/vela/readiness/route.ts: Vela env and delegation readiness endpoint.
  • examples/next-basic-chat/app/assistant.tsx: client-side readiness status strip before chat usage.
  • examples/nextjs/src/index.ts: thin Next.js SDK wrapper for Hosted Connect and server execution prepare.
  • examples/nextjs/src/index.test.ts: wrapper behavior test for env credentials, connect sessions, and prepared execution calls.
  • packages/sdk-ai-sdk/README.md: optional AI SDK adapter package.
  • apps/dogfood/local-chat/app/assistant.tsx: assistant-ui demo with scoped integration and idempotent reporter.
  • apps/dogfood/local-chat/lib/vela-demo.ts: Hosted Connect return URL scope and raw fetch relay call.
  • docs/sdk/integration-guide.md: longer server-side integration guide.
  • packages/sdk-core/README.md: exported helper summary.

Local docs are static. Run the SDK and demo gate with pnpm check:sdk. Run the Console / Dashboard / SDK boundary smoke with pnpm smoke:dogfood; it verifies the assistant-ui demo return URL builder strips stale scope, opens Hosted Connect through SDK createConnectSession(), then verifies the Return to app URL through the same demo scope helper before SDK readiness, execution report, Dashboard revoke, delegation relay invalidation, API Clip revoke block, relay credential invalidation, app-side execution block, and scope cleanup checks. Run the Worker API / relay gate with pnpm check:api. Run the full repo dogfood gate with pnpm check:dogfood. Check the SDK core with pnpm --filter @vela/sdk test and pnpm --filter @vela/sdk typecheck. Check the AI SDK adapter with pnpm --filter @vela/ai-sdk test and pnpm --filter @vela/ai-sdk typecheck. Check the thin Next.js SDK wrapper with pnpm --filter @vela/example-nextjs test and pnpm --filter @vela/example-nextjs typecheck. Check the Next basic chat demo with pnpm --filter @vela/example-next-basic-chat test, pnpm --filter @vela/example-next-basic-chat lint, pnpm --filter @vela/example-next-basic-chat typecheck, and pnpm --filter @vela/example-next-basic-chat build. Check the assistant-ui dogfood demo with pnpm --filter @vela/assistant-ui-demo test, pnpm --filter @vela/assistant-ui-demo lint, pnpm --filter @vela/assistant-ui-demo typecheck, and pnpm --filter @vela/assistant-ui-demo build. Run pnpm assistant-ui-demo:deploy to publish the root-path static export to the vela-assistant-ui-demo Cloudflare Pages project. Run the local dogfood surfaces with pnpm dev:vela for the control plane at http://localhost:4000, pnpm dev:next-basic-chat for the server-side AI SDK chat sample at http://localhost:3000, and pnpm dev:assistant-ui-demo for the browser-side assistant-ui demo at http://localhost:4100. The top Demo AI App link also opens the local 4100 surface; for SDK dogfood, use pnpm dev:assistant-ui-demo. Run one 4100 demo surface at a time because pnpm dev:ai-app and pnpm dev:assistant-ui-demo both bind that port. Run pnpm docs:check for the static docs check; it compiles the marked TypeScript snippets on this page and a package import smoke for the public @vela/sdk / @vela/ai-sdk APIs. Open this file directly, or run pnpm dev:docs to serve the same apps/docs/public directory through Cloudflare Pages dev. Run pnpm docs:smoke to verify the static preview responds with the SDK docs page. Deploy the static surface with pnpm docs:deploy.