Build a SaaS onboarding investigation agent

A new customer signs up, maybe connects one thing, then goes quiet. The reason is usually somewhere in the product events, the CRM notes or the support queue, and finding it means opening three systems and lining up dates. That slow, repetitive work is a fair job for a narrow agent.

This tutorial applies the nine-step method from our guide to building your first AI agent without code to that job, focusing on what changes when the data is product usage and customer records. AI Chronicle has not built this agent in any product. The worked example is a labelled hypothetical, and no outputs, accuracy figures or customer results are claimed. Where we mention a vendor, we report what its documentation describes, read in October 2026.

What the agent does, and what it must not

If you need a refresher on what makes software an agent, see our explainer on how AI agents plan and use tools. Here, the job statement is:

When a CSM flags an account, or an account passes the onboarding checkpoint without meeting the written activation definition, gather that account's product events, CRM notes and linked support tickets for the onboarding window. Test the listed stall hypotheses against them. Write a diagnosis memo with evidence, confidence and one suggested next action to the CSM review queue. Never contact the customer, change the account or update the CRM.

The suggested next action is advice to the CSM. A person decides whether anything reaches the customer.

When not to build this agent

Skip it, or fix something else first, if any of these are true:

• You have no written activation definition. Without one, the agent will invent its own idea of "stalled".
• Your events are not linked to accounts. In business software, usage questions are about the account, not one user. Segment's spec describes the Group call as how you "associate an individual user with a group, such as a company, organization, account, project, or team".[1] If events carry no account identifier, fix the instrumentation first.
• A rule would do. If "no sign-in for seven days" is all you need to know, a fixed alert is cheaper. Our guide on choosing between an AI agent and an AI workflow covers that line.
• You cannot make the connections read-only. If a tool can write, the design is no longer this one.
• You want automated outreach. That is a different, higher-risk build.
• Nobody responsible for data protection has agreed the purpose. See the next section.

Start with the purpose, then strip the data

Events, CRM notes and tickets all contain personal data about the customer's staff. In the EU and UK, the GDPR principles apply, and this agent tests several at once. This is design guidance, not legal advice.

Purpose limitation. Article 5(1)(b) requires personal data to be collected for "specified, explicit and legitimate purposes" and not processed in an incompatible way.[2] The UK regulator, the ICO, says organisations must check that a new purpose is compatible with the original one and warns against "function creep".[3] Write the agent's purpose down: diagnosing onboarding blockers so the CSM can help the account. Then refuse to stretch it into sales scoring or judging individual users.

Data minimisation. Article 5(1)(c) requires data to be "adequate, relevant and limited to what is necessary in relation to the purposes for which they are processed".[2] The ICO's guidance puts the practical rule plainly:

“You must not collect personal data on the off-chance that it might be useful in the future.”

— ICO, Principle (c): Data minimisation.[4]

Data protection by design and by default. Article 25(2) requires measures ensuring that, by default, "only personal data which are necessary for each specific purpose of the processing are processed", covering the amount collected, the extent of processing, storage period and accessibility.[2] The ICO adds that you must "specify the personal information you need before you start using it", and that a data protection impact assessment is required for high-risk processing and good practice otherwise.[5]

In practice, that means an allowlist of fields per source, applied before anything reaches the agent:

• Product events: event name, timestamp, account ID and a pseudonymous user ID. Segment's B2B SaaS spec, for example, lets a Signed Up event carry first name, last name, email and phone.[6] The agent needs none of them to see that a second user never joined.
• CRM: account stage, owner and onboarding notes. Not deal values or contact details.
• Tickets: subject, status, tags, dates and a body with personal details masked.

Amplitude's documentation describes Data Access Control, which can hide properties classified as PII, revenue or sensitive, but lists it as an Enterprise feature and notes that organisation admins always see all classifications.[7] A filtered view or export you control is more portable.

Tools and permissions

Each tool returns data for one account only. OWASP's guidance on excessive agency, a top risk for applications built on large language models, recommends read-only access where reading is all that is needed and puts the enforcement outside the model:

“Implement authorization in downstream systems rather than relying on an LLM to decide if an action is allowed or not.”

— OWASP Gen AI Security Project, LLM06:2025 Excessive Agency.[8]

Check the defaults. Zendesk's developer documentation warns: "If you don't specify a scope, the token defaults to full read and write access across all Zendesk resources."[9] It recommends requesting the narrowest scope and setting allowed scopes on the OAuth client as a ceiling.[9] Assume every connector is permissive until checked.

The worked example: a stalled trial account

This is a hypothetical design example. The account, events and memo below are invented to show the shape of a run. They are not outputs from any system.

Imagine a project-management SaaS company. Its written activation definition, owned by the product team, says an account is activated when it has connected its calendar integration and at least two users have each created a project. Account 4471, a fictional ten-person agency, started a trial and has met neither condition at its onboarding checkpoint.

The agent reads the account's events. The admin signed in on three separate days. A custom Integration Connect Failed event from the company's own tracking plan fired three times on day two. There are no Invite Sent events. One ticket from day two reports a calendar-sync error and is waiting on the customer. A CSM note from the kickoff call says the agency's IT contractor must approve new OAuth apps.

The agent then tests each hypothesis in the evidence matrix below.

AI Chronicle

Two rows light up. The failed connection events and the open ticket point to a setup error. The CRM note points to a pending approval. The memo might read:

ACCOUNT        4471 (onboarding day 9; activation definition v3)
STATUS         Not activated: calendar not connected; 1 of 2 required users
LIKELY CAUSE   Calendar connection blocked, probably pending the customer's
               OAuth app approval
CONFIDENCE     Medium. Events, ticket and CRM note agree on the blocker;
               no source confirms the approval is still pending
EVIDENCE       - Integration Connect Failed x3, day 2 (events)
               - Ticket: calendar-sync error, status pending (support)
               - Kickoff note: IT contractor approves OAuth apps (CRM, CSM opinion)
ALSO CONSIDERED Single-user evaluation: no Invite Sent events, but likely
               downstream of the blocker. Not a separate diagnosis.
NEXT ACTION    CSM to ask the admin whether IT approval is pending, and
  (for CSM)    check with support on the open ticket
OPEN QUESTIONS Was the approval request ever sent?

Notice the label on the CRM note. The ICO's guidance on data minimisation makes a point that suits this job:

“…your records should make clear that it is opinion rather than fact.”

— ICO, Principle (c): Data minimisation.[4]

Activation is your definition, not the agent's

The weakest word in this design is "stalled". There is no universal activation metric or benchmark onboarding time, and the agent must not invent one, such as "most accounts activate within a week", unless you measured it in your own data and supplied the result.

Write the definition before building. Amplitude's taxonomy playbook starts tracking-plan design with business objectives, one of which is finding the "aha" moment in the product, then breaks them into the events on each critical path.[10] The output of that exercise, not the model, defines activation.

Decide whether it is measured per user or per account. Amplitude's documentation notes that it reports on individual users by default; with its account-level reporting add-on, different members of a group can complete different funnel steps and still count as a conversion.[11] User-level data can make an account look stuck when two colleagues have each done half the work. Version the definition and quote the version in every memo.

Failure modes specific to this agent

• Mistaking a tracking gap for a stall. Missing events can mean a broken release, not a quiet customer. Route those to the data owner.
• Treating CRM notes as facts. Notes are a CSM's interpretation at a moment. Label them as opinion and date them.
• Identity mismatches. The product's account ID, the CRM company record and the ticketing organisation may not line up. If IDs disagree, stop and flag; never merge records by name.
• Prompt injection through tickets. A ticket is customer-written text. OWASP's prompt-injection guidance covers indirect injection from external content and advises: "Separate and clearly denote untrusted content to limit its influence on user prompts."[12] Read-only tools limit what any injected instruction could do.
• Sensitive data in free text. Customers paste all sorts into tickets. Redact before the agent reads.
• Function creep. A tidy account dossier is tempting to reuse for upsell targeting or judging the customer's staff. That is a new purpose and needs its own assessment.[3]

For a broader way to trace which layer of an agent failed, see our guide to why AI agents fail. Hallucinated causes are a special risk here; our explainer on why plausible AI answers fail explains why fluent wording is not evidence.

Test cases before launch

Each case is a constructed account with a written expected outcome. The Result column is empty on purpose: these are cases to run, not results we observed.

Run each case several times after any change to instructions, tools, fields or model, and record the configuration version. Our analysis of what AI agent demos leave out explains why one clean run proves little.

Rolling out, and who answers for it

Follow the method guide's staged rollout: shadow mode first, comparing memos with what CSMs concluded on their own, then memos in the CSM queue, where each acceptance, edit or rejection becomes evidence for any widening.

Name the owners of the activation definition and the field allowlist, the memo reviewers and whoever can switch the agent off. Set a retention period for memos, since they are records about named people. The CSM, not the agent, answers for what happens next; our analysis of who is accountable when an AI agent acts takes that question further.

Questions readers commonly ask

Can the agent message the customer if the CSM approves?

Not in this design. Keeping outreach in the CSM's own tools means the agent never holds a send ability that injected text could misuse. Customer-email drafting would be a new agent with its own approval step and tests.

Do we need customers' consent to run this agent?

It depends on your lawful basis, your contracts and what you told users in your privacy information, so ask whoever handles data protection. The ICO's guidance says to document purposes and check that any new purpose is compatible with the original one.[3]

Which analytics tool works best?

AI Chronicle has not tested any. What matters is that events carry an account identifier, that you can export only allowlisted fields and that the connection is read-only. Segment and Amplitude both document account-level concepts.[1][11]

Why not let the agent update the CRM with its diagnosis?

A draft diagnosis is a hypothesis; once it sits in the CRM it starts to look like fact. Let the CSM decide what is recorded.

The next step

Once the agent is producing memos your CSMs trust, apply the same pattern to a reporting job with more numbers and fewer people: build a growth reporting agent that assembles metrics with their sources and flags what it cannot verify.

About these sources

All pages were accessed on 16 October 2026. Regulations and regulator guidance are cited for the principles they state; this article is not legal advice. ICO guidance applies to the UK GDPR, which mirrors the EU text for the provisions cited, and the ICO notes that some pages are under review following the Data (Use and Access) Act 2025. Vendor documentation establishes what a product is described as doing, not how well it works. AI Chronicle has not built or tested the example agent; the account, memo, tables and test cases are illustrative.

Related reading

• Build a research agent with source verification
• Build an invoice-exception investigation agent