Build an AI Agent with TypeScript
How to Build a TypeScript AI Voice Agent Using the Syllable SDK
Getting Started
Building your first voice agent in TypeScript on the Syllable SDK is quick, easy and gives you the power to scale. In this guide, we'll walk through how to spin up an intelligent agent in just a few minutes using TypeScript.
The SDK gives developers full control over the agent-building process, from defining behavior and personality to connecting live data sources and external tools.
Table of Contents
Why use the SDK?
1. Environment Setup
2. Create a Prompt
3. Add a Data Source
4. Define Tools
5. Create a Message
6. Assemble Your Agent
7. Test and Iterate
What's Next
Why Use the TypeScript SDK?
If you've explored the Syllable Console, you know how easy it is to configure agents in a no-code environment. The TypeScript SDK offers the same power, but with full developer flexibility:
Automate agent creation and updates programmatically
Define prompts, tools, and messages entirely in code
Integrate seamlessly with your existing infrastructure and CI/CD pipelines
Leverage TypeScript's type safety and modern patterns
In short, the SDK is ideal if you're building deeply integrated systems and need the power of programmatic control. Docs: Visit the TypeScript SDK on GitHub.
1. Environment Setup
Before you begin, make sure you have:
Node.js v18 or later installed
Reviewed the environment setup guide and obtained a Syllable API token
Note: You can access your Syllable API key in the Syllable Console under your Profile -> API tokens
Install the SDK with npm:
npm install syllable-sdk
2. Create a Prompt
Prompts are the heart of every Syllable agent. They define the agent's personality, capabilities, and boundaries using natural language. The prompt tells the LLM exactly who the agent is, what it should do, and what it must never do.
Docs: Working with Prompts
import { SyllableSDK } from 'syllable-sdk';
import { PromptLlmProvider } from 'syllable-sdk/models/components/index.js';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const prompt = await syllableSDK.prompts.create({
name: 'Tutorial Weather Prompt',
description: 'Prompt for a weather agent',
type: 'prompt_v1',
context: `You are a weather agent. You can tell the user information about the current
weather in a given city, and also answer general weather-related questions.
When asked about any other topic, don't answer and instead remind the caller that
you are a weather agent. Keep the tone professional, friendly, and clear.
You are chatting with a user, so always respond naturally and conversationally.
Do not use nonverbal cues, describe system actions, or add any other information.`,
tools: [],
llmConfig: {
provider: PromptLlmProvider.Openai,
model: 'gpt-5.2',
version: '2025-12-11',
apiVersion: null,
},
includeDefaultTools: false,
});
console.log(prompt);
Note: Save the prompt ID returned in the console - you will need it later.
3. Add a Data Source
A data source allows your agent to access static information - for example, a glossary of meteorological terms or FAQs. We'll create a short weather facts data source for this tutorial.
Docs: Data Sources
import { SyllableSDK } from 'syllable-sdk';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const dataSource = await syllableSDK.dataSources.create({
name: 'tutorial_weather_facts',
description: 'General information about weather',
text: `The following are some general facts about weather.
1. Types of Weather
Sunny: Clear skies with abundant sunshine.
Rainy: Precipitation in the form of rain, occurring when moisture-laden clouds condense.
Snowy: Frozen precipitation forms snowflakes when temperatures are below freezing.
Windy: Strong winds caused by pressure differences in the atmosphere.
Cloudy: Overcast skies with various cloud formations.
Stormy: Thunderstorms, hurricanes, or tornadoes characterized by severe conditions.
2. Weather Symbols
Weather maps use symbols to represent conditions:
Sun: Clear skies. Cloud: Overcast. Raindrops: Rain. Snowflake: Snow.`,
chunk: false,
chunkDelimiter: null,
});
console.log(dataSource);
Note: The name tutorial_weather_facts is referenced later in the tool definition - keep it exactly as shown.
4. Define Tools
Tools let your agent call external APIs or look up information in a data source. We'll create two tools: one to query our weather facts data source, and one to fetch real-time weather from the Open-Meteo API.
Docs: Define a Tool
Step 4a - Create a Service
Tools must belong to a service. Create a service first, then note its ID.
import { SyllableSDK } from 'syllable-sdk';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const service = await syllableSDK.services.create({
name: 'Tutorial Weather Service',
description: 'Service for weather information',
});
console.log(service);
Note: Save the service ID - you'll pass it to both tool definitions.
Step 4b - Create the Data Source Tool
This tool queries Helix, Syllable's document search service, using the weather facts data source as its knowledge base.
import { SyllableSDK } from 'syllable-sdk';
import { StaticToolParameterType, ToolArgumentLocation, ToolHttpMethod, Type }
from 'syllable-sdk/models/components/index.js';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const generalWeatherInfoTool = await syllableSDK.tools.create({
name: 'tutorial_general_weather_information',
serviceId: yourServiceIdHere,
definition: {
type: Type.Endpoint,
endpoint: {
url: 'http://helix-app/v1/search',
method: ToolHttpMethod.Post,
argumentLocation: ToolArgumentLocation.Body,
},
tool: {
type: 'function',
function: {
name: 'tutorial_general_weather_information',
description: 'Look up general weather information from data sources.',
parameters: {
type: 'object',
required: ['question'],
properties: {
question: {
type: 'string',
description: 'A user inquiry about weather content.',
},
},
},
},
},
staticParameters: [
{
name: 'doc',
description: 'Data sources to which the tool should have access.',
required: true,
type: StaticToolParameterType.DataSourceList,
default: ['tutorial_weather_facts'],
},
],
},
});
console.log(generalWeatherInfoTool);
Note: Save the tool ID.
Step 4c - Create the Real-Time Weather Tool
This tool calls the Open-Meteo API to return live weather data for any city, using latitude and longitude as inputs.
import { SyllableSDK } from 'syllable-sdk';
import { StaticToolParameterType, ToolArgumentLocation, ToolHttpMethod, Type }
from 'syllable-sdk/models/components/index.js';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const realTimeWeatherTool = await syllableSDK.tools.create({
name: 'tutorial_get_weather',
serviceId: yourServiceIdHere,
definition: {
type: Type.Endpoint,
endpoint: {
url: 'https://api.open-meteo.com/v1/forecast',
method: ToolHttpMethod.Get,
argumentLocation: ToolArgumentLocation.Query,
},
tool: {
type: 'function',
function: {
name: 'tutorial_get_weather',
description: 'Get the weather for a city.',
parameters: {
type: 'object',
properties: {
longitude: { type: 'number', description: 'The longitude of the city.' },
latitude: { type: 'number', description: 'The latitude of the city.' },
},
required: ['longitude', 'latitude'],
},
},
},
staticParameters: [
{
name: 'current',
description: 'Information to retrieve from the Open-Meteo API, comma-separated.',
required: true,
type: StaticToolParameterType.String,
default: 'temperature_2m,relative_humidity_2m,precipitation,rain,showers,snowfall',
},
],
},
});
console.log(realTimeWeatherTool);
Note: Save this tool ID as well.
Step 4d - Update the Prompt to Include the Tools
Now update the prompt you created in Step 2 to add the two new tools and expand the context with instructions for when to call each one.
import { SyllableSDK } from 'syllable-sdk';
import { PromptLlmProvider } from 'syllable-sdk/models/components/index.js';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const updatedPrompt = await syllableSDK.prompts.update({
id: yourPromptIdHere,
name: 'Tutorial Weather Prompt',
description: 'Prompt for a weather agent',
type: 'prompt_v1',
context: `You are a weather agent. You can tell the user information about the current
weather in a given city, and also answer general weather-related questions.
When asked about information for a city, call "tutorial_get_weather" with the city
information (longitude and latitude). Reply with the current temperature and relative
humidity. Using the response, tell the caller the weather conditions in one simple
sentence, like "sunny" or "rainy." If you can't determine the coordinates, ask for
more information.
When asked a general weather question, call "tutorial_general_weather_information"
with the user's question.
When asked about any other topic, remind the caller you are a weather agent.
Keep the tone professional, friendly, and clear.`,
tools: ['tutorial_general_weather_information', 'tutorial_get_weather'],
llmConfig: {
provider: PromptLlmProvider.Openai,
model: 'gpt-5.2',
version: '2025-12-11',
apiVersion: null,
},
includeDefaultTools: false,
});
console.log(updatedPrompt);
5. Create a Message
A message is what your agent says first when a call or chat begins. You can tailor greetings by time of day, day of week, or campaign. For this tutorial we'll create a simple, friendly opener.
Docs: Create a Message
import { SyllableSDK } from 'syllable-sdk';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const message = await syllableSDK.customMessages.create({
name: 'Tutorial Weather Greeting',
text: "Hello! I'm a weather agent. I can tell you the current weather in any city, " +
"or answer general questions about weather. What would you like to know?",
rules: [],
});
console.log(message);
Note: Save the message ID - you'll need it in the next step.
6. Assemble Your Agent
With all the pieces ready - prompt, data source, tools, and message - it's time to put it all together and create the agent.
Docs: Assemble Your Agent
import { SyllableSDK } from 'syllable-sdk';
import { AgentSttProvider, AgentWaitSound }
from 'syllable-sdk/models/components/index.js';
const syllableSDK = new SyllableSDK({
apiKeyHeader: 'your_key_here',
});
const agent = await syllableSDK.agents.create({
name: 'Tutorial Weather Agent',
description: 'An agent that can answer questions about the weather',
type: 'ca_v1',
promptId: yourPromptIdHere,
customMessageId: yourMessageIdHere,
timezone: 'America/Los_Angeles',
sttProvider: AgentSttProvider.GoogleSTTV2,
waitSound: AgentWaitSound.Keyboard1,
toolHeaders: null,
variables: {},
});
console.log(agent);
7. Test and Iterate
Your agent is live immediately after creation. The best way to test it is in the Syllable Console - click Agents, find your agent, and use the built-in test conversation window to chat or call it directly.
With the TypeScript SDK you can:
Update your agent's behavior programmatically and redeploy instantly
Integrate with call routing or embed onto a web site
Because everything lives in code, your agents can evolve alongside your product through the same pull-request and review workflow as the rest of your codebase.
What's Next
Find the TypeScript Agents SDK Documentation on GitHub
Add more tools and connect real-time systems to your agent
Build a pipeline to programmatically manage multiple agents at scale
Explore channel targets to give your agent a real phone number
If you're ready to build production-ready AI agents at scale, the TypeScript SDK is your best friend. Start simple, iterate quickly, and ship powerful experiences.
Sign up or log in to get your API key and start building today.
Check out our demo agents
Take a look at how our agents work in real-world business use cases.