> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a research agent

> Design, field, and inspect research with the public API and MCP tools

## Start with a reviewable study

An agent can create a draft, help design its interview plan, invite participants, and retrieve evidence. The researcher should review the saved plan and the current recruitment estimate before fieldwork starts. Use an API key with `read` and `write` scopes for draft work; paid panel launch also requires `panel:launch` and a positive lifetime spend cap.

<Steps>
  <Step title="Create a draft">
    Call `POST /api/public/v1/studies/` with an `Idempotency-Key`. Save the returned study ID. See the [study lifecycle](/api-reference/study-lifecycle) for state transitions.
  </Step>

  <Step title="Design the plan">
    Call `POST /api/public/v1/studies/{study_id}/customize-plan` once per conversation turn. Relay returned `questions[]` when `decisions` is `human`. If the researcher delegates ordinary design choices with `decisions: "agent"`, show the returned `assumptions[]` and any remaining questions. Review the persisted plan before recruiting.
  </Step>

  <Step title="Choose recruitment">
    For your own participants, create invitations or a share link. For a paid panel, request the current estimate, show the amount and target to the researcher, then launch with a key that has the required scope and spend cap. The plan customization call never starts recruitment.
  </Step>

  <Step title="Follow progress and evidence">
    Poll fielding progress and report jobs, or subscribe to [webhook events](/api-reference/webhooks/overview). Retrieve the persisted report and source interviews. Keep interview IDs and source references with each answer; distinguish quotations from analysis and recommendations.
  </Step>
</Steps>

The [runnable TypeScript examples](/api-reference/developer-examples) include a fixture mode that uses fictional data and makes no network calls. Start there, then validate the narrow live path your application needs with an authorized test study.

## Connect through MCP

The [MCP setup guide](/mcp-server/overview) covers authentication and tool discovery. Discover the tool schema at runtime, because MCP and REST names or response shapes can differ. The default tool surface includes write operations; use API key scopes and spend caps to limit what a connected agent can do.

## Evaluate before a live launch

Use a fixed set of realistic briefs and record the study ID, request IDs, tool calls, final plan, estimate, and source references for each run. Include cases with missing audience details, a returned planning question, an uncertain write response, an empty study, and a paid panel estimate that exceeds the key's cap.

| Check | Pass condition |
| - | - |
| Plan questions | The agent relays required `questions[]` or labels its `assumptions[]` before claiming the plan is final. |
| Fieldwork approval | The saved plan and current estimate are shown before any paid launch call. |
| Retry safety | A timed-out write reuses its original `Idempotency-Key` with identical input, and the agent checks persisted state when the outcome remains uncertain. |
| Evidence | Every attributed quotation can be found in an accessible source interview; analysis and recommendations are labelled separately. |
| Access and spend | Read-only keys cannot write; paid operations are rejected without their specific scope and a sufficient cap. |

Count passes and failures by scenario, retain failed traces, and rerun the same set when the API contract, tool surface, or agent prompt changes. Fixture results demonstrate integration behavior; they do not establish real research quality. The [examples release checklist](https://github.com/user-intuition/examples/blob/main/docs/release-check.md) covers response shapes, pagination, citations, and source access.

## Current output formats

The public API exposes structured reports, transcript segments, and [private CSV or JSONL interview exports](/api-reference/interview-exports). Downloadable highlight clips and slide decks are still under development. Use the persisted report and interview endpoints for current integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.