Skip to main content

​
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 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

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

​
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 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.