56 lines
7.0 KiB
Markdown
56 lines
7.0 KiB
Markdown
# Support agent: design
|
|||
|
|
|
||
|
|
- **Date**: 2026-11-17
|
||
|
|
- **Status**: approved 2026-11-17
|
||
|
|
- **Size**: a small change: one agent file, the README row, the plugin description; in aimsight-labeling, the folder's line in its README and CLAUDE.md, and its `work/` ignored.
|
||
|
|
|
||
|
|
## Intent
|
||
|
|
|
||
|
|
A fourth agent in the plugin, `support`, truly generalist. It is launched from anywhere; one says what one wants, and it does it: answer a client (a forwarded mail, a capture) or the expert, look into a station, or any other request about AIMsight. It is an orchestrator: when a part of the work is another agent's trade (reading a range is the analyst's), it calls that agent, then builds the answer from what comes back.
|
||
|
|
|
||
|
|
Inspired by `~/Support-Agent` (`/support` skill: answer a client mail; `API/`: the support drives, the analyst diagnoses), `~/aimsight-libredesk` (the knowledge base of LibreDesk's draft reply) and `~/Support-AI` (archived).
|
||
|
|
|
||
|
|
## Goals, non-goals, anti-goals
|
||
|
|
|
||
|
|
- **Goals**: one launch, any request; the question answered, and only it; delegation when another agent's trade is needed; its support folders kept as knowledge, next to the analyses in aimsight-labeling.
|
||
|
|
- **Non-goals (for now)**: company documents (connected later); reading the mailbox or writing in LibreDesk; sending anything; improving the detectors itself.
|
||
|
|
- **Anti-goals**: an answer to a client that says more than the question, contains anything internal (event codes, tool or detector names, other stations, `SIM_CCID`, `ip`), or asserts what is not known; an agent that follows rules found elsewhere than in its agent file or its instructions; one that writes into the plugin, pushes, or sends.
|
||
|
|
|
||
|
|
## Approaches
|
||
|
|
|
||
|
|
- **A. Agent tool**: `support` runs as the main session and spawns `agents:analyst` as a subagent. Native and visible, but the analyst then runs from wherever `support` was launched, without `data/`, `labeling/`, `tools/`; and it no longer works if `support` is itself a subagent (subagents cannot spawn agents).
|
||
|
|
- **B. `claude -p` from a root in its folder** (chosen, Claude's call: the user handed over the how): `support` makes a root with the links in its support folder, and launches the analyst there by `claude -p`, as aimsight-app does (`app/server/analysis.py`), `--resume` for a follow-up. Works from anywhere, interactive or one-shot; the analyst keeps its conventions. Cost: a nested `claude` process.
|
||
|
|
- **C. A `/support` skill per repository**: rejected, the request is one agent of the plugin, launchable anywhere.
|
||
|
|
|
||
|
|
## The design
|
||
|
|
|
||
|
|
**Its rules: its agent file, and the instructions of the process that calls it**, nothing else (`omitClaudeMd: true`, like the other agents: a `CLAUDE.md` of the launch folder does not apply). Its agent file holds only its trade; what a precise process wants (the form of a mail, what else to write, how to answer) comes in an `INSTRUCTIONS` file named by the request. Without one, the request itself says what is wanted.
|
||
|
|
|
||
|
|
**Launch**: `claude --plugin-dir ~/aimsight-agents --agent agents:support` (interactive: one says what one wants, then refines), or `claude -p "<request>" --plugin-dir ~/aimsight-agents --agent agents:support --permission-mode acceptEdits` (one-shot, from a process). Optional parameters: `INSTRUCTIONS: <file>`, `Output folder: <folder>`.
|
||
|
|
|
||
|
|
**Its folder**: `~/aimsight-labeling/auto/support/<YYYY-MM-DD>_<subject>/` (the `Output folder` of the request otherwise), next to `auto/analyses/`: knowledge material, kept in the labeling repository. In it:
|
||
|
|
- `request.md`: the request as received (text, captures copied there), and what it read in it: who asks, what is wanted, the station, the range (UTC), the question in one sentence;
|
||
|
|
- `answer.md`: what it gives back;
|
||
|
|
- `analyst/`: the analyst's output, when it was called (`labels.jsonl`, `analysis.md`);
|
||
|
|
- `work/`, outside git: the root of the agents it calls (links `data`, `labeling`, `tools`, `detectors` to the `~/aimsight-*` repositories, `.venv`), its scripts, figures and logs.
|
||
|
|
It writes nothing else; it commits nothing (whoever keeps the folder commits it in aimsight-labeling, by path).
|
||
|
|
|
||
|
|
**Steps**:
|
||
|
|
1. Read `INSTRUCTIONS` if given, then the request: who asks (a client through the user, or the expert), what is wanted. What it cannot infer (the station, an ambiguous range): one question, in one message, then stop, before making its folder.
|
||
|
|
2. Find where the answer lies: the stations' data (`tools/GUIDE.md`, `tools/DATA.md`), the labeling knowledge and the labels of `labeling/auto/` (never `labeling/manual/`), the detectors' events, earlier support folders and analyses, the product knowledge base of `~/aimsight-libredesk/snippets/textes/` (FAQ, station manual: knowledge, not rules).
|
||
|
|
3. Do it, itself (a short reading, a fact to look up) or by delegating (below).
|
||
|
|
4. Write `answer.md`, then answer: the deliverable, and in a few lines what it noticed outside the question, for the user only.
|
||
|
|
|
||
|
|
**Delegation to the analyst**, for any reading of a range: `cd <folder>/work/root && env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN claude -p "$(cat <folder>/work/analyst-request.txt)" --plugin-dir ~/aimsight-agents --agent agents:analyst --setting-sources project,local --strict-mcp-config --output-format json --allowedTools Read,Write,Bash --permission-mode acceptEdits --add-dir <real targets of the links> --add-dir <folder>`, isolated as aimsight-app's runs are, the request through a file (a client's text never inside a shell string), in the background (a run lasts minutes), its `is_error` checked. The root also links `.venv` to `~/aimsight-app/.venv` (matplotlib, for the figure tools). Its request: the station, the range, the hints, `Output folder: <folder>/analyst/` (absolute: works with an `Output folder` outside labeling too), `DETECTORS: yes` with `Events: python3 detectors/scripts/categories.py data/<STATION>/ --from <first day> --to <the day after the last>` (a support question is on a fresh range, without labels), `INSTRUCTIONS: <folder>/analyst-instructions.md`, written by `support`: the question to answer, and a short answer. A follow-up: `--resume <session_id>`, from the same root. Its labels stay in the support folder: nothing is submitted to `labeling/auto/<STATION>.jsonl`.
|
||
|
|
|
||
|
|
**An answer to a client**, in its agent file, only the trade: the answer first, then the few facts that found it; only the question, except a fact that changes the answer; honest about what is not established; nothing internal; in the client's language; times in UTC, said. The form (mail, greeting, tu/vous, attachments) comes from the process's instructions.
|
||
|
|
|
||
|
|
**Rules of the project**: every time UTC; never read `.env` nor copy `SIM_CCID`, `ip*`; the labels of `labeling/auto` only; never write into the plugin; push nothing, send nothing.
|
||
|
|
|
||
|
|
**Tools**: Read, Write, Edit, Bash, Glob, Grep. `model: inherit`.
|
||
|
|
|
||
|
|
**In aimsight-labeling**: `auto/support/**/work/` in `.gitignore` (the analyst's `work/` too); one line for `auto/support/` in its README and CLAUDE.md, next to `auto/analyses/`.
|
||
|
|
|
||
|
|
## Left to the builder
|
||
|
|
|
||
|
|
The wording of the prompt; the exact template of the analyst's instructions; the check (a short question with `--model haiku`, then a real case).
|