# Quick Start Guide

Create an AI agent and query it.

## Prerequisites

* Twig account at [app.twig.so](https://app.twig.so)
* Data to index: PDF/Word files, or a documentation website URL

## Step 1: Create Your Organization

On first login:

1. Go to [app.twig.so](https://app.twig.so)
2. Sign in with email/password or SSO (Google, Microsoft)
3. Fill the organization setup form:
   * **Organization name** (required)
   * **Industry** (optional dropdown)
   * **Invite team members** (optional, can skip)
4. Click **Complete Setup**

**Expected result**: You see the main dashboard with "Data", "Agents", "Playground" menu items

## Step 2: Add a Data Source

### Option A: Upload a File

1. Click **Data** in left navigation
2. Click **Add Data Source** button (top right)
3. Select **File Upload** from the modal
4. Choose file: PDF, DOCX, TXT (max 50MB per file)
5. Click **Upload**
6. Wait for processing (progress bar shows chunking, embedding)

**Expected result**: Status changes to "Active" with green indicator. Shows chunk count (e.g., "256 chunks indexed").

**Processing time**: \~1-3 minutes for a 100-page PDF

### Option B: Connect a Website

1. Click **Data** in left navigation
2. Click **Add Data Source** button
3. Select **Website Crawler**
4. Enter base URL: `https://docs.example.com`
5. Set max pages (default: 100, max: 10,000)
6. Click **Start Crawl**

**Expected result**: Status "Crawling" → "Processing" → "Active". Shows pages crawled count.

**Processing time**: \~5-10 minutes for 100 pages

### Other Connectors

* **Confluence**: OAuth flow, select spaces
* **Google Drive**: OAuth flow, select folders
* **Slack**: OAuth flow, select channels (last 90 days of messages)

See [Data Sources](broken://pages/xKEWHPieiEGCCjd0xJ4l) for connector-specific setup

## Step 3: Create an Agent

1. Click **Agents** in left navigation
2. Click **Create Agent** button
3. Fill the form:
   * **Name**: e.g., "Customer Support Agent" (required)
   * **Data Sources**: Check the data source from Step 2 (required)
   * **System Prompt** (optional): "You are a customer support assistant. Provide concise answers with citations."
   * **RAG Strategy**: Leave as "Redwood" (default)
   * **Model**: Leave as "GPT-4" (default)
4. Click **Create Agent**

**Expected result**: Agent appears in agents list with status "Active". Agent ID is visible (format: `agent_abc123`).

## Step 4: Test Your Agent

1. Click **Playground** in left navigation
2. Select your agent from the dropdown
3. Type a question in the input field (must relate to your indexed data)
4. Press Enter or click **Send**

**Expected result**:

* Response appears in chat window (typical: 2-5 seconds)
* Citations shown below response with document names and chunk IDs
* Retrieved sources panel (right side) shows the chunks used

**How to verify it works**:

* Click a citation → opens source document at that location
* Check "Sources Used" panel → shows 5-10 chunks with similarity scores (0.0-1.0)
* Response references content from your data (not generic AI knowledge)

## What's Next?

### Improve Agent Accuracy

* **Add data sources**: Agents → \[Your Agent] → Data Sources tab → Add more
* **Tune system prompt**: Agents → \[Your Agent] → Configuration → edit System Prompt field
* **Change RAG strategy**: Agents → \[Your Agent] → Configuration → RAG Strategy dropdown
  * Redwood: 1-2s latency (current)
  * Cedar: 2-3s latency, query rewriting
  * Cypress: 3-5s latency, reranking, best accuracy
* **Test queries**: Run 10-20 test questions in Playground, check citation accuracy

### Deploy

* **REST API**: Settings → API Keys → Generate, use `/api/v1/query` endpoint
* **Embed widget**: Deployments → Widget → Copy embed code (iframe)
* **Chrome extension**: Chrome Web Store → "Twig AI" → Install, paste API key
* **Slack integration**: Integrations → Slack → Authorize workspace

### Monitor

* **Inbox**: Review → Inbox → see all queries, mark accurate/inaccurate
* **Analytics**: Dashboard → shows query count, avg latency, accuracy rate
* **Evals**: Evaluation → Create Test Set → add question/expected answer pairs, run against agent

## Troubleshooting

### Data Source Stuck at "Processing"

**Symptom**: Status stays "Processing" for >10 minutes

**Diagnostic steps**:

1. Data → \[Your Data Source] → Logs tab → check for error messages
2. Common errors:
   * "401 Unauthorized" → OAuth token expired, reconnect
   * "Rate limit exceeded" → Wait 1 hour, crawler resumes automatically
   * "Invalid file format" → Convert to PDF/DOCX, re-upload

**Fix**: Based on error message. If no error after 30 minutes, contact support with data source ID.

### Agent Returns "No relevant information found"

**Symptom**: Agent responds with "I don't have information about that"

**Diagnostic steps**:

1. Playground → Check "Sources Used" panel → if empty, retrieval failed
2. Possible causes:
   * Query doesn't match indexed content (semantic mismatch)
   * Data source not connected to agent
   * Similarity threshold too high (default: 0.7)

**Fix**:

* Agents → \[Your Agent] → Data Sources tab → verify data source is checked
* Try exact phrase from your document in query
* Lower similarity threshold: Configuration → Advanced → Similarity Threshold → 0.5

### Query Takes >10 Seconds

**Symptom**: Response latency exceeds 10 seconds

**Diagnostic steps**:

1. Playground → Query → Check response time breakdown (bottom of response)
2. Identify slow step:
   * Retrieval >3s → Too many chunks indexed, contact support
   * LLM >8s → Model overloaded, retry in 1-2 minutes
   * Embedding >1s → Network issue, check connection

**Fix**: Switch to Redwood strategy (Configuration → RAG Strategy) for 1-2s responses.

### When This Doesn't Apply

These steps assume default settings on Free/Pro plan. Enterprise configurations may differ.

***

**Next steps**: [Authentication](/getting-started/authentication.md) for API access, or [Core Concepts](/getting-started/core-concepts.md) for RAG terminology.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.