> ## Documentation Index
> Fetch the complete documentation index at: https://docs.featherhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Agents are Feather's reusable conversation workers. Versions define behavior, models, prompts, tools, and channel-specific settings.

Agents are the center of the Feather platform. They define who the assistant is, what it can do, and how it behaves across conversations.

## Agent Model

Feather separates an agent into two layers:

* **Agent**: the stable identity for a use case such as support, qualification, reminders, or scheduling
* **Agent version**: the deployable snapshot that contains the prompt, tools, models, voice, and channel-specific settings

This model lets you iterate safely: build a new version, test it, then deploy it when ready.

## Agent Types

Feather supports two primary agent types:

* **CALL** for live voice conversations
* **TEXT** for SMS and message-first use cases

Text-capable agents can also power outbound email threads and web chat flows when the related channel settings are configured.

## What Lives on a Version

An agent version can include:

* Prompt instructions and variables
* Custom tools and pre-built tools
* Knowledge base collections
* Language, voice, STT, TTS, and LLM settings
* Call behavior such as voicemail handling, interruption tuning, and silence timeouts
* Message behavior such as SMS and email token limits or inactivity windows

## Prompt Design

Keep prompts operational, not aspirational. A good production prompt usually covers:

* The agent's job
* What information it must collect
* What tools it is allowed to use
* When to escalate, transfer, or stop
* Tone and response length

### Example Prompt Shape

```json theme={"system"}
{
  "system": "You are a renewal specialist for Feather Labs. Confirm who you are speaking with, explain the reason for the conversation, answer contract questions, and offer the next step.",
  "variables": [
    {
      "name": "accountName",
      "required": false,
      "defaultValue": "the account"
    },
    {
      "name": "renewalDate",
      "required": false
    }
  ],
  "tools": ["lookup_contract", "create_follow_up_task"],
  "preBuiltTools": []
}
```

## Creating an Agent

This request creates a text-capable agent with prompt variables and message settings.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agents" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renewals Assistant",
    "description": "Handles proactive renewal outreach",
    "agentType": "TEXT",
    "useKnowledgeBase": true,
    "prompt": {
      "system": "You are a renewal specialist for Feather Labs. Be concise, confirm account context, and move the customer toward the next step.",
      "variables": [
        {
          "name": "accountName",
          "required": false
        },
        {
          "name": "renewalDate",
          "required": false
        }
      ],
      "tools": ["lookup_contract", "create_follow_up_task"],
      "preBuiltTools": []
    },
    "voicemailMessage": null,
    "overrideSTTConfig": null,
    "sms": {
      "inactivityTimeoutHours": 24,
      "smsMaxTokens": 500,
      "smsTemperature": 0.7
    }
  }'
```

## Deployments

Creating an agent gives you an initial version, but live traffic uses the version you deploy. Common pattern:

1. Create or update a version.
2. Run tests or internal QA.
3. Deploy that version.
4. Route phone numbers, workflows, or public entry points to the deployed version.

## When to Create a New Version

Create a new version when you change any of these:

* Prompt behavior
* Tools or tool permissions
* Knowledge base attachments
* Voice, model, or language settings
* Channel configuration such as email sender identity or silence tuning

## Related Concepts

<CardGroup cols={2}>
  <Card title="Conversations" icon="headset" href="/documentation/core-concepts/calls">
    See how agents are exposed over voice, SMS, email, and web chat.
  </Card>

  <Card title="Tools" icon="wrench" href="/documentation/core-concepts/tools">
    Extend agent behavior with custom actions.
  </Card>

  <Card title="Knowledge Base" icon="database" href="/documentation/core-concepts/knowledge-base">
    Ground answers in your own documents.
  </Card>

  <Card title="Agents API" icon="code" href="/api-reference/agents/create-a-new-agent">
    Browse the full agent management API.
  </Card>
</CardGroup>