Core Concepts

Before you write your first sdkStart call, it helps to know what you’re actually calling. This page lays out the four objects Wetel is built from and how they relate. Read this after Getting Started and before Core API Flow — the mutation names will make a lot more sense once the shape underneath them is clear.

Wetel is a hosted runtime, not a library

This is worth stating plainly, because it’s the single biggest thing to get right before integrating: Wetel is not a code library or SDK that you assemble a conversation loop out of. If you’ve used a code-first AI SDK before — the kind where you write a function that calls a generateText/streamText-style primitive, manage the message history yourself, and wire up your own tool-calling loop — Wetel is structurally different. You don’t write that loop. You configure an agent’s persona and a workflow’s logic through the GraphQL API (or, eventually, a visual builder), and Wetel’s own infrastructure runs the actual conversation: it calls the LLM, tracks state, executes the workflow graph, and streams results back to you as events.

The embeddable <vai-avatar> component and the sdkStart/sdkSendMessage mutations are a thin last-mile client layer. They open a session and pass messages into it — they don’t contain any of the agent’s reasoning. All of that lives server-side, in the workflow.

The four objects

Tenant

A tenant is the top-level isolation boundary. One tenant maps to one customer or organization. Every other object described on this page — agents, workflows, sessions, knowledge bases, API keys — belongs to exactly one tenant, and nothing crosses that boundary: a request authenticated for one tenant can never see or affect another tenant’s data.

Wetel also supports two different tenant isolation modes (a shared database with row-level isolation, or a fully dedicated database per tenant) — that distinction doesn’t affect how you call the API, so it’s covered separately in Multi-Tenancy rather than duplicated here.

Agent

An agent is the object you configure before integrating anything. It holds:

• a persona (personaPrompt) — who the agent is, its tone, its scope boundaries;
• voice/avatar settings, if you’re doing a spoken integration;
• a workflowId, pointing at the workflow that actually drives its behavior.

The important thing to internalize: the persona defines identity, not logic. personaPrompt says nothing about what steps the agent takes, what tools it calls, or how it branches on user input — that’s the workflow’s job entirely. Two agents can share an identical persona and behave completely differently if they’re wired to different workflows.

An agent with no workflow attached — or one attached to an unpublished workflow — doesn’t fail loudly. It just replies with a generic fallback to everything, including a plain “hello.” See the Workflows Overview publishing section for the exact mechanics of this gotcha before you assume a broken agent is a bug in your call.

Workflow

A workflow is the thing that actually decides what happens on each turn of a conversation: a directed graph of typed nodes connected by edges. Node types include start, llm, condition, router, response, webhook, tool, action, and end_session — each one an instruction (call the model, branch on a value, call a tool, send a reply, end the conversation). Edges connect nodes and determine which path execution takes next.

This is the layer where the actual product behavior lives. If you want an agent to check a condition, call your own backend, or answer differently depending on intent, you build that into the workflow graph — not the agent’s persona prompt. Full node-by-node reference and a worked example are in Workflows Overview.

Session

A session is one instance of a live conversation between an end user and an agent. It’s created by calling sdkStart (API-key-authenticated, for runtime integrations) or startSession (JWT-authenticated, for a dashboard-driven flow). Once a session exists, it runs the agent’s attached workflow turn by turn as messages come in — each session is a fresh execution of the same graph, with its own state.

The turn-by-turn execution model

A session doesn’t call the LLM exactly once per user message and hand back a single reply. Each message triggers a full pass through the workflow graph, which can involve several nodes in sequence — for example: classify the message’s intent with an llm node, dispatch on that classification with a router node, call an external system with a tool node, and finally produce the reply with a response node. All of that can happen for one user message.

Because a pass through the graph can take a few seconds and involve multiple steps, results don’t come back as a single synchronous response — they stream back as discrete events over a subscription (NodeExecutingEvent as each node runs, AiResponseEvent chunks as the reply is generated, and so on). The full event catalogue and subscription mechanics are covered in Events & Subscriptions — this page is just flagging that the model is “stream of events describing a graph execution,” not “request in, reply out.”

Where the SDK/embed layer fits

<vai-avatar> and the sdkStart / sdkSendMessage mutations exist to let a client — a webpage, a mobile app, whatever you’re building — open a session and drive it from the outside. They are intentionally thin:

• sdkStart opens a session against an agent and returns a short-lived token.
• sdkSendMessage pushes a user message into that session.
• The session’s subscription streams back what the workflow produces.

None of these carry any of the agent’s actual decision-making. That logic is fixed at the workflow layer, server-side, before any client ever connects. Swapping out your frontend, or embedding the same agent in five different products, changes nothing about how the agent behaves — because behavior isn’t a client-side concern in this model at all.

How it fits together

flowchart TD
  T[Tenant] --> A[Agent<br/>persona + voice config]
  A -->|workflowId| W[Workflow<br/>nodes + edges graph]
  A -->|sdkStart| S[Session<br/>one live conversation]
  W -.drives execution of.-> S
  S -->|sdkSendMessage / events| C[Client<br/>vai-avatar or your own UI]

A tenant owns agents and workflows. An agent points at the workflow that defines its behavior. Starting a session creates a live conversation that executes that workflow turn by turn. A client — your frontend, or the <vai-avatar> component — connects to that session to send messages and receive events, without ever touching the logic that produces them.

Next steps

• Getting Started — a minimal working example, end to end.
• Core API Flow — the full sdkStart → sdkSendMessage → subscription → sdkEndSession lifecycle.
• Agents — persona, use case, and workflow wiring in detail.
• Workflows Overview — the node/edge graph model, node-by-node.
• Multi-Tenancy — the isolation model and the gateway pattern for reselling Wetel to your own customers.