integrate-agentkit

Integrate AgentKit

Take this repo from a connection to a connected account, an authorized token, and one downstream API call. Then stop.

Guardrails

• MUST pass the exact dashboard Connection Name (connection_name in Python, connectionName in Node). Never invent a slug. Never use a connector field for that value.
• MUST re-fetch the connected account immediately before using the token. Scalekit auto-refreshes.
• MUST print the authorization link and stop when the process is not interactive. Re-run from the token step after the user finishes OAuth.

Gotchas

• Read SDK credentials from SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET. Some samples use SCALEKIT_ENV_URL; use SCALEKIT_ENVIRONMENT_URL here.
• A connection is dashboard connector config. A connected account is one user authorized on that connection.
• The connection already exists from setup-agentkit. This skill starts there.
• Gmail can use Connection Name gmail when the dashboard has no Gmail row. Every other connector must already have a dashboard connection. Record that name exactly.
• Default language is Python. If the repo is Node, open references/node.md. If the language is unknown, stay on Python.

Step 1 — Confirm the Connection Name

Use the Connection Name already recorded by setup-agentkit.

If none is recorded:

• User named a connector: use the dashboard Connection Name exactly as shown.
• User did not name one: Gmail, Connection Name gmail.
• Non-Gmail with no dashboard row: name setup-agentkit and stop.

Done when: a Connection Name is written down. For Gmail with no dashboard row, that name is gmail.

Step 2 — Init the SDK

If the repo is Node, follow references/node.md from here.

If env vars are missing, collect them from app.scalekit.com → Developers → Settings → API Credentials. Put them in the project env file. Do not invent values.

pip install scalekit-sdk-python python-dotenv requests

from scalekit import ScalekitClient
import os
from dotenv import load_dotenv
load_dotenv()

sk_client = ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
)
actions = sk_client.actions

Done when: the client initializes from those three env vars, and source files do not hardcode the secret.

Step 3 — Create the connected account

Replace "user_123" with the project's user id. Replace "gmail" with the recorded Connection Name.

response = actions.get_or_create_connected_account(
    connection_name="gmail",
    identifier="user_123"
)
connected_account = response.connected_account

Done when: a connected account exists for that identifier and Connection Name.

Step 4 — Authorization link if not ACTIVE

If connected_account.status is ACTIVE, skip this step.

import sys

if connected_account.status != "ACTIVE":
    link_response = actions.get_authorization_link(
        connection_name="gmail",
        identifier="user_123"
    )
    print("Authorize here:", link_response.link)
    if not sys.stdin.isatty():
        print("Complete OAuth in a browser, then re-run from Step 5 (fetch tokens).")
        raise SystemExit(0)
    input("Press Enter after authorizing...")

In a web app, redirect to link.

Done when: status is ACTIVE, or the authorization link is printed. A non-interactive run stops here until the user finishes OAuth.

Step 5 — Fetch the token

Re-fetch immediately. Do not reuse a token from Step 3.

response = actions.get_connected_account(
    connection_name="gmail",
    identifier="user_123"
)
tokens = response.connected_account.authorization_details["oauth_token"]
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]

Done when: access_token is present.

Step 6 — Call one downstream API

Use access_token as a Bearer token. Default: five unread Gmail messages.

import requests

headers = {"Authorization": f"Bearer {access_token}"}
list_url = "https://gmail.googleapis.com/gmail/v1/users/me/messages"

messages = requests.get(
    list_url, headers=headers, params={"q": "is:unread", "maxResults": 5}
).json().get("messages", [])

for msg in messages:
    data = requests.get(
        f"{list_url}/{msg['id']}", headers=headers,
        params={"format": "metadata", "metadataHeaders": ["From", "Subject", "Date"]}
    ).json()
    hdrs = data.get("payload", {}).get("headers", [])
    print(next((h["value"] for h in hdrs if h["name"] == "Subject"), "No Subject"))
    print(next((h["value"] for h in hdrs if h["name"] == "From"), "Unknown"))
    print(data.get("snippet", ""))
    print("-" * 50)

For a non-Gmail connector, keep the same token path. Change only this HTTP call. Look up the provider API from https://docs.scalekit.com/agentkit/connectors.md.

Done when: one downstream API call succeeds with the fetched token.

Reach for

• setup-agentkit if the connection or env is missing
• discover-connectors for the live tool catalog
• integrate-agentkit-host for OpenClaw or Hermes
• expose-agentkit-mcp to expose tools over MCP
• references/node.md for the Node SDK path
• references/frameworks.md for LangChain and Google ADK

Live lookups

• Docs index: https://docs.scalekit.com/llms.txt
• Connector catalog: https://docs.scalekit.com/agentkit/connectors.md
• MCP: https://mcp.scalekit.com