Skip to main content

Agent Configuration Guide

This guide covers creating and managing AI agent configurations using the WIIL Platform JS SDK. Agent configurations define the model, behavior, and capabilities of AI assistants deployed across various channels.

Quick Start​

import { WiilClient, LLMType, AssistantType, BusinessSupportServices } from 'wiil-js';

const client = new WiilClient({
  apiKey: 'your-api-key',
});

// Get a valid modelId from the support models registry
const model = await client.supportModels.getDefaultMultiMode();

// First, create an instruction configuration
const instruction = await client.instructionConfigs.create({
  instructionName: 'Customer Support Instructions',
  role: 'Customer Support Agent',
  introductionMessage: 'Hello! How can I help you today?',
  instructions: 'You are a helpful customer support agent.',
  guardrails: 'Always be polite and professional.',
  supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

// Create an agent configuration
const agent = await client.agentConfigs.create({
  name: 'Harper',
  modelId: model.modelId,
  instructionConfigurationId: instruction.id,
  defaultFunctionState: LLMType.MULTI_MODE,
  assistantType: AssistantType.GENERAL,
});

console.log('Agent created:', agent.id);

Prerequisites​

Agent configurations require an Instruction Configuration to be created first. The instruction configuration defines the agent's role, behavior guidelines, and conversation flow.

// Get a valid modelId from the support models registry
const model = await client.supportModels.getDefaultMultiMode();

// First, create an instruction configuration
const instruction = await client.instructionConfigs.create({
  instructionName: 'Customer Support Instructions',
  role: 'Customer Support Agent',
  introductionMessage: 'Hello! How can I help you today?',
  instructions: 'You are a helpful customer support agent.',
  guardrails: 'Always be polite and professional.',
  supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

// Then create the agent configuration
const agent = await client.agentConfigs.create({
  name: 'Harper',
  modelId: model.modelId,
  instructionConfigurationId: instruction.id,
});

Enums​

LLMType​

enum LLMType {
  STS = 'sts',              // Speech-to-speech
  TTS = 'tts',              // Text-to-speech
  STT = 'stt',              // Speech-to-text
  TRANSCRIBE = 'transcribe', // Transcription
  TEXT_PROCESSING = 'text',  // Text processing only
  MULTI_MODE = 'multi_mode'  // Multi-modal (default)
}

AssistantType​

enum AssistantType {
  PHONE = 'phone',    // Phone-based assistant
  WEB = 'web',        // Web chat assistant
  EMAIL = 'email',    // Email assistant
  GENERAL = 'general' // General purpose (default)
}

Agent Configuration Schema​

FieldTypeRequiredDescription
namestringYesAgent name (max 30 characters)
modelIdstringYesLLM model ID from Wiil model registry
instructionConfigurationIdstringYesID of linked instruction configuration
defaultFunctionStateLLMTypeNoOperational mode (default: MULTI_MODE)
assistantTypeAssistantTypeNoChannel specialization (default: GENERAL)
usesWiilSupportModelbooleanNoUse Wiil's model registry (default: true)
requiredModelConfigobjectNoAdditional model parameters
useCustomModelbooleanNoOpt out of platform default model configs; use only the specified modelId and requiredModelConfig (default: false)
textProcessingModelIdstring | nullNoSeparate model ID for text processing, if different from modelId
call_transfer_configCallTransferConfig[]NoPhone transfer configurations
metadataobjectNoCustom metadata

CallTransferConfig Schema​

FieldTypeRequiredDescription
transfer_numberstringYesPhone number to transfer to
transfer_typestringNo'blind' or 'warm' (default: 'warm')
transfer_conditionsstring[]YesConditions that trigger transfer

Custom Model Configuration​

By default, an agent uses the platform's managed configuration for the selected model. Two optional fields give you finer control:

  • useCustomModel — set to true to opt out of the platform's default model configuration and use only the modelId and requiredModelConfig you provide.
  • textProcessingModelId — route text processing to a separate model, distinct from the main modelId.
const agent = await client.agentConfigs.create({
  name: 'Harper',
  modelId: model.modelId,
  instructionConfigurationId: instruction.id,
  useCustomModel: true,
  requiredModelConfig: {
    voiceId: 'rachel',
    languageId: 'en-US',
    temperature: 0.7,
  },
  textProcessingModelId: 'YUSI21217J1',
});

CRUD Operations​

Create Agent Configuration​

// Get a valid modelId from the support models registry
const model = await client.supportModels.getDefaultMultiMode();

// Create instruction configuration first (see Prerequisites section)
const instruction = await client.instructionConfigs.create({
  instructionName: 'Support Agent Instructions',
  role: 'Support Agent',
  introductionMessage: 'Hello!',
  instructions: 'You are a helpful support agent.',
  guardrails: 'Be professional.',
  supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

const agent = await client.agentConfigs.create({
  name: 'Harper',
  modelId: model.modelId,
  instructionConfigurationId: instruction.id,
  defaultFunctionState: LLMType.MULTI_MODE,
  assistantType: AssistantType.GENERAL,
  metadata: { department: 'support', tier: 'premium' },
});

console.log('Created agent:', agent.id);
console.log('Agent name:', agent.name);

Get Agent Configuration​

const agent = await client.agentConfigs.get('agent_123');

console.log('Agent name:', agent.name);
console.log('Model ID:', agent.modelId);
console.log('Assistant type:', agent.assistantType);

List Agent Configurations​

const result = await client.agentConfigs.list({
  page: 1,
  pageSize: 20,
});

console.log('Total agents:', result.meta.totalCount);
result.data.forEach(agent => {
  console.log(`- ${agent.name} (${agent.id})`);
});

Update Agent Configuration​

const updated = await client.agentConfigs.update({
  id: 'agent_123',
  name: 'Riley',
  metadata: { department: 'sales', updated: true },
});

console.log('Updated name:', updated.name);

Delete Agent Configuration​

const deleted = await client.agentConfigs.delete('agent_123');

if (deleted) {
  console.log('Agent deleted successfully');
}

Agent Graph​

The agent graph is a read-only, fully hydrated view of an agent: its instruction configuration, the knowledge sources attached to that instruction, and every deployment (each paired with its channel). It is assembled server-side from the underlying resources, so there are no create or update variants — to change it, update the individual resources (agent, instruction, knowledge source, or deployment configuration).

const graph = await client.agentConfigs.getGraph('agent_123');

console.log('Agent:', graph.agent.name);
console.log('Role:', graph.instruction?.role);
console.log('Knowledge sources:', graph.knowledgeSources.length);

graph.deployments.forEach(node => {
  console.log(`Deployment ${node.deployment.id} → channel ${node.channel?.id}`);
});

Response Structure​

FieldTypeDescription
agentAgentConfigurationCore agent configuration — the root of the graph
instructionInstructionConfiguration | nullInstruction configuration (role/persona) linked to this agent
knowledgeSourcesKnowledgeSource[]Knowledge sources attached to the instruction configuration
deploymentsAgentDeploymentNode[]All deployments that use this agent, each paired with its channel

Each AgentDeploymentNode pairs a deployment with its resolved channel:

FieldTypeDescription
deploymentDeploymentConfigurationDeployment configuration using this agent
channelDeploymentChannel | nullResolved deployment channel for this deployment

Phone Agent with Call Transfer​

Configure call transfer for phone-based agents:

// Get a valid modelId from the support models registry
const model = await client.supportModels.getDefaultMultiMode();

// Create phone support instruction configuration first
const phoneInstruction = await client.instructionConfigs.create({
  instructionName: 'Phone Support Instructions',
  role: 'Phone Support Agent',
  introductionMessage: 'Thank you for calling. How can I assist you?',
  instructions: 'You are a phone support agent. Be concise and helpful.',
  guardrails: 'Transfer to human when requested or for complex issues.',
  supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

const phoneAgent = await client.agentConfigs.create({
  name: 'PhoneSupport',
  modelId: model.modelId,
  instructionConfigurationId: phoneInstruction.id,
  assistantType: AssistantType.PHONE,
  call_transfer_config: [
    {
      transfer_number: '+15551234567',
      transfer_type: 'warm',
      transfer_conditions: [
        'Customer requests human agent',
        'Issue requires supervisor approval',
        'Technical problem beyond AI capability',
      ],
    },
    {
      transfer_number: '+15559876543',
      transfer_type: 'blind',
      transfer_conditions: [
        'Billing dispute over $500',
        'Legal inquiry',
      ],
    },
  ],
});

Complete Example​

Full workflow demonstrating agent configuration lifecycle:

import { WiilClient, LLMType, AssistantType, BusinessSupportServices } from 'wiil-js';

const client = new WiilClient({
  apiKey: process.env.WIIL_API_KEY!,
});

async function manageAgentConfigurations() {
  // 1. Get a valid modelId from the support models registry
  const model = await client.supportModels.getDefaultMultiMode();
  console.log('Using model:', model.modelId);

  // 2. Create instruction configuration first
  const instruction = await client.instructionConfigs.create({
    instructionName: 'Sales Agent Instructions',
    role: 'Sales Representative',
    introductionMessage: 'Hi! I can help you find the perfect product.',
    instructions: 'You are a knowledgeable sales assistant. Help customers find products that match their needs.',
    guardrails: 'Never pressure customers. Be honest about product limitations.',
    supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
  });

  console.log('Instruction created:', instruction.id);

  // 3. Create agent configuration
  const agent = await client.agentConfigs.create({
    name: 'SalesBot',
    modelId: model.modelId,
    instructionConfigurationId: instruction.id,
    defaultFunctionState: LLMType.MULTI_MODE,
    assistantType: AssistantType.WEB,
    metadata: { department: 'sales', version: '1.0' },
  });

  console.log('Agent created:', agent.id);

  // 4. Retrieve agent by ID
  const retrieved = await client.agentConfigs.get(agent.id);
  console.log('Retrieved agent:', retrieved.name);

  // 5. List all agents
  const allAgents = await client.agentConfigs.list({ page: 1, pageSize: 50 });
  console.log('Total agents:', allAgents.meta.totalCount);

  // 6. Update agent configuration
  const updated = await client.agentConfigs.update({
    id: agent.id,
    name: 'SalesAssistant',
    metadata: { department: 'sales', version: '1.1', updated: true },
  });

  console.log('Updated agent name:', updated.name);

  // 7. Clean up - delete agent and instruction
  await client.agentConfigs.delete(agent.id);
  console.log('Agent deleted');

  await client.instructionConfigs.delete(instruction.id);
  console.log('Instruction deleted');
}

manageAgentConfigurations().catch(console.error);

Best Practices​

  1. Create instruction configurations first - Agent configurations require an instruction configuration ID. Always create the instruction before the agent.

  2. Use meaningful agent names - Names are limited to 30 characters. Choose descriptive names that indicate the agent's purpose.

  3. Match assistantType to deployment - Set the appropriate assistant type for your deployment channel:

    • PHONE for voice-based interactions
    • WEB for chat widgets
    • EMAIL for email automation
    • GENERAL for multi-channel or API-only use

  4. Configure call transfers for phone agents - When deploying phone agents, set up appropriate transfer conditions to route complex issues to human agents.

  5. Use metadata for organization - Store department, version, and other organizational data in the metadata field.

Troubleshooting​

Missing instructionConfigurationId​

Error:

WiilValidationError: instructionConfigurationId is required

Solution: Create an instruction configuration first and pass its ID:

// Get a valid modelId from the support models registry
const model = await client.supportModels.getDefaultMultiMode();

const instruction = await client.instructionConfigs.create({
  instructionName: 'My Instructions',
  role: 'Assistant',
  instructions: 'Be helpful.',
  supportedServices: [BusinessSupportServices.APPOINTMENT_MANAGEMENT],
});

const agent = await client.agentConfigs.create({
  name: 'MyAgent',
  modelId: model.modelId,
  instructionConfigurationId: instruction.id, // Required
});

Invalid modelId​

Error:

WiilAPIError: Model not found in registry

Solution: Use a valid model ID from the Wiil support models registry:

// Option 1: Get the default multi-mode model
const model = await client.supportModels.getDefaultMultiMode();
console.log('Model ID:', model.modelId);

// Option 2: List all available models
const models = await client.supportModels.list();
models.forEach(model => {
  console.log(`${model.modelId}: ${model.name}`);
});

Name Too Long​

Error:

WiilValidationError: name must be at most 30 characters

Solution: Keep agent names concise (30 characters or less):

// Bad
const agent = await client.agentConfigs.create({
  name: 'Super Advanced Customer Support AI Assistant v2',  // Too long!
  // ...
});

// Good
const agent = await client.agentConfigs.create({
  name: 'CustomerSupportAI',  // 17 characters
  // ...
});