POST
/
api
/
v1
/
agents
/
Python (SDK)
import os
from syllable_sdk import SyllableSDK, models


with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as ss_client:

    res = ss_client.agents.create(request={
        "name": "Weather agent",
        "description": "Agent for answering questions about weather.",
        "labels": [
            "Information",
            "Weather",
        ],
        "type": "ca_v1",
        "prompt_id": 1,
        "custom_message_id": 1,
        "language_group_id": 1,
        "timezone": "America/New_York",
        "prompt_tool_defaults": [
            {
                "tool_name": "get_weather",
                "default_values": [
                    {
                        "field_name": "temperature_unit",
                        "default_value": "fahrenheit",
                    },
                ],
            },
        ],
        "variables": {
            "vars.location_name": "Main Street Pizza",
        },
        "tool_headers": {
            "some-header": "some-value",
        },
        "stt_provider": models.AgentSttProvider.GOOGLE_STT_V2_CHIRP_2_,
        "wait_sound": models.AgentWaitSound.NO_SOUND,
    })

    # Handle response
    print(res)
{
  "name": "Weather agent",
  "description": "Agent for answering questions about weather.",
  "label": "Information",
  "labels": [
    "Information",
    "Weather"
  ],
  "type": "ca_v1",
  "prompt_id": 1,
  "custom_message_id": 1,
  "language_group_id": 1,
  "timezone": "America/New_York",
  "prompt_tool_defaults": [
    {
      "default_values": [
        {
          "default_value": "fahrenheit",
          "field_name": "temperature_unit"
        }
      ],
      "tool_name": "get_weather"
    }
  ],
  "languages": [
    "en-US",
    "es-US"
  ],
  "variables": {
    "vars.location_name": "Main Street Pizza"
  },
  "tool_headers": {
    "some-header": "some-value"
  },
  "agent_initiated": false,
  "stt_provider": "Google STT V2 (Chirp 2)",
  "wait_sound": "No Sound",
  "id": 1,
  "updated_at": "2024-01-01T00:00:00Z",
  "last_updated_by": "user@email.com",
  "prompt": {
    "name": "Weather Agent Prompt",
    "description": "Prompt for a weather agent.",
    "type": "prompt_v1",
    "context": "You are a weather agent. Answer the user's questions about weather and nothing else.",
    "tools": "hangup",
    "llm_config": {
      "model": "gpt-4o",
      "provider": "openai",
      "version": "2024-08-06"
    },
    "id": 1,
    "edit_comments": "Updated prompt text to include requirement to not answer questions that aren't about weather.",
    "last_updated": "2024-01-01T12:00:00Z",
    "last_updated_by": "user@email.com",
    "agent_count": 5,
    "version_number": 1,
    "tools_full": [
      {
        "name": "Weather Fetcher",
        "definition": {
          "endpoint": {
            "argument_location": "query",
            "method": "get",
            "url": "https://api.open-meteo.com/v1/forecast"
          },
          "tool": {
            "function": {
              "description": "Get the weather for a city",
              "name": "get_weather",
              "parameters": {
                "properties": {
                  "latitude": {
                    "description": "Latitude of the city",
                    "type": "number"
                  },
                  "longitude": {
                    "description": "Longitude of the city",
                    "type": "number"
                  },
                  "current": {
                    "default": "temperature_2m,relative_humidity_2m,precipitation,rain,showers",
                    "description": "Information to retrieve from the open-meteo API, comma-separated",
                    "type": "string"
                  }
                },
                "required": [
                  "latitude",
                  "longitude",
                  "current"
                ],
                "type": "object"
              }
            },
            "type": "function"
          },
          "type": "endpoint"
        },
        "service_id": 1,
        "id": 1,
        "last_updated_comments": "Updated to use new API endpoint",
        "service_name": "<string>",
        "prompts_info": [
          {
            "id": 1,
            "name": "Test Prompt"
          }
        ],
        "agents_info": [
          {
            "id": 1,
            "name": "Test Agent"
          }
        ],
        "last_updated": "2023-11-07T05:31:56Z",
        "last_updated_by": "user@email.com"
      }
    ]
  },
  "custom_message": {
    "name": "Customer service greeting",
    "text": "Hello and thank you for calling customer service. How can I help you today?",
    "label": "Customer service",
    "rules": [
      {
        "date": "2025-01-01",
        "description": "Closed on New Year's Day",
        "invert": false,
        "text": "Hello, thank you for calling. Sorry, we're closed today.",
        "time_range_end": "17:00",
        "time_range_start": "09:00"
      },
      {
        "days_of_week": [
          "sa",
          "su"
        ],
        "description": "Closed on weekends",
        "invert": false,
        "text": "Hello, thank you for calling. Sorry, we're closed on weekends.",
        "time_range_end": "17:00",
        "time_range_start": "09:00"
      }
    ],
    "id": 1,
    "updated_at": "2024-01-01T00:00:00Z",
    "agent_count": 1,
    "last_updated_by": "user@email.com",
    "type": "greeting"
  },
  "channel_targets": [
    {
      "agent_id": 1,
      "channel_id": 1,
      "target": "+19995551234",
      "target_mode": "voice",
      "fallback_target": "+19995551235",
      "is_test": true,
      "id": 1,
      "channel_name": "+19995551234",
      "updated_at": "2024-01-01T00:00:00Z",
      "last_updated_by": "user@email.com",
      "agent": {}
    }
  ],
  "tools": [
    {
      "name": "Weather Fetcher",
      "definition": {
        "endpoint": {
          "argument_location": "query",
          "method": "get",
          "url": "https://api.open-meteo.com/v1/forecast"
        },
        "tool": {
          "function": {
            "description": "Get the weather for a city",
            "name": "get_weather",
            "parameters": {
              "properties": {
                "latitude": {
                  "description": "Latitude of the city",
                  "type": "number"
                },
                "longitude": {
                  "description": "Longitude of the city",
                  "type": "number"
                },
                "current": {
                  "default": "temperature_2m,relative_humidity_2m,precipitation,rain,showers",
                  "description": "Information to retrieve from the open-meteo API, comma-separated",
                  "type": "string"
                }
              },
              "required": [
                "latitude",
                "longitude",
                "current"
              ],
              "type": "object"
            }
          },
          "type": "function"
        },
        "type": "endpoint"
      },
      "service_id": 1,
      "id": 1,
      "last_updated_comments": "Updated to use new API endpoint",
      "service_name": "<string>",
      "prompts_info": [
        {
          "id": 1,
          "name": "Test Prompt"
        }
      ],
      "agents_info": [
        {
          "id": 1,
          "name": "Test Agent"
        }
      ],
      "last_updated": "2023-11-07T05:31:56Z",
      "last_updated_by": "user@email.com"
    }
  ],
  "language_group": {
    "name": "Call Center 1 Languages",
    "description": "Languages spoken by operators at Call Center 1",
    "language_configs": [
      {
        "dtmf_code": 1,
        "language_code": "en-US",
        "voice_display_name": "Alloy",
        "voice_provider": "OpenAI"
      },
      {
        "dtmf_code": 2,
        "language_code": "es-US",
        "voice_display_name": "es-US-Neural2-B",
        "voice_provider": "Google"
      }
    ],
    "skip_current_language_in_message": true,
    "id": 1,
    "edit_comments": "Added Spanish support.",
    "agents_info": [
      {
        "id": 1,
        "name": "Test Agent"
      }
    ],
    "updated_at": "2024-01-01T00:00:00Z",
    "last_updated_by": "user@mail.com"
  }
}

Authorizations

​
Syllable-API-Key
string
header
required

Body

application/json

Request model to create an agent.

​
name
string
required

The agent name

Examples:

"Weather agent"

​
type
string
required

The agent type. Must be "ca_v1" currently.

Examples:

"ca_v1"

​
prompt_id
integer
required

ID of the prompt associated with the agent

Examples:

1

​
custom_message_id
integer
required

Internal ID of the custom message that should be delivered at the beginning of a conversation with the agent

Examples:

1

​
timezone
string
required

The time zone in which the agent operates

Examples:

"America/New_York"

"America/Chicago"

​
variables
object
required

Custom context variables for the conversation session. Keys should be prefixed with "vars.".

Examples:
{ "vars.location_name": "Main Street Pizza" }
​
tool_headers
object | null
required

Optional headers to include in tool calls for agent. (It is discouraged to use this field for "Authorization" headers, as values here are not encrypted. Instead, set up a service with either basic, bearer, or custom header auth; attach the appropriate tools to that service, and the attached tools will automatically use the auth configured on the service.)

Examples:
{ "some-header": "some-value" }
​
description
string | null

The agent description

Examples:

"Agent for answering questions about weather."

​
label
string | null
deprecated

The agent label (DEPRECATED - use labels instead.)

Examples:

"Information"

​
labels
string[] | null

The agent labels

Examples:
["Information", "Weather"]
​
language_group_id
integer | null

Internal ID of the language group associated with the agent

Examples:

1

​
prompt_tool_defaults
AgentToolDefaults · object[]

Agent-level static parameter values for the agent's tools, overriding any tool-level defaults

Examples:
[
  {
    "default_values": [
      {
        "default_value": "fahrenheit",
        "field_name": "temperature_unit"
      }
    ],
    "tool_name": "get_weather"
  }
]
​
languages
string[]
deprecated

BCP 47 codes of languages the agent supports. (DEPRECATED - pass an empty list here and use language group ID to link agent to a language group instead.)

Examples:
["en-US", "es-US"]
​
agent_initiated
boolean
default:false

Whether the agent initiates conversation with a user after the custom message is delivered

Examples:

false

​
stt_provider
enum<string> | null

Speech-to-text provider for the agent. Speech-to-text providers supported by agents.

Available options:
Google STT V2 (Chirp 2),
Deepgram Nova 3,
Google STT V2,
Google STT V1,
Deepgram Nova 2
Examples:

"Google STT V2 (Chirp 2)"

"Deepgram Nova 3"

"Google STT V2"

"Google STT V1"

"Deepgram Nova 2"

​
wait_sound
enum<string> | null

Sound to play while waiting for a response from the LLM. Wait sounds supported by agents.

Available options:
No Sound,
Keyboard 1,
Keyboard 2,
Call Center
Examples:

"No Sound"

"Keyboard 1"

"Keyboard 2"

"Call Center"

Response

Successful Response

Response model for agent operations. When a user interacts with the Syllable system, they do so by communicating with an agent. An agent is linked to a prompt, a custom message, and one or more channel targets to define its behavior and capabilities. For more information, see Console docs.

​
name
string
required

The agent name

Examples:

"Weather agent"

​
type
string
required

The agent type. Must be "ca_v1" currently.

Examples:

"ca_v1"

​
prompt_id
integer
required

ID of the prompt associated with the agent

Examples:

1

​
custom_message_id
integer
required

Internal ID of the custom message that should be delivered at the beginning of a conversation with the agent

Examples:

1

​
timezone
string
required

The time zone in which the agent operates

Examples:

"America/New_York"

"America/Chicago"

​
variables
object
required

Custom context variables for the conversation session. Keys should be prefixed with "vars.".

Examples:
{ "vars.location_name": "Main Street Pizza" }
​
tool_headers
object | null
required

Optional headers to include in tool calls for agent. (It is discouraged to use this field for "Authorization" headers, as values here are not encrypted. Instead, set up a service with either basic, bearer, or custom header auth; attach the appropriate tools to that service, and the attached tools will automatically use the auth configured on the service.)

Examples:
{ "some-header": "some-value" }
​
id
integer
required

Internal ID of the agent

Examples:

1

​
updated_at
string<date-time>
required

Timestamp of most recent update

Examples:

"2024-01-01T00:00:00Z"

​
last_updated_by
string | null
required

Email of the user who last updated the agent

Examples:

"user@email.com"

​
description
string | null

The agent description

Examples:

"Agent for answering questions about weather."

​
label
string | null
deprecated

The agent label (DEPRECATED - use labels instead.)

Examples:

"Information"

​
labels
string[] | null

The agent labels

Examples:
["Information", "Weather"]
​
language_group_id
integer | null

Internal ID of the language group associated with the agent

Examples:

1

​
prompt_tool_defaults
AgentToolDefaults · object[]

Agent-level static parameter values for the agent's tools, overriding any tool-level defaults

Examples:
[
  {
    "default_values": [
      {
        "default_value": "fahrenheit",
        "field_name": "temperature_unit"
      }
    ],
    "tool_name": "get_weather"
  }
]
​
languages
string[]
deprecated

BCP 47 codes of languages the agent supports. (DEPRECATED - pass an empty list here and use language group ID to link agent to a language group instead.)

Examples:
["en-US", "es-US"]
​
agent_initiated
boolean
default:false

Whether the agent initiates conversation with a user after the custom_message is delivered

Examples:

false

​
stt_provider
string | null

Speech-to-text provider for the agent.

Examples:

"Google STT V2 (Chirp 2)"

"Deepgram Nova 3"

"Google STT V2"

"Google STT V1"

"Deepgram Nova 2"

​
wait_sound
string | null

Sound to play while waiting for a response from the LLM.

Examples:

"No Sound"

"Keyboard 1"

"Keyboard 2"

"Call Center"

​
prompt
object | null

The prompt associated with the agent. Response model for prompt operations. A prompt defines the behavior of an agent by delivering instructions to the LLM about how the agent should behave. A prompt can be linked to one or more agents. A prompt can also be linked to tools to allow an agent using it to use those tools. For more information, see Console docs.

​
custom_message
object | null

The message associated with the agent. Will be delivered as a greeting at the beginning of a conversation. Response model for custom message operations. A custom message is a pre-configured message delivered by an agent as a greeting at the beginning of a conversation. Multiple agents can use the same custom mesasage. A custom message has one or more rules defined, which allow for different messages to be dynamically selected and delivered at runtime based on the current time and either date or day of the week. For more information, see Console docs.

​
channel_targets
ChannelTargetResponse · object[] | null

Channel targets associated with the agent

​
tools
ToolResponse · object[] | null

Tools associated with the agent

​
language_group
object | null

The language group associated with the agent Response model for language group operations. A language group is a collection of language, voice, and DTMF configuration that can be linked to an agent to define the languages and voices it supports. For more information, see Console docs.