|
1 | | -# Customer Support Pack |
| 1 | +# animus-pack-customer-support |
2 | 2 |
|
3 | | -A first-party Animus reference pack that turns the orchestrator into an autonomous |
4 | | -tier-1 support agent. New tickets get triaged into categories, urgency-scored, and |
5 | | -a draft response is written for a human to review-and-send. The reviewer just edits |
6 | | -the draft and clicks send — Animus did the reading, the routing, and the writing. |
| 3 | +**Moved.** This reference pack now lives at its own repo: |
7 | 4 |
|
8 | | -This is **the first non-coding reference pack** for Animus. It exists to prove the |
9 | | -"self-hosted workflow engine for AI agents, BYO models, BYO data sources" framing |
10 | | -in practice and to give agencies, support leads, and ops teams a working starter |
11 | | -they can fork. |
| 5 | +→ **https://github.com/launchapp-dev/animus-pack-customer-support** |
12 | 6 |
|
13 | | -## What you'll need |
| 7 | +Install via: |
14 | 8 |
|
15 | | -- `animus` CLI installed (`curl -fsSL https://animus.sh/install | bash` or follow |
16 | | - [the install guide](../../docs/getting-started/installation.md)) |
17 | | -- An Anthropic API key exported as `ANTHROPIC_API_KEY`. The default |
18 | | - workflow YAML pins every agent to a Claude model (Haiku for the |
19 | | - cheap classify/handoff phases, Sonnet for drafting) and `setup.sh` |
20 | | - only installs `animus-provider-claude`. To use OpenAI or Gemini |
21 | | - instead, see [`docs/customizing.md`](docs/customizing.md) — you'll |
22 | | - edit each agent's `model` + `tool` and install the matching provider |
23 | | - plugin before running setup. |
24 | | -- A directory to drop ticket markdown files into. The pack provides 5 sample |
25 | | - tickets you can use to dry-run before wiring up a real source. |
26 | | - |
27 | | -## Setup |
28 | | - |
29 | | -From the root of your project, run: |
30 | | - |
31 | | -```bash |
32 | | -PROJECT_ROOT="$(pwd)" |
33 | | - |
34 | | -# 1. Install plugins, copy the workflow into .animus/workflows/, and |
35 | | -# split the bundled sample-tickets.md into one file per ticket |
36 | | -# under tickets/inbox/. setup.sh is idempotent; re-running never |
37 | | -# clobbers edits to existing ticket files. |
38 | | -bash packs/customer-support/scripts/setup.sh |
39 | | - |
40 | | -# 2. Smoke-test the markdown subject backend |
41 | | -animus subject list --kind ticket --project-root "$PROJECT_ROOT" |
42 | | - |
43 | | -# 3. Start the daemon |
44 | | -animus daemon start --auto-install --project-root "$PROJECT_ROOT" |
45 | | - |
46 | | -# 4. Dispatch a triage run against a single ticket. See "Dispatching |
47 | | -# tickets — current limitation" below for why we pass --title + |
48 | | -# --description instead of --subject-id. |
49 | | -TICKET_FILE="$PROJECT_ROOT/tickets/inbox/TKT-1001.md" |
50 | | -animus workflow run animus.customer-support/triage-ticket \ |
51 | | - --title "$(head -n 1 "$TICKET_FILE" | sed 's/^## //')" \ |
52 | | - --description "$(tail -n +2 "$TICKET_FILE")" \ |
53 | | - --sync \ |
54 | | - --project-root "$PROJECT_ROOT" |
| 9 | +``` |
| 10 | +animus pack install launchapp-dev/animus-pack-customer-support@v0.1.0 |
55 | 11 | ``` |
56 | 12 |
|
57 | | -Inspect the run. Animus generates a fresh UUID workflow id per dispatch |
58 | | -and writes outputs under |
59 | | -`~/.animus/<repo-scope>/state/workflows/<workflow-id>/phase-outputs/`, |
60 | | -so you can either: |
61 | | - |
62 | | -1. **List recent runs to find the id**, then drill in: |
63 | | - |
64 | | - ```bash |
65 | | - animus workflow list --project-root "$PROJECT_ROOT" |
66 | | - animus output phase-outputs \ |
67 | | - --workflow-id <id-from-list> \ |
68 | | - --project-root "$PROJECT_ROOT" |
69 | | - ``` |
70 | | - |
71 | | -2. **Capture the id at dispatch time via `--json`** (the CLI envelope is |
72 | | - `animus.cli.v1` — payload sits under `data`): |
73 | | - |
74 | | - ```bash |
75 | | - WF_ID=$(animus workflow run animus.customer-support/triage-ticket \ |
76 | | - --title "..." --description "..." --sync --json \ |
77 | | - --project-root "$PROJECT_ROOT" \ |
78 | | - | jq -r '.data.workflow_id') |
79 | | - animus output phase-outputs --workflow-id "$WF_ID" \ |
80 | | - --project-root "$PROJECT_ROOT" |
81 | | - ``` |
82 | | - |
83 | | -3. **Browse on disk** if you prefer. Persisted per-phase outputs live |
84 | | - under `~/.animus/<repo-scope>/state/workflows/<workflow-id>/phase-outputs/` |
85 | | - as JSON files, one per phase. Run logs live under |
86 | | - `~/.animus/<repo-scope>/runs/<run-id>/`. List the most recent |
87 | | - workflow output dirs for any active project: |
88 | | - |
89 | | - ```bash |
90 | | - ls -dt ~/.animus/*/state/workflows/*/phase-outputs/ 2>/dev/null \ |
91 | | - | head -5 |
92 | | - ``` |
93 | | - |
94 | | -The exact field shapes of `--json` envelope payloads are evolving; if any |
95 | | -of the `jq` paths above return `null` on your install, run the command |
96 | | -without `--json` once to see the human output, then adapt. |
97 | | - |
98 | | -## Dispatching tickets — current limitation |
99 | | - |
100 | | -`animus workflow run` currently accepts `--task-id`, `--requirement-id`, or |
101 | | -`--title` to identify the subject. There is **no first-class |
102 | | -`--subject-id` flag for arbitrary subject kinds yet**. That means today's |
103 | | -dispatch path for this pack creates a `custom` subject and passes the |
104 | | -ticket title + body inline (the `--description` flag) — the workflow's |
105 | | -LLM phases see the ticket content and produce a draft, but the final |
106 | | -`ticket_flag_for_review` phase cannot write the status back to the real |
107 | | -`animus-subject-markdown` ticket record (the run is not associated to |
108 | | -the ticket's backend-qualified id). |
109 | | - |
110 | | -What works today: |
111 | | - |
112 | | -- `classify`, `draft_response`, and `summarize_for_human` produce real |
113 | | - output you can read via `animus output phase-outputs`. |
114 | | -- The reviewer takes the draft and acts on it in their support tool. |
115 | | - |
116 | | -What doesn't work end-to-end yet: |
117 | | - |
118 | | -- `ticket_flag_for_review` updating the ticket subject's status. The phase |
119 | | - prompt instructs the agent to call `animus subject status --kind |
120 | | - ticket --id <id>` and that will work if the agent passes the correct |
121 | | - backend-qualified id — but the run envelope doesn't carry it |
122 | | - automatically because the dispatch went through `--title`. |
123 | | - |
124 | | -**The fix is a CLI primitive — `animus workflow run --subject-id <id> |
125 | | ---subject-kind ticket`** — which would let the markdown backend resolve |
126 | | -the subject context (title + body) up-front and thread the |
127 | | -backend-qualified id through the run envelope. That's the headline |
128 | | -missing primitive this pack surfaces. |
129 | | - |
130 | | -## What you get |
131 | | - |
132 | | -The `triage-ticket` workflow has four phases: |
133 | | - |
134 | | -| Phase | What it does | |
135 | | -|---|---| |
136 | | -| `classify` | Reads ticket subject + body. Returns a JSON verdict with `category` (billing / bug / feature / security / integration / other) and `urgency` (low / med / high / critical). | |
137 | | -| `draft_response` | Picks tone from the category (apologetic for billing, investigatory for bugs, curious for feature asks, urgent for security) and drafts a customer-facing reply. | |
138 | | -| `summarize_for_human` | Produces a TL;DR + the top 3 suggested edits for the reviewer so they can approve fast. | |
139 | | -| `ticket_flag_for_review` | Sets the ticket subject status to `blocked` (the protocol-normalized "needs human action" state) and adds an `awaiting-human-review` label so it surfaces in the reviewer's inbox. | |
140 | | - |
141 | | -Outputs land under `~/.animus/<repo-scope>/runs/<workflow-id>/` like any other |
142 | | -Animus workflow. Each phase's structured output is captured separately for audit. |
143 | | - |
144 | | -## Customize it |
145 | | - |
146 | | -This pack is meant to be forked. The two files you'll edit most are: |
147 | | - |
148 | | -- **`workflows/triage-ticket.yaml`** — change the categories, urgency rubric, tone |
149 | | - guides, models per phase (cheap Haiku for `classify`, stronger model for |
150 | | - `draft_response`), or the directives the agents see. |
151 | | -- **`subjects/sample-tickets.md`** — replace with your own tickets once you've |
152 | | - validated the pipeline. |
153 | | - |
154 | | -For deeper changes — swapping the LLM, wiring to Zendesk/Intercom, adjusting the |
155 | | -human-review gate — see [`docs/customizing.md`](docs/customizing.md). |
156 | | - |
157 | | -## What's NOT included |
158 | | - |
159 | | -Honesty section. This is a **reference pack**, not a turnkey product: |
160 | | - |
161 | | -- **No real ticket source integration.** The pack uses |
162 | | - `animus-subject-markdown` reading markdown files from a directory. To pull |
163 | | - from Zendesk, Intercom, Front, Help Scout, or email, you need a subject |
164 | | - backend plugin for that source. See `docs/customizing.md` for the shape. |
165 | | -- **No send-on-approve UI.** The reviewer reads the draft from `animus output` |
166 | | - output and copies it into their real support tool. A "send from Animus" |
167 | | - experience is a follow-up pack (it would need an action plugin per support |
168 | | - tool). |
169 | | -- **No long-running context.** Each ticket is triaged independently. There's no |
170 | | - cross-ticket memory ("we've already replied to this user 3 times this week" |
171 | | - is not modelled). |
172 | | -- **No SLA timers.** Urgency is scored, but the pack doesn't escalate when a |
173 | | - ticket goes stale. Wire up a schedule + a dispatcher agent (the |
174 | | - `requirements` pattern in `.animus/workflows/requirements.yaml` shows how) |
175 | | - to add that. |
| 13 | +Or clone for inspection / forking: |
176 | 14 |
|
177 | | -If you build any of the above on top of this pack, please open a PR — the |
178 | | -intent is that this pack grows into a library of support patterns over time. |
| 15 | +``` |
| 16 | +git clone https://github.com/launchapp-dev/animus-pack-customer-support |
| 17 | +``` |
179 | 18 |
|
180 | | -## Architecture |
| 19 | +This stub will be removed entirely in a future ao-cli release once the |
| 20 | +`animus pack install` flow + marketplace discovery are wired up. For |
| 21 | +now it's kept as a redirect for anyone browsing the ao-cli tree. |
181 | 22 |
|
182 | | -See [`docs/architecture.md`](docs/architecture.md) for a 1-page diagram of how |
183 | | -tickets flow through the phases and which plugins are involved. |
| 23 | +See the parent index at [`packs/README.md`](../README.md) for the full |
| 24 | +list of reference packs. |
0 commit comments