> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Super Magic Agent

> Build an agent that runs unattended on matching tickets: set the trigger, give it a prompt or a shared skill, approve its write tools, and troubleshoot a run with Flow Chats and Flow logs.

<Warning>
  **Beta.** Super Magic Agents are enabled per workspace. Ask your Customer Success contact to
  turn them on. **Run Skill** — pointing an agent at a saved skill — is also beta.
</Warning>

Super Magic in chat waits for you to ask. An agent doesn't. You give it a job, decide what it's
allowed to change, and it runs on every ticket that matches, on its own. That last part is the
**trigger**, and it's what turns an assistant into an agent.

## Start from the library, not a blank box

The [Magic Library](/skill-library/overview) is full of jobs already written for this. Anything
tagged **Agent** was written to run unattended and carries a *Running as a Flow* section telling
the agent how to behave when nobody's watching.

Filter to the **Agent** entries, pick the one closest to your workflow, and adjust the board
names, status names and tone to match your desk. That's the whole job most of the time.

Two other ways in:

* **Ask Super Magic to build it.** Describe the outcome in plain language and ask it to create
  the flow and the agent together. Usually the fastest route — review what it produced before you
  enable it.
* **Write it yourself.** Fine, but read [the three rules](#three-rules-that-fix-most-failures)
  first.

## Before you start

* Super Magic enabled for your workspace, and Super Magic Agents enabled on top of it
* A **test board and a test ticket** — don't point a new agent at a live board on its first run
* The person creating the agent needs **full write access**

## What an agent is made of

| Part                 | What it is                                                                                                                              |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Context**          | What it knows about the situation — the company, contact, ticket, device, conversation.                                                 |
| **Tools**            | The actions it can take. Tools are what move it from advice to doing the work.                                                          |
| **The instructions** | Either a prompt written into the flow, or a shared skill the flow points at. Whichever you use, it must carry every rule the job needs. |
| **A trigger**        | What starts it: a [Flow](/inbox/flows) firing on a ticket event.                                                                        |

## Build it

<Steps>
  <Step title="Set the trigger">
    **Admin → Flows → New flow.** The conditions decide which tickets the agent sees, and they're
    the biggest lever you have. **Start narrow** — one board, one status, or a single test client —
    then widen once you trust the output.

    Two things to know:

    * It fires **once per ticket, permanently** — not once per status change. See
      [the once-per-ticket rule](#a-flow-only-runs-once-per-ticket).
    * It fires on the ticket **as it is at that moment**. If your agent needs a field another flow
      writes, ordering matters.
  </Step>

  <Step title="Add the agent and choose how it gets its instructions">
    Add an action, pick the Super Magic agent action, and choose between:

    * **A prompt written into the flow** — best when only this flow needs it. There's an
      **Improve prompt** button that tightens a draft.
    * **A shared skill** *(beta)* — best when a technician also triggers the same job by hand from
      chat, so the instructions live in one place.

    Only **shared** skills run in a flow. A personal skill will silently do nothing, and only an
    admin can set a skill to shared.
  </Step>

  <Step title="Approve the tools">
    Tick the write tools you're comfortable with it using unattended. Read tools are always on and
    never need approval.

    **The two modes have opposite defaults**, which is the single most common source of confusion:

    | How it gets instructions | Nothing ticked means                     |
    | ------------------------ | ---------------------------------------- |
    | A prompt in the flow     | Reads only, changes nothing              |
    | A shared skill           | It gets every automation-safe write tool |

    So an agent that reads correctly but never changes anything is almost always an empty tool
    list. And a skill-based action you want tightly scoped needs its tools ticked explicitly. Each
    library entry lists the tools it needs in its header — tick those.
  </Step>

  <Step title="Test it">
    Leave the flow **disabled**, create a test ticket that matches, then enable it and watch.
    Three places to look: the ticket itself, **Super Magic → Flow Chats** for the agent's
    reasoning, and **Flows → Logs** for whether it fired at all.
  </Step>
</Steps>

## Who the agent runs as

Not a service account. Every run acts as a **real member** of your workspace:

* A prompt-based agent runs as **whoever last saved the flow**.
* A skill-based agent runs as **whoever created the skill**.

Two consequences. The run appears in that person's **Flow Chats**, not everyone's. And if that
person is deactivated, **the action stops running silently**. If an agent stops working the week
someone leaves, open the flow and save it again while signed in as an active member.

## Three rules that fix most failures

**1. Load the ticket first.** The agent starts knowing only which thread it's on — not the body,
not the client, not the contact. Every prompt that works starts by fetching it:

> Load the ticket. Call `search_tickets` with the current `internal_ticket_id` and
> `include_messages=true`. Read the result before doing anything else.

**2. One tool call at a time.** Agents fail most often when they try to do several things at once.

> Make one tool call at a time. Read the full result before deciding the next call. Never batch or
> parallelise calls.

**3. Say what to do when it can't finish.** Without a stop condition, it guesses.

> If you cannot confidently identify the company, add an internal note explaining what you
> checked, and stop. Do not assign anything.

Two smaller ones: **name the actual tool** rather than the outcome (`assign_contact`, not "move it
to the right company"), and if you want the client to see a message say **`is_internal=false`**
explicitly, because the agent defaults to internal notes.

<Note>
  **Shorter prompts perform better.** Cutting a long dispatch prompt from around 12,000 characters
  to 3,000 makes it more consistent and far easier to troubleshoot. Aim under 3,000 — which is also
  the saved-skill limit. If you're over, don't delete requirements: ask Super Magic to make it
  shorter without changing what it does.
</Note>

## What doesn't work in a flow yet

**Documentation search does work.** IT Glue and Hudu are built into the agent directly, so those
searches are available in a flow exactly as they are in chat. Your documentation layer is not the
gap.

What isn't available in a flow run: **NinjaOne, ConnectWise Automate, ImmyBot, TimeZest, PSA
Configurations**, and anything reached over a connector — including **Liongard, Notion and
Linear**.

If a job works when you run it from chat but does nothing in a flow, this is almost always why.
Check the entry's **Connectors** line before you build: one that needs nothing, or needs only IT
Glue and Hudu, works today. Anything else will still run, but the agent has no such tool to call —
and rather than stopping it works with what it has and gives you a confident answer that is wrong,
such as reporting a device can't be found when it exists. Run those from Super Magic chat instead.

## A flow only runs once per ticket

De-duplication is on **flow plus ticket, permanently**. A QA agent that runs on *Complete* won't
run again when the technician fixes the ticket and sets *Complete* a second time.

The workaround is **two flows**, which de-duplicate independently:

1. **QA Agent 1** triggers on `Status = Complete` on your main board. On failure it sets *Re-open*
   and moves the ticket to a QA board.
2. **QA Agent 2** triggers on `Status = Complete` on the QA board. On failure it sets *Re-open* and
   leaves it there.

The technician always just sets *Complete*. It costs you one spare board.

## Setting a company

There's no company field the agent can set. Assign the right contact with `assign_contact` and the
ticket follows that contact onto their company — which means "company but no contact" isn't
reachable. If the agent can't find a contact, have it **stop** rather than half-route the ticket.

## Destructive actions are blocked

Rebooting a device, running a maintenance session, executing a runbook — these are blocked in any
unattended run. They need a person to confirm.

## Plan level

On a plan below **AI Pro**, Super Magic runs with a much smaller set of tools. If something is
missing entirely, check your plan on [Plans & Licenses](/inbox/plans-licenses).

## When it goes wrong

**Flows → Logs** answers *did it fire?* Filter **Type** to agent runs, and open a row for the
condition tree showing what each rule expected against what actually arrived on the ticket.

One catch: **agent actions report `Dispatched`, not `Success`.** The agent runs in the background,
so when the flow finishes the outcome isn't known yet. `Dispatched` means the handoff worked,
nothing more.

**Super Magic → Flow Chats** answers *what did it actually do?* — every tool call, every result,
its reasoning at each step. This is where you troubleshoot the agent itself.

| What you see                                   | Usually                                    | Fix                                                                                            |
| ---------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Reads right, but nothing changed on the ticket | No write tools ticked                      | Tick them — an empty list means read-only for a prompt-based agent                             |
| Works in chat, does nothing in the flow        | It needs a connector tool                  | IT Glue and Hudu are fine; Liongard, RMM and other connectors aren't. Use a native job for now |
| Errors part-way through                        | Tried several calls at once                | Add the one-call-at-a-time rule                                                                |
| Seems to know nothing about the ticket         | Never told to load it                      | Make `search_tickets` step 1                                                                   |
| Didn't fire at all                             | Conditions didn't match, or it already ran | Check the condition tree. Once per ticket, forever                                             |
| Stopped working, nothing changed in the flow   | The member who saved it was deactivated    | Re-save the flow as an active member                                                           |
| Nothing reached the customer                   | It wrote an internal note                  | Say `is_internal=false`                                                                        |
| Results vary run to run                        | Prompt too long, or repeats itself         | Compress it                                                                                    |
| A skill-based action does nothing              | The skill is personal                      | Set it to shared — needs an admin                                                              |
| Assigns to the wrong company                   | Weak contact match, and it guessed         | Add a stop condition                                                                           |

## Raising a ticket

Raise it as a normal Thread support ticket, mention it's a Super Magic Agent in a flow, and
include:

1. **The prompt, in full**
2. **The flow conditions**
3. The ticket ID where it went wrong
4. **The link to the Flow Chat**, which carries the whole tool-by-tool trace

Items 1, 2 and 4 resolve most cases on their own.

## Contribute back

Built something good? The library is crowdsourced. Fork
[Thread-Magic/super-magic-skills](https://github.com/Thread-Magic/super-magic-skills), add a
`SKILL.md`, and open a pull request — once merged it goes live on this site. The bar: one real
workflow, guardrails inside the prompt, and no client or partner data.

## Next step

Browse [Agents](/skill-library/agents) for jobs worth running this way, or read
[Meet Super Magic](/super-magic/meet-super-magic-your-ai-assistant-in-the-inbox) for how the
interactive, confirm-each-write mode works.


## Related topics

- [Meet Super Magic: Your AI Agent in Inbox](/super-magic/meet-super-magic-your-ai-assistant-in-the-inbox.md)
- [Build Your Magic Agents Service Catalog](/ai-agents/building-your-magic-agents-service-catalog.md)
- [Build with Super Magic](/start-here/roles/automation-engineer/build-with-super-magic.md)