Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Cartesia

Scalekit connector
Open markdown

The Cartesia connector lets your AI agent act in each user's Cartesia account. Each user connects their own Cartesia access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 39 tools.

Tools
39
What they doRead · write · destructive
30 · 6 · 330 read6 write3 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Cartesia connection

    In AgentKit > Connections, create a Cartesia connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'cartesia'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Cartesia:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'cartesia_accents_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Cartesia credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • cartesia_accents_listList the accents Cartesia supports, optionally filtered by language, locale, or whether a voice can be localized into them.Read-only

    List Accents

    List the accents Cartesia supports, optionally filtered by language, locale, or whether a voice can be localized into them. Returns accents, each with id, name, language, locale, is_locale_default and is_localizable. Use this to find a valid accent id for cartesia_voice_update or cartesia_voice_localize (localize needs is_localizable true).

    Inputs

    is_localizableboolean
    Set to true to return only accents a voice can be localized into with cartesia_voice_localize. Example: true
    languagestring
    Return only accents of this ISO 639-1 language code. Example: es
    localestring
    Return only accents of this BCP-47 locale. Example: es-MX
  • cartesia_agent_getGet one Managed Agent with its complete current configuration.Read-only

    Get Agent

    Get one Managed Agent with its complete current configuration. Returns id, name, description, version, created_at, updated_at and config (instructions, initial_message, audio, model, language, tools, system_tools, turn and other settings). Use this to read an agent's prompt, voice and model before changing it with cartesia_agent_update. Use cartesia_agent_versions_list for its change history.

    Inputs

    agent_idstringrequired
    ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
  • cartesia_agent_models_listList the LLMs available to Cartesia Managed Agents, with latency and pricing metadata.Read-only

    List Agent Models

    List the LLMs available to Cartesia Managed Agents, with latency and pricing metadata. Returns data (each model's id, display_name, provider, description, average_latency_ms and per-million-token pricing), has_more and next_page. Use this to choose the model_id for cartesia_agent_create or cartesia_agent_update. Use cartesia_models_list for speech (TTS/STT) models.

    Inputs

    ending_beforestring
    Pagination cursor: the ID of the first model on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: gpt-5.4-mini
    limitinteger
    Number of models to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
    starting_afterstring
    Pagination cursor: the ID of the last model on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: gpt-5.4-mini
  • cartesia_agent_tool_getGet one shared agent tool (webhook or client) with its full definition.Read-only

    Get Agent Tool

    Get one shared agent tool (webhook or client) with its full definition. Returns id, name, description, type, execution settings, and the webhook api_schema or client parameters; with expand agents, also the agents that use it. Use this to inspect what a tool does before attaching it to an agent. Use cartesia_agent_tools_list to find tool IDs.

    Inputs

    tool_idstringrequired
    ID of the agent tool. Get it from cartesia_agent_tools_list. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
    expandarray
    Extra data to include. The only value is agents, which adds the agents that currently use the tool. Example: ["agents"]
  • cartesia_agent_tools_listList the shared webhook and client tools that Managed Agents in your account can call, optionally filtered by type or agent.Read-only

    List Agent Tools

    List the shared webhook and client tools that Managed Agents in your account can call, optionally filtered by type or agent. Returns data (tools with id, name, description, type and settings), has_more and next_page. Use this to find a tool ID to reference in an agent's config.tools. Use cartesia_agent_tool_get for one tool's full definition.

    Inputs

    agent_idstring
    Return only tools used by this agent, from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
    ending_beforestring
    Pagination cursor: the ID of the first tool on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
    limitinteger
    Number of tools to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
    starting_afterstring
    Pagination cursor: the ID of the last tool on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
    typestring
    Return only webhook tools or client tools. Example: webhookone of webhookclient
  • cartesia_agent_version_getGet one immutable configuration version of an agent.Read-only

    Get Agent Version

    Get one immutable configuration version of an agent. Returns id, description, created_at, created_by and the complete config of that version. Use this to compare or restore an older configuration: pass its config to cartesia_agent_update to roll back. Use cartesia_agent_get for the current configuration.

    Inputs

    agent_idstringrequired
    ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
    version_idstringrequired
    ID of the agent configuration version. Get it from cartesia_agent_versions_list. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
  • cartesia_agent_versions_listList an agent's configuration history, newest first.Read-only

    List Agent Versions

    List an agent's configuration history, newest first. Each version is an immutable snapshot of the full configuration. Returns data (versions with id, description, created_at and created_by), has_more and next_page. Use this to audit or roll back agent changes. Use cartesia_agent_version_get for one version's full config.

    Inputs

    agent_idstringrequired
    ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
    ending_beforestring
    Pagination cursor: the ID of the first version on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
    limitinteger
    Number of versions to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
    starting_afterstring
    Pagination cursor: the ID of the last version on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
  • cartesia_agents_listList the Managed Agents in your Cartesia account, optionally searching by name or description.Read-only

    List Agents

    List the Managed Agents in your Cartesia account, optionally searching by name or description. Returns data (agent summaries with id, name, description and timestamps; full configuration is left out), has_more and next_page. Use this to find an agent_id. Use cartesia_agent_get for one agent's full configuration.

    Inputs

    ending_beforestring
    Pagination cursor: the ID of the first agent on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
    limitinteger
    Number of agents to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
    qstring
    Text to match against agent name or description. Example: receptionist
    starting_afterstring
    Pagination cursor: the ID of the last agent on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE