Getting Started

For semi-structured protocols, set the Interview Mode to Structured when creating an agent. You can then define an interview guide with ordered questions, follow-up probes, and transition messages.

You can build the guide directly in the dashboard, or upload a CSV or JSON file. Download the template from the dashboard to see the expected format:

// interview-guide.json
{
  "questions": [
    {
      "text": "Can you tell me about your experience with...?",
      "probes": [
        "What specific aspects stood out?",
        "How did that compare to your expectations?"
      ],
      "max_follow_ups": 3,
      "transition": "Thank you, now I'd like to ask about..."
    }
  ],
  "closing_message": "Thank you for your time."
}

The agent will follow the guide as a backbone but can adapt naturally. It probes when appropriate, moves on after the configured number of follow-ups, and uses transition messages between questions.

When you select Text as the modality, the agent conducts interviews via a chat interface instead of voice. No STT or TTS keys are needed.

• • Choose from several avatar styles: Robot, Neutral, Male, Female, or None.
• • The transcript output format is identical to voice agents, same export, same analytics.
• • Works with any chat-compatible LLM (GPT-4.1, Claude, Gemini, etc.).

Each agent has a Participant ID mode that controls how sessions are linked to individual participants. Pick the mode that fits your study design:

OASIS uses LiteLLM under the hood, which means you can use virtually any LLM provider with a unified API format.

If you want to keep audio processing on your own infrastructure — or just avoid third-party API costs — you can point OASIS at any server that speaks the OpenAI STT/TTS protocol.

Compatible servers include Speaches (faster-whisper), Kokoro, Piper, LocalAI, and similar projects. Set the following in .env:

• • SELF_HOSTED_STT_URL — base URL of your STT server (e.g. http://my-server:8000/v1)
• • SELF_HOSTED_TTS_URL — base URL of your TTS server
• • SELF_HOSTED_STT_MODEL / SELF_HOSTED_TTS_MODEL — model name the server expects (defaults to whisper-1 and tts-1)

Then select "Self-Hosted" as the STT or TTS provider in the agent form. API keys are optional — most local servers don't require them.

For GDPR-sensitive studies, OASIS supports routing all OpenAI traffic through the EU regional endpoint (eu.api.openai.com). This covers chat completions, Realtime, STT, TTS, and embeddings.

Set OPENAI_USE_EU=true in .env (or toggle it in the dashboard Settings under feature flags). This requires that the OpenAI project tied to your API key has data-residency enabled and a Zero Data Retention or Modified Abuse Monitoring amendment in place.

For non-OpenAI providers, you can use Scaleway (EU-based LLM-as-a-Service), self-hosted models, or any provider that meets your institutional data-handling requirements.

Authentication is off by default. To enable basic login protection for the dashboard:

# In .env:
AUTH_ENABLED=true
AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password

Then recreate the backend container: docker compose up -d --force-recreate backend. Interview links remain publicly accessible. Authentication only protects the admin dashboard.

OASIS supports telephone-based interviews via Twilio Media Streams. Add your Twilio credentials to .env, assign a phone number to an agent in the dashboard, and participants can call in for voice interviews.

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1234567890

The backend exposes a TwiML webhook that Twilio calls when someone dials your number. Audio is streamed over WebSockets using Pipecat's TwilioFrameSerializer.

Upload documents to a study's knowledge base to give your agent context about the research topic. Documents are chunked, embedded, and stored in PostgreSQL via pgvector for similarity search.

By default, embeddings use OpenAI's text-embedding-3-small (1536 dimensions). To use a self-hosted embedding server instead, set EMBEDDING_API_URL in .env — any OpenAI-compatible endpoint works (e.g. LocalAI, TEI, vLLM).

During an interview, the agent queries the knowledge base to retrieve relevant context before generating a response. Useful for topic-specific interviews where the agent needs factual grounding.

The FastAPI backend serves auto-generated OpenAPI documentation. Once your instance is running:

• • Swagger UI: http://localhost/api/docs
• • ReDoc: http://localhost/api/redoc

Key endpoints include: