# Welcome to Vaultkit Docs
Source: https://docs.vaultkit.dev/index
From Zero to Agentic Chat with User Data in Minutes.
# Welcome to Vaultkit Docs
Begin your integration with the Vaultkit SDK resources below:
* [Core Concepts](sdk-concepts)
* [Vaultkit SDK Overview](sdk-overview)
* [SDK Quickstart](sdk-quickstart)
* [SDK Configuration](sdk-configuration)
# Backend Integration
Source: https://docs.vaultkit.dev/sdk-backend-integration
Use Vaultkit for internal agents, scheduled jobs, and server-side automation without UI components.
# Backend Integration
Vaultkit isn't just for user-facing applications. You can also use it for:
* **Internal agents** (backend services that act on behalf of users)
* **Scheduled jobs** (automated tasks that need to call external APIs)
* **Multi-tenant systems** (per-user vault provisioning on the server)
The key difference from user-facing flows is that there's no UI component layer—you're managing vaults and connections directly.
## Pre-configured vaults (simplest)
If you have a static vault already set up in the Vaultkit dashboard, you can connect directly without any UI. For an introduction to vaults and how they work, see [Core Concepts](sdk-concepts#vault).
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
// Backend service connecting to a pre-configured vault
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: "user_123", // the end user this action is on behalf of
vaultId: "vault_abc123", // your pre-configured vault
});
await vaultkit.connect();
// vaultkit.tools is now ready to use with your LLM or directly
console.log(`Connected. Found ${vaultkit.tools.length} tools.`);
// Use tools directly or pass to your LLM runtime
const result = await vaultkit.tools[0].execute({ /* params */ });
```
## Dynamic vault provisioning (per-user)
For multi-tenant systems where each user gets their own vault, use feature mappings:
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
async function provisionUserVault(userId: string) {
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: userId,
featureMappingId: "feat_internal_automation", // your feature template
});
await vaultkit.connect();
// Vaultkit automatically created/found a vault for this user
return vaultkit.tools;
}
```
The first time a user connects, Vaultkit creates a vault from the feature mapping. Subsequent calls reuse the existing vault.
## Restricting providers and scopes
You can further limit which providers or permissions a vault has:
```ts theme={null}
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: "user_456",
featureMappingId: "feat_automation",
selectedProviders: ["gmail", "slack"], // only enable these two
selectedScopes: ["read"], // read-only access
});
await vaultkit.connect();
```
This is useful for:
* **Least privilege**: Only enable the providers a job actually needs
* **Customer restrictions**: Limit what an agent can do for a particular user
* **Testing**: Create isolated vaults with limited permissions
## Example: Scheduled email automation
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
async function dailyEmailDigest(userId: string) {
// Get tools for this user's vault
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: userId,
vaultId: "vault_email_digest", // pre-configured vault for this job
});
await vaultkit.connect();
// Use with Vercel AI SDK to generate an email
const { text } = await generateText({
model: openai("gpt-4"),
tools: vaultkit.tools,
prompt: "Create a daily digest of unread emails and send a summary.",
});
console.log(`Digest sent for user ${userId}`);
return text;
}
// Run daily via cron, GitHub Actions, etc.
await dailyEmailDigest("user_789");
```
## Error handling
Backend flows should handle disconnections and retries:
```ts theme={null}
import { AuthenticationError, ConnectionError } from "@vaultkit/ai-sdk";
try {
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: userId,
vaultId: vaultId,
retries: 5, // more retries for reliability
timeout: 60000, // longer timeout for batch jobs
});
await vaultkit.connect();
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Invalid API key or vault ID");
// Handle auth failure (don't retry)
} else if (error instanceof ConnectionError) {
console.error("Network error - may retry");
// Retry logic here
}
}
```
## Logging and observability
For backend services, enable detailed logging:
```ts theme={null}
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY,
userId: userId,
vaultId: vaultId,
log: (level, message, data) => {
// Send to your observability stack (DataDog, New Relic, etc.)
console.log(`[vaultkit:${level}] ${message}`, data);
},
});
```
## No UI components needed
Backend flows don't use `FeatureSelect`, `AuthComponent`, or `VaultkitProvider`. Manage everything programmatically with `createVaultkitClient` directly.
For more configuration options, see [SDK Configuration](sdk-configuration).
# Core Concepts
Source: https://docs.vaultkit.dev/sdk-concepts
Learn the key Vaultkit primitives—features, vaults, tools, providers, and approvals—before wiring the SDK into your product.
# Core Concepts
Vaultkit’s SDK mirrors the same objects you configure in the dashboard. Understanding how they fit together helps you reason about what the UI components render and which credentials your agent receives.
## Feature
A **feature** is the customer-facing bundle you expose in your product (for example “Email assistant”). Features are created in the dashboard and include:
* A title and description your end users recognize.
* The list of **providers** (integrations) required for that capability.
* The scopes/permissions each provider needs.
* An optional connection to a specific vault (static mode) or instructions for generating one per user (dynamic mode).
`FeatureSelect` surfaces these features so end users can opt into the flows they need.
## Provider
A **provider** represents an external service (Gmail, Outlook, Slack, GitHub, etc.) exposed through Vaultkit. Providers are attached to features and vaults, and they determine which OAuth buttons appear in `AuthComponent`.
## Vault
A **vault** is a per-user configuration that defines which providers and tools are available to your agent. Think of it as a permission set—it specifies what providers (Gmail, Slack, etc.) the user has connected and what tools the agent is allowed to call on their behalf.
Vaults can be created two ways:
* **Static** – One vault with a fixed set of providers. You create this in the dashboard and reuse the same vault ID across multiple users. Best for internal agents and backend services where all users need the same set of tools. For example, a scheduled email job might have a vault with just Gmail connected.
* **Dynamic** – One vault per user, created automatically when they enable a feature. Best for user-facing apps where different users might select different providers.
**Note:** Features are optional. They exist to help app builders organize which providers are available to users. For internal agents, you can skip features entirely and create a vault directly with whatever providers you need.
When `createVaultkitClient()` connects, it looks up the vault, verifies which providers are connected, and returns the list of available tools your agent can call.
## Tool
A **tool** is an executable action (usually proxied through Composio) that your agent can call, such as “Send Gmail message” or “Create GitHub issue.” Tools are attached to vaults; when `createVaultkitClient().connect()` runs, it returns the list of tools the agent is allowed to use. These map directly onto the tool schema you pass into the Vercel AI SDK or another LLM runtime.
## Approval *(coming soon)*
An **approval** is a human-in-the-loop gate on a tool. This capability is on our roadmap; when released, the dashboard will let you flag sensitive tools, the SDK will raise an `ApprovalError` until an operator decides, and telemetry will record each decision. For now, treat approvals as a planned enhancement.
## How they relate
```text theme={null}
Feature (Email assistant)
├── Providers: Gmail, Outlook
├── Scopes: read, send, delete
└── Vault(s)
├── Static vault (shared) or dynamic per end user
└── Tools (Send email, Draft reply, Archive thread)
```
1. You define the feature and its providers in the dashboard.
2. End users enable the feature via `FeatureSelect` and authenticate each provider through `AuthComponent`.
3. The SDK resolves the vault tied to that feature/user and exposes the tool list to your agent.
4. Approvals and telemetry keep humans in control of sensitive actions.
Keep this mental model handy while building—every SDK call maps back to these primitives.
# SDK Configuration
Source: https://docs.vaultkit.dev/sdk-configuration
Explore every option supported by createVaultkitClient and how to tailor the connection to your needs.
# SDK Configuration
`createVaultkitClient` accepts a `VaultkitConfig` object. Use it to control authentication, timeouts, retries, logging, and the way dynamic vaults are generated.
## Required properties
Always provide these three values when creating a client:
| Property | Type | Description |
| --------------------------------- | -------- | ------------------------------------------------------------------------------- |
| `apiKey` | `string` | Your Vaultkit API key (represents your organization). |
| `userId` | `string` | Identifier for the end user the agent is acting on behalf of. |
| `vaultId` *or* `featureMappingId` | `string` | Either a static vault ID, or a dynamic vault template ID. Only one is required. |
> **About static vs. dynamic vaults:**
>
> * Use `vaultId` if you have a pre-configured vault in the Vaultkit dashboard.
> * Use `featureMappingId` to generate vaults on demand. Vaultkit will create a per-user vault the first time `connect()` is called.
## Optional properties
Fine-tune behavior with these optional settings:
| Property | Type | Default | Purpose |
| ------------------- | --------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `selectedProviders` | `string[]` | `undefined` | Restrict which providers to activate for dynamic vaults. Must be a subset of the feature mapping's providers. |
| `selectedScopes` | `string[]` | `undefined` | Further limit provider permissions for dynamic vaults. |
| `timeout` | `number` | `30000` | Timeout (ms) for discovery requests made during `connect()`. |
| `retries` | `number` | `3` | Retry attempts for transient network failures. |
| `baseUrl` | `string` | `https://app.vaultkit.dev` | Only set this if using a self-hosted or custom Vaultkit instance. Default points to production. |
| `log` | `(level, message, data?) => void` | Lightweight console logger | Receive verbose status messages (`info`, `warn`, `error`). Useful for piping diagnostics to your observability stack. |
## Example: Interactive flow (recommended)
This is the typical flow for apps with user-facing UIs. Users select features and authenticate providers through the SDK UI components, then you create a client with the resulting vault.
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
// After user has selected a feature via FeatureSelect UI
// and authenticated providers via AuthComponent
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY!,
userId: currentUser.id,
vaultId: userSelectedVault.id, // from FeatureSelect UI state
});
await vaultkit.connect();
```
## Example: Programmatic flow (advanced)
Use this only when you need to dynamically provision vaults server-side without user interaction.
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
// Backend agent or automation service that provisions vaults on demand
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY!,
userId: targetUser.id,
featureMappingId: "feat_customer_support", // pre-configured feature template
selectedProviders: ["gmail", "slack"], // optional: restrict providers
selectedScopes: ["read", "write"], // optional: restrict permissions
timeout: 45_000, // optional: increase for slower networks
retries: 5, // optional: more retries for unreliable connections
log: (level, message, meta) => {
console[level]("[vaultkit]", message, meta ?? "");
},
});
await vaultkit.connect();
```
## Example: Backend/Internal agent (no UI)
For internal services and scheduled jobs, use pre-configured vaults without any UI components:
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
// Scheduled job or internal service
// No user interaction, just programmatic access
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY!,
userId: "user_to_act_on_behalf_of",
vaultId: "vault_daily_digest", // pre-configured in dashboard
retries: 5, // higher retries for batch jobs
timeout: 60_000, // longer timeout
});
await vaultkit.connect();
// vaultkit.tools is now ready to use
```
For more details on backend integration patterns, see [Backend Integration](sdk-backend-integration).
## Inspecting the client
`createVaultkitClient` returns a small API:
* `vaultkit.tools` – Getter that exposes the array of Vaultkit tools after `connect()` succeeds.
* `await vaultkit.connect()` – Resolves the correct vault and fetches tools. It also handles dynamic provisioning when `featureMappingId` is present.
* `await vaultkit.disconnect()` – Clears in-memory tool state. Call this in `finally` blocks to avoid leaking resources.
If you need to share discovery results across multiple requests (for example in a long-lived worker), keep the client in a module-level cache and call `connect()` once during startup.
# Dynamic Vault Provisioning
Source: https://docs.vaultkit.dev/sdk-dynamic-vaults
Generate per-user vaults on demand using feature mappings and the Vaultkit SDK.
# Dynamic Vault Provisioning
Dynamic vaults let you expose a single feature to customers while Vaultkit quietly provisions a dedicated vault for each end user. This keeps credentials scoped and auditable without leaking internal IDs to your integrators.
## How it works
1. Configure a **feature mapping** in the Vaultkit dashboard ([Dashboard → Feature Mappings](https://app.vaultkit.dev/dashboard/features)) in either static or dynamic mode. Set the feature name, description, providers (for example Gmail, Outlook), and the scopes each provider requires. This metadata is what `FeatureSelect` and `AuthComponent` render to end users.
2. Pass the mapping’s ID to the SDK via `featureMappingId`.
3. When `connect()` runs, the SDK checks whether a vault already exists for the end user.
* If it exists, the SDK reuses it and loads the available tools.
* If not, it calls `POST /api/vaultkit/generate-vault`, creates a vault with the permitted providers and scopes, and returns the new ID.
4. Tool discovery continues as normal and your agent receives the merged toolset.
## Basic implementation
```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY!,
userId: customer.id,
featureMappingId: "feat_github_triage",
});
await vaultkit.connect();
```
## Limiting providers and scopes
Dynamic mappings can allow multiple providers. If you want to capture user intent at runtime (for example GitHub **and** Slack vs. GitHub only), pass the user’s selection to the SDK.
```ts theme={null}
const vaultkit = createVaultkitClient({
apiKey: env.VAULTKIT_API_KEY,
userId: customer.id,
featureMappingId: "feat_dynamic_support",
selectedProviders: customer.selectedProviders,
selectedScopes: customer.selectedScopes,
});
```
The SDK enforces that the requested providers/scopes are subsets of what the feature mapping allows. Anything outside that set results in an `AuthenticationError`.
## Persisting generated vaults
The SDK exposes everything it learns while provisioning:
```ts theme={null}
const vault = await vaultkit.connect();
console.log(
"Resolved vault ID:",
vaultkit.tools.length ? vaultkit.tools[0].vaultId : "(in tools metadata)"
);
```
If you need to surface the generated vault ID elsewhere (for example to show in your admin tools), listen to the responses from your own API layer. The Vaultkit REST API returns `generated_vault_id` in the payload from `/api/vaultkit/generate-vault`.
## Pair with the Feature Selection component
`FeatureSelection` (exported from `@vaultkit/ai-sdk`) gives end users a UI for choosing which features and providers to enable. It writes the user’s choices into the shared context so you can feed them into the client before calling `connect()`.
```tsx theme={null}
import { FeatureSelection, VaultkitProvider, useVaultkit } from "@vaultkit/ai-sdk";
function FeatureStep() {
const { selectedFeatures, getSelectedProviders } = useVaultkit();
// Use these helpers to populate selectedProviders / selectedScopes when connecting
return ;
}
```
Once the user confirms their selection, create a client with the chosen feature mapping ID and call `connect()` as shown above.
# Error Handling
Source: https://docs.vaultkit.dev/sdk-error-handling
Use the Vaultkit SDK’s typed errors to build resilient agents and human-in-the-loop workflows.
# Error Handling
The SDK wraps every failure in a typed `VaultkitError` subclass so you can decide how the agent should respond. Catch these errors around your calls to `connect()` or inside the logic that executes tools.
## Error classes
| Error | When it is thrown | Typical response |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `AuthenticationError` | Missing/invalid API key, conflicting `vaultId`/`featureMappingId`, revoked credentials, or forbidden provider selection. | Rotate credentials, prompt the user to reconnect, or fall back to a limited experience. |
| `ConnectionError` | Vaultkit service is unreachable or network retries were exhausted. | Retry with backoff, surface a status badge, or queue work for later. |
| `ToolError` | A tool failed to execute (for example invalid parameters returned by the LLM). | Show the error to the end user or ask the agent to reformulate the request. |
| `ApprovalError` | The tool requires a human decision before continuing. | Pause the workflow, notify an operator, or poll the approval endpoint until a decision is made. |
All error classes extend `VaultkitError`, which exposes `message`, `code`, and an optional `statusCode`.
## Pattern example
```ts theme={null}
import {
createVaultkitClient,
AuthenticationError,
ConnectionError,
ToolError,
ApprovalError,
} from "@vaultkit/ai-sdk";
export async function runAgent(prompt: string) {
const vaultkit = createVaultkitClient({
apiKey: process.env.VAULTKIT_API_KEY!,
userId: "customer-123",
vaultId: process.env.VAULTKIT_VAULT_ID,
});
try {
await vaultkit.connect();
const response = await agentRunner({ prompt, tools: vaultkit.tools });
return { ok: true, data: response };
} catch (error) {
if (error instanceof AuthenticationError) {
return { ok: false, reason: "invalid-credentials" };
}
if (error instanceof ApprovalError) {
queueApprovalNotification(error);
return { ok: false, reason: "awaiting-approval" };
}
if (error instanceof ConnectionError) {
scheduleRetry({ prompt });
return { ok: false, reason: "retrying" };
}
if (error instanceof ToolError) {
return { ok: false, reason: "tool-failure", details: error.message };
}
throw error; // bubble up unexpected failures
} finally {
await vaultkit.disconnect();
}
}
```
## Logging helpers
Pass a `log` function to `createVaultkitClient` to receive structured messages about connection attempts, discovered tools, timeouts, and retries. This makes it easy to correlate application logs with Vaultkit’s telemetry in production.
```ts theme={null}
const vaultkit = createVaultkitClient({
apiKey,
userId,
vaultId,
log: (level, message, meta) => {
logger[level]({ message, ...meta, source: "vaultkit" });
},
});
```
Pair the SDK logs with the Vaultkit dashboard → Tool Telemetry screen to monitor the full lifecycle of each request.
# Vaultkit SDK Overview
Source: https://docs.vaultkit.dev/sdk-overview
Understand what the @vaultkit/ai-sdk package provides and how it fits into the Vaultkit platform.
# Vaultkit SDK Overview
The `@vaultkit/ai-sdk` package is the fastest way to wire an AI agent into Vaultkit. It handles vault resolution, tool discovery, and approval-aware execution so you can focus on the business logic that drives your agent. If you are new to Vaultkit terminology, review the [Core Concepts](sdk-concepts) first.
## What the SDK Provides
* **Unified client** – `createVaultkitClient` connects an agent to Vaultkit, validates credentials, and retrieves the tool definitions exposed by the customer’s vault.
* **Dynamic vault provisioning** – Optional feature mappings let Vaultkit create per-user vaults on demand without exposing internal IDs to integrators.
* **Typed error surfaces** – Consistent error classes (`AuthenticationError`, `ConnectionError`, `ToolError`, `ApprovalError`) let you react to auth failures, network issues, or human approval workflows.
* **UI primitives** – Drop-in React components (`FeatureSelection`, `VaultkitAuthComponent`, `VaultkitConnectionManager`) expose onboarding, OAuth, and connection management flows that talk directly to your Vaultkit workspace.
* **Context for advanced apps** – `VaultkitProvider` and `useVaultkit` share state across components so you can compose custom dashboards or embed Vaultkit inside your product.
## How the SDK Fits in
```text theme={null}
Agent runtime (Edge Function, Worker, Server) ─┬─ @vaultkit/ai-sdk client
└─ Vercel AI SDK / LangChain / custom stack
│
├─ Vaultkit API (vault configuration, approvals, telemetry)
│
└─ Composio tool catalog + provider OAuth flows
```
1. Your agent calls `createVaultkitClient` with a Vaultkit API key and either a `vaultId` or `featureMappingId`.
2. The client resolves the vault that should be used for the end user, fetches the tool schemas, and exposes them to your AI runtime.
3. Optional UI components handle the human-in-the-loop steps (feature selection, provider OAuth, connection management).
4. Vaultkit records telemetry and approval decisions, so your operations team can audit the workflow in the dashboard.
## Use Cases
The SDK supports two primary patterns:
### User-facing agents
Your customers interact with your application and select which tools/providers to enable. You use UI components (`FeatureSelect`, `AuthComponent`) to guide them through feature selection and OAuth, then connect agents on their behalf.
**Best for:**
* SaaS applications with multiple end users
* Self-service onboarding experiences
* Giving users control over which providers to connect
**Start with:** [SDK Quickstart](sdk-quickstart)
### Internal/backend agents
Your service connects to pre-configured vaults and acts autonomously (no user interaction needed). Common use cases: scheduled jobs, internal automation, multi-tenant backends.
**Best for:**
* Scheduled jobs (daily digests, data syncing)
* Internal services and microservices
* Backend automation that doesn't need user interaction
**Start with:** [Backend Integration](sdk-backend-integration)
Both paths use the same `createVaultkitClient` core—the difference is whether you include UI components and how you manage vault configuration.
## When to Use It
Use the SDK when you need to:
* Let an agent act on behalf of a customer while respecting Vaultkit's approval policies.
* Dynamically assemble toolkits per end user or per feature without provisioning infrastructure manually.
* Give customers a self-service UI for connecting providers and managing their vault access (or manage vaults programmatically).
* Integrate with the Vercel AI SDK (or any runtime that accepts a tool array) without hand-writing discovery logic.
If you only need REST access to Vaultkit without any AI tooling, the raw Vaultkit API may be sufficient. Otherwise, pick your use case above to get started.
# SDK Quickstart
Source: https://docs.vaultkit.dev/sdk-quickstart
Get started with Vaultkit—wrap your app with VaultkitProvider, collect feature selections, authenticate providers, and connect tools.
# SDK Quickstart
## 1. Install dependencies
```bash theme={null}
pnpm add @vaultkit/ai-sdk @ai-sdk/openai
```
## 2. Provide Vaultkit credentials
Create environment variables for the required credentials: your Vaultkit API key and the end-user ID. The vault ID is optional—use it only if you have a static vault; otherwise, use dynamic vaults via feature mappings.
```bash theme={null}
# .env.local (Required)
NEXT_PUBLIC_VAULTKIT_API_KEY=your-api-key-here
NEXT_PUBLIC_VAULTKIT_USER_ID=test-user-123
# .env.local (Optional)
NEXT_PUBLIC_VAULTKIT_VAULT_ID=vault_id_if_using_static_vault
```
## 3. Wrap your page with `VaultkitProvider`
```tsx theme={null}
import { VaultkitProvider } from "@vaultkit/ai-sdk";
import DemoPageInner from "./DemoPageInner";
export default function DemoPage() {
return (
);
}
```
The provider shares feature, authentication, and vault state across every child component. The SDK connects to Vaultkit automatically using the defaults (no configuration needed).
## 4. Let users pick features and connect providers
Before the UI renders anything meaningful, create at least one **Feature** in the Vaultkit dashboard ([Dashboard → Feature Mappings](https://app.vaultkit.dev/dashboard/features)). Each feature bundles the providers and tools the end user can opt into. For example:
* *Feature*: "Email assistant"
* *Description*: "Monitor and help manage your inbox"
* *Providers*: Gmail, Outlook
* *Permissions / Scopes*: create, read, update, delete
Once the feature is saved, `FeatureSelect` surfaces it to end users, and `AuthComponent` automatically lists the OAuth buttons for the configured providers.
> **Important:** If no feature exists in the dashboard, `FeatureSelect` renders an empty list and `AuthComponent` has nothing to authenticate. Always seed the dashboard first—either manually or by script—before wiring these components into your app.
```tsx theme={null}
"use client";
import {
FeatureSelect,
AuthComponent,
} from "@vaultkit/ai-sdk";
export function DemoPageInner() {
return (
{/* Your agent UI lives in the other column */}
);
}
```
> **Note:** `FeatureSelect` and `AuthComponent` assume they are rendered inside a `VaultkitProvider`. If you want standalone components that manage their own provider, import `FeatureSelection` or `VaultkitAuthComponent` instead.
## 5. Connect your agent
Once users have selected features and authenticated providers, use `createVaultkitClient` to connect your agent:
```tsx theme={null}
import { createVaultkitClient, useVaultkit } from "@vaultkit/ai-sdk";
export function MyAgent() {
const { generatedVaults } = useVaultkit();
const handleConnect = async () => {
const activeVault = generatedVaults.find((vault) => vault.is_active);
if (!activeVault?.generated_vault_id) return;
const vaultkit = createVaultkitClient({
apiKey: process.env.NEXT_PUBLIC_VAULTKIT_API_KEY!,
userId: process.env.NEXT_PUBLIC_VAULTKIT_USER_ID!,
vaultId: activeVault.generated_vault_id,
});
await vaultkit.connect();
// Now vaultkit.tools is populated and ready to use with your LLM
return vaultkit.tools;
};
return ;
}
```
Pass `vaultkit.tools` to your LLM runtime (Vercel AI SDK, LangChain, etc.) to enable tool calling. For more details, see [SDK Configuration](sdk-configuration).
# React Components
Source: https://docs.vaultkit.dev/sdk-react-components
Embed Vaultkit onboarding flows with pre-built React components for feature selection, provider authentication, and connection management.
# React Components
The `@vaultkit/ai-sdk` package exports three core components for managing the user onboarding flow:
| Component | Purpose |
| ------------------ | -------------------------------------------------------------- |
| `FeatureSelect` | Lists feature mappings and lets users toggle providers/scopes. |
| `AuthComponent` | Launches provider OAuth flows and shows connection status. |
| `VaultkitProvider` | Shares vault, feature, and connection state. |
These "inner" components assume they live inside a `VaultkitProvider`. If you prefer self-contained widgets that instantiate their own provider, use the top-level wrappers: `FeatureSelection`, `VaultkitAuthComponent`, and `VaultkitConnectionManager`.
## Self-contained components
If you are not already inside a `VaultkitProvider`, import the outer components—they create their own provider internally.
```tsx theme={null}
import {
FeatureSelection,
VaultkitAuthComponent,
VaultkitConnectionManager,
} from "@vaultkit/ai-sdk/client-components";
export function SettingsPage({ apiKey, userId }: Props) {
return (
console.table(connections)}
/>
);
}
```
Both approaches hit the same Vaultkit endpoints; choose the one that fits your architecture.
### `FeatureSelection` props
| Prop | Type | Default | Description |
| ------------------ | ----------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `apiKey` | `string` | — | Required Vaultkit API key for the current workspace. |
| `userId` | `string` | — | Identifies the end user whose selections should be stored. |
| `organizationId` | `string` | — | Optional organization/workspace identifier used when your accounts span multiple tenants. |
| `baseUrl` | `string` | `"https://app.vaultkit.dev"` | Override when pointing at a different Vaultkit environment. |
| `featureMappingId` | `string` | — | Locks the UI to a single feature instead of showing the full catalog. |
| `showAllFeatures` | `boolean` | `true` | When false, hides inactive features from the list. |
| `className` | `string` | — | Applies a custom class to the outer wrapper for additional styling. |
| `style` | `React.CSSProperties` | — | Inline style overrides for the outer wrapper. |
| `title` | `string` | `"Choose the features you want to enable"` | Heading text shown above the feature list. |
| `subtitle` | `string` | `"Authorize the services for the features"` | Supporting copy beneath the heading. |
| `theme` | `'light' \| 'dark' \| 'auto'` | `"auto"` | Forces light/dark styling or syncs to the user’s `prefers-color-scheme` setting. |
## Reading selections and connections
`useVaultkit()` exposes everything the UI components collect:
```tsx theme={null}
import { useVaultkit } from "@vaultkit/ai-sdk";
function Summary() {
const { selectedFeatures, featureProviders, connections } = useVaultkit();
return (