setting-up-support-agent

Setting Up a Support Agent

Overview

This is the orchestrator. It turns a web app into a deployable support kit by running the stage skills in order, assembling their outputs, shipping a runtime, then telling the operator the local, off-model steps only a human can do. The end goal is a support agent that diagnoses an end user's real situation from read-only live state, resolves what it can from the knowledge base, and escalates a proposed fix to a human when a change is needed — it never mutates anything.

Runtime brain (default agent). At runtime the kit is driven by an LLM tool-agent: the model diagnoses by freely calling the kit's read-only tools and composes the answer. There is no decision tree to author for control flow — the runbooks are consumed as advisory guidance ("symptom → when to escalate"), not walked. Safety does not rest on branching; it rests on two hard, structural facts:

1. A scoped read-only DB role (column-grants + row-level security) — there is no write tool, so the model physically cannot change data, and RLS confines every read to the acting user.
2. A single explicit escalate_to_human tool — the only way the agent can "act", logged prominently; the agent is instructed never to claim it made a change. A deterministic walker mode (the runbooks as an actual decision tree) remains available for auditable/offline runs, but agent is the shipped default.

Core principle: this skill coordinates; it does not re-implement. Each stage is delegated to its own skill, which owns the rules for that artifact. Between stages there is a mandatory human-review gate.

Decisions to gather first (ask only what you cannot infer)

1. End-user app path — the source of the knowledge base. This is the app real users use, NOT an admin/back-office tool. If only an admin codebase is offered, stop and say the end-user app is required for the knowledge base.
2. Backend source path — where the read-only tools and runbooks are derived from (often the admin/back-office code). May differ from the end-user app.
3. Schema exposure mode — grounded | aliased | blind (default to blind: the model never sees real schema; names are bound locally by support-binder). Applies to schema-backed connections (SQL, and non-SQL where it has a schema); it does not apply to API/custom connections.
4. Escalation channel — Telegram, email, or both.
5. User follow-up channel — how a user is told their issue was resolved (e.g. email).
6. Connection types (read-only). Ask the operator: "Besides tool→SQL connections, does the agent need other read-only connection types to diagnose a user's live state — external API calls (HTTP), a non-SQL data store, or custom read-only executions? Select all that apply." Multi-select; default = SQL only. Every selected type MUST be read-only — non-negotiable; discovering-support-tools enforces it per type. The chosen set becomes the connections list in the config.
7. SQL engine (only if SQL is enabled) — Postgres/Supabase is the supported target today.
8. Brain model — which AI model powers the agent brain at runtime. Ask the operator (it must support tool/function calling). This becomes runtime.model in the config and drives the runtime by default. (e.g. nvidia_nim/qwen/qwen3-coder-480b-a35b-instruct, a llama-3.x-70b-instruct, or a Claude model.)