# Agent Configuration

Configure your AI agents for optimal performance with detailed settings for behavior, data access, and deployment.

## Overview

Agent configuration determines:

* How the agent responds to queries
* Which data sources it can access
* What tone and style it uses
* Performance characteristics
* Security and privacy settings

## Configuration Sections

### 1. Basic Information

**Required Settings:**

**Agent Name**

* Clear, descriptive name
* Examples: "Customer Support Agent", "API Documentation Assistant"
* Used in UI and API references
* Visible to users

**Description**

* Brief explanation of agent's purpose
* Helps team members understand use case
* Not shown to end users
* Example: "Handles billing and subscription questions for support team"

**Avatar/Icon**

* Visual identifier for agent
* Upload custom image or generate AI avatar
* Recommended: 512x512 pixels, PNG format
* Falls back to default if not provided

**Status**

* **Active**: Agent is live and usable
* **Inactive**: Agent is hidden and unavailable
* **Draft**: Work in progress, testing only

### 2. Data Source Selection

Control what knowledge the agent can access.

**Adding Data Sources:**

1. Click **Add Data Source**
2. Select from connected sources
3. Choose specific tags/categories (optional)
4. Set priority (for Cypress strategy)

**Data Source Configuration:**

```typescript
{
  "dataSources": [
    {
      "id": "ds-1",
      "name": "Product Documentation",
      "enabled": true,
      "tags": ["product", "features"],    // Filter by tags
      "tier": 1,                           // Priority level (Cypress)
      "restrictToGroups": ["support"]      // Access control
    }
  ]
}
```

**Best Practices:**

* Start with 1-3 focused data sources
* Add more based on performance
* Use tags to filter content
* Organize by tier for Cypress strategy

### 3. Instructions & Prompts

Define how the agent behaves and responds.

**System Instructions**

The core prompt that defines agent behavior:

```
You are a helpful customer support assistant for [Company Name].

Your responsibilities:
- Answer questions about products and services
- Help with account and billing issues
- Guide users through technical setup

Guidelines:
- Be friendly and professional
- Provide step-by-step instructions when needed
- Always cite sources for your answers
- If you don't know, say so and suggest contacting support

Tone: Professional yet approachable
Style: Clear, concise explanations with examples
```

**Instruction Components:**

**Identity:**

```
You are a [role] for [organization].
You help users with [specific tasks].
```

**Responsibilities:**

```
- Primary task 1
- Primary task 2
- Scope limitations
```

**Guidelines:**

```
- Behavioral rules
- Response format
- Citation requirements
- Uncertainty handling
```

**Tone & Style:**

```
Tone: [Professional/Friendly/Technical]
Style: [Concise/Detailed/Conversational]
Format: [Paragraphs/Bullet points/Step-by-step]
```

**Example Instructions by Use Case:**

**Technical Documentation Agent:**

```
You are a technical documentation assistant for developers.

Provide:
- Code examples in relevant languages
- API endpoint references
- Step-by-step integration guides
- Troubleshooting steps

Format responses as:
1. Brief explanation
2. Code example
3. Expected output
4. Common issues

Tone: Technical, precise
Style: Structured, example-driven
```

**Sales Enablement Agent:**

```
You are a sales enablement assistant.

Help sales reps with:
- Product features and benefits
- Pricing and packaging information
- Competitive differentiators
- Customer success stories

Focus on:
- Value propositions
- ROI and business impact
- Addressing objections
- Closing techniques

Tone: Professional, persuasive
Style: Benefit-focused, concise
```

### 4. Response Configuration

Fine-tune how the agent generates responses.

**Response Length:**

| Setting      | Description            | Token Limit | Best For                    |
| ------------ | ---------------------- | ----------- | --------------------------- |
| **Concise**  | Brief, direct answers  | 150         | Quick facts, simple queries |
| **Standard** | Balanced explanations  | 350         | Most use cases              |
| **Detailed** | Comprehensive coverage | 600         | Complex topics, tutorials   |
| **Custom**   | User-defined           | 50-1000     | Specific needs              |

**Response Style:**

**Paragraph Format:**

```
Default format with flowing text and natural sentence structure.
Good for explanations and narratives.
```

**Bullet Points:**

```
- Structured information
- Easy to scan
- Clear hierarchy
- Good for features, steps, lists
```

**Step-by-Step:**

```
1. First action
2. Second action
3. Third action
Good for: Tutorials, processes, troubleshooting
```

**Code-Focused:**

```
Emphasis on code examples and technical details.
Minimal prose, maximum code.
Good for: API docs, developer tools
```

### 5. Model Configuration

Choose and tune the language model.

**Model Selection:**

| Model             | Speed     | Quality   | Cost | Best For                    |
| ----------------- | --------- | --------- | ---- | --------------------------- |
| **GPT-4o**        | Fast      | Excellent | High | Production, high quality    |
| **GPT-4**         | Medium    | Excellent | High | Complex reasoning           |
| **GPT-3.5-turbo** | Very Fast | Good      | Low  | High volume, simple queries |
| **Claude 3**      | Fast      | Excellent | High | Long context, analysis      |

**Advanced Parameters:**

**Temperature** (0.0 - 1.0)

* **0.0**: Deterministic, consistent, factual
* **0.3**: Slightly varied, mostly consistent
* **0.7**: Balanced (default)
* **1.0**: Creative, varied, unpredictable

```
Use Cases:
- 0.0-0.3: Technical docs, factual Q&A, compliance
- 0.4-0.7: General support, conversational
- 0.8-1.0: Creative content, brainstorming
```

**Max Tokens** (50 - 4000)

* Sets maximum response length
* Includes response + context
* Lower = faster, cheaper
* Higher = more comprehensive

**Top P** (0.0 - 1.0)

* Nucleus sampling parameter
* 0.9 (default) works for most cases
* Lower = more focused
* Higher = more diverse

**Frequency Penalty** (0.0 - 2.0)

* Reduces word repetition
* 0.0 = no penalty
* 0.5 = moderate penalty (recommended)
* 2.0 = strong penalty

**Presence Penalty** (0.0 - 2.0)

* Encourages topic diversity
* 0.0 = no penalty
* 0.5 = moderate penalty
* 2.0 = strong penalty

### 6. RAG Strategy

Choose retrieval and generation approach.

**Strategy Options:**

**Redwood (Standard RAG)**

```yaml
Speed: ~1-2s
Accuracy: Good
Cost: Lowest
Best for:
  - Clear, simple questions
  - High-volume use cases
  - Cost-sensitive deployments
```

**Cedar (Context-Aware)**

```yaml
Speed: ~2-3s
Accuracy: Better
Cost: Medium
Best for:
  - Conversational queries
  - Follow-up questions
  - Ambiguous phrasing
```

**Cypress (Advanced)**

```yaml
Speed: ~3-4s
Accuracy: Best
Cost: Highest
Best for:
  - Complex queries
  - High accuracy requirements
  - Diverse terminology
```

[See RAG Strategies Overview](/product/overview-1.md) for detailed comparison.

**Strategy Configuration:**

```typescript
{
  "strategyCode": "CEDAR",
  "topK": 10,                      // Documents to retrieve
  "retrievalMode": "hybrid",       // hybrid, dense, or sparse
  "rerankResults": false,          // Enable for Cypress
  "memoryTurns": 5                 // Conversation turns to remember
}
```

### 7. Privacy & Security

Control data access and security.

**Privacy Mode:**

**Private Data Only**

* Uses only organization-specific data sources
* No external knowledge
* Higher security
* More controlled responses
* Recommended for: Sensitive information, compliance

**Public + Private Data**

* Accesses org data + general knowledge
* Broader coverage
* More comprehensive answers
* Recommended for: General use cases

**Data Access Control:**

```typescript
{
  "configAIUseOnlyPrivateData": true,
  "restrictDataSources": true,
  "allowedDataSources": ["ds-1", "ds-2"],
  "deniedDataSources": ["ds-3"],
  "accessControl": {
    "requireAuth": true,
    "allowedGroups": ["support", "sales"],
    "deniedGroups": ["contractors"]
  }
}
```

**Security Settings:**

**PII Detection:**

* Automatically detect personally identifiable information
* Mask or redact sensitive data
* Log PII access attempts

**Content Filtering:**

* Block inappropriate content
* Filter specific keywords
* Enforce content policies

**Rate Limiting:**

```typescript
{
  "rateLimits": {
    "requestsPerMinute": 60,
    "requestsPerDay": 10000,
    "tokensPerDay": 1000000
  }
}
```

### 8. Citation & Source Settings

Configure how sources are cited.

**Citation Behavior:**

| Setting              | Description                     | When to Use                 |
| -------------------- | ------------------------------- | --------------------------- |
| **Always Cite**      | Every response includes sources | High trust requirements     |
| **Cite When Used**   | Only when directly quoting      | Balanced approach (default) |
| **Minimal Citation** | Only for factual claims         | Conversational agents       |
| **No Citations**     | Never show sources              | Not recommended             |

**Source Display:**

```typescript
{
  "citations": {
    "style": "inline",           // inline, footnote, or end
    "showURL": true,
    "showTitle": true,
    "showExcerpt": false,
    "maxCitations": 5,
    "sortBy": "relevance"        // relevance or recency
  }
}
```

### 9. Conversation & Memory

Manage conversation context.

**Memory Configuration:**

**Session-Based Memory:**

```typescript
{
  "memory": {
    "enabled": true,
    "sessionTTL": 3600,          // 1 hour
    "maxTurns": 10,              // Conversations to remember
    "summarizeAfter": 10,        // Auto-summarize long chats
    "persistAcrossSessions": false
  }
}
```

**User-Level Memory:**

```typescript
{
  "memory": {
    "enabled": true,
    "persistAcrossSessions": true,
    "rememberPreferences": true,
    "rememberContext": true,
    "privacyMode": "encrypted"
  }
}
```

**Memory Behavior:**

* **Ephemeral**: Reset after session
* **Short-term**: Remember for 24 hours
* **Long-term**: Persist indefinitely
* **User-controlled**: User can clear

### 10. Advanced Features

Optional advanced configurations.

**Agentic Workflows:**

Enable tool use and function calling:

```typescript
{
  "isUsingAgenticWorkflow": true,
  "availableTools": [
    {
      "name": "search_database",
      "description": "Search customer database",
      "parameters": {...}
    },
    {
      "name": "calculate",
      "description": "Perform calculations",
      "parameters": {...}
    }
  ],
  "maxToolCalls": 5,
  "toolTimeout": 30000
}
```

**Custom Metadata:**

```typescript
{
  "metadata": {
    "department": "Support",
    "costCenter": "CC-1234",
    "owner": "support@company.com",
    "version": "2.1",
    "tags": ["production", "tier1"]
  }
}
```

**Webhook Integration:**

```typescript
{
  "webhooks": {
    "onQuery": "https://api.company.com/webhooks/query",
    "onResponse": "https://api.company.com/webhooks/response",
    "onError": "https://api.company.com/webhooks/error"
  }
}
```

## Configuration Templates

### Customer Support Agent

```yaml
name: "Customer Support Agent"
description: "24/7 customer support assistant"

dataSources:
  - Product Documentation
  - FAQ Database
  - Support Tickets (anonymized)

instructions: |
  You are a friendly customer support assistant.
  Help customers with:
  - Product questions
  - Technical issues
  - Billing inquiries
  
  Always:
  - Be empathetic and patient
  - Provide step-by-step guidance
  - Offer to escalate complex issues

strategyCode: "CEDAR"
model: "gpt-4o"
temperature: 0.7
responseLength: "standard"
privacyMode: "private"
citations: "always"
```

### Technical Documentation Agent

```yaml
name: "API Documentation Assistant"
description: "Developer-focused technical assistant"

dataSources:
  - API Reference
  - Code Examples
  - Integration Guides

instructions: |
  You are a technical documentation assistant for developers.
  Provide code examples, API references, and integration guides.
  
  Format:
  1. Brief explanation
  2. Code example
  3. Expected output
  4. Common issues

strategyCode: "REDWOOD"
model: "gpt-3.5-turbo"
temperature: 0.3
responseLength: "detailed"
responseStyle: "code-focused"
privacyMode: "private"
citations: "always"
```

### Sales Enablement Agent

```yaml
name: "Sales Enablement Agent"
description: "Sales team assistant for product info"

dataSources:
  - Product Catalog
  - Pricing Information
  - Competitive Intelligence
  - Success Stories

instructions: |
  You are a sales enablement assistant.
  Help sales reps with product information,
  pricing, competitive positioning, and value propositions.
  
  Focus on business value and ROI.

strategyCode: "CEDAR"
model: "gpt-4o"
temperature: 0.6
responseLength: "standard"
responseStyle: "bullet-points"
privacyMode: "private"
citations: "minimal"
```

## Best Practices

### 1. Start Simple

✅ Begin with basic configuration ✅ Add 1-2 focused data sources ✅ Use default RAG strategy (Cedar) ✅ Test thoroughly before advancing ❌ Don't overconfigure initially

### 2. Clear Instructions

✅ Be specific about behavior ✅ Include examples ✅ Define boundaries ✅ Specify tone and style ❌ Don't write vague instructions

### 3. Appropriate Strategy

✅ Redwood: Simple, high-volume ✅ Cedar: Conversational, general use ✅ Cypress: High accuracy, complex ❌ Don't use Cypress for everything

### 4. Regular Review

✅ Review configuration monthly ✅ Update based on analytics ✅ Adjust based on feedback ✅ Test after changes ❌ Don't "set and forget"

## Testing Configuration

### Playground Testing

1. Open agent in Playground
2. Test various query types:
   * Simple factual questions
   * Complex multi-part queries
   * Follow-up questions
   * Edge cases
3. Review responses and citations
4. Adjust configuration based on results

### A/B Testing

```typescript
// Create two versions
agent_v1.config = { temperature: 0.7 }
agent_v2.config = { temperature: 0.3 }

// Route 50% traffic to each
// Compare metrics after 1 week
// Deploy winner
```

### Configuration Validation

```bash
# Validate configuration via API
curl -X POST https://api.twig.so/api/ai-agent-managers/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "config": {...}
  }'
```

## Troubleshooting

### Agent Not Responding Well

**Check:**

1. Are instructions clear and specific?
2. Are correct data sources connected?
3. Is RAG strategy appropriate?
4. Is temperature too high/low?

### Inconsistent Responses

**Solutions:**

* Lower temperature (0.3-0.5)
* More specific instructions
* Add examples in system prompt
* Switch to Cedar for context

### Slow Performance

**Solutions:**

* Switch to Redwood strategy
* Reduce topK
* Use GPT-3.5-turbo
* Reduce max tokens

## Next Steps

* [Prompt Engineering](/product/overview/prompt-engineering.md) - Craft effective prompts
* [RAG Strategies](/product/overview-1.md) - Choose optimal strategy
* [Agent Deployment](https://github.com/thrivapp/twig-help-docs/blob/staging/ai-agents/deployment.md) - Deploy your agent
* [Performance Tuning](/product/monitoring/performance-tuning.md) - Optimize performance


---

# 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/product/overview/configuration.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.