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

# Agents

> Learn how to create, configure, and deploy AI agents on thinnestAI.

# Agents

An **agent** is the core building block of thinnestAI. It's an AI-powered assistant that can hold conversations over the phone, in chat, or as part of an automated workflow. Each agent has its own instructions, model, voice, tools, and knowledge.

## What is an Agent?

Think of an agent as a virtual team member. You tell it what to do (via instructions), give it access to information (via knowledge), and equip it with abilities (via tools). It then handles conversations autonomously, following your guidelines.

Common use cases:

* **[Customer Support](/docs/examples/customer-support)** — Answer product questions, troubleshoot issues, process returns
* **[Appointment Booking](/docs/examples/appointment-booking)** — Check availability, schedule meetings, send confirmations
* **[Lead Qualification](/docs/examples/lead-qualification)** — Ask qualifying questions, collect information, route to sales
* **[Order Management](/docs/examples/order-management)** — Check order status, process changes, handle refunds
* **[Surveys & Feedback](/docs/examples/survey-agent)** — Conduct phone surveys, collect NPS scores, gather feedback
* **[Real Estate Agent](/docs/examples/real-estate-agent)** — Handle property inquiries and schedule showings

See [Examples](/docs/examples) for complete step-by-step guides for each use case.

## Creating an Agent via the Dashboard

1. Navigate to **Agents** in the sidebar and click **+ New Agent**.
2. Configure the following settings:

### Basic Settings

| Setting          | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| **Name**         | A descriptive name for your agent (e.g., "Booking Assistant") |
| **Instructions** | The system prompt that defines your agent's behavior          |
| **Model**        | The AI model powering your agent (see [Models](/docs/models)) |
| **Voice**        | The voice your agent uses for phone calls                     |

### Advanced Settings

| Setting         | Description                                                         |
| --------------- | ------------------------------------------------------------------- |
| **Temperature** | Controls randomness (0 = deterministic, 1 = creative). Default: 0.7 |
| **Max Tokens**  | Maximum response length per turn                                    |
| **Memory**      | Enable conversation memory (see [Memory](/docs/memory))             |
| **Markdown**    | Enable markdown formatting in chat responses                        |

3. Click **Create Agent**.

## Creating an Agent via the API

### Create a Basic Agent

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "instructions": "You are a customer support agent for Acme Corp. Help customers with their questions about products, orders, and returns. Be friendly and concise.",
    "model": "claude-sonnet",
    "voice": "alloy",
    "temperature": 0.7
  }'
```

### Create an Agent with Tools and Knowledge

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Booking Agent",
    "instructions": "You are an appointment booking agent. Check available slots using the calendar tool, book appointments, and send confirmation emails.",
    "model": "gpt-4o",
    "voice": "nova",
    "tools": ["google_calendar", "gmail"],
    "knowledge_sources": ["ks_faq_doc_id"],
    "temperature": 0.3
  }'
```

### Response

```json theme={null}
{
  "id": "agent_abc123",
  "name": "Booking Agent",
  "status": "active",
  "model": "gpt-4o",
  "voice": "nova",
  "tools": ["google_calendar", "gmail"],
  "created_at": "2026-03-05T10:30:00Z"
}
```

## Agent Settings Reference

### Choosing a Model

Different models have different strengths. For voice agents, we recommend:

* **Claude Sonnet** — Best balance of speed and intelligence. Great for most voice use cases.
* **GPT-4o** — Strong reasoning, fast responses. Good for complex conversations.
* **Gemini** — Good for multilingual support and long context windows.

See [Models](/docs/models) for a full comparison.

### Choosing a Voice

thinnestAI supports multiple voice options for your phone agents. You can preview voices in the dashboard before selecting one. Voice options include:

* **alloy** — Neutral, professional tone
* **nova** — Warm, friendly tone
* **echo** — Clear, authoritative tone
* **shimmer** — Soft, approachable tone
* **onyx** — Deep, confident tone

### Writing Instructions

Your agent's instructions are the most important configuration. They define personality, behavior, boundaries, and goals. See [Prompts](/docs/prompts) for detailed guidance.

## Assigning Tools

Tools give your agent the ability to take actions — look up data, send emails, book appointments, and more.

1. Go to your agent's **Tools** tab.

2. Click **+ Add Tool** and choose from available integrations:
   * **Google Calendar** — Read and create calendar events
   * **Gmail** — Send and read emails
   * **Google Sheets** — Read and write spreadsheet data
   * **HTTP Request** — Call any external API
   * **Knowledge Search** — Search the agent's knowledge base
   * **SMS** — Send text messages
   * **Custom Webhook** — Trigger custom workflows

3. Configure any required credentials (e.g., Google OAuth).

4. Save changes.

### Via the API

```bash theme={null}
curl -X PATCH https://api.thinnest.ai/agents/agent_abc123 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["google_calendar", "gmail", "knowledge_search"]
  }'
```

## Adding Knowledge

Knowledge gives your agent information to draw from during conversations. You can upload documents, connect websites, or add structured data.

1. Go to your agent's **Knowledge** tab.

2. Click **+ Add Source** and choose:
   * **File Upload** — PDF, DOCX, TXT, CSV files
   * **Website URL** — Crawl and index a website
   * **Text** — Paste raw text content
   * **GitHub Repository** — Index code repositories

3. The content is automatically processed, chunked, and embedded for retrieval.

Your agent will search its knowledge base during conversations and include relevant information in its responses.

## Testing Your Agent

### Chat Testing

Click **Test Chat** on your agent's page to open a chat interface. This is the fastest way to test your agent's behavior and iterate on its instructions.

### Phone Testing

If you've assigned a phone number, simply call it. You can also trigger a test outbound call from the dashboard:

1. Go to **Phone** tab.
2. Click **Test Call**.
3. Enter a phone number to call.
4. Your agent will call that number and start a conversation.

### Review Call Logs

After testing, review the conversation in **Call Logs**:

* Full transcript of the conversation
* Audio recording (if enabled)
* Token usage and cost
* Tool calls made during the conversation
* Duration and other metadata

## Updating an Agent

```bash theme={null}
curl -X PATCH https://api.thinnest.ai/agents/agent_abc123 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "instructions": "Updated instructions here...",
    "temperature": 0.5
  }'
```

## Versioning Core Behavior (system prompt)

Iterating on a system prompt without losing the version that's working in production is the most common pain point with prompt engineering. The **Core Behavior** panel ships an opt-in version-history system so you can snapshot a working prompt, experiment freely, and roll back if the new copy underperforms.

> **Manual save only.** Versions are **not** created automatically when you save the agent — you have to click **Save version** before each risky edit. This keeps the history list short and signal-heavy: every row is a checkpoint you actually wanted to keep.

### Where to find it

In the agent's **Behavior** tab, the **Core Behavior** card header has three icon buttons:

| Icon           | What it does                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 💾 **Save**    | Snapshots the current prompt as a new version. Optional one-line message ("v3 — tightened voice tone") so you can recognise it later. |
| 🕐 **Clock**   | Opens the version history drawer with up to 10 most-recent snapshots.                                                                 |
| ⤢ **Maximize** | Opens the prompt in a full-screen editor (unchanged).                                                                                 |

### Saving a version

1. Edit the Core Behavior text as usual.
2. Click **Save** (💾) when you're at a point you want to be able to return to.
3. Add an optional message in the dialog (200-char cap). Press Enter to save.
4. A toast confirms `Saved as v4`. If the prompt is byte-identical to the latest existing version, you'll see `Already saved — identical to the latest version` instead — no duplicate row is created.

### Browsing and restoring

1. Click the **Clock** (🕐) icon to open the history drawer.
2. Each row shows version number, optional message, who saved it, when, and character count.
3. Click any row to open a **side-by-side diff**: the saved version on the left, your current draft on the right.
4. Click **Use this version** to replace your current draft with the saved text. (Your previous current draft is **not** auto-saved as a new version — save it before restoring if you want to be able to roll back.)
5. The next time the agent autosaves, the restored prompt becomes the live one.

### Retention

* **10 most-recent versions** per agent.
* When you save the 11th, the oldest is pruned automatically.
* Versions are immutable after insert — they're an audit log, not editable.
* Deleting an agent cascades the version history with it.

### Multi-seat workspaces

Each version row records `created_by` (the Auth0 subject of whoever clicked **Save**). The drawer doesn't surface user names today, but the data is in the row for future filtering by author.

## Duplicating an Agent

Need a copy of an existing agent — same instructions, model, voice, tools and knowledge — to experiment with without touching the original? Use **Duplicate** instead of rebuilding from scratch.

From the **Agents** list in the dashboard:

1. Hover the agent card (or its row in list view).
2. Click the **copy** icon next to the trash icon.
3. A new agent appears immediately with the same configuration and the suffix `(Copy)` added to the name (`(Copy 2)`, `(Copy 3)` and so on if you duplicate more than once).

What gets copied:

| Carried over                                  | Reset on the duplicate                                          |
| --------------------------------------------- | --------------------------------------------------------------- |
| Name (with `(Copy)` suffix)                   | Public ID — the duplicate gets a fresh `ag_...`                 |
| Model + instructions + voice config           | `publish_config` — the duplicate starts as a **draft**          |
| Tools, knowledge attachments, flow graph      | Phone-number assignment — duplicates don't auto-take a number   |
| Agent type (simple / graph / team / workflow) | Audit log keeps a `duplicate_agent` record linked to the source |

> **Why is `publish_config` reset?** A duplicate is meant for experimentation. Starting it as a draft means you can edit the cloned prompt or swap a model without accidentally pushing changes to the live deployment that hosted the original.

## Deleting an Agent

```bash theme={null}
curl -X DELETE https://api.thinnest.ai/agents/agent_abc123 \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

Deleting an agent will release any assigned phone numbers and stop all active sessions.

## Listing Agents

```bash theme={null}
curl https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

```json theme={null}
{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Support Agent",
      "status": "active",
      "model": "claude-sonnet",
      "created_at": "2026-03-05T10:30:00Z"
    },
    {
      "id": "agent_def456",
      "name": "Booking Agent",
      "status": "active",
      "model": "gpt-4o",
      "created_at": "2026-03-04T14:15:00Z"
    }
  ]
}
```

## Team Agents

For complex workflows, you can create **team agents** — groups of specialized agents that work together. Team agents support multiple coordination modes:

* **Coordinate** — A lead agent delegates tasks to specialists
* **Route** — Incoming requests are routed to the best-fit agent
* **Collaborate** — Agents work together, passing context between them
* **Tasks** — Each agent handles a specific task in sequence

Configure teams in the **Flow Editor** in the dashboard, or via the API.