discovering-connector-tools

用途

本技能用于发现某个 Scalekit AgentKit 连接器（connector）当前实际可用的工具，并解释这些工具的输入与输出 schema。当用户询问 Gmail、Slack、Salesforce、Notion、GitHub、Google Calendar 等连接器有哪些工具可用，或需要了解某个具体工具需要哪些输入字段时使用。

核心原则：以实时 AgentKit 元数据作为工具名称、必填输入和输出 schema 的唯一可信来源，不要依赖静态连接器笔记作为完整目录，因为它们可能滞后于实时平台。

前置条件

安装 SDK（按项目语言选择）：

# Python
pip install scalekit-sdk-python python-dotenv

# Node.js
npm install @scalekit-sdk/node dotenv

环境变量——在运行发现前放入 .env（或导出）：

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=<from dashboard>
SCALEKIT_CLIENT_SECRET=<from dashboard>

凭据获取位置：app.scalekit.com → Developers → Settings → API Credentials。

连接器 / provider slug：SDK 中的 providers 期望大写连接器类型 slug（例如 GMAIL、SLACK、SALESFORCE、NOTION、GITHUB、GOOGLECALENDAR）。可用连接器的可信来源是 Connectors catalog 和 Scalekit Dashboard → AgentKit → Connections。优先使用实时 get_tools 响应，而非任何静态列表。

发现工作流

确定目标连接器（来自上述目录/仪表盘的 slug）或确切的工具名称。
使用 Scalekit SDK 获取实时工具元数据（见下方代码）。
汇总：工具名称、连接器、工具功能、input_schema.required 中的必填字段、input_schema.properties 中的可选字段、output_schema.properties 中的重要字段。
为工作流推荐最小可用工具集。

实时工具发现（Python）

from scalekit import ScalekitClient
import os
from dotenv import load_dotenv
load_dotenv()  # loads SCALEKIT_* from .env

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

# List ALL tools for a provider — page until exhausted (do not stop after one call)
page_token = None
while True:
    page = sk_client.actions.get_tools(
        providers=["GMAIL"], page_size=100, page_token=page_token
    )
    for tool in page.tools:
        print(f"Tool: {tool.name}")
        print(f"  Description: {tool.description}")
        print(f"  Input schema: {tool.input_schema}")
        print(f"  Output schema: {tool.output_schema}")
    page_token = getattr(page, "next_page_token", None) or getattr(page, "nextPageToken", None)
    if not page_token:
        break

# Get a specific tool by name
tool = sk_client.actions.get_tools(tool_name="gmail_fetch_mails")

实时工具发现（Node.js / TypeScript）

import { ScalekitClient } from '@scalekit-sdk/node';
import 'dotenv/config'; // loads SCALEKIT_* from .env

const client = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL as string,
  process.env.SCALEKIT_CLIENT_ID as string,
  process.env.SCALEKIT_CLIENT_SECRET as string
);

// List ALL tools for a provider — page until exhausted
let pageToken: string | undefined;
do {
  const page = await client.actions.getTools({
    providers: ['GMAIL'],
    pageSize: 100,
    pageToken,
  });
  for (const tool of page.tools) {
    console.log(`Tool: ${tool.name}`);
    console.log(`  Description: ${tool.description}`);
  }
  pageToken = page.nextPageToken;
} while (pageToken);

// Get a specific tool by name
const tool = await client.actions.getTools({ toolName: 'gmail_fetch_mails' });

术语

connector：Gmail、Slack、Salesforce、Notion 或自定义连接器。
connection：用于授权的确切仪表盘配置名称。
connected account：每个用户的已授权记录。
tool：连接器暴露的可执行动作。

在解释中使用 connector。仅当 SDK 或 API 过滤字段字面上期望该名称时，才使用 provider。

护栏

必须将实时工具元数据（get_tools）视为可信来源——绝不要依赖静态文档作为完整目录。
必须在将工具集交给 LLM 之前进行限制——更少的相关工具能提高选择准确性。
不得在此执行工具或授权已连接账户——那属于 integrating-agentkit。本技能只发现和解释 schema。
connection_name 是确切的仪表盘值——可能不等于连接器 slug。
分页：get_tools 每次调用最多返回 page_size 个结果。上述示例循环 next_page_token / nextPageToken 直到为空——必须同样处理；绝不要假设一次调用返回所有工具。
如果 get_tools 返回空：验证连接器已在仪表盘中配置，且连接名称完全匹配。

深入参考

AgentKit 概览：docs.scalekit.com/agentkit/overview
工具发现：docs.scalekit.com/agentkit/tool-discovery
连接器目录：docs.scalekit.com/agentkit/connectors

何时切换技能

使用 integrating-agentkit 进行完整集成工作流（创建账户、授权、执行）。
使用 Scalekit MCP 服务器（https://mcp.scalekit.com）交互式验证工具调用。
使用 exposing-agentkit-via-mcp 通过 MCP 暴露已发现的工具。