Skip to main content
GET
/
api
/
v1
/
agents
/
{agent_id}
Typescript (SDK)
import { SyllableSDK } from "syllable-sdk";

const syllableSDK = new SyllableSDK({
  apiKeyHeader: process.env["SYLLABLESDK_API_KEY_HEADER"] ?? "",
});

async function run() {
  const result = await syllableSDK.agents.getById({
    agentId: 910445,
  });

  console.log(result);
}

run();
{
  "name": "<string>",
  "type": "<string>",
  "prompt_id": 123,
  "custom_message_id": 123,
  "timezone": "<string>",
  "variables": {},
  "tool_headers": {
    "some-header": "some-value"
  },
  "id": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "last_updated_by": "[email protected]",
  "description": "Agent for answering questions about weather.",
  "label": "Information",
  "labels": [
    "Information",
    "Weather"
  ],
  "language_group_id": 1,
  "prompt_tool_defaults": [
    {
      "tool_name": "<string>",
      "default_values": [
        {
          "field_name": "<string>",
          "default_value": "<unknown>"
        }
      ]
    }
  ],
  "languages": [
    "<string>"
  ],
  "agent_initiated": false,
  "stt_provider": "Google STT V2 (Chirp 2)",
  "wait_sound": "No Sound",
  "prompt": {
    "name": "<string>",
    "type": "<string>",
    "llm_config": {
      "provider": "azure_openai",
      "model": "gpt-4o",
      "version": "2024-05-13",
      "api_version": "2024-06-01",
      "temperature": 1,
      "seed": 123
    },
    "id": 123,
    "last_updated": "2024-01-01T12:00:00Z",
    "description": "Prompt for a weather agent.",
    "context": "You are a weather agent. Answer the user's questions about weather and nothing else.",
    "tools": [],
    "session_end_enabled": false,
    "session_end_tool_id": 1,
    "edit_comments": "Updated prompt text to include requirement to not answer questions that aren't about weather.",
    "last_updated_by": "[email protected]",
    "session_end_tool": {
      "name": "<string>",
      "definition": {
        "tool": {
          "function": {
            "name": "<string>",
            "description": "<string>",
            "parameters": "<unknown>"
          },
          "type": "function"
        },
        "type": "endpoint",
        "endpoint": {
          "url": "<string>",
          "method": "get",
          "argument_location": "body"
        },
        "context": {
          "task": {
            "id": "<string>",
            "config": {},
            "variables": [
              {
                "name": "<string>",
                "value": "<unknown>",
                "value_from": {
                  "expression": "<string>",
                  "type": "cel"
                },
                "type": "string",
                "description": "<string>",
                "title": "<string>",
                "format": "<string>",
                "pattern": "<string>",
                "enum": [
                  "<string>"
                ],
                "examples": [
                  "<unknown>"
                ]
              }
            ],
            "metadata": {
              "priority": 123,
              "parent_tool_name": "<string>"
            },
            "tool": {
              "name": "<string>",
              "description": "<string>"
            },
            "type": "expression",
            "version": "v1alpha",
            "inputs": [
              {
                "name": "<string>",
                "type": "string",
                "description": "<string>",
                "title": "<string>",
                "format": "<string>",
                "pattern": "<string>",
                "enum": [
                  "<string>"
                ],
                "examples": [
                  "<unknown>"
                ],
                "required": true
              }
            ],
            "expression": {
              "expression": "<string>",
              "type": "cel"
            },
            "output": "<unknown>",
            "on": {
              "start": [
                {
                  "name": "<string>",
                  "value": "<unknown>",
                  "value_from": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "if": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "action": "set"
                }
              ],
              "submit": [
                {
                  "name": "<string>",
                  "value": "<unknown>",
                  "value_from": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "if": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "action": "set"
                }
              ]
            }
          }
        },
        "defaults": "<unknown>",
        "static_parameters": [
          {
            "default": "fahrenheit",
            "description": "Whether the temperature information should be fetched in Celsius or Fahrenheit",
            "name": "temperature_unit",
            "required": false,
            "type": "string"
          }
        ],
        "result": "<unknown>",
        "options": {
          "propagate_tool_result": false
        }
      },
      "service_id": 123,
      "id": 123,
      "last_updated": "2023-11-07T05:31:56Z",
      "last_updated_by": "<string>",
      "last_updated_comments": "Updated to use new API endpoint",
      "service_name": "<string>",
      "prompts_info": [
        {
          "id": 123,
          "name": "<string>"
        }
      ],
      "agents_info": [
        {
          "id": 123,
          "name": "<string>"
        }
      ]
    },
    "agent_count": 5,
    "version_number": 1,
    "tools_full": [
      {
        "name": "<string>",
        "definition": {
          "tool": {
            "function": {
              "name": "<string>",
              "description": "<string>",
              "parameters": "<unknown>"
            },
            "type": "function"
          },
          "type": "endpoint",
          "endpoint": {
            "url": "<string>",
            "method": "get",
            "argument_location": "body"
          },
          "context": {
            "task": {
              "id": "<string>",
              "config": {},
              "variables": [
                {
                  "name": "<string>",
                  "value": "<unknown>",
                  "value_from": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "type": "string",
                  "description": "<string>",
                  "title": "<string>",
                  "format": "<string>",
                  "pattern": "<string>",
                  "enum": [
                    "<string>"
                  ],
                  "examples": [
                    "<unknown>"
                  ]
                }
              ],
              "metadata": {
                "priority": 123,
                "parent_tool_name": "<string>"
              },
              "tool": {
                "name": "<string>",
                "description": "<string>"
              },
              "type": "expression",
              "version": "v1alpha",
              "inputs": [
                {
                  "name": "<string>",
                  "type": "string",
                  "description": "<string>",
                  "title": "<string>",
                  "format": "<string>",
                  "pattern": "<string>",
                  "enum": [
                    "<string>"
                  ],
                  "examples": [
                    "<unknown>"
                  ],
                  "required": true
                }
              ],
              "expression": {
                "expression": "<string>",
                "type": "cel"
              },
              "output": "<unknown>",
              "on": {
                "start": [
                  {
                    "name": "<string>",
                    "value": "<unknown>",
                    "value_from": {
                      "expression": "<string>",
                      "type": "cel"
                    },
                    "if": {
                      "expression": "<string>",
                      "type": "cel"
                    },
                    "action": "set"
                  }
                ],
                "submit": [
                  {
                    "name": "<string>",
                    "value": "<unknown>",
                    "value_from": {
                      "expression": "<string>",
                      "type": "cel"
                    },
                    "if": {
                      "expression": "<string>",
                      "type": "cel"
                    },
                    "action": "set"
                  }
                ]
              }
            }
          },
          "defaults": "<unknown>",
          "static_parameters": [
            {
              "default": "fahrenheit",
              "description": "Whether the temperature information should be fetched in Celsius or Fahrenheit",
              "name": "temperature_unit",
              "required": false,
              "type": "string"
            }
          ],
          "result": "<unknown>",
          "options": {
            "propagate_tool_result": false
          }
        },
        "service_id": 123,
        "id": 123,
        "last_updated": "2023-11-07T05:31:56Z",
        "last_updated_by": "<string>",
        "last_updated_comments": "Updated to use new API endpoint",
        "service_name": "<string>",
        "prompts_info": [
          {
            "id": 123,
            "name": "<string>"
          }
        ],
        "agents_info": [
          {
            "id": 123,
            "name": "<string>"
          }
        ]
      }
    ]
  },
  "custom_message": {
    "name": "<string>",
    "text": "<string>",
    "id": 123,
    "updated_at": "2023-11-07T05:31:56Z",
    "last_updated_by": "<string>",
    "preamble": "If this is an emergency, please hang up and call 911.",
    "label": "Customer service",
    "rules": [],
    "agent_count": 1,
    "type": "greeting"
  },
  "channel_targets": [
    {
      "agent_id": 123,
      "channel_id": 123,
      "target": "<string>",
      "target_mode": "voice",
      "id": 123,
      "channel_name": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_updated_by": "<string>",
      "fallback_target": "+19995551235",
      "is_test": false,
      "agent": "<unknown>"
    }
  ],
  "tools": [
    {
      "name": "<string>",
      "definition": {
        "tool": {
          "function": {
            "name": "<string>",
            "description": "<string>",
            "parameters": "<unknown>"
          },
          "type": "function"
        },
        "type": "endpoint",
        "endpoint": {
          "url": "<string>",
          "method": "get",
          "argument_location": "body"
        },
        "context": {
          "task": {
            "id": "<string>",
            "config": {},
            "variables": [
              {
                "name": "<string>",
                "value": "<unknown>",
                "value_from": {
                  "expression": "<string>",
                  "type": "cel"
                },
                "type": "string",
                "description": "<string>",
                "title": "<string>",
                "format": "<string>",
                "pattern": "<string>",
                "enum": [
                  "<string>"
                ],
                "examples": [
                  "<unknown>"
                ]
              }
            ],
            "metadata": {
              "priority": 123,
              "parent_tool_name": "<string>"
            },
            "tool": {
              "name": "<string>",
              "description": "<string>"
            },
            "type": "expression",
            "version": "v1alpha",
            "inputs": [
              {
                "name": "<string>",
                "type": "string",
                "description": "<string>",
                "title": "<string>",
                "format": "<string>",
                "pattern": "<string>",
                "enum": [
                  "<string>"
                ],
                "examples": [
                  "<unknown>"
                ],
                "required": true
              }
            ],
            "expression": {
              "expression": "<string>",
              "type": "cel"
            },
            "output": "<unknown>",
            "on": {
              "start": [
                {
                  "name": "<string>",
                  "value": "<unknown>",
                  "value_from": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "if": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "action": "set"
                }
              ],
              "submit": [
                {
                  "name": "<string>",
                  "value": "<unknown>",
                  "value_from": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "if": {
                    "expression": "<string>",
                    "type": "cel"
                  },
                  "action": "set"
                }
              ]
            }
          }
        },
        "defaults": "<unknown>",
        "static_parameters": [
          {
            "default": "fahrenheit",
            "description": "Whether the temperature information should be fetched in Celsius or Fahrenheit",
            "name": "temperature_unit",
            "required": false,
            "type": "string"
          }
        ],
        "result": "<unknown>",
        "options": {
          "propagate_tool_result": false
        }
      },
      "service_id": 123,
      "id": 123,
      "last_updated": "2023-11-07T05:31:56Z",
      "last_updated_by": "<string>",
      "last_updated_comments": "Updated to use new API endpoint",
      "service_name": "<string>",
      "prompts_info": [
        {
          "id": 123,
          "name": "<string>"
        }
      ],
      "agents_info": [
        {
          "id": 123,
          "name": "<string>"
        }
      ]
    }
  ],
  "language_group": {
    "name": "<string>",
    "language_configs": [
      {
        "language_code": "yue-HK",
        "voice_provider": "OpenAI",
        "voice_display_name": "Achernar (English)",
        "dtmf_code": 123,
        "voice_speed": 1,
        "voice_pitch": 0
      }
    ],
    "skip_current_language_in_message": true,
    "id": 123,
    "updated_at": "2023-11-07T05:31:56Z",
    "last_updated_by": "<string>",
    "description": "Languages spoken by operators at Call Center 1",
    "edit_comments": "Added Spanish support.",
    "agents_info": [
      {
        "id": 1,
        "name": "Test Agent"
      }
    ]
  }
}

Authorizations

​
Syllable-API-Key
string
header
required

Path Parameters

​
agent_id
integer
required

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

Example:

"Weather agent"

​
type
string
required

The agent type. Must be "ca_v1" currently.

Example:

"ca_v1"

​
prompt_id
integer
required

ID of the prompt associated with the agent

Example:

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

Example:

1

​
timezone
string
required

The time zone in which the agent operates

Examples:

"America/New_York"

"America/Chicago"

​
variables
Variables · object
required

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

Example:
{ "vars.location_name": "Main Street Pizza" }
​
tool_headers
Tool Headers · object
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.)

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

Internal ID of the agent

Example:

1

​
updated_at
string<date-time>
required

Timestamp of most recent update

Example:

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

​
last_updated_by
string | null
required

Email of the user who last updated the agent

Example:

"[email protected]"

​
description
string | null

The agent description

Example:

"Agent for answering questions about weather."

​
label
string | null
deprecated

The agent label (DEPRECATED - use labels instead.)

Example:

"Information"

​
labels
string[] | null

The agent labels

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

Internal ID of the language group associated with the agent

Example:

1

​
prompt_tool_defaults
AgentToolDefaults · object[]

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

Example:
[
  {
    "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.)

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

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

Example:

false

​
stt_provider
string | null

Speech-to-text provider for the agent.

Example:

"Google STT V2 (Chirp 2)"

​
wait_sound
string | null

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

Example:

"No Sound"

​
prompt
PromptResponse · object

The prompt associated with the agent.

​
custom_message
CustomMessageResponse · object

The message associated with the agent. Will be delivered as a greeting at the beginning of a conversation.

​
channel_targets
ChannelTargetResponse · object[] | null

Channel targets associated with the agent

​
tools
ToolResponse · object[] | null

Tools associated with the agent

​
language_group
LanguageGroupResponse · object

The language group associated with the agent