Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to AI21 Studio

Scalekit connector
Open markdown

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

Tools
8
What they doRead · write · destructive
4 · 3 · 14 read3 write1 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 AI21 Studio connection

    In AgentKit > Connections, create an AI21 Studio 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 = 'ai21'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize AI21 Studio:', 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: 'ai21_library_files_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their AI21 Studio 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
  • ai21_library_file_getGet the metadata of one library file: name, size, labels, status, public URL and dates.Read-only

    Get Library File

    Get the metadata of one library file: name, size, labels, status, public URL and dates.

    Inputs

    file_idstringrequired
    ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.
  • ai21_library_files_listList the files in your AI21 Studio library, optionally filtered by exact name, status or label.Read-only

    List Library Files

    List the files in your AI21 Studio library, optionally filtered by exact name, status or label. Returns per file its id, name, path, size, labels, status and dates. Use the ids or labels in Maestro file_search tools.

    Inputs

    labelstring
    Only files with this label (case-sensitive, exact match). Example: hr-policies.
    limitinteger
    Number of files to return, up to 1,000 (default 1,000). Example: 100.
    namestring
    Exact file name, e.g. mydoc.txt (no substring match). Example: handbook.pdf.
    offsetinteger
    Number of files to skip. Example: 0.
    statusstring
    Only files in this status. Example: PROCESSED.one of DB_RECORD_CREATEDUPLOADEDUPLOAD_FAILEDPROCESSEDPROCESSING_FAILED
  • ai21_maestro_run_getGet a Maestro run by ID.Read-only

    Get Maestro Run

    Get a Maestro run by ID. Returns its status (in_progress, completed or failed) and, when completed, the result text plus data_sources and requirements_result if requested.

    Inputs

    run_idstringrequired
    ID of the run, from ai21_maestro_run_create. Example: 4a7b2c9d-1e3f-4a5b-8c6d-7e8f9a0b1c2d.
  • ai21_chat_completion_createGenerate a chat response with an AI21 Jamba model from a list of messages, optionally grounded in documents you pass or with function tools the model may call.Write

    Create Chat Completion (Jamba)

    Generate a chat response with an AI21 Jamba model from a list of messages, optionally grounded in documents you pass or with function tools the model may call. Returns choices with the assistant message (content and any tool_calls), finish_reason and token usage. Use ai21_maestro_run_create for multi-step tasks with requirements, web or file search.

    Inputs

    messagesarrayrequired
    Conversation so far, each message an object with role (system, user, assistant or tool) and content. An optional first system message sets the tone. Example: [{"role": "user", "content": "Summarize our refund policy in two sentences."}].
    modelstringrequired
    Jamba model: jamba-large or jamba-mini (latest version of each). Example: jamba-mini.one of jamba-largejamba-mini
    documentsarray
    Documents to ground the answer in, each with content and optional metadata (a list of key/value objects). Example: [{"content": "Refunds are accepted within 30 days of purchase.", "metadata": [{"key": "title", "value": "Refund policy"}]}]
    max_tokensinteger
    Maximum tokens to generate, up to 4096. Example: 512.
    ninteger
    Number of responses to generate, 1 to 16 (temperature must be above 0 when more than 1). Example: 1.
    response_formatobject
    Set to {"type": "json_object"} to make the model reply with valid JSON. Example: {"type": "json_object"}
    stoparray
    Strings that end the response when generated. Example: ["###"]
    temperaturenumber
    Sampling temperature from 0.0 to 2.0; higher is more varied. Defaults to 0.4. Example: 0.4.
    toolsarray
    Functions the model may call, each {"type": "function", "function": {name, description, parameters}}. Example: [{"type": "function", "function": {"name": "get_order", "description": "Get an order by ID", "parameters": {"type": "object", "properties": {"order_id": {"ty...
    top_pnumber
    Nucleus sampling from 0 to 1. Defaults to 1.0. Example: 0.9.
  • ai21_library_file_updateUpdate a library file's labels or public URL.Write

    Update Library File

    Update a library file's labels or public URL. Returns no content on success.

    • Idempotent

    Inputs

    file_idstringrequired
    ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.
    labelsarray
    New labels for the file (replaces the current labels). Example: ["hr-policies", "2026"]
    public_urlstring
    Public URL of the document, shown as its source. Example: https://example.com/handbook.pdf.
  • ai21_maestro_run_createStart an AI21 Maestro run: an agent that plans and executes a task from an instruction, checks the output against your requirements and can use web search, file search over your library, HTTP tools or MCP servers.Write

    Create Maestro Run

    Start an AI21 Maestro run: an agent that plans and executes a task from an instruction, checks the output against your requirements and can use web search, file search over your library, HTTP tools or MCP servers. Returns the run with its id and status (in_progress). Poll ai21_maestro_run_get until status is completed to read the result.

    Inputs

    inputstringrequired
    The task or question for Maestro, as a plain instruction. Example: Compare the three cheapest plans on our pricing page and recommend one for a 5-person team.
    system_promptstringrequired
    High-level instruction that sets Maestro's role, context and style for the run. Example: You are a helpful analyst for Acme Corp. Today's date is 2026-11-17.
    budgetstring
    Effort: low (one step, the default), medium or high (several strategies, most thorough and costly). Example: low.one of lowmediumhigh
    includearray
    Extra output fields to include: data_sources and/or requirements_result. Example: ["data_sources", "requirements_result"]
    modelsarray
    Models Maestro may use, e.g. jamba-large, jamba-mini, gpt-4.1, claude-4-sonnet or gemini-2.5-flash. Example: ["jamba-large"]
    requirementsarray
    Up to 10 requirements the output must meet, each with name, description (up to 128 words) and optional is_mandatory. Example: [{"name": "length", "description": "Write at most 3 paragraphs", "is_mandatory": true}]
    response_languagestring
    Language of the response; detected from the input when empty. Example: english.one of arabicdutchenglishfrenchgermanhebrewitalianportuguesespanish
    toolsarray
    Tools Maestro may use, each with a type: web_search (optional urls), file_search (optional labels or file_ids), http (function and endpoint) or mcp (server_label and server_url). Example: [{"type": "web_search", "urls": ["example.com"]}]
  • ai21_library_file_deleteDelete a file from the library.Destructive

    Delete Library File

    Delete a file from the library. Files still processing cannot be deleted.

    • Idempotent

    Inputs

    file_idstringrequired
    ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.