Claude Agent SDK

What you'll buildCopy Anchor Link

A Claude agent that texts a test number with VoiceLayer's message_send tool, then answers a simulated incoming text from your own process. You use @voicelayer/agents/claude, which gives the Claude Agent SDK the VoiceLayer channel tools over MCP. It adds no tools of its own, so they are the same in every framework.

PrerequisitesCopy Anchor Link

• Node.js 22 or later, and TypeScript 5.2 or later if you compile your own (the examples run with tsx). The examples are ES modules with top-level await, and use await using, which closes a connection when the file ends (TypeScript 5.2 or later with esnext.disposable in lib; or close it yourself with await tools[Symbol.asyncDispose]()).
• A test key in VOICELAYER_API_KEY (vl_test_…): see Authentication and API keys. With a test key every send goes to a simulated carrier and costs nothing.
• An Anthropic API key in ANTHROPIC_API_KEY.
• No phone number needed: with a test key, your workspace's free test sender stands in for one.

InstallCopy Anchor Link

npm install @voicelayer/agents @anthropic-ai/[email protected]

Set the keys once. VoiceLayer's helpers read VOICELAYER_API_KEY themselves, so no example passes a key:

export VOICELAYER_API_KEY=vl_test_...
export ANTHROPIC_API_KEY=...
npm pkg set type=module

Give your agent VoiceLayer's toolsCopy Anchor Link

Save this as agent.ts.

import { query } from '@anthropic-ai/claude-agent-sdk';
import { voicelayerMcp } from '@voicelayer/agents/claude';

// VoiceLayer's tools and none of Claude Code's own (files, shell, web): this agent only talks.
const options = { ...voicelayerMcp(), tools: [], systemPrompt: 'You answer customers in one short sentence.' };

for await (const message of query({ prompt: 'Text "Hello from VoiceLayer" to +15550101 over sms.', options })) {
  if (message.type === 'result') console.log(message.subtype === 'success' ? message.result : `Stopped: ${message.subtype}`);
}

• voicelayerMcp() returns options for query(): the VoiceLayer MCP server and the list of its tools Claude may use without a permission prompt.
• tools: [] removes Claude Code's built-in file, shell and web tools: this agent only talks.
• query() asks Claude to text +15550101, a reserved test number. Claude calls mcp__voicelayer__message_send.

Run it:

npx --yes tsx agent.ts

The agent texts the test number and prints its answer.

Answer incoming messagesCopy Anchor Link

Direct mode: your process answers the conversations VoiceLayer hands to code. Save this as serve.ts.

import { serveDirect } from '@voicelayer/agents/claude';

await serveDirect({ tools: [], systemPrompt: 'You answer customers in one short sentence.' });

serveDirect(options) answers incoming messages: each message in a conversation your code controls becomes one Claude turn, and the reply is sent back in that conversation. It keeps running until you stop the process. To let Claude use VoiceLayer's tools while it answers, spread ...voicelayerMcp() into the options.

npx --yes tsx serve.ts

voicelayer: answering incoming messages (Ctrl+C to stop)

Test it without a personCopy Anchor Link

With the server from the last step running, open a second terminal and simulate a person texting you. Save this as simulate.ts.

import { simulateInbound } from '@voicelayer/agents';

const { conversationId } = await simulateInbound({ text: 'What are your opening hours?' });
console.log(`Simulated a text from +15550101 in conversation ${conversationId}`);

npx --yes tsx simulate.ts

The first terminal prints voicelayer: replied in conversation …. Open Conversations in the dashboard and turn on test conversations to see the text and the reply. Both went to the simulated carrier.

Direct mode answers conversations your code controls (api). A new workspace's free test sender is yours by default; if the number you use has an agent that answers texts, hand the conversation to your code first.

To answer real people, swap the test key for a live key. Nothing else changes.

Handle errorsCopy Anchor Link

A missing key stops the program at start with a message that names VOICELAYER_API_KEY. A wrong key, or anything else the API refuses, comes back as an error with a stable code:

If the first terminal never prints a reply, the conversation is answered by your workspace's agent, not by your code. See Hand off a conversation.

Next stepsCopy Anchor Link

• The MCP tools: what each tool does and which scope it needs.
• Test mode: more ways to simulate people.
• Python frameworks: the same setup in Python.