1) Domain intake layer
Receives domain events (lead, job, quote, invoice, review), validates scope, and maps to the owning agent.
ServiceHub Agent Architecture
ServiceHub AI Agents: How the System Actually Runs
This is an implementation-focused guide for teams designing or reviewing automation behavior in production.
Why this page exists
The features page explains product value. This page explains architecture decisions and operational behavior so engineering, ops, and support teams can align.
- Defines clear boundaries for each agent to reduce coupling.
- Documents event handoffs and idempotency strategy.
- Captures tenant/store isolation and control requirements.
- Outlines reliability and cost controls for scaled workloads.
Human vs Agent in daily operations
This is where automation changes outcomes in real service workflows.
| Scenario | Human-only flow | LeadDuo Agent flow | Business impact |
|---|---|---|---|
| Missed call while tech is on a roof | Call is missed and callback is delayed until someone is free. | Instant text-back, quick triage, and quote/booking link sent automatically. | Higher chance of recovering leads that would have been lost. |
| After-hours emergency inquiry | No response until morning; customer contacts competitors. | Immediate acknowledgment and emergency routing based on rules. | Faster response and improved close rate on urgent jobs. |
| Quote sent but customer goes silent | Manual follow-up is inconsistent and often skipped. | Timed, policy-based follow-ups continue until stop conditions are met. | More quote recoveries with less admin effort. |
| Invoice past due | Team manually chases payments across channels. | Automated reminder cadence with payment links and audit trail. | Lower days outstanding and steadier cash collection. |
Examples illustrate typical outcomes and do not guarantee specific revenue.
Reference architecture
ServiceHub automation is designed as layered agent orchestration rather than one large monolith function.
2) Agent decision layer
Applies business policy (rules, thresholds, dry-run/auto mode, emergency overrides) and decides next action.
3) Action execution layer
Performs side effects (send message, assign tech, schedule reminder, emit payment chase step) using idempotent keys.
4) Observability and audit layer
Writes service activity history and execution outcomes for explainability, debugging, and compliance.
Agent responsibilities
Each agent should own one business domain and expose explicit event interfaces.
Concierge Agent
Customer communication hub for inbound/outbound SMS and email, including triage and response routing.
Intake Agent
Collects missing job requirements (forms, photos, confirmations) before dispatch execution.
Scheduling Agent
Handles assignment and dispatch optimization with rule constraints and optional dry-run previews.
Billing Agent
Runs quote/invoice/deposit communication and payment chase workflows with explicit step states.
Reputation Agent
Automates review request and post-service sentiment workflows.
Ops & Integrations Agent
Runs staff summaries, integration token refresh, and internal operational notifications.
Responsibility matrix
| Agent | Primary trigger | Primary output | Control mode |
|---|---|---|---|
| Concierge | inbound message / reminder due | SMS/email action | template + gating rules |
| Intake | job missing required data | intake request event | required field policy |
| Scheduling | new/updated scheduled work | assignment or optimization plan | dry-run / auto / threshold |
| Billing | invoice lifecycle events | payment outreach sequence | cadence + escalation policy |
| Reputation | job completed | review request + analysis | timing + approval workflow |
| Ops/Integrations | scheduled ops checks | staff/internal notifications | store/user scope |
Handoff pattern
- Domain event is received.
- Owning agent verifies tenant and store boundaries.
- Agent decides action based on policy and context.
- Agent emits typed event or executes side effect.
- Outcome is logged to activity history.
- Retry path uses deterministic idempotency key.
Event contract discipline
Use a stable envelope for all inter-agent messages so new handlers can be added without breaking existing flow.
Example event envelope
{
"name": "servicehub.dispatch.optimization_requested",
"data": {
"userId": "user_abc123",
"storeId": "store_xyz789",
"idempotencyKey": "opt|store_xyz789|2026-02-06",
"payload": "{"mode": "dry_run", "date": "2026-02-06"}"
}
}Security and isolation guardrails
- Always scope reads/writes by owner userId and storeId.
- Reject execution if scope cannot be proven.
- Use per-endpoint rate limits on public flows.
- Use OTP attempt controls and abuse throttling on verification endpoints.
- Log before/after state for high-impact automation changes.
Reliability patterns
- Idempotent execution keys for message sends and state transitions.
- Catch-up sweeps for delayed or missed timed events.
- Explicit retry/backoff for external provider failures.
- Activity timeline entries for operator replays and debugging.
How we improved efficiency and invocation cost
Moved from frequent polling to event-driven timing
We schedule per-entity delayed events where possible and keep cron sweeps lightweight as safety nets.
Batched work where semantics allow
We use set-based claims and batched emits to reduce per-item step overhead.
Suppressed duplicate trigger noise
We apply idempotency, debounce, and rate-limit controls so noisy upstream events do not multiply invocations.
Minimize unnecessary reads
We load only fields needed for the specific decision path to reduce CPU and query cost.
How we rolled this out
Phase 1: Suggestion mode first
We started with agent-generated plans/messages and human approval to validate correctness and team trust.
Phase 2: Hybrid automation
We moved routine low-risk actions to auto-run while keeping high-impact changes behind explicit apply.
Phase 3: Controlled auto mode
For stable paths, we enabled full automation with guardrails, audit logs, and catch-up workers.
How We Avoid Common Anti-Patterns
- Split workflows into domain agents instead of one mega-function.
- Used stable rate-limit keys that do not include user-controlled bypass values.
- Applied approved plan snapshots instead of recomputing new plans at apply time.
- Enforced fail-closed validation when required model checks are unavailable.
- Restricted operations to explicit tenant/store scope before read/write actions.
- Replaced heavy cron sweeps with per-entity scheduling plus lightweight catch-up.
FAQ
Who owns customer reminders and follow-ups?
Scheduling/Billing determine due events; Concierge executes outbound customer messaging.
Should dispatch optimization run automatically on every job?
Generally no. Use manual store/day triggers with dry-run previews first, then selectively enable auto mode.
How do we prevent cross-tenant leakage?
Every handler must enforce tenant/store scoped queries and reject ambiguous ownership.
How do we recover from delayed events?
Keep a lightweight catch-up sweep that re-enqueues overdue entities with idempotent keys.
Put This Architecture to Work
Use these patterns in your own operations: automate routine work, keep approvals for high-impact actions, and maintain clear audit trails.
Need the product walkthrough instead? Jump to the features page.