From zero to a working automation
This is the path an administrator walks the first time: a model that answers, knowledge it can cite, an agent that uses both, and a ServiceDesk Plus trigger that fires it. Every step ends with a checkpoint — something you can observe. Do not move to the next step until the current checkpoint passes; otherwise two failures arrive together and neither is diagnosable.
Before you start
Section titled “Before you start”| Requirement | Why |
|---|---|
| A reachable MAIA Plus installation, signed in as administrator | Everything below is in the WebUI |
| An AI provider account and key | Nothing reasons without one |
| A ServiceDesk Plus account with Developer Space access | For the last step only |
Set Data Protection now, not later — from step 1 the ticket text you test with leaves the host.
Step 1 — A provider profile
Section titled “Step 1 — A provider profile”AI providers → Create profile: name, vendor, endpoint, key, model identifier.
Checkpoint: Save & test connection reports a completed call. A test that fails on authentication is a key or endpoint problem; fix it here, not later.
Step 2 — Three routes
Section titled “Step 2 — Three routes”On the same page, assign Agent, Completion and Embedding to that profile.
Checkpoint: the route rows name your profile, not a default. An unassigned route fails instead of falling back — that is the single most common cause of “the agent does nothing”.
Step 3 — A document with a citable answer
Section titled “Step 3 — A document with a citable answer”Knowledge Vault → upload one short document that contains a fact you can ask about.
Checkpoint: the document reaches Indexed, and the approval queue is empty. If it stays pending, the embedding route in step 2 is the suspect. See Knowledge indexing.
Step 4 — An agent
Section titled “Step 4 — An agent”Agents → create one: instructions, surfaces (technician Copilot), tools kb_search and ticket_read, knowledge scope including the portal.
Checkpoint: the Effective knowledge scope panel lists the portal you expect. An empty scope answers nothing and returns no error.
Step 5 — Prove the agent before wiring anything
Section titled “Step 5 — Prove the agent before wiring anything”Response Simulator → ask the question from step 3.
Checkpoint: the answer cites your document. An answer without citations means retrieval is not reached — fix that before adding a trigger, because a webhook will not make retrieval work.
Step 6 — A webhook key for one target
Section titled “Step 6 — A webhook key for one target”Webhook keys → Create key, target automation, pick the agent and the event type. Copy the value once.
Checkpoint: the key starts with whk_ and you have stored it somewhere you can retrieve. It is never displayed again.
Step 7 — The ServiceDesk Plus side
Section titled “Step 7 — The ServiceDesk Plus side”Custom triggers → create the webhook record (method, URL, headers) and then the trigger rule that fires it.
Checkpoint: in Enterprise Audit → Requests the call appears. A 401 means the key and the target disagree; no row at all means the trigger never fired or the URL is unreachable. Both are covered in Connections.
Step 8 — Read the run, not the log
Section titled “Step 8 — Read the run, not the log”Open the run from step 7 and follow it: which agent, which tools, whether a write was proposed, whether anything was written.
Checkpoint: you can answer “what did it read, what did it write, who approved it” from the audit alone. When you can, the automation is real — and every later change has a baseline to compare against.
What this path deliberately skips
Section titled “What this path deliberately skips”- Assignment models — optional, and they need historical tickets to train on.
- Workflow graphs — a workflow can replace the automation later; build it once the agent answers reliably.
- MCP tools — external capabilities area, not part of a first installation.
Related topics
Section titled “Related topics”Diagnostics · Enterprise Audit · Troubleshooting · Check installation health