Provision Agents for Your Customers With a Template Hire

A role template is a ready-made AI employee (agent, workflow, knowledge bases) that Wetel has prepared. Workspace owners can hire one from the dashboard. If you build a product on Wetel, you can hire the same roles from your own backend, with an API key.

Status: live on staging and in production (since 2026-10-09). No API key can hire until it is granted the templates:hire scope by a workspace owner or by Wetel staff.

This page was called “Hiring Role Templates With an API Key (Partners)”; the reference sections below are unchanged, and it now also walks through provisioning one agent per customer of your product (below).

sequenceDiagram
    participant Y as Your backend
    participant W as Wetel API
    Y->>W: partnerAgentTemplates (x-api-key with templates:hire)
    W-->>Y: templates, canHire, parameters, slots
    Y->>W: partnerHireAgentTemplate (templateKey, idempotencyKey, slotBindings)
    W-->>Y: installId, status, agentId, pendingSlotCount
    opt status PENDING_SETUP
        Y->>W: partnerBindAgentTemplateSlot (installId, slotKey, resourceId)
        W-->>Y: status READY, isLive true
    end
    Y->>W: sdkStart (agentId, clientId)
    W-->>Y: sessionId, avatarToken

Hiring is one synchronous call; binding is only needed when a template has required slots you did not bind at hire time. Once the install is READY, the agent is an ordinary agent in the workspace and takes sessions like any other.

What you need

1. A PRO workspace. Other plans get canHire: false in the list below.
2. An API key carrying the templates:hire scope. Only the workspace owner can grant it, when creating the key:

mutation CreatePartnerKey($name: String!) {
  createNamedApiKey(name: $name, scopes: ["templates:hire"]) {
    id
    name
    key
  }
}

The key is shown once. A member who passes scopes is refused; Wetel staff can also set or clear a key’s scopes. The scope only adds rights: the key still does everything a plain runtime key does.

3. A template Wetel has listed for partners. Templates are listed per audience (gallery, partners, or both); ask Wetel which ones your key may hire. A template that is unknown, not listed for partners, deprecated or not hireable all answer the same Template "<key>" not found.

Send the key as x-api-key and, as on every request, x-huat-platform: customer.

Step 1: list what you can hire

query {
  partnerAgentTemplates {
    edges {
      node {
        key
        name
        description
        canHire
        cannotHireReason
        parameters {
          key
          label
          type
          required
        }
        slots {
          slotKey
          label
          kind
          required
        }
        knowledgeBases
      }
    }
  }
}

You get labels only (a slot shows its slotKey, label and kind): never a persona, prompt, workflow, endpoint or credential. slots are the things that must exist before the role can go live (for example a custom action or an MCP connector); parameters are values you fill in. Pagination is Relay-style (first up to 50).

Step 2: hire

mutation Hire($input: PartnerHireAgentTemplateInput!) {
  partnerHireAgentTemplate(input: $input) {
    installId
    status
    isLive
    agentId
    pendingSlotCount
    publishError
    slots {
      slotKey
      status
    }
  }
}

{
  "input": {
    "templateKey": "partner-image-reader",
    "idempotencyKey": "order-8841-hire",
    "parameters": {}
  }
}

A real response (staging, a template with no slots):

{
  "installId": 5,
  "status": "READY",
  "isLive": true,
  "agentId": 238,
  "pendingSlotCount": 0,
  "publishError": null,
  "slots": []
}

The call is synchronous. In one request it creates the agent (inactive), its workflow and its knowledge bases, then publishes and activates the agent when no required slot is waiting. Otherwise the install is PENDING_SETUP, pendingSlotCount says how many slots are left, and the agent takes no real traffic until they are finished.

Input	Notes
templateKey	Required.
idempotencyKey	Required, 8 to 64 characters of letters, digits, - or _. Repeating the call with the same key and request returns the first install and counts nothing twice. The same key with a different request, or a key already used by another API key or the dashboard, is refused with CONFLICT.
parameters	Values by key (text, URL or integer). Use variables, not an inline literal.
versionId	Optional; a specific non-deprecated version. Default is the current one.
slotBindings	Optional, see below.

Step 3: check and finish setup

query {
  partnerAgentTemplateInstall(id: "5") {
    installId
    status
    isLive
    pendingSlotCount
    publishError
    slots {
      slotKey
      status
    }
  }
}
query {
  partnerAgentTemplateInstalls(status: "PENDING_SETUP", first: 20) {
    edges {
      node {
        installId
        status
      }
    }
  }
}

You only ever see installs made with this API key. An install made by another key, from the dashboard or by Wetel staff answers the same NOT_FOUND as an id that does not exist.

Bind existing resources

Create the resource first (a custom action or MCP connector in the workspace), then bind it to a pending slot:

mutation Bind($id: ID!, $slot: String!, $res: Int!) {
  partnerBindAgentTemplateSlot(
    installId: $id
    slotKey: $slot
    resourceId: $res
  ) {
    installId
    status
    isLive
    pendingSlotCount
    publishError
  }
}

Binding the last required slot publishes the workflow and activates the agent. If publishing fails, publishError explains and the install stays PENDING_SETUP. A resource of the wrong kind, or one that cannot do what the role needs, answers one generic refusal and binds nothing. A slot already set up, or an install that is not waiting for setup, is a CONFLICT; binding the same resource to the same slot twice is harmless. Binding stores no credential, and there is deliberately no operation for a partner to supply a credential.

Share resources across hires with slotBindings

To make several hires use one shared custom action, MCP connector or knowledge base, pass slotBindings on the hire instead of creating new ones:

{
  "input": {
    "templateKey": "...",
    "idempotencyKey": "...",
    "slotBindings": [{ "slotKey": "orders_api", "resourceId": 41 }]
  }
}

slotKey comes from the slots of partnerAgentTemplates (the workspace gallery never shows it). At most one binding per slot; only custom action, MCP connector and knowledge base slots; a slot cannot be both bound and given a credential. Every binding is checked before anything is created, and a refused one answers a generic message and creates nothing. A bound knowledge base is never written to. On a replay (same idempotencyKey) the first install is returned and slotBindings is ignored. Removing a role later does not delete a resource it only borrowed.

Recipe: one agent per customer

A common shape for a product built on Wetel: each of your customers gets its own copy of a role, hired the moment they sign up, and your product starts sessions on that copy.

1. Hire once per customer, with a stable idempotencyKey. Derive it from your own customer id and the role, for example cust-48213-support-v1. If the call times out or your process restarts, repeat it with the same key and the same request: you get the first install back and nothing is counted twice. Never generate a fresh key for a retry.
2. Share what should be shared. Pass slotBindings for resources every customer’s copy uses (one custom action into your own API, one knowledge base with your product documentation), so each hire does not create its own copy. Resources that must differ per customer are created first in the workspace and bound per hire.
3. Store the result on your customer record: installId, agentId, templateKey and templateVersion. To keep every customer on the same version, pass versionId on each hire instead of taking the current one.
4. Wait for READY. If the install is PENDING_SETUP, bind the remaining slots, then read it back with partnerAgentTemplateInstall(id). An agent still being set up refuses sdkStart with FORBIDDEN.
5. Start sessions on the customer’s agent. From your server, call sdkStart with that agentId and a clientId naming the end user, with an ordinary runtime key. The hire key does not need to be the one that starts sessions; a separate named key for runtime traffic keeps the templates:hire right off your busiest servers.

Where the agents live. Every role hired with a key goes into the key’s own workspace. One workspace holding all your customers’ copies is the simplest setup, and the per-key ceilings below (200 roles at once, 50 hires a day) apply to it. If a customer needs its own workspace (its own usage, data and owners), that workspace’s owner creates a key with the templates:hire scope for you, and you hire into it with that key. Ask Wetel to raise a key’s ceilings before a large onboarding.

Limits and errors

Limit	Value
Active hired roles per key	200
Hires per 24 hours per key	50
partnerHireAgentTemplate, partnerAgentTemplates, reads	60 per minute per client IP
partnerBindAgentTemplateSlot	20 per minute per client IP

Wetel can set other quotas for a key; a refusal names the limit and creates nothing.

Situation	Code
Key lacks the templates:hire scope	FORBIDDEN (This API key is not allowed to do this)
Template unknown, gallery-only, deprecated or not hireable	NOT_FOUND (Template "<key>" not found)
Install of another key or path	NOT_FOUND
idempotencyKey already used for another request or by another key	CONFLICT
Slot already set up, install not waiting	CONFLICT

Configuration problems on Wetel’s side answer one generic message and are logged for Wetel; they never describe the template’s internals to you.

Test checklist

• partnerAgentTemplates lists the template with canHire: true.
• A hire returns READY with an agentId (or PENDING_SETUP with the slots you expect).
• Repeating the hire with the same idempotencyKey returns the same installId, and a different request with that key is a CONFLICT.
• Binding the last slot makes the install READY and isLive: true.
• sdkStart with the new agentId starts a session, and a reply arrives.
• A key without the scope is refused with FORBIDDEN, and creates nothing.

What this does not do

• The partner operations cannot remove a hired role, move it to another template version or edit its workflow. Those are workspace-owner tasks, done on the agent like any other agent in the workspace.
• No operation supplies a credential: create the custom action or MCP connector in the workspace and bind it.
• You cannot publish your own templates through this API. Wetel prepares and lists the templates a partner key may hire.
• It never shows you a template’s persona, prompts, workflow or endpoints.

See also: sdkStart, Rate limiting, Agents set up from a role template (the workspace-owner path), Authentication, Error handling.