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

# Permanent Agents

> Create reusable agents manageable via the iwy dashboard

## Choosing the Right Agent Type

iwy offers two types of agents:

| Type                                             | Best For                                  | Sessions per Agent | Visible in Dashboard |
| ------------------------------------------------ | ----------------------------------------- | ------------------ | -------------------- |
| [Single-Use](/api-reference/code-first/overview) | Personalized, per-session experiences     | 1                  | No                   |
| **Permanent** (you are here)                     | Reusable agents with dashboard management | Unlimited          | Yes                  |

**Not sure which to use?** See the [full comparison](/api-reference/api-reference#single-use-vs-permanent-agents). Both are production-ready.

***

## Overview

Permanent agents persist in your account forever and can be used for unlimited sessions. Configure them anytime at [dashboard.iwy.ai](https://app.iwy.ai) or via the API. This is ideal for:

* **Reusable agents**: Use the same agent ID across unlimited sessions
* **Visual configuration**: Edit agents through the dashboard UI
* **Team collaboration**: Multiple team members can manage agents
* **CI/CD automation**: Programmatically update agents via scripts

## How It Works

Resources created through this API appear in and can be managed from the iwy dashboard. This gives you the best of both worlds:

1. **Visual editing** - Use the dashboard for quick changes and testing
2. **Programmatic control** - Use the API for automation and integration
3. **Persistent storage** - Agents and tools are stored long-term in your account

## Authentication

All API endpoints require authentication using a Bearer token. You can find your API key in your [account settings](https://app.iwy.ai/settings).

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Base URL

```
https://api.iwy.ai/v1
```

## Core Concepts

### Agents

Agents are conversational AI entities that can interact with users through text and voice. Each agent has:

* **LLM Configuration**: The language model, system prompt, and personality
* **STT/TTS Settings**: Speech-to-text and text-to-speech providers
* **Video Avatar**: Visual representation for video calls
* **Tool Integration**: Custom functions the agent can call
* **Publish Status**: Control visibility (draft, private, or public)

### Tools

Tools are custom functions that extend your agent's capabilities by connecting to external services via webhooks. Each tool defines:

* **Parameters Schema**: JSON Schema describing expected inputs
* **Webhook URL**: Your API endpoint to call
* **Authentication**: Headers and auth configuration
* **Timeout Settings**: Maximum execution time

## Quick Start

### 1. Create a Tool

First, create a custom tool that your agent can use:

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/tool \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Fetches current weather for a city",
    "server_url": "https://your-api.com/weather",
    "parameters_schema": {
      "type": "object",
      "required": ["city"],
      "properties": {
        "city": {
          "type": "string",
          "description": "City name"
        }
      }
    }
  }'
```

### 2. Create an Agent

Create an agent with your tool:

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weather Assistant",
    "publish_status": "private",
    "configuration": {
      "llm": {
        "model": "gemini-2.0-flash",
        "provider": "google",
        "system_prompt": "You are a helpful weather assistant",
        "first_message": "Hello! Ask me about the weather."
      },
      "tool_calling": {
        "selected_tool_ids": ["YOUR_TOOL_ID"]
      }
    }
  }'
```

### 3. Embed in Your App

Use the agent in your application:

```html theme={"dark"}
<live-avatar agentid="YOUR_AGENT_ID"></live-avatar>
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>
```

Or find other components at:

* [https://www.npmjs.com/package/@iwy/live-widgets](https://www.npmjs.com/package/@iwy/live-widgets)
* [https://github.com/iwy-ai/live-widgets](https://github.com/iwy-ai/live-widgets)

## API Endpoints

### Agents

* **List Agents**: Get all agents in your account
* **Create Agent**: Create a new agent
* **Get Agent**: Retrieve agent configuration
* **Update Agent**: Modify agent settings
* **Delete Agent**: Remove an agent

### Tools

* **List Tools**: Get all tools in your account
* **Create Tool**: Create a new tool
* **Get Tool**: Retrieve tool configuration
* **Update Tool**: Modify tool settings
* **Delete Tool**: Remove a tool
* **Test Tool**: Test tool execution with sample parameters

### Sessions

* **Start Agent Session**: Start a video call session with an agent

## Support

Need help? [Contact us](https://www.iwy.ai/contact)