System tools - Cartesia Docs

System tools are built-in actions configured directly on an agent. config.system_tools currently supports three slots: 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."
          }
        ]
      }
    }
  }
}

Reads return all three slots. A disabled slot is null. On PATCH:

Omit a slot to leave it unchanged.
Send null to disable it.
Send the config object to enable or update any slot settings.

An empty object enables end_call or send_dtmf with defaults. Set description to direct 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.

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