developer-docs/src/content/docs/agentkit/sdks/python/index.mdx at 4fa5eb33c942eafd0f587230ffccdd33ead4afb1 · scalekit-inc/developer-docs

title

Python SDK reference

description

Complete API reference for the Scalekit Python SDK: actions client, MCP server provisioning, framework adapters, tools client, and modifiers.

sidebar

label
Python SDK

tableOfContents

minHeadingLevel	maxHeadingLevel
2	4

head

tag	content
style	.sl-markdown-content h3 { font-size: var(--sl-text-lg); } .sl-markdown-content h4 { font-size: var(--sl-text-base); margin-top: 2.5rem; padding-left: 0.75rem; border-left: 3px solid var(--sl-color-accent); }

import { Aside } from '@astrojs/starlight/components'; import MethodParams from '@/components/MethodParams.astro'; import MethodReturns from '@/components/MethodReturns.astro';

scalekit_client.actions is the primary interface for AgentKit. It handles connected account management, MCP server provisioning, tool execution, and framework integrations.

Install and initialize

pip install scalekit-sdk-python

import os
import scalekit.client

scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENV_URL"),
)

actions = scalekit_client.actions

Actions client

Authentication

get_authorization_link

Generates a time-limited OAuth magic link to authorize a user's connection.

magic_link = actions.get_authorization_link(
    identifier="user@example.com",
    connection_name="gmail",
    user_verify_url="https://your-app.com/verify",
)
# Redirect the user to magic_link.link

verify_connected_account_user

Verifies the user after OAuth callback. Call this from your redirect URL handler.

result = actions.verify_connected_account_user(
    auth_request_id=request.args["auth_request_id"],
    identifier="user@example.com",
)
# Redirect to result.post_user_verify_redirect_url

Connected accounts

get_or_create_connected_account

Fetches an existing connected account or creates one if none exists. Use this as the default when setting up a user.

account = actions.get_or_create_connected_account(
    connection_name="gmail",
    identifier="user@example.com",
)
print(account.connected_account.id)

get_connected_account

Fetches auth details for a connected account. Returns sensitive credentials. Protect access to this method.

Use this when you know the connected account already exists and you need its credential payload. For first-time setup or general application flows, prefer get_or_create_connected_account so new users do not hit a not-found error.

Requires connected_account_id or connection_name + identifier.

list_connected_accounts

create_connected_account

Creates a connected account with explicit auth details.

Returns CreateConnectedAccountResponse. Same shape as get_or_create_connected_account.

update_connected_account

Requires connected_account_id or connection_name + identifier.

Returns UpdateConnectedAccountResponse.

delete_connected_account

Deletes a connected account and revokes its credentials. Requires connected_account_id or connection_name + identifier.

Returns DeleteConnectedAccountResponse.

Tool execution

execute_tool

Executes a named tool via Scalekit. Pre- and post-modifiers run automatically if registered.

result = actions.execute_tool(
    tool_name="gmail_fetch_emails",
    tool_input={"max_results": 5, "label": "UNREAD"},
    identifier="user@example.com",
)
emails = result.data

Proxied API calls

request

Makes a REST API call on behalf of a connected account. Scalekit injects the user's OAuth token automatically.

Returns requests.Response. Use .json(), .status_code, and standard response attributes.

response = actions.request(
    connection_name="gmail",
    identifier="user@example.com",
    path="/gmail/v1/users/me/messages",
    query_params={"maxResults": 5, "q": "is:unread"},
)
messages = response.json()["messages"]

MCP server provisioning

actions.mcp generates per-user MCP-compatible server URLs. Any MCP-compatible agent framework (LangChain, Google ADK, Anthropic, OpenAI, and others) can connect to these URLs directly.

Two-step model: Create a config once (defines which connectors and tools to expose), then call ensure_instance per user to get their personal MCP server URL.

Configs

actions.mcp.create_config

from scalekit.actions.types import McpConfigConnectionToolMapping

config = actions.mcp.create_config(
    name="email-agent",
    connection_tool_mappings=[
        McpConfigConnectionToolMapping(
            connection_name="gmail",
            tools=["gmail_fetch_emails", "gmail_send_email"],
        )
    ],
)

actions.mcp.list_configs

Returns ListMcpConfigsResponse.

actions.mcp.update_config

Returns UpdateMcpConfigResponse.

actions.mcp.delete_config

Returns DeleteMcpConfigResponse.

Instances

actions.mcp.ensure_instance

Creates an MCP instance for this user if one doesn't exist, or returns the existing one. Call this on every session; it's idempotent.

The instance.url field is the MCP server URL to give to the user's agent or IDE.

instance = actions.mcp.ensure_instance(
    config_name="email-agent",
    user_identifier="user@example.com",
)
mcp_url = instance.instance.url
# Give mcp_url to the user's agent or IDE

actions.mcp.get_instance_auth_state

Returns authorization status per connector. Use include_auth_links=True to generate fresh auth links for connections that need authorization or re-authorization.

auth_state = actions.mcp.get_instance_auth_state(
    instance_id=instance.instance.id,
    include_auth_links=True,
)
for conn in auth_state.connections:
    if conn.connected_account_status != "ACTIVE":
        # Send conn.authentication_link to the user to authorize
        print(f"{conn.connection_name}: {conn.authentication_link}")

actions.mcp.get_instance

Returns GetMcpInstanceResponse.

actions.mcp.list_instances

Returns ListMcpInstancesResponse.

actions.mcp.update_instance

At least one of name or config_name is required.

Returns UpdateMcpInstanceResponse.

actions.mcp.delete_instance

Returns DeleteMcpInstanceResponse.

Framework adapters

Pre-built integrations for LangChain and Google ADK. Use these when your agent runs in one of these frameworks and you prefer native tool objects over an MCP URL.

`actions.mcp.ensure_instance` generates a URL compatible with any MCP-supporting framework. Use framework adapters only when native tool objects are required.

LangChain

pip install langchain

actions.langchain.get_tools

from langchain.agents import create_react_agent

tools = actions.langchain.get_tools(identifier="user@example.com")
agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)

Google ADK

pip install google-adk

actions.google.get_tools

Same parameters as actions.langchain.get_tools.

Returns List[ScalekitGoogleAdkTool]. Pass it directly to a Google ADK agent.

tools = actions.google.get_tools(identifier="user@example.com")

Tools client

scalekit_client.actions.tools gives access to raw tool schemas. Use this when building a custom adapter or passing schemas directly to an LLM API (e.g. Anthropic, OpenAI).

actions.tools.list_tools

actions.tools.list_scoped_tools

Lists tools scoped to a specific user. This is what framework adapters use internally to fetch per-user tool schemas.

tools_response = scalekit_client.actions.tools.list_scoped_tools(
    identifier="user@example.com",
)
# Pass tools_response.tools to your LLM's tool call API

actions.tools.execute_tool

Low-level tool execution. Bypasses modifiers. Prefer actions.execute_tool in most cases.

Returns ExecuteToolResponse. Same shape as actions.execute_tool.

Modifiers

Modifiers intercept tool calls to transform inputs or outputs, useful for validation, enrichment, or logging.

@actions.pre_modifier(tool_names=["gmail_fetch_emails"])
def add_default_label(tool_input):
    tool_input.setdefault("label", "UNREAD")
    return tool_input

@actions.post_modifier(tool_names=["gmail_fetch_emails"])
def filter_attachments(tool_output):
    tool_output["emails"] = [e for e in tool_output["emails"] if not e.get("has_attachment")]
    return tool_output

Decorator	Receives	Returns
`@actions.pre_modifier(tool_names)`	`dict`	Modified `dict`
`@actions.post_modifier(tool_names)`	`dict`	Modified `dict`

tool_names accepts a string or a list of strings. Multiple modifiers for the same tool chain in registration order.

Error handling

from scalekit.common.exceptions import ScalekitNotFoundException, ScalekitServerException

try:
    account = actions.get_connected_account(
        connection_name="gmail",
        identifier="user@example.com",
    )
except ScalekitNotFoundException:
    # Account does not exist: create it or redirect to auth
    pass
except ScalekitServerException as e:
    print(e.error_code, e.http_status)

Exception	When raised
`ScalekitNotFoundException`	Resource not found
`ScalekitUnauthorizedException`	Invalid credentials
`ScalekitForbiddenException`	Insufficient permissions
`ScalekitServerException`	Base class for all server errors

Uh oh!

FilesExpand file tree

index.mdx

Latest commit

History