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
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. 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>Create the AI21 Studio connection
In AgentKit > Connections, create an AI21 Studio connection. The name you give it is the
connection_nameyour code passes. See Configure connections.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.actionsconst connector = 'ai21'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'ai21_library_files_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "ai21"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize AI21 Studio:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="ai21_library_files_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach 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 toexecute_toolai21_library_file_download_link_getGet a signed URL to download a library file's contents.Read-onlyGet Library File Download Link
Get a signed URL to download a library file's contents. Returns the URL as a string.
Inputs
file_idstringrequired- ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.
ai21_library_file_getGet the metadata of one library file: name, size, labels, status, public URL and dates.Read-onlyGet 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-onlyList 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-onlyGet 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.WriteCreate 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.WriteUpdate 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.WriteCreate 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.DestructiveDelete 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.
No tools match.