System tools - Cartesia Docs

Cartesia provides and runs system tools; you choose which ones to enable and configure on the agent. config.system_tools currently supports three tools: end_call, send_dtmf, and transfer_to_number.

Tools page in the Playground with End call, Send keypad tones, and Transfer call toggles — Turn system tools on from the Tools page in the Playground.

{
  "config": {
    "system_tools": {
      "end_call": {
        "description": "End the call after the caller explicitly says goodbye.",
        "pre_tool_speech": "force"
      },
      "send_dtmf": null,
      "transfer_to_number": {
        "description": null,
        "pre_tool_speech": "auto",
        "transfers": [
          {
            "destination": {
              "type": "phone",
              "phone_number": "+14155550100"
            },
            "condition": "The caller asks to speak with billing."
          }
        ]
      }
    }
  }
}

Agent responses include all three system tools, with disabled tools set to null. In config.system_tools for a PATCH request:

Omit the tool to leave its current setting unchanged.
Send null to disable the tool.
Send the config object to enable or update any tool settings.

For end_call and send_dtmf, {} enables the tool with defaults; it does not leave the current setting unchanged. We generally recommend you keep the default description for the tool, which is optimized for our system, but for more control, you can set description to direct how and when the model should invoke the tool. For example, require an explicit goodbye before ending a call or prevent the agent from hanging up when it reaches voicemail. Set it to null to use the built-in description. pre_tool_speech controls whether the agent speaks before acting. auto lets the agent decide, force asks it to speak first, and off doesn’t ask it to.

End call

Allows the agent to end a call when the conversation is complete or the caller asks to hang up.

Send DTMF

Allows the agent to send one or more keypad tones, such as 12#, while navigating a phone menu. Supported tones are 0 through 9, *, and #.

Transfer to number

Transfers a phone call to a configured destination. For each destination, provide a phone number in E.164 format, such as +14155550123, a SIP URI such as sip:user@host, or a dynamic variable such as {{transfer_number}}. Add a condition that tells the model when to use it. Set the destinations with Update agent, using your agent ID:

PATCH /v1/agents/{agent_id}

{
  "config": {
    "system_tools": {
      "transfer_to_number": {
        "transfers": [
          {
            "destination": { "type": "phone", "phone_number": "+14155550100" },
            "condition": "The caller has a billing or payment question."
          },
          {
            "destination": { "type": "sip_uri", "sip_uri": "sip:user@host" },
            "condition": "The caller reports a technical problem with their device."
          },
          {
            "destination": { "type": "phone", "phone_number": "{{transfer_number}}" },
            "condition": "The caller asks for a person and no other destination applies."
          }
        ]
      }
    }
  }
}

Supply dynamic variables such as transfer_number in the outbound call request or through a webhook assignment. A variable used as a phone destination must contain a valid E.164 number when the transfer runs. Conditions and tool descriptions also support dynamic variables. In the Playground, open Tools, enable Transfer call, and choose Phone number, SIP URI, or Dynamic variable for each rule’s Destination. Set type to "sip_uri" and provide sip_uri in the form sip:user@host or sips:user@host, using a lowercase scheme and including both a user and a host. The sip_uri can also be a single dynamic variable, such as {{sip_uri}}, whose value is the complete SIP URI when the transfer runs. Variables inside a URI, such as sip:{{user}}@host, are not supported. In the Playground, choose Dynamic variable for the rule’s Destination and set Destination type to SIP URI.

Transfers require a Twilio or SIP-trunked phone call; SIP URI destinations require SIP trunking. On Playground and v1 WebSocket calls, the tool returns an error instead of transferring the call.

​End call

​Send DTMF

​Transfer to number

End call

Send DTMF

Transfer to number