Build a TFU Live agent

Creation pricing

Orb appearance

Prerequisites

• An agency API key with agents:read to inspect an agent or agents:write to create, edit and prepare it. Write scope also covers reads.
• A connected sub-account belonging to that key’s agency. A narrower credential location binding still applies. Supplying another locationId does not grant access.
• For trial runs, use an authorised test environment and synthetic records. Check the actual database and external providers before using a local server; running locally does not make its actions simulated.

Step 1: Create an empty draft

{
  "id": "example_agent",
  "draft": true
}

Step 2: Discover only the capabilities you need

Step 3: Translate the business request into a reviewed edit

{
  "ifVersion": "REPLACE_WITH_LOADED_VERSION",
  "name": "Consultation desk",
  "brain": {
    "prompt": "Help people arrange a consultation. Confirm that their postal code is covered before offering an appointment.",
    "capabilities": [
      "outreach"
    ],
    "capabilityConfig": {
      "workflows": {
        "wf_area2k9x": {
          "id": "wf_area2k9x",
          "name": "Check service area",
          "description": "Use when the caller wants to know whether we serve their area.",
          "steps": [
            {
              "id": "zip",
              "type": "collect_information",
              "config": {
                "items": [
                  {
                    "id": "zip_code",
                    "label": "Zip code",
                    "question": "What is the zip code of the address?",
                    "type": "text",
                    "field": "contact.postalCode"
                  }
                ]
              }
            },
            {
              "id": "coverage",
              "type": "check_zip_code",
              "config": {
                "field": "contact.postalCode",
                "codes": [
                  "10001"
                ]
              },
              "outputs": {
                "in_area": [
                  {
                    "id": "covered",
                    "type": "steer_agent",
                    "config": {
                      "guidance": "Offer a consultation."
                    }
                  }
                ],
                "out_of_area": [
                  {
                    "id": "outside",
                    "type": "steer_agent",
                    "config": {
                      "guidance": "Explain that this area is not covered."
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  },
  "voice": {
    "voiceId": "marin",
    "prompt": "Speak at a calm pace and pronounce addresses clearly."
  }
}

Step 4: Prepare the exact saved version

{
  "ifVersion": "REPLACE_WITH_LOADED_VERSION"
}

Boundaries

• Creating a TFU Live agent also creates its linked, paused campaign. Saving or preparing it does not activate that campaign. Campaign permissions and activation checks remain separate. Campaign settings stay shared; current customer TFU campaign mutation adapters remain incomplete. Ordinary outcome prompts and workflow graphs are intentionally not applicable, not aliases for Brain text.
• TFU Live create/get/update own complete authored revisions. Use GET /api/tfu-live-agents?locationId=... for its list and GET /api/tfu-live-agents/{id}/operations for current runtime support. A split test is run from the dashboard; the API does not offer it for a TFU Live agent yet (Agent split tests).
• The agent’s abilities are brain.capabilityConfig.workflows, part of the complete authored aggregate. Each workflow is a tool for the AI: its name gives the tool name, its description is when to run it, and renaming it renames the tool. There are no special workflows; every node can be used in any workflow. Collect information is the only way the AI supplies inputs: its items become the tool’s arguments. A node with outputs ends its list: the steps after it go on its outputs. Tags are never chosen by the AI: Check tag, Add tag and Remove tag each hold one tag. A Transfer node has the outputs Connected, Nobody available and Not connected; a call makes one transfer attempt, a fallback transfer goes only on Nobody available, and after Connected only actions and Conditions may follow. Put on DND ends the lead’s journey, so only internal steps may follow it, in one list (Add tag, Remove tag, Set field, Move stage, Add note, Notify teammate, Send webhook); nothing that contacts the lead or needs the call, and no Condition. The catalog’s workflows contract lists the node formats and limits. Saving validates the workflows with the runtime validator but executes nothing, and refuses an invalid workflow with 422, naming the workflow and step. Custom fields, pipelines and calendars a new or changed step names must exist in this sub-account. HTTPS webhooks also pass outbound URL policy. A webhook sends the call’s context (workflow, sentAt, ids, contact, call) plus its fields, each from fixed text, a contact field, a call detail or a collected answer. Authentication headers must be secret: send {"secret":{"value":"…"}} once, and the value is stored encrypted and read back only as {"secret":{"id":"…"}}, which you send back unchanged to keep it. The formats workflows replaced (brain.hooks, followUps, outcomeSteering, customTools, appointments, per-tool settings such as transfer_call or check_area_code, and workflows keyed by tool id) are refused until the agent’s migration has run.
• A Notify teammate node sending to Slack uses symbolic main or alerts channels, resolved by the runtime from the call tenant. authoring.bindingWarnings distinguishes an unverified mapping from a ready integration.
• Transfer destinations and team-channel mappings require existing authorised configuration. A Transfer node names its destination; it does not create one.
• Split tests, master setup and provider-specific tuning are not part of this contract. Voice delivery instructions do not implement numeric provider controls.
• The internal conversational builder retrieves focused authoring guidance and capability details through its own authenticated tools. Customer backends can use this guide and the discovery requests above; this API does not expose the internal builder conversation, voice session or arbitrary tool executor.

Shared campaign controls, separate authoring

Handle errors

In the API

Share a client test

• A number no contact holds yet gets a new contact. In GoHighLevel that contact carries the source TFU AI Test Link, and a campaign that starts on a new contact skips it, so a number typed into a test page is not dialled for real.
• A number that already belongs to a contact uses that contact, and it keeps its own name, because anyone with the link can type any number. Answers to Personalise the call are saved on the contact.
• A stop on the number never refuses the test. Before the run, the test lifts every stop that would block it: the do-not-call list, the kill switch, and Do Not Disturb for calls and texts. A stop the person asked for is lifted too, and the list keeps a record of who lifted it.
• The upcoming appointments that earlier test calls booked are cancelled, without the calendar’s notifications. Appointments a person or a real lead booked stay.
• A channel that GoHighLevel holds as permanent Do Not Disturb stays on. The person set it, for example by texting STOP, and only they can lift it, by texting START. If the call channel is held that way, the run cannot start.
• A booking made by a test call starts the calendar’s confirmation campaign, and any campaign that starts on tfu_ai_booked, as a test run, not as a real lead.
• The billing checks run before the contact is found or made, so a run refused for billing leaves nothing in the CRM.

• Create agent
• Get agent
• Update agent
• Agent field glossary

Related

• The workflows contract
• The guidance the AI builder retrieves
• What an agent is
• Authentication
• Go live