​
What Are Agents?

An agent in Feather AI is a configurable AI-powered conversational interface that can:
  • Make and receive phone calls across inbound and outbound channels
  • Handle multi-turn conversations with context awareness
  • Engage in natural conversations using advanced AI prompts
  • Integrate with external tools for dynamic functionality
  • Access knowledge bases for informed responses
  • Transfer calls to human agents when needed
  • Collect and process user information systematically
Think of agents as your AI employees that can handle conversations at scale while maintaining consistency and following your business rules.

​
Agent Architecture

​
Agent vs Agent Version

Feather AI uses a two-level architecture:
  • Agent: The persistent identity with metadata like name and description
  • Agent Version: The actual configuration that defines behavior, AI models, and conversation flow
This separation allows you to:
  • Maintain multiple configurations for the same agent
  • Test new versions before deploying them
  • Roll back to previous versions if needed
  • Track the complete history of changes

​
Deployment Model

Only one version per agent can be deployed (active) at a time. The deployed version is what handles live conversations, while other versions remain available for testing or future deployment.

​
Creating and Managing Agents

​
Create an Agent

Start by creating an agent with basic metadata: 
POST /api/v1/agents
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Customer Support Agent",
  "description": "Handles general customer inquiries and support requests"
}

​
Create Agent Versions

Configure the agent’s behavior by creating versions: 
POST /api/v1/agents/{agentId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "mode": "PROMPT",
  "prompt": {
    "variables": [],
    "tools": ["knowledge-search"],
    "system": "You are a helpful customer service representative. Be friendly, professional, and helpful."
  },
  "sttConfigId": "nova-3-stt",
  "ttsConfigId": "aura-2-tts",
  "llmConfigId": "gpt-4o-mini-llm",
  "voiceId": "6011b4c8-6140-4b7e-8a92-d9880de97b77",
  "channels": ["OUTBOUND_CALL"],
  "useKnowledgeBase": false,
  "enableBackgroundAudio": false,
  "backgroundAudio": 50
}

​
Deploy a Version

Activate a version to handle live conversations: 
PATCH /api/v1/agents/{agentId}/versions/{versionId}/deploy
Authorization: Bearer YOUR_API_KEY

​
Update and Iterate

Create new versions to evolve your agent’s capabilities, test them, and deploy when ready.

​
Agent Configuration

Agents use conversational AI powered by system prompts for natural, free-form conversations. This approach is ideal for:
  • Open-ended customer service
  • Sales conversations
  • General inquiry handling
  • Complex problem-solving

​
Configuration Example

{
  "mode": "PROMPT",
  "prompt": {
    "variables": [
      {
        "name": "companyName",
        "value": "Acme Corp"
      },
      {
        "name": "supportEmail", 
        "value": "support@acme.com"
      }
    ],
    "tools": ["knowledge-search", "ticket-creation", "order-lookup"]
  },
  "sttConfigId": "nova-3-stt",
  "ttsConfigId": "aura-2-tts", 
  "llmConfigId": "gpt-4o-mini-llm",
  "voiceId": "6011b4c8-6140-4b7e-8a92-d9880de97b77",
  "channels": ["OUTBOUND_CALL"],
  "useKnowledgeBase": true,
  "enableBackgroundAudio": false,
  "backgroundAudio": 50
}

​
AI Models Configuration

Speech-to-Text (STT) - Configure how the agent processes spoken input:
  • sttConfigId: Reference to STT configuration
  • overrideSTTConfig: Custom STT settings for this agent
Text-to-Speech (TTS) - Configure how the agent speaks:
  • ttsConfigId: Reference to TTS configuration
  • voiceId: Specific voice selection
  • overrideTTSConfig: Custom TTS settings
Language Model (LLM) - Configure the AI brain:
  • llmConfigId: Reference to LLM configuration
  • overrideLLMConfig: Custom LLM settings

​
Tools and Integrations

Agents can execute custom tools to interact with your business systems: 
{
  "tools": [
    {
      "id": "crm-lookup",
      "name": "Look up customer in CRM",
      "description": "Search for customer information",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {"type": "string"},
          "phone": {"type": "string"}
        }
      }
    }
  ]
}
Pre-built Tools - Access platform-provided capabilities:
  • Calendly: Schedule appointments
  • Knowledge Base: Search company documentation
  • Lead Management: Update lead information

​
Knowledge Base Integration

Enable agents to access your knowledge base for informed responses: 
{
  "useKnowledgeBase": true,
  "system": "You can search our knowledge base to answer customer questions accurately. Always cite sources when referencing company policies or procedures."
}

​
Variables and Context

Use variables to personalize conversations: 
{
  "prompt": {
    "variables": [
      {
        "name": "customerName",
        "value": "{{lead.firstName}}"
      },
      {
        "name": "companyName",
        "value": "Acme Corp"
      },
      {
        "name": "appointmentTime",
        "value": null
      }
    ]
  }
}
Variables maintain state throughout the conversation, allowing agents to:
  • Remember information collected earlier
  • Personalize responses based on context
  • Pass data between tool calls and responses
  • Integrate with external systems

​
Phone Number Integration

Inbound Numbers - Configure which phone numbers route to this agent: 
{
  "inboundPhoneNumbers": [
    {
      "id": "phone-123",
      "number": "+1234567890"
    }
  ]
}
Outbound Numbers - Configure which numbers the agent uses for outbound calls: 
{
  "outboundPhoneNumbers": [
    {
      "id": "phone-456", 
      "number": "+1987654321"
    }
  ]
}

​
Best Practices

Design Considerations:
  1. Start Simple: Begin with basic prompts and gradually add complexity
  2. Plan Fallbacks: Always include error handling and fallback scenarios
  3. Test Thoroughly: Use multiple versions to test before deploying
  4. Monitor Performance: Track conversation success rates and user satisfaction
Prompt Engineering:
  1. Be Specific: Provide clear instructions about the agent’s role and capabilities
  2. Set Boundaries: Define what the agent can and cannot do
  3. Include Examples: Show the desired conversation style and format
  4. Plan for Edge Cases: Handle unexpected inputs gracefully

​
Common Use Cases

Customer Support Agent:
  • Handle common inquiries using knowledge base
  • Collect information for ticket creation
  • Escalate complex issues to human agents
  • Provide 24/7 availability
Sales Outreach Agent:
  • Qualify leads through natural conversation
  • Schedule demonstrations and meetings using tools
  • Update CRM systems with conversation results
  • Personalize outreach based on lead data
Appointment Scheduling Agent:
  • Collect availability through conversation
  • Integrate with calendar systems via tools
  • Send confirmation messages
  • Handle rescheduling requests naturally
Lead Qualification Agent:
  • Score leads based on conversational responses
  • Collect detailed qualification information naturally
  • Route qualified leads to sales teams
  • Nurture unqualified leads for future follow-up

​
Next Steps