Design an Agent: Detect, Investigate, Act

Every useful FunnelStory agent does three things: it detects a moment worth acting on, investigates the account before deciding anything, and acts — either on its own or by drafting the next step for a person to approve. Designing those three parts on paper first is the fastest way to an agent your team trusts. This guide gives you the worksheet, shows how each column maps to FunnelStory, and walks through three filled-in examples you can build with Claude.

The same shape runs through FunnelStory's own agents: the Needle Mover investigation detects an open concern, reads the account's evidence, and drafts an Action Card.

The worksheet

Fill in one row per agent before you build anything.

Use case	Detect	Investigate	Act	Mode	Measure
What outcome does this agent serve, for which accounts?	What event or condition starts a run?	What must the agent know about the account before it decides?	What does it do, and for whom?	Assist (a person approves) or Auto (it acts)	How will you know it's working?

Keep each agent to one use case. Two narrow agents are easier to test, trust, and measure than one that tries to cover everything.

Detect: choose the trigger

The Detect column becomes the agent's trigger.

You want to catch…	Trigger	Configure
A customer email, chat, ticket, or meeting as it arrives	Conversation	The conversation types to watch
A new concern or opportunity, such as a pricing worry or a champion leaving	Needle Mover	The labels and impacts to watch
A change FunnelStory computes, such as a prediction moving to Churn	Signal	The signal rules, such as Subscription Tag Change
A product event, such as a feature used for the first time	Activity	The activities to watch
Every account that matches a condition today, such as an Outcome Agent roster or renewals 30 days out	Query	SQL that returns one row per account; each row starts one run
A recurring digest	Schedule or Interval	When to run

Most triggers also take an account filter, so you can limit a run to, say, enterprise accounts or accounts predicted to churn. Detect narrowly: an agent that fires on every email trains your team to ignore it.

Investigate: decide what the agent reads

The Investigate column is what separates a reliable agent from one that guesses. Instead of reconstructing the customer from raw logs, the agent reads the account's accrued context from FunnelStory's semantic database with the semantic.query function, usually as a tool on an AGENT step so it can pull more evidence when the first pass isn't enough.

Question the agent should answer	Where it looks
Who are the stakeholders and champions, and what do they care about?	account_profiles, and facts with kind stakeholder
What does the account care about, and what value has it seen?	account_profiles, and facts with kinds concern, value, outcome, and commitment
Is the relationship thin or fading?	relationship_map_history
What's open right now?	needle_movers, tickets, and tasks
What happened recently?	conversations, meetings, and activities
What's the commercial picture?	accounts: ARR, renewal date, prediction, and health score

Start with account_profiles for a consolidated account narrative, and reach for the raw tables only for specifics. Write the investigation step's prompt to cite what it found — the account, the date, the source — so the person reviewing the output can check it.

Act: choose Assist or Auto

The Act and Mode columns decide who is in control.

Mode	How it works	Functions
Assist	The agent drafts; a person reviews and acts. Output lands as an Action Card with the reasoning, next steps, and a drafted email the CSM can edit and send.	tasks.create
Auto	The agent acts on its own.	slack.send_message, email.send, hubspot.update_record, hubspot.enroll_contact_in_sequence, salesforce.update_record

A good rule: anything a customer will read starts in Assist. Internal notifications, such as a Slack alert to the account team, can run in Auto from day one. Move a customer-facing agent to Auto only after its drafts are going out without edits.

Build it with Claude

With the MCP server connected, paste your worksheet row into Claude and ask it to build the agent:

"Read the FunnelStory flow guide, then build a draft agent from this design. Detect: … Investigate: … Act: … Mode: Assist. Test it on a recent example before I publish it."

Claude reads the flow authoring guide over MCP, saves the agent as a draft with save_flow, checks which records the trigger would pick up with preview_flow_triggers, and test-runs it with run_flow. A draft doesn't run on its own, so nothing reaches a customer until you publish it. See Vibe coding for more, or Getting started to build the same agent on the canvas.

Example 1: Triage customer hand-raisers

Customers ask for help, raise a concern, or ask about pricing in email, chat, and tickets. Triage by hand takes days; this agent does the first pass in minutes.

Use case	Detect	Investigate	Act	Mode	Measure
Respond to hand-raises from paying accounts within a day	Conversation trigger on emails, chats, and tickets, filtered to paying accounts	Read the message; check the account's profile, open needle movers and tickets, renewal date, and who the sender is	If it's a real ask, create an Action Card with the recommended response and a drafted reply; skip routine messages	Assist	Time from message to response; Action Cards completed

Tell the agent explicitly what not to act on, such as auto-replies, newsletters, and messages your support team already answered, so it stays quiet when nothing needs doing.

Example 2: Work an Outcome Agent roster

After you activate a Retention Outcome Agent, this agent gives every at-risk account a personal first touch.

Use case	Detect	Investigate	Act	Mode	Measure
Move the activated at-risk cohort to the target adoption before renewal	Query trigger that returns each account on the cohort's at-risk roster (see the SQL in the retention guide)	Read the account's usage of the signals in the cohort, its profile, and open needle movers; find the likely reason it hasn't adopted	Create an Action Card with the next best action for this account and a drafted email to the right contact	Assist	The run's Result and ARR Protected on the Outcome Agents page

Attach this agent to the activated run under Attached Agentic Flow, so the cohort report records which agent's work it measures.

Example 3: A champion leaves

A champion leaving is one of the strongest early signs of churn, and the window to rebuild the relationship is short.

Use case	Detect	Investigate	Act	Mode	Measure
Rebuild coverage within two weeks when a key contact leaves	Needle Mover trigger on Personnel Change risks	Read the relationship map history and stakeholder facts: who else is engaged, who held the role, and what the champion cared about	Post a Slack alert to the account team with who left and who's left; create an Action Card to introduce the team to the next most engaged contact	Auto for the Slack alert, Assist for the Action Card	Accounts with two or more engaged contacts 30 days later

Test, then measure

• Test before publishing. Run the draft against real past examples, including ones it should ignore. See Testing and runs.
• Watch the first week. Check each run's history and read the Action Cards it creates. Tighten the trigger if it fires too often; add evidence to the investigation step if its reasoning is thin.
• Measure against the worksheet. The Measure column is the agent's goal. When it serves an Outcome Agent run, the run's daily report is your scorecard.

Related

• Prevent Churn with a Retention Outcome Agent and Grow Expansion with an Expansion Outcome Agent
• Triggers and Functions reference
• LLM steps — giving an AGENT step tools such as semantic.query and tasks.create
• Action Cards — where Assist-mode output lands
• Built-in agents — FunnelStory's own agents that follow the same shape