> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to AI21 Studio

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.

**Authentication:** Bearer Token
**Categories:** AI
**Tools:** 8: 4 read, 3 write, 1 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=AI21)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".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](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   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)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_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.actions

   connection_name = "ai21"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_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 call
   result = actions.execute_tool(
       tool_input={},
       tool_name="ai21_library_files_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their AI21 Studio credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'ai21_library_file_download_link_get',
  toolInput: {
    file_id: '<file_id>',
  },
  connector: 'ai21',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="ai21_library_file_download_link_get",
    tool_input={
        "file_id": "<file_id>",
    },
    connection_name="ai21",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `ai21_library_file_download_link_get`

Get Library File Download Link · Read-only

Get a signed URL to download a library file's contents. Returns the URL as a string.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `file_id` (`string`, required): ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.

Example input: `{"file_id":"<file_id>"}`

### `ai21_library_file_get`

Get Library File · Read-only

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

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `file_id` (`string`, required): ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.

Example input: `{"file_id":"<file_id>"}`

### `ai21_library_files_list`

List Library Files · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `label` (`string`, optional): Only files with this label (case-sensitive, exact match). Example: hr-policies.
- `limit` (`integer`, optional): Number of files to return, up to 1,000 (default 1,000). Example: 100.
- `name` (`string`, optional): Exact file name, e.g. mydoc.txt (no substring match). Example: handbook.pdf.
- `offset` (`integer`, optional): Number of files to skip. Example: 0.
- `status` (`string`, optional): Only files in this status. Example: PROCESSED. One of: `DB_RECORD_CREATED`, `UPLOADED`, `UPLOAD_FAILED`, `PROCESSED`, `PROCESSING_FAILED`.

Example input: `{}`

### `ai21_maestro_run_get`

Get Maestro Run · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `run_id` (`string`, required): ID of the run, from ai21_maestro_run_create. Example: 4a7b2c9d-1e3f-4a5b-8c6d-7e8f9a0b1c2d.

Example input: `{"run_id":"<run_id>"}`

### `ai21_chat_completion_create`

Create Chat Completion (Jamba) · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `messages` (`array`, required): 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."}].
- `model` (`string`, required): Jamba model: jamba-large or jamba-mini (latest version of each). Example: jamba-mini. One of: `jamba-large`, `jamba-mini`.
- `documents` (`array`, optional): 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_tokens` (`integer`, optional): Maximum tokens to generate, up to 4096. Example: 512.
- `n` (`integer`, optional): Number of responses to generate, 1 to 16 (temperature must be above 0 when more than 1). Example: 1.
- `response_format` (`object`, optional): Set to {"type": "json_object"} to make the model reply with valid JSON. Example: {"type": "json_object"}
- `stop` (`array`, optional): Strings that end the response when generated. Example: ["###"]
- `temperature` (`number`, optional): Sampling temperature from 0.0 to 2.0; higher is more varied. Defaults to 0.4. Example: 0.4.
- `tools` (`array`, optional): 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_p` (`number`, optional): Nucleus sampling from 0 to 1. Defaults to 1.0. Example: 0.9.

Example input: `{"messages":[{"role":"user","content":"Summarize our refund policy in two sentences."}],"model":"jamba-large"}`

### `ai21_library_file_update`

Update Library File · Write

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

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `file_id` (`string`, required): ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.
- `labels` (`array`, optional): New labels for the file (replaces the current labels). Example: ["hr-policies", "2026"]
- `public_url` (`string`, optional): Public URL of the document, shown as its source. Example: https://example.com/handbook.pdf.

Example input: `{"file_id":"<file_id>"}`

### `ai21_maestro_run_create`

Create Maestro Run · Write

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.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `input` (`string`, required): 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_prompt` (`string`, required): 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.
- `budget` (`string`, optional): Effort: low (one step, the default), medium or high (several strategies, most thorough and costly). Example: low. One of: `low`, `medium`, `high`.
- `include` (`array`, optional): Extra output fields to include: data_sources and/or requirements_result. Example: ["data_sources", "requirements_result"]
- `models` (`array`, optional): Models Maestro may use, e.g. jamba-large, jamba-mini, gpt-4.1, claude-4-sonnet or gemini-2.5-flash. Example: ["jamba-large"]
- `requirements` (`array`, optional): 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_language` (`string`, optional): Language of the response; detected from the input when empty. Example: english. One of: `arabic`, `dutch`, `english`, `french`, `german`, `hebrew`, `italian`, `portuguese`, `spanish`.
- `tools` (`array`, optional): 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"]}]

Example input: `{"input":"<input>","system_prompt":"<system_prompt>"}`

### `ai21_library_file_delete`

Delete Library File · Destructive

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

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `file_id` (`string`, required): ID of the file in the library, from ai21_library_files_list. Example: 8f3c2b1a-4d5e-6f70-8192-a3b4c5d6e7f8.

Example input: `{"file_id":"<file_id>"}`

## Related

Other AI connectors ([all 216](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
