Enquiry Agent¶
Thinklio Built-in Agent Specification Version 0.1 | March 2026
1. Purpose and Problem Statement¶
The Enquiry Agent is the inbound intake agent. It monitors configured inbound channels — email addresses, messaging platform numbers, web form webhooks — and converts inbound contacts into structured Items that can be tracked, assigned, prioritised, and resolved.
It is the bridge between the outside world reaching out and the internal team responding. Without it, inbound contacts are handled ad hoc: emails pile up in a shared inbox, WhatsApp messages go to someone's personal phone, and there's no record of what came in, what was responded to, or what's still waiting.
The Enquiry Agent gives every inbound contact a structured record and a place in a managed workflow.
2. The Item Data Object¶
Items are the Enquiry Agent's primary output and the central data object it manages. An Item represents a single inbound contact or internally-created work request.
Item
├── item_id UUID
├── type enum (enquiry | support | issue | feedback | complaint | order | other)
├── status enum (new | open | pending | waiting_on_contact | resolved | closed)
├── priority enum (urgent | high | normal | low)
├── subject string
├── description string (full content of the inbound contact)
├── source Source
│ ├── channel enum (email | sms | whatsapp | telegram | slack | web_form | manual | agent)
│ ├── address string (email address, phone number, etc.)
│ ├── received_at timestamp
│ └── raw_ref string | null (message ID, webhook event ID, etc.)
├── contact
│ ├── person_id UUID | null (Rolodex match)
│ ├── org_id UUID | null (Rolodex match)
│ ├── name string | null (from inbound if person not matched)
│ └── contact_detail string | null (email/phone from inbound)
├── assigned_to UUID | null (user or team)
├── team string | null
├── tags string[]
├── created_at timestamp
├── created_by UUID (agent or user)
├── updated_at timestamp
├── due_at timestamp | null
├── resolved_at timestamp | null
└── linked_records[]
├── record_type enum (Note | Task | Person | Organisation | Artefact | Interaction)
└── record_id UUID
Items are distinct from Tasks: Tasks are things a user needs to do; Items are inbound work requests that may generate Tasks. An Item can be linked to one or more Tasks (e.g. "investigate this issue" and "respond to the customer" as separate tasks arising from a single Item).
3. UI Structure¶
Chat Tab¶
Natural language Item management: - "What's in the queue today?" - "Assign the Lavan Lawyers enquiry to James" - "Show me all open support issues more than 3 days old" - "Mark item #482 as resolved — reply sent" - "How many items came in this week compared to last week?" - "Create a new Item: phone call from Tom Archer at Novansa asking about the contract renewal"
Queue Tab¶
The primary working view. A prioritised list of open Items, filterable by type, status, priority, assignee, team, channel, and date. Each row shows: type badge, subject, contact (linked to Rolodex where matched), channel icon, age, priority indicator, and assignee.
Clicking an Item opens the Item detail panel: - Full description / original message - Contact details with Rolodex link (or "new contact" prompt) - Interaction history with this contact - Linked tasks - Activity log (all status changes, assignments, notes) - Reply action (opens Mail or Messenger Agent in context) - Assign, set priority, set due date, add note, close/resolve controls
Board Tab¶
A Kanban view of Items by status:
Useful for teams managing shared queues. Cards can be filtered by assignee or team.
Analytics Tab¶
Aggregate views over Item data: - Volume by day/week/month and by type - Average resolution time - Items by assignee and team - Open items ageing (how long items have been open, by priority band) - Channel breakdown (where inbound contacts are coming from) - Common tags and topics (derived from Item subjects and descriptions)
4. Inbound Channel Configuration¶
The Enquiry Agent monitors one or more inbound channels. Each channel is configured with:
Channel
├── channel_id UUID
├── type enum (email | sms | whatsapp | webhook)
├── address string (email address, phone number, or webhook URL)
├── label string (e.g. "Support inbox", "Hello address", "Web enquiry form")
├── default_item_type enum (enquiry | support | issue | etc.)
├── default_priority enum
├── default_team string | null
├── auto_assign_to UUID | null
├── classification_rules ClassificationRule[]
└── credential_ref UUID (Keeper reference for channel access)
Classification Rules¶
Items created from a channel can be automatically typed, prioritised, and assigned based on content rules:
ClassificationRule
├── conditions[]
│ ├── field enum (subject_contains | body_contains | sender_domain | sender_email)
│ ├── operator enum (contains | equals | matches_regex)
│ └── value string
└── actions[]
├── set_type enum | null
├── set_priority enum | null
├── assign_to UUID | null
└── add_tag string | null
Example: emails to support@org.com with "urgent" in the subject → type: support, priority: high.
5. Contact Matching and Creation¶
When an Item is created, the Enquiry Agent queries Rolodex to match the inbound contact:
- Match by email address or phone number (exact match)
- If matched: link the Item to the existing Person record
- If not matched: create a minimal unverified Person record from available inbound data (name header, email, phone), flag as unverified, link the Item
The unverified flag prompts a user to review and enrich the record in Rolodex. It does not block Item processing.
If the contact is matched and has interaction history, the Item detail panel surfaces a brief relationship summary: previous Items, last interaction date, and any open Tasks linked to their record.
6. Configuration¶
6.1 Admin Configuration¶
| Setting | Description |
|---|---|
| Item types | Configurable set of Item types for this workspace |
| Default SLA by priority | Expected resolution times by priority level |
| Team definitions | Teams that Items can be assigned to |
| Auto-assignment rules | Routing logic for new Items beyond channel-level defaults |
| Escalation triggers | Conditions under which an Item is automatically escalated (e.g. open > 48 hours at high priority) |
| Notification policy | How assignees and teams are notified of new and escalated Items |
6.2 User Configuration¶
| Setting | Description |
|---|---|
| My queue filters | Default filters for the Queue tab |
| Notification preferences | When to be notified about Items assigned to the user |
| Reply tone | Default tone for agent-drafted replies (professional / friendly / concise) |
7. Agent Capabilities¶
| Capability | Description |
|---|---|
| Create item | Create a new Item from any source |
| Update item | Change status, priority, assignment, type, or other fields |
| Assign | Assign an Item to a user or team |
| Query items | Answer questions about Item state ("how many open support issues?") |
| Summarise queue | Natural language summary of current Item queue for a user or team |
| Draft reply | Compose a reply to the contact via the appropriate channel |
| Escalate | Increase priority and notify the relevant person |
| Close/resolve | Mark an Item as resolved or closed with optional resolution note |
| Create task from item | Generate a Taskmaster task linked to an Item |
| Analytics summary | Produce a volume or performance summary for a given period |
8. SLA Tracking¶
Each Item has an implicit SLA based on its priority and the workspace SLA configuration:
| Priority | Default target resolution time |
|---|---|
| Urgent | 4 hours |
| High | 24 hours |
| Normal | 72 hours |
| Low | 7 days |
Items approaching or breaching SLA are: - Flagged with a visual indicator in the Queue and Board views - Surfaced proactively in the Summary tab of Taskmaster for assigned users - Subject to escalation if an escalation trigger is configured
9. Inter-Agent Behaviour¶
- Mail Agent routes inbound emails matching routing rules to the Enquiry Agent
- Messenger Agent routes inbound messages matching routing rules to the Enquiry Agent
- Rolodex is queried for contact matching and interaction history; new contacts are created in Rolodex
- Taskmaster receives tasks created from Items
- Keeper provides credentials for monitored inbound channels
10. Use Cases¶
UC-1: Inbound support email handling¶
A customer emails support@org.com. The Enquiry Agent creates an Item (type: support, normal priority), matches the sender to an existing Rolodex contact, links their interaction history, and assigns it to the support team. A team member opens the Item, sees the customer's prior support history, drafts a reply via the Mail Agent, and marks the Item as pending.
UC-2: Inbound WhatsApp enquiry¶
A prospective client sends a message to the business WhatsApp number. The Messenger Agent routes it to the Enquiry Agent. An Item is created (type: enquiry), a minimal Rolodex record is created for the unknown sender, and it is assigned to the sales team.
UC-3: Manual item creation¶
A user takes a phone call from a client. They open the Enquiry Agent and say "create a new item: Tom Archer from Novansa called to say the contract renewal is delayed by two weeks — he'll send an update on Friday." The agent creates an Item, links it to Tom's Rolodex record, and creates a linked Taskmaster task: "Follow up with Tom Archer if no update received by Friday."
UC-4: Queue morning briefing¶
The team lead asks "what does the queue look like this morning?" The agent returns: 4 new items overnight (2 support, 1 enquiry, 1 complaint), 3 items approaching SLA breach, and a summary of the oldest open unassigned item.
UC-5: Escalation¶
An Item has been open at high priority for 22 hours without a status update. The escalation trigger fires: the Item is bumped to urgent, the assigned user receives a notification, and the team lead is notified if no action is taken within 2 hours.
11. Open Questions¶
- Item types are configurable, but should there be a set of canonical types that cannot be removed (support, enquiry, issue) to ensure other agents can rely on them?
- Web form webhook support requires Thinklio to expose a webhook endpoint per channel. This is infrastructure scope — should it be in the initial release or deferred?
- The Analytics tab is useful but potentially scope-heavy. A minimal first version might simply show volume counts; trend charts and resolution time analysis could follow.
- Multiple assignees per Item (e.g. assigned to a team and individually to two people) adds flexibility but complicates notification logic. Single assignee for the initial release?
Previous: Messenger Agent