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 — Answer product questions, troubleshoot issues, process returns
Appointment Booking — Check availability, schedule meetings, send confirmations
Lead Qualification — Ask qualifying questions, collect information, route to sales
Order Management — Check order status, process changes, handle refunds
Surveys & Feedback — Conduct phone surveys, collect NPS scores, gather feedback
Real Estate Agent — Handle property inquiries and schedule showings

See Examples for complete step-by-step guides for each use case.

Creating an Agent via the Dashboard

Navigate to Agents in the sidebar and click + New Agent.
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)
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)
Markdown	Enable markdown formatting in chat responses

Click Create Agent.

Creating an Agent via the API

Create a Basic Agent

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

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

{
  "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 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 for detailed guidance.

Assigning Tools

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

Go to your agent’s Tools tab.
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
Configure any required credentials (e.g., Google OAuth).
Save changes.

Via the API

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.

Go to your agent’s Knowledge tab.
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
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:

Go to Phone tab.
Click Test Call.
Enter a phone number to call.
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

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

Edit the Core Behavior text as usual.
Click Save (💾) when you’re at a point you want to be able to return to.
Add an optional message in the dialog (200-char cap). Press Enter to save.
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

Click the Clock (🕐) icon to open the history drawer.
Each row shows version number, optional message, who saved it, when, and character count.
Click any row to open a side-by-side diff: the saved version on the left, your current draft on the right.
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.)
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:

Hover the agent card (or its row in list view).
Click the copy icon next to the trash icon.
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

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

curl https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"

{
  "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.

​Agents

​What is an Agent?

​Creating an Agent via the Dashboard

​Basic Settings

​Advanced Settings

​Creating an Agent via the API

​Create a Basic Agent

​Create an Agent with Tools and Knowledge

​Response

​Agent Settings Reference

​Choosing a Model

​Choosing a Voice

​Writing Instructions

​Assigning Tools

​Via the API

​Adding Knowledge

​Testing Your Agent

​Chat Testing

​Phone Testing

​Review Call Logs

​Updating an Agent

​Versioning Core Behavior (system prompt)

​Where to find it

​Saving a version

​Browsing and restoring

​Retention

​Multi-seat workspaces

​Duplicating an Agent

​Deleting an Agent

​Listing Agents

​Team Agents