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:

{
  "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)

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

Cedar (Context-Aware)

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

Cypress (Advanced)

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

See RAG Strategies Overview for detailed comparison.

Strategy Configuration:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

User-Level Memory:

{
  "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:

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

Custom Metadata:

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

Webhook Integration:

{
  "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

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

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

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

// 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

# 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 - Craft effective prompts
• RAG Strategies - Choose optimal strategy
• Agent Deployment - Deploy your agent
• Performance Tuning - 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 /dev/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.