AI Connect/How to create/How to create
How to create
Five end-to-end builds that no other platform offers: a consumer chatbot, department copilots, an agent fleet, unattended automations and a multi-tenant SaaS. Each one starts from a single Application key and turns a different kind of actor into an isolated user with its own connectors, credentials and capabilities.
The Quickstart showed you one call. Read this line slowly, because it is the whole future in one sentence: with a single Application key, every user of your product gets thousands of AI connections from day one, each user isolated with their own connectors, credentials and capabilities, and none of them ever exposed to Vinkius. No platform on the market offers that sentence. The five complete builds in this section are what it looks like in production: a consumer chatbot, department copilots, an agent fleet, unattended automations and a multi-tenant SaaS, each written so a developer can start at the top and finish with working AI that acts in the real world.
The primitive underneath all five is the one the rest of the industry does not offer: any entity that needs to act becomes a user. Industry cost analyses put a homegrown version of that architecture at six figures over three years, and it still never finishes shipping. On the AI Connect SDK it is the starting line, not the finish line.
The idea that unlocks everything
In every tutorial the same line appears:
const user = vinkius.user(externalId);That externalId is a value you define. It is not a Vinkius account, not an email, not a human being. It is an opaque, URL-safe string that your backend already controls, and the SDK treats it as the boundary that isolates connectors, credentials and capabilities. Because it is opaque, it can name anything that needs to act:
Your externalId names… | It is… | Why it matters |
|---|---|---|
alice_123 | a human end-user | every customer brings their own GitHub, Slack, Gmail |
dept-finance | a department | the finance copilot acts on finance's own accounts |
triage-agent | an autonomous AI agent | each agent gets its own connectors and spend cap |
svc-nightly-sync | a service account | a cron job connects the database without any human involvement |
cus_acme_u_9f2 | a user inside your customer | your whole SaaS ships connectors, per-tenant isolated |
A "user" in the AI Connect SDK is any entity that should own an isolated set of connections and capabilities. It does not have to be a person. This one reframe is the reason the SDK scales from a weekend chatbot to an agent fleet to a white-labeled enterprise platform without changing a single call.
Sit with how radical that is. Every connectivity platform the industry has shipped so far connects an application to a service. None of them hands your product its own per-entity user model, with credentials your code can never read back. The line above does, and it is the difference between renting connectivity for your app and owning a connectivity platform for your users.
Start with the build you need
| Build | Who the "user" is | What you ship |
|---|---|---|
| Multi-user consumer chatbot | one human per account | a product assistant where every user's AI sees their tools |
| Department copilots for a logistics company | one department | internal assistants, one per team, on one app key |
| A fleet of AI agents, each its own user | one autonomous agent | a swarm where every agent has scoped connectors and its own metering |
| Unattended automations and service accounts | a process, not a person | scheduled jobs, webhooks and CI that connect systems with no browser |
| A multi-tenant AI SaaS | a user inside your customer | white-label AI for every customer of your platform |
The flow every build shares
Whichever entity you model, the runtime loop is identical. Learn it once and you can build all five from memory:
- Create one client on your server from a single Application key.
- Identify the actor: pass
vinkius.user(externalId)the id that owns the action. - Connect a connector:
user.connector('github').connect(), store credentials once, never read them back. - Discover capabilities:
user.capabilities()returns only what this actor has ready. - Pass them to a model: one adapter converts the set to OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain or plain JSON Schema.
- Execute and feed back: run the model's tool call;
isErrorlets the agent recover instead of crash.
Start with the build closest to what you already have. If you run a support bot, start with the chatbot. If you are an internal platform team, start with the department copilots. If you are shipping the next AI-native product, start with the multi-tenant SaaS. Every page ends with a production checklist so you can ship, not just prototype.
The competitive advantage, in detail
Every build below leans on the same architecture, and understanding it is what makes the "you don't own the integration infrastructure" promise credible rather than marketing.
- Two planes, one secret. A control plane (
users,connectors,credentials,catalog) over REST, and an execution plane (listing and running capabilities) that talks JSON-RPC straight to each connection's runtime. Everything is reached with a singlevk_app_sk_*key; the runtime speaks the MCP protocol internally, but that never surfaces in your vocabulary. - Metered, revocable per connection. Each connection owns a
vk_live_*data-plane token. Spend and instant revocation are per connection, which is why a department, an agent or a service account can be isolated financially and operationally, not just logically. - Write-only credentials. Your server stores a user's connector secrets and can see which fields are configured, but nothing, not your code, the model or the dashboard, ever reads the values back.
- Redaction by default. Observability
hooksare fed scrubbed data:Authorization, credential-shaped fields andvk_live_*URL segments are masked before your callback runs. - Zero runtime dependencies, everywhere. Native
fetch, dual ESM/CJS, typed, it runs on Node 18+, Bun, Deno and the edge, so the same build target covers a cron container and a Worker. - Retry and idempotency, reasoned through. Transient failures are retried automatically with full-jitter backoff, and declaring an
idempotencyKeyis what makes even a non-idempotent write safe to retry.
None of the above is a feature you configure per build, it is inherited by every external_id you create. That inheritance is the advantage: the isolation, metering and security guarantees apply automatically to humans, departments, agents, processes and tenants alike.
Before you start
Every build assumes the same three prerequisites, covered in depth in Installation and Authentication and scope:
- Node.js 18+ or any server runtime with
fetch(Bun, Deno, edge, Cloudflare Workers) @vinkius/connectinstalled- A Vinkius App ID (
vk_app_…) and Application Key (vk_app_sk_…) in server environment variables
Every snippet in this section runs on your server. The Application Key and your users' connector credentials must never appear in a browser bundle, a mobile binary, or a model prompt. Ship a thin backend route in front of the SDK; the browser talks to your route, your route talks to Vinkius.
Ready? No other platform on the market can host this section, because none of them offers its premise: that a user is any entity that needs to act. Pick a build and finish it, with working AI that acts for every user you define.
What you just got
Not a pitch: the properties this build inherits automatically.
Connections and capabilities resolve only inside one external_id. No cross-actor leakage is possible, and you wrote none of that enforcement.
Your server stores secrets and can read back which fields are configured, never the values. Not your code, the model, or a dashboard can exfiltrate them.
Every connection owns a vk_live_* token, so cost and revocation are per connection. One call to disconnect() is a complete, auditable stop.
One CapabilitySet converts to OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex, Workers AI or neutral JSON Schema. Only the last line changes.
idempotencyKey, timeoutMs and AbortSignal per call; automatic full-jitter retries on transient failures; typed VinkiusError branches. No bespoke harness.
Give it to your AI agent
An Agent Skill (SKILL.md) for this build. Preview the first lines below, then copy or download it into your repo under .claude/skills/: Claude Code, Cursor or any Agent-Skills-compatible agent follows it to implement this pattern correctly.