Agents

An agent is the top-level object you configure inside Wetel before integrating it into your product. It holds the agent’s persona, which workflow drives its behavior, and (optionally) voice/avatar settings for spoken integrations.

Agent configuration is a one-time admin/operator task, done by a human with dashboard access — not something your end-user-facing application does at runtime. If you haven’t set up authentication yet, start with Getting Started and Authentication.

Creating an agent

mutation CreateLibraryAgent {
  createAgent(
    input: {
      name: "Library Assistant"
      position: "Library Concierge"
      personaPrompt: "You are a friendly, knowledgeable library assistant. You help users find books, check room availability, and navigate library services. Always be concise. If you don't know, say so."
      useCase: SUPPORT
      voiceTier: STANDARD
    }
  ) {
    id
  }
}

Headers:

x-huat-platform: customer
Authorization: Bearer <your-dashboard-access-token>

createAgent requires name, personaPrompt, position, useCase, and voiceTier. voiceTier is required even for text-only agents — pick any value; it’s simply unused unless you activate voice.

The persona prompt

personaPrompt is the agent’s system prompt — its identity, tone, and behavioral guardrails. This is the field that defines “who” the agent is; it says nothing on its own about the agent’s logic (what steps it takes, what tools it calls) — that’s the job of the workflow (see below).

Keep it focused: identity, tone, scope boundaries, and what to do when it doesn’t know an answer. Detailed step-by-step behavior (branching, tool calls, structured responses) belongs in the workflow graph, not the prompt.

useCase: the AgentUseCase enum

useCase is a fixed enum, not a free-form label:

enum AgentUseCase {
  CUSTOM
  EDUCATION
  INTERVIEW
  ONBOARDING
  SALES
  SUPPORT
}

This isn’t just a tag for your own records — it selects which built-in evaluation prompt runs at session end, and what shape the resulting evaluation takes (a recommendation enum specific to that use case, plus score, summary, strengths, weaknesses). Pick whichever value best matches what the agent is actually for.

For anything that doesn’t fit the five built-in verticals, use CUSTOM and supply your own evaluationPromptTemplate and evaluationRecommendationLabels to override the default evaluation prompt and recommendation set.

You can confirm the current enum values at any time via introspection:

{
  __type(name: "AgentUseCase") {
    enumValues {
      name
    }
  }
}

Wiring up a workflow

An agent’s actual behavior — what it says, what tools it calls, how it branches — lives in a workflow graph, not the agent record itself. See Workflows Overview for the full node/edge model.

workflowId is not settable when you create the agent — it only exists on the update input. The real flow is:

1. Create the agent (above).
2. Author and publish a workflow.
3. Attach it: updateAgent(id: <agentId>, input: { workflowId: <workflowId> }).

mutation AttachWorkflow {
  updateAgent(id: "1", input: { workflowId: 1 }) {
    id
    workflowId
  }
}

The most common first-integration mistake: an unpublished workflow does nothing — silently

Attaching a workflow via workflowId is not enough on its own. A workflow you create with createWorkflow and configure with updateWorkflow starts out unpublished. An unpublished workflow executes zero nodes for every session that uses it — there is no error anywhere. The agent will simply reply with a generic fallback message to every single input, including a plain “hello.”

Before a workflow will actually run, you must explicitly publish it:

mutation PublishWorkflow {
  publishWorkflow(id: 1) {
    id
    isPublished
    version
  }
}

isPublished starts false and version increments on every publish. If your agent isn’t doing anything even though the graph looks correct and workflowId is set, check isPublished first — before assuming the graph itself is broken.

Voice and avatar configuration

These fields only matter if you activate voice/avatar integration (see the maturity ladder in Core API Flow) — text-only integrations can ignore all of them.

Field	Type	Notes
voiceTier	VoiceTier! enum (STANDARD, WAVENET, NEURAL2)	Voice-quality tier hint; required on createAgent regardless of integration type.
avatarBackend	AvatarBackend enum (CLIENT_3D, HOSTED_API)	Avatar rendering backend. See below.
avatarGender	AvatarGenderCode enum (M, F)	Discoverable via introspection: { __type(name: "AvatarGenderCode") { enumValues { name } } }.
avatarGlb	String (filename, e.g. "brunette-t.glb")	Must reference an actually-uploaded 3D avatar model. Used only with CLIENT_3D backend.
ttsVoice	String	A Google Cloud TTS voice name, e.g. en-US-Neural2-F.
ttsLang	String	BCP-47 locale matching ttsVoice, e.g. en-US.
lipsyncLang	String	Lipsync module language; only en is verified in current deployments.
speakingRate	Float	See below.
vadThreshold	Float	Voice-activity-detection threshold.

To discover current valid values for avatarGlb and a curated ttsVoice subset without leaving GraphQL, use the agentConfigOptions query:

{
  agentConfigOptions {
    avatarModels {
      id
      gender
      label
      filename
    }
    recommendedTtsVoices {
      name
      languageCode
      gender
      tier
    }
    ttsVoiceCatalogUrl
    sttLanguageCatalogUrl
    lipsyncModuleDocsUrl
  }
}

Use the returned filename directly as avatarGlb’s value. For the full Google Cloud TTS voice catalog beyond the curated subset, see ttsVoiceCatalogUrl.

speakingRate range

speakingRate is a continuous float, not a discrete option set. Valid range is 0.25 to 4.0 (enforced server-side), where 1.0 is normal speed. Values outside this range are rejected.

avatarBackend: avatar rendering options

avatarBackend selects which technology renders the agent’s video avatar during a session:

• CLIENT_3D (default) — The agent appears as a 3D avatar rendered client-side by the <vai-avatar> component. This is the standard option for most integrations and requires no additional vendor integration. The specific 3D model is determined by avatarGlb.
• HOSTED_API (pilot) — The agent appears as a photorealistic video avatar rendered by a hosted service. This option provides a more realistic visual experience than the default 3D avatar. Currently in limited pilot availability — contact your Wetel representative to enable this for your account.

When using HOSTED_API, the avatarGlb field is ignored (the hosted service manages avatar selection independently). All other voice and TTS settings (ttsVoice, ttsLang, lipsyncLang, speakingRate) are respected as with the client-side option.

LLM provider override (pilot)

Every agent runs on a platform-wide default language model. Two fields let you override that per agent, or tenant-wide:

Field	Type	Notes
llmProviderOverride	LlmProviderType enum (BEDROCK_MANTLE, WEBBYXAI_HAIKU, GEMINI_DIRECT)	Which model provider answers this agent’s turns. See below.
llmModelOverride	String	Which specific model, when llmProviderOverride is BEDROCK_MANTLE. See below.

Currently in limited pilot availability — contact your Wetel representative to enable this for your account. Resolution order is agent override → tenant override → the platform default; leaving both fields unset (the default for every agent today) means you’re unaffected by anything below.

• WEBBYXAI_HAIKU (platform default) — Anthropic Claude Haiku, with an automatic fallback to a secondary model on any failure. llmModelOverride is ignored for this provider — it’s a single fixed model.
• GEMINI_DIRECT — Google Gemini directly. Also a single fixed model; llmModelOverride is ignored.
• BEDROCK_MANTLE (pilot) — AWS Bedrock’s open-weight model catalog (Meta, Mistral, Qwen, DeepSeek, and others — dozens of models). This is the only provider llmModelOverride actually does anything for: set it to any model id Bedrock Mantle currently offers (your Wetel representative can share the current list) to pick a specific one. Leave llmModelOverride unset to use a sensible default within the Bedrock catalog. Every provider automatically falls back to the platform default on failure — a misconfigured or unavailable llmModelOverride degrades gracefully rather than breaking the agent.

To clear either field back to “no override,” send an explicit null on updateAgent/updateTenant — omitting the field leaves whatever was previously set unchanged.

Next steps

• Core API Flow — the sdkStart → sdkSendMessage → sdkEndSession integration flow that actually runs a configured agent.
• Workflows Overview — the node/edge graph model that drives agent behavior.
• Troubleshooting — common first-integration issues, including the unpublished-workflow trap above.