Setup Your First Agent

Setup your first agent guide

Setup Your First Agent

Build your first AIVAH agent in five short steps. This walkthrough mirrors the live product flow: create an agent, give it a face and a voice, test it in the Playground, share it publicly, and wire it up to your tools.

Step 1: Create Your Agent

Open Agents in the side navigation (/agents) and click the + button to start a fresh agent at /agents/create.

Create agent form – Name, Agent Capabilities, Agent Prompt, Persona, and Documents

Configure the basics

• Name – becomes the slug shown next to the heading (@my-agent).
• Agent Capabilities → Presenter – leave off for a knowledge-base agent that accepts URLs, files, and text. Turn on for a presenter that takes a single PDF or video and produces slide-aligned answers with a built-in Quiz overlay.
• Agent Prompt – freeform instructions that shape behaviour.
• Persona – a short label of your agent’s tone (for example witty and casual).

Presenter toggle on – this constrains the agent to a single PDF or video and unlocks the Quiz overlay

Add knowledge content

Click Add document to attach knowledge sources. Knowledge-base agents accept any mix of URL / Files / Text; presenter agents accept a single PDF or video.

Add document dropdown – Add URL, Add Files, or Create Text

Add URL

Paste any publicly accessible link – website pages, blog posts, YouTube/Vimeo videos, or documentation. Aivah fetches and indexes the page automatically.

Add URL modal

Add Files

Drag-and-drop or pick files (up to 21 MB each). Supported types include .pdf, .docx, .txt, .csv, .xlsx, .html, .md, .epub, .json, .xml, .mp4, .mp3, .jpg, .png.

Add Files modal with the full list of supported file types

Create Text

Paste raw text content – ideal for FAQs, policies, or short snippets.

Create Text modal

Presenter agents accept only a single PDF or a single video at a time. Delete the existing file to replace the deck.

Finalise

Click Create Agent. The agent enters processing, you’re redirected to the agents list, and Aivah polls every few seconds until the status flips to completed. If a single source fails, open the agent detail view and hit the inline refresh on just that item.

Agents workspace – every agent with its type, capability badges, and live training status

---

Step 2: Pick a Persona – Avatar, Character, and Voice

Aivah keeps everything visual in one workspace: Side nav → Customization.

Avatars (3D)

Browse the full Ready Player Me-based avatar library and set defaults from Customization → Avatars.

Avatars grid – every 3D companion in your account

For step-by-step avatar creation, see Create Avatar.

Characters (2D)

Characters are lightweight image-based personas – upload a photo, crop it, name it, and it’s instantly selectable everywhere a character can be picked.

Characters page – upload an image and it becomes a selectable 2D persona

1. Click Upload Image

   Open Customization → Characters and pick a photo. JPG, PNG, and WEBP are supported.

2. Crop the face

   The Crop Character Image modal opens. Pick an aspect ratio (1:1, 3:4, 4:5, or Custom), name the character, then save.

   

   Crop Character Image modal

3. Edit or delete anytime

   The pencil icon reopens an Edit modal where you can change the name, Agent Prompt, and Agent Idle Prompt that describe how the character behaves when speaking or idle.

   

   Edit Character modal

Voices

Customization → Voices lists every built-in voice plus any clones you’ve made. Click + Create to add your own.

Voices page – built-in voices plus your private clones

1. Open the Add voice modal

   Click + Create to launch the dialog.

   

   Add voice modal – Name, Language, Voice Sample, and Description

2. Pick the language

   Choose from English, French, German, Spanish, Portuguese, and more.

3. Upload or record a sample

   Use Upload File for a clean mono recording (up to 10 MB) or Record Audio in the browser (up to 1 minute).

   

   Record Audio mode – capture up to 1 minute right in the browser

4. Save

   Click Add to my voice. Once processed, the voice appears wherever voices can be picked.

---

Step 3: Test in the Playground

Open the Chat workspace from the side navigation. New chats start at /new-playground/new-chat; existing conversations live at /{conversationId}/chat and /{conversationId}/avatar-chat.

New chat composer – pick agent, character, model, and voice from the pills

Configure the conversation from the composer pills

Every important option is one click away from the composer:

Agent

Switch the active agent without leaving the composer

LLM

Pick between OpenAI, Gemini, Grok, and OpenAI Realtime model families

Voice

Voices are filtered to those supported by the selected model

Character

The Character picker covers 2D personas, including the ones you've uploaded

Try the three modes

Text chat

Type your message, attach files with the paper-clip, ask for an image or video, or trigger a web search inline.

Text chat conversation with credits badge in the top-right

Add photos and files directly from the composer

Avatar chat

The 3D avatar fills the canvas and the side panel keeps the transcript + composer in view.

Avatar chat in a Zen scene with the productivity toolbar on the left rail

Tap a Character to chat with a 2D persona in full-screen mode

Voice-only

Click the mic to start a voice-first session. The voice orb expands while the avatar listens and responds.

Voice orb during a voice-only session

Generate media right from the composer

Ask the agent to draw, animate, or research – the chat composer routes the request to the right model automatically.

Image generation runs inline, then the result auto-saves to AI Drive

Animate any generated image into a short video with a follow-up prompt

Tune the avatar and scene from Preferences

The palette icon next to the composer opens Preferences. Use it to set the default avatar and the 3D scene the avatar chat opens in.

Preferences modal – Avatar tab

Preferences modal – Scene tab (Standard, Zen, Web Results, Video, Presenter)

---

Step 4: Share Your Agent

Open Shared in the side navigation to publish a public link, bubble, or iframe.

Shared workspace – every published agent with its link type badge

Create a shared agent

Click the + button to open the two-step create flow.

1. Persona step – pick the agent, model, voice, tools, and instructions

   

   Persona step – Link Type, Model, Voice, Knowledge Base, MCP Tools, Instructions, Lead capture

   Choose the Link Type that fits your distribution plan:

   • Direct Link – a clean URL you can post anywhere.
   • Iframe – an embeddable widget for your website.
   • Chat Bubble – a floating bubble script for any site.
2. Optional – add a lead capture form

   Click Add lead capture form inside the Persona step. Configure title, consent text, and one or more fields (name, email, phone, custom). Mark each as required or optional.

   

   Data Collection Form modal – fields, consent, and a Mandatory toggle

3. Experience step – pick the avatar / character, scene, and branding

   Switch tabs between Companion Avatars (3D) and Characters (2D), pick a scene, and decide what logo appears in the embed.

   

   Experience step – Companion Avatars tab with scene picker

   

   Experience step – Characters tab

4. Publish

   Click Publish. The agent appears in the Shared list with a copy button for its public URL.

Pick the right distribution

After publishing, the Share Options dialog gives you every distribution snippet for that agent:

Direct Link

A simple URL plus a Direct Link With Voice variant.

Share Options – Direct Link tab

Iframe

Two iframe variants – companion (avatar only) and companion-scene (full scene).

Share Options – Iframe tab

Chat Bubble

A drop-in <script> that floats a chat bubble in the corner of any page.

Share Options – Chat bubble tab

---

Step 5: Connect Channels and Tools

Open Integrations in the side navigation to plug your agent into the rest of your stack.

MCP Tools

One-click OAuth connectors for Gmail, Slack, Notion, Linear, GitHub, Calendar, Drive, Sheets, Outlook, Composio and many more. Toggle on a connector, run the OAuth flow, and Aivah verifies the connection automatically.

MCP page – every connector with a live X/N Active counter

Channels – Slack & WhatsApp

Let the same agent respond inside your team’s chat tools.

• Slack uses the included App Manifest plus a Bot Token, Signing Secret, and your Member ID. Invite the bot then use /aivah.
• WhatsApp uses QR pairing – click Connect, scan the QR with WhatsApp → Linked Devices, and you’re live.

Channels page – Slack and WhatsApp configurations side-by-side

Telephony

Bring your own Twilio number (or mint a free Vapi number). The detail page splits into Connection (SIP URI + credentials) and Interaction (Language Model + Voice + System Prompt) tabs.

Telephony empty state – click Create Phone Number to add your first one

Connection tab – Twilio SIP URI and credentials

Interaction tab – Language Model, Voice, and System Prompt for phone calls

Tasks – Cron jobs and Heartbeat

Schedule recurring jobs (with a Channel column for Web, Slack, WhatsApp, etc.) or wire up heartbeat monitors. Anything created by you, or by the agent in response to a request, lands here.

Cron Jobs tab – a scheduled reminder running on the Web channel

Manage Memory

Every long-term key/value the agent has stored, with timestamps and a Download CSV action. Use it for audit, GDPR exports, or quick edits when memories drift.

Manage Memory – every stored key/value pair with timestamps

---

You’re Live

Your AIVAH agent is now:

• Trained on your knowledge sources and showing as completed
• Given a face (Avatar or Character) and a voice
• Tested live in the Playground (text, avatar, and voice-only modes)
• Shared with a public link, optional iframe / chat-bubble, and a lead form
• Wired to MCP tools, Channels, Phone, Tasks, and Memory

What’s next

1. Best Practices – patterns we’ve learned from hundreds of agents in production
2. Productivity – generate slides, podcasts, mind maps – turn the same agent into ready-to-share assets
3. Insights – track unique users, credits, chat logs, leads, and call logs
4. Subscriptions and Credits – pick a plan, top up credits, and manage billing