Building the Customer Truth Layer

Part 6 of the series: The Customer Truth Layer for AI Agents

You have read about why agents get customers wrong, what the Customer Truth Layer looks like in the agent stack, and how Human Signal provides structured feedback that agents can act on. Now here is how to build it.

This is the practical implementation guide for integrating real customer intelligence into your agent workflow. We will walk through the architecture, the setup for major platforms, the study lifecycle, three implementation patterns for different use cases, and the decision logic for knowing when to launch new research versus querying existing intelligence.

Architecture Overview

The architecture has a write path for new research and a read path for existing study evidence.

Write path. Create a metadata draft with create_study, then send the research brief through customize_study. Relay any planning questions to the user. Retrieve the persisted plan with get_study and obtain approval before recruitment. The user must choose panel or BYOP explicitly. For a panel study, use launch_panel with dry_run: true to obtain the recruitment estimate. Show the country, language, cost, and timeline; launch with the same settings after approval. Each launch specifies one country. Audiences below 10% incidence require a feasibility request.

Read path. Agents can list studies, retrieve selected study reports, and inspect supporting interviews. They can compare that retrieved evidence in their own context. Direct cross-study Intelligence Hub search is available in the dashboard; the current public API and MCP catalog do not expose Hub search, Hub sessions, or presentation generation.

Your application stores study IDs, approval context, and source references. This lets later decisions build on evidence already collected without assuming a native Hub search API.

Connecting Your Agent

Use the hosted endpoint, https://mcp.userintuition.ai/mcp, with OAuth in compatible clients. For local stdio, run npx -y @userintuition-ai/mcp with USERINTUITION_API_KEY set to your ui_sk_ key. The CLI supports browser login and API-key management. Hosted OAuth does not require exchanging a user-supplied API key.

For a local stdio client that uses an MCP configuration file:

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {"USERINTUITION_API_KEY": "ui_sk_your_key_here"}
    }
  }
}

Keep real keys out of version control. For shell workflows:

npm install -g @userintuition-ai/mcp
userintuition-mcp login
userintuition-mcp list
userintuition-mcp list_studies

Start with a read such as list_studies to check your connection. See the current MCP setup guide for client-specific instructions and the research skills for workflow guidance.

The Study Lifecycle

Design and approve

Create a metadata draft with create_study, then send the research brief through customize_study. Relay any planning questions to the user. Retrieve the persisted plan with get_study and obtain approval before recruitment. The user must choose panel or BYOP explicitly.

These are illustrative MCP tool calls in workflow order, not an unattended launch script. Replace placeholder IDs with values returned by the server. The example assumes the user has chosen panel recruitment.

create_study({"name":"Headline research","recruiting_method":"panel"})
customize_study({"study_id":"<study-id>","message":"Compare our three headline options with US product managers. Explore relevance, clarity, and reasons for preference. <include the options>"})

Continue customize_study with the user’s answers if it returns a planning question. Once a plan is saved:

get_study({"study_id":"<study-id>"})

Show the full saved plan for approval. Use Customize Plan for audience criteria, screeners, and concept or prototype assets; create_study is not a raw discussion-guide submission tool. Voice in English with Elliot is the default unless the user requests other supported settings. Prototype tests support voice or video, not chat.

Recruit

For a panel study, use launch_panel with dry_run: true to obtain the recruitment estimate. Show the country, language, cost, and timeline; launch with the same settings after approval. Each launch specifies one country. Audiences below 10% incidence require a feasibility request.

launch_panel({"study_id":"<study-id>","target":25,"incident_rate":50,"country_code":"US","dry_run":true})

The target and incidence above are illustrative, not a claim about your audience. Use the approved values. A dry run estimates recruitment; it does not field interviews. After approval, call the same tool with the same settings and dry_run: false. Timing depends on the audience and fielding conditions.

For a BYOP study, use create_participants with 1–100 unique participant emails per batch after the saved plan and invitations are approved. Invitations send by default; set silent: true on individual participant records when invitations should not send. Source customer lists through your own authorized export or integration; MCP has no direct CRM segment-sync tools.

Retrieve evidence

Interviews complete over time. Record the study ID so a later session can resume. Provisioning status describes interviewer setup; it does not by itself prove that a panel is fielding or complete.

list_interviews({"study_id":"<study-id>","status":"completed","page":1,"page_size":20})
get_study_report({"study_id":"<study-id>"})

Paginate before counting completions or comparing quality. get_study_report returns report text, references, interview count, stale status, and timestamps in JSON. Use generate_report when analysis is needed, and get_interview to verify supporting messages and recording links. Preference shares, credibility scores, and ranked themes are not guaranteed typed fields in this response.

generate_report works on a selected study. If a write times out, inspect the saved study or report before repeating it. A timeout alone does not establish that the operation failed.

For automated notification, the current tools support account-wide completed-interview webhooks. New registrations provide a signing secret. Delivery has no automatic retries, so consumers should reconcile notifications against interview records.

Pattern 1: Pre-Decision Validation

The most common integration pattern: an agent checks whether it has sufficient customer signal before making a customer-facing decision.

The workflow:

1. Agent identifies a decision that requires customer signal (e.g., choosing between two headlines).
2. Agent selects relevant studies and retrieves their reports: “What do we know about customer preferences for [relevant topic]?”
3. If existing signal is sufficient (recent, high-confidence, relevant to the specific context): the agent acts on accumulated intelligence. No new study needed. Decision made in seconds.
4. If existing signal is insufficient (outdated, low-confidence, or the specific question has not been studied): the agent launches a new study, waits for results, and acts on the fresh Human Signal.

When to use this pattern: Any time an agent is about to make a customer-facing choice — selecting messaging, prioritizing features, crafting responses, choosing positioning. The pre-decision check adds minimal latency when existing intelligence is available and ensures grounded signal when it is not.

Decision factors for “sufficient signal”:

• Recency: How old is the existing data? Signal about messaging preferences from last week is more actionable than signal from six months ago.
• Confidence: How strong is the evidence? A finding supported by 47 conversations carries more weight than one from 8.
• Specificity: Does the existing signal address this exact question, or a related but different one? General messaging preferences may not transfer to a specific product launch context.
• Stakes: How consequential is the decision? A social media post warrants less verification rigor than a pricing page rewrite.

Pattern 2: Continuous Monitoring

For ongoing tracking of brand perception, competitive positioning, or feature satisfaction.

The workflow:

1. Agent schedules periodic studies at defined intervals (weekly, biweekly, monthly) on key topics.
2. Each study runs against a consistent audience and question framework, enabling time-series analysis.
3. Results feed the hub, building a longitudinal view of how customer perception changes over time.
4. Other agents retrieve the selected study reports and compare sources to describe changes over time.

When to use this pattern: Brand health tracking, competitive positioning monitoring, post-launch sentiment tracking, or any context where understanding change over time matters as much as understanding current state.

Example: A brand management agent runs a monthly claim reaction study testing whether customers believe the company’s core positioning claims. Over six months, the hub accumulates a trend line showing that credibility for the “fastest time to insight” claim is declining while credibility for the “evidence you can cite” claim is strengthening. This trend informs a strategic repositioning decision that no single study would have triggered.

Pattern 3: Test-and-Iterate

For creative workflows where the agent produces customer-facing content and refines it based on real feedback.

The workflow:

1. Agent generates initial content (landing page copy, email subject line, product description).
2. Agent launches a message test or preference check with the draft content.
3. Agent receives Human Signal results identifying what works, what confuses, and what falls flat.
4. Agent revises the content based on specific feedback: strengthening elements that resonated, clarifying elements that confused, and addressing objections that surfaced.
5. Agent optionally tests the revised version to confirm improvements.

When to use this pattern: Any creative or copywriting workflow where the agent produces content that will be seen by customers. The iterative loop ensures that the final output is grounded in real human reactions rather than the agent’s inference about what will work.

Example: A marketing agent writes three versions of an onboarding email. It runs a message test on all three. Results show that Version B has the best clarity score but Version A has stronger emotional resonance. The agent synthesizes: it takes Version A’s opening (which participants found warm and inviting) and Version B’s body (which participants found clearest). It tests the synthesized version. Clarity improves 15% over the original Version B while maintaining Version A’s emotional resonance.

This iterative refinement — grounded in real human reactions at each step — is something agents cannot do with synthetic feedback or training data inference. Each iteration is informed by genuine human responses to the specific content being tested.

How Do You Design the Decision Logic?

The most sophisticated aspect of the Customer Truth Layer is knowing when to launch new research versus when to act on existing intelligence. Here is a simple decision framework agents can follow:

Query the hub first, always. Before launching any new study, check whether accumulated intelligence addresses the question. This is fast (seconds) and free.

Evaluate existing signal on four dimensions:

1. Recency. Is the most recent relevant finding less than 30 days old? If yes, lean toward using existing signal. If the data is older, consider whether the topic is stable (brand values change slowly) or volatile (competitive perception changes fast).

2. Confidence. Is the finding supported by at least 20 conversations? Fewer conversations means wider uncertainty. High-stakes decisions warrant higher confidence thresholds.

3. Specificity match. Does the existing signal address this exact question? “Enterprise buyers prefer reliability messaging” is useful context for a reliability-themed campaign, but it may not tell you whether your specific reliability claim is believable. A specific question warrants specific research.

4. Decision stakes. What is the cost of being wrong? A social media post can tolerate more uncertainty than a pricing page. Match the verification rigor to the consequence of error.

Default to new research when in doubt. A study costs from $150 and takes 2-3 hours. A wrong customer-facing decision costs far more. When existing signal is ambiguous, dated, or only tangentially relevant, the expected value of fresh research almost always exceeds the cost.

What Is Coming Next?

An integration can already coordinate study planning, approved recruitment, and evidence retrieval. Direct Hub search, a typed claim-level findings contract, and durable research-job recovery would extend that workflow, but they are not capabilities to assume from the current public surface.

Build against the published tool reference and revisit the contract when adding a new workflow. Treat an architectural possibility as a proposal until a supported operation exists.

Agentic Market Research Integration Patterns

The implementation patterns above describe how agents interact with the Customer Truth Layer. At a higher level, these patterns compose into what we call agentic market research: the practice of having AI agents autonomously commission, run, and act on real consumer research as a routine part of their decision-making workflow.

The MCP integration described in this guide is the technical foundation. But the strategic value emerges from how organizations deploy these patterns across their agent ecosystem. A marketing agent using pre-decision validation before every campaign launch. A product agent using continuous monitoring to track feature sentiment quarterly. A content agent using test-and-iterate to refine messaging through multiple rounds of real consumer feedback.

Each of these agents connects to the same Customer Intelligence Hub. Their studies accumulate in the same knowledge base. Cross-functional intelligence emerges as the hub recognizes connections between a product agent’s feature reaction study and a marketing agent’s messaging preference check. The whole becomes greater than the sum of the individual studies.

For teams evaluating how to implement agentic market research, the technical integration is the simplest part (MCP connection takes minutes). The strategic decisions are: which agent workflows should include customer validation? What confidence thresholds warrant new research versus querying existing intelligence? How do you design decision logic that balances speed with rigor?

The complete guide to agentic market research covers these strategic questions in depth. The agentic consumer insights definition guide covers the methodology. The platform comparison helps evaluate tools. And the MCP integration guide provides a complementary technical walkthrough focused specifically on the MCP connection patterns.

Get started with agentic research — connect your first agent in minutes →

Series: The Customer Truth Layer for AI Agents

1. Your AI Agent Is Confidently Wrong About Your Customers
2. The Agent Stack Is Missing a Layer: Customer Truth
3. Human Signal: The Data Type Your AI Agent Doesn’t Have
4. Why Synthetic Panels Can’t Replace Real Customers (And What Can)
5. Compound Intelligence: Why Your Agent Gets Smarter With Every Conversation
6. Building the Customer Truth Layer: A Technical Guide (you are here)