Skip to main content

​
Agents

An agent defines the personality, capabilities, and behavior of your AI voice assistant. Use phone.agent() to create and validate an agent configuration.

​
Basic Agent

const agent = phone.agent({
  systemPrompt: "You are a helpful customer support agent for Acme Corp.",
  firstMessage: "Hello! How can I help you today?",
  voice: "alloy",
  model: "gpt-4o-mini-realtime-preview",
});

​
AgentOptions

ParameterTypeRequiredDefaultDescription
systemPromptstringYes—Instructions that define the agent’s persona and behavior.
voicestringNoProvider defaultVoice ID. Depends on the provider (e.g., "alloy" for OpenAI, "21m00Tcm4TlvDq8ikWAM" for ElevenLabs).
modelstringNo"gpt-4o-mini-realtime-preview"AI model identifier.
languagestringNo"en"BCP-47 language code.
firstMessagestringNo—Greeting spoken when the call connects.
toolsToolDefinition[]No—Function calling tools. See Tools.
providerstringNo"openai_realtime"AI provider mode. See Providers.
elevenlabsKeystringNo—ElevenLabs API key (required for elevenlabs_convai provider).
elevenlabsAgentIdstringNo—ElevenLabs agent ID (required for elevenlabs_convai provider).
deepgramKeystringNo—Deepgram API key (for pipeline mode STT).
sttSTTConfigNo—STT config for pipeline mode. Use Patter.deepgram() or Patter.whisper().
ttsTTSConfigNo—TTS config for pipeline mode. Use Patter.elevenlabs() or Patter.openaiTts().
variablesRecord<string, string>No—Dynamic variables for {placeholder} substitution in systemPrompt.
guardrailsGuardrail[]No—Output guardrails. See Guardrails.

​
Validation Rules

The phone.agent() method validates:
  • Provider: Must be one of "openai_realtime", "elevenlabs_convai", or "pipeline". Throws if invalid.
  • Tools: Must be an array. Each tool requires name and webhookUrl fields.
  • Variables: Must be a plain object (not an array).
// Throws: provider must be one of: openai_realtime, elevenlabs_convai, pipeline
phone.agent({
  systemPrompt: "...",
  provider: "invalid" as any,
});

// Throws: tools[0] missing required 'webhookUrl' field
phone.agent({
  systemPrompt: "...",
  tools: [{ name: "lookup", description: "Look up data", parameters: {} }] as any,
});

​
Dynamic Variables

Use {placeholder} syntax in your system prompt. Variables are replaced at call time: 
const agent = phone.agent({
  systemPrompt: "You are a support agent for {company}. The caller's name is {caller_name}.",
  variables: {
    company: "Acme Corp",
    caller_name: "John",
  },
});
Variables can also be overridden per-call when making outbound calls. See Features.

​
System Tools

Two system tools are automatically injected into every agent:
  • transfer_call — Transfers the call to a specified phone number (E.164 format).
  • end_call — Ends the current call with an optional reason.
You do not need to define these in your tools array. The AI model can invoke them based on conversation context.