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

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

Basic Settings

Advanced Settings

3. 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.

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

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

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
  }'

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.