AI Agents

Create and manage AI agents that can interact with customers, answer questions, and perform actions in your store.

Create an Agent

Create a new AI agent for your store. Each agent has its own model, system prompt, tools, and channels.

curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/agents \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "model": "claude-opus-4-6",
    "system_prompt": "You are a helpful customer support agent for our store. Help customers with orders, products, and general questions.",
    "tools": ["orders_list", "orders_get", "products_list", "customers_get"],
    "channels": ["webchat", "sms"],
    "welcome_message": "Hi! How can I help you today?",
    "is_default": true
  }'

// Response (201 Created)
{
  "object": "agent",
  "id": "72d7aaa8-2e8b-48a0-a38d-f332f69600bb",
  "name": "Customer Support",
  "model": "claude-opus-4-6",
  "status": "active",
  "channels": ["webchat", "sms"],
  "is_default": true,
  "created_at": "2026-03-09T12:00:00.000Z"
}

Agent Configuration

Field	Type	Description
name	string	Display name for the agent.
model	string	LLM model identifier (e.g. claude-opus-4-6, gpt-4o).
system_prompt	string	Instructions that define the agent's behavior and personality.
tools	string[]	Array of tool IDs the agent can use during conversations.
channels	string[]	Communication channels: webchat, sms, email, pos.
welcome_message	string	Initial message shown when a conversation starts.
is_default	boolean	Whether this is the default agent for the store.
max_conversations_per_day	number	Daily conversation limit. null for unlimited.
fallback_agent_id	string	Agent to hand off to when this agent cannot help.

Agent Templates

Start from a pre-built template instead of configuring everything from scratch. Templates include a system prompt, recommended tools, and channel defaults.

// List available templates
curl https://vm.whaletools.cloud/v1/agent-templates \
  -H "x-api-key: wk_live_your_key_here"

// Create an agent from a template
curl -X POST https://vm.whaletools.cloud/v1/stores/{storeId}/agents \
  -H "x-api-key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "customer-support",
    "name": "My Support Agent",
    "channels": ["webchat"]
  }'

Template fields can be overridden in the create request. Any field you provide takes precedence over the template default.

Conversations

Send messages to an agent and receive streaming responses. Conversations maintain context across multiple messages.

// Send a message (SSE streaming response)
const response = await fetch(
  'https://vm.whaletools.cloud/agent/api/chat',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_SERVICE_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: '72d7aaa8-2e8b-48a0-a38d-f332f69600bb',
      message: 'What were the top selling products this week?',
      storeId: 'your-store-id',
      source: 'api',
    }),
  }
);

// Read SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // Each line: data: {"type":"text","text":"..."}
  console.log(chunk);
}

Cost Budgets and Usage

Monitor and control agent costs with daily conversation limits and plan-based budgets. Usage metrics are available via the API and the control plane dashboard.

•Conversation limits. Set max_conversations_per_day to cap daily usage per agent.
•Plan limits. Each store plan includes a maximum number of agents. The API enforces this when creating new agents.
•Token tracking. Input and output tokens are logged per conversation and visible in analytics.
•Cost guards. The platform includes automatic circuit breakers that pause agents if costs exceed configurable thresholds.