Welcome to Help Center

Technical documentation for building and deploying AI knowledge agents with Twig

Twig is an API-first RAG platform for building AI agents backed by your data sources.

What is Twig?

Twig provides:

• RAG infrastructure with vector search and LLM orchestration

• Data connectors for ingestion and sync from external sources

• Agent configuration APIs and UI for behavior, prompts, and RAG strategy selection

• Validation framework to check for hallucinations, missing citations, and accuracy

• Deployment targets: REST API, embeddable widgets, browser extensions, Slack/Outlook/Zendesk apps

Core Capabilities

🔌 Data & Integration

• Data Connectors - Zendesk, Confluence, Slack, Google Drive, SharePoint, OneDrive, GitBook, Notion, websites, and others. See full list.

• Sync Schedules - Configure refresh intervals (hourly, daily, weekly, or manual) per data source

• PII Detection - Regex-based and NER-based filtering before indexing (configurable per organization)

• Multi-Tenant Architecture - Organization-level data isolation with per-tenant embeddings

• REST API & MCP Server - Programmatic control over agents, queries, data sources, and evals

🤖 Agent Builder & Intelligence

• Agent Configuration UI - Web UI for configuring prompts, temperature, model selection, and data source filters

• RAG Strategies - Redwood (single-pass retrieval), Cedar (multi-query expansion), Cypress (agentic multi-hop with tool calling)

• Session Memory - Conversation history stored per session (retention: 30 days default)

• Agentic Workflows - Multi-step reasoning with function calling (requires Cypress RAG strategy)

• Agent Personas - System prompt configuration, response length limits, tone presets, data source scoping

✅ Quality & Validation

• 7-Dimensional Validation - Checks for: hallucination (claim not in sources), missing data (retrieval gaps), accuracy (factual errors), relevance (off-topic), tone (persona mismatch), completeness (partial answers), citations (source attribution)

• Source Attribution - Inline citations with document ID, chunk ID, and URL (when available)

• Evaluation Framework (Evals) - Run test queries against agents to measure: answer accuracy, latency (p50/p95), retrieval precision/recall, cost per query

• Quality Workbench - Review agent responses, tag incorrect answers, capture feedback for fine-tuning

• Hybrid Inbox - Agent drafts responses, human approves/edits before sending (available in Zendesk/HelpScout apps)

🚀 Deployment & Scalability

• Deployment Channels - REST API, embeddable widget (iframe), Chrome extension, Slack app, Outlook add-in, Zendesk native app, HelpScout app

• Infrastructure - Self-hosted: Docker/Kubernetes manifests available. Cloud: Hosted on AWS with auto-scaling.

• Observability - Query logs with retrieval traces (which chunks were retrieved, why), latency breakdowns (embedding, retrieval, LLM), error tracking

• Caching - Query result cache (configurable TTL), embedding cache (deduplication at ingestion)

🔐 Enterprise Security

• SSO Integration - SAML 2.0 and OAuth 2.0 (Google, Microsoft, Okta, Auth0)

• Role-Based Access Control - Roles: Admin, Developer, Viewer. Permissions: manage agents, manage data sources, view analytics, API access.

• Data Residency - Embeddings and metadata stored in: US East (default), EU West, AP Southeast (configurable per organization)

• Compliance - GDPR: data deletion APIs, export APIs. HIPAA: BAA available on Enterprise plan.

• Audit Trails - All queries, data source syncs, user actions logged with timestamps, user IDs, IP addresses

Quick Start

Prerequisites: Twig account with API access

# Set your API key
export TWIG_API_KEY="your_api_key_here"

# Create an agent
curl -X POST https://api.twig.so/v1/agents \
  -H "Authorization: Bearer $TWIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Agent", "rag_strategy": "redwood"}'

# Query the agent
curl -X POST https://api.twig.so/v1/query \
  -H "Authorization: Bearer $TWIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_123", "query": "What is your refund policy?"}'

Full setup instructions: Quick Start Guide

For Engineers

🏗️ Architecture & Concepts

• Platform Architecture - Ingestion pipeline, vector DB, LLM orchestration, API layer

• RAG Concepts - Embeddings, vector search, chunking, retrieval scoring

• RAG Strategy Selection - Redwood vs Cedar vs Cypress: latency, cost, and accuracy tradeoffs

💻 API & Integration

• REST API Reference - Endpoints for agents, queries, data sources, evals

• Authentication - API key generation, bearer token usage, key rotation

• Webhooks - Events: data_sync_complete, eval_run_complete, agent_query_complete

• SDKs - TypeScript, Python clients (npm/pip packages)

• Rate Limits - Current limits: 100 req/min (queries), 10 req/min (data sync)

🤖 Building Agents

• Agent Creation - API and UI steps, required fields, default values

• Agent Configuration - System prompts, temperature (0-2), model selection (GPT-4, Claude)

• Agentic Workflows - Multi-step planning with Cypress RAG strategy

• Function Calling - Custom tools, OpenAPI spec format, authentication

📊 Data Pipeline

• Data Source Setup - OAuth flows, API credentials, sync schedules, filters

• Chunking Configuration - Chunk size (default: 512 tokens), overlap (default: 50 tokens), splitting strategies

• Vector Search Tuning - Similarity thresholds, reranking, hybrid search

🔍 Debugging & Monitoring

• Retrieval Debugging - View retrieved chunks, similarity scores, reranking decisions

• Evaluation Framework - Create test sets, run evals, track metrics over time

• Performance Tuning - Latency analysis: embedding (avg 50ms), retrieval (avg 200ms), LLM (varies)

• Cost Tracking - Per-query cost breakdown: embedding, LLM tokens, vector search

Troubleshooting by Symptom

Symptom	Diagnostic Guide
Agent returns wrong or hallucinated answers	Retrieval Accuracy - Check retrieval scores, increase top_k, adjust similarity threshold
Semantic search returns irrelevant results	Vector Search Tuning - Verify embedding model, test query expansion, enable reranking
Context window exceeded error	Token Management - Reduce top_k, decrease chunk size, use truncation
Query latency >3s	Performance Analysis - Profile embedding/retrieval/LLM steps, check cache hit rate
Data source sync fails	Data Integration Errors - Verify credentials, check rate limits, review error logs

View all solutions

Security & Compliance

• Authentication & Authorization - API keys, SSO, role permissions

• SSO Setup - SAML/OAuth configuration steps

• PII Detection - Enable PII filters, configure regex patterns

• Data Privacy - Data residency options, deletion APIs, export APIs

Support

• Technical Support: [email protected]

• Issue Reports: Include: query ID, agent ID, timestamp, error message, reproduction steps

Next Steps

New to RAG? Start with RAG Concepts - covers embeddings, vector search, and retrieval.