用于 ADK 的 StackOne 插件¶

Supported in ADKPython

StackOne ADK 插件通过 StackOne 的统一 AI 集成网关，将你的 ADK 智能体连接到数百个提供商。该插件无需为每个 API 手动定义工具函数，而是从你连接的提供商中动态发现可用工具，并将其作为 ADK 中的原生工具公开。它支持人力资源信息系统 (HRIS)、候选人跟踪系统 (ATS)、客户关系管理 (CRM)、生产力和日程安排工具，以及更多集成项目。

使用场景¶

销售和收入运营：构建智能体在你的 CRM（如 HubSpot、Salesforce）中查找潜在客户、丰富联系人数据、起草个性化外联邮件并记录活动——所有都在一次对话中完成。
人事运营：创建智能体在你的 ATS（如 Greenhouse、Ashby）中筛选候选人、在你的日历工具（如 Google Calendar、Calendly）中检查可用性、收集面试评分卡、在流水线各阶段移动申请人，并自动入职到你的 HRIS（如 BambooHR、Workday）——涵盖整个员工生命周期，无需人工干预。
营销自动化：构建广告系列智能体，将受众群体从你的 CRM 同步到你的电子邮件平台（如 Mailchimp、Klaviyo），触发邮件序列，并跨渠道报告参与度指标。
产品交付：创建智能体对来自支持工具（如 Intercom、Zendesk、Slack）的传入反馈进行分类，在项目管理工具（如 Linear、Jira）中划分优先级并创建问题，并使用来自可观测性平台（如 PagerDuty、Datadog）的洞见解决事件——在单个工作流中统合产品研究、交付和可靠性。

先决条件¶

一个至少连接了一个提供商的 StackOne 账号
来自 StackOne 控制面板的 StackOne API 密钥
一个 Gemini API 密钥

安装¶

pip install stackone-adk

或者使用 uv：

uv add stackone-adk

与智能体配合使用¶

环境变量

在运行以下示例之前，将你的 API 密钥设置为环境变量：

export STACKONE_API_KEY="your-stackone-api-key"
export GOOGLE_API_KEY="your-google-api-key"

一旦设置了 STACKONE_API_KEY，该插件会自动读取它并发现你连接的账户。

Python

配合 App 使用（推荐）直接配合 Runner 使用

import asyncio

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from stackone_adk import StackOnePlugin


async def main():
    plugin = StackOnePlugin()
    # 或者指定特定账户：
    # plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

    tools = plugin.get_tools()
    print(f"发现 {len(tools)} 个工具")

    agent = Agent(
        model="gemini-flash-latest",
        name="scheduling_agent",
        description="通过 StackOne 管理日程安排、人力资源和 CRM。",
        instruction=(
            "你是一个由 StackOne 支持的得力助手。 "
            "你通过使用可用工具帮助用户管理其日常安排、人力资源和 CRM 任务。\n\n"
            "始终保持乐于助人，并提供清晰、有条理的回复。"
        ),
        tools=tools,
    )

    app = App(
        name="scheduling_app",
        root_agent=agent,
        plugins=[plugin],
    )

    async with InMemoryRunner(app=app) as runner:
        events = await runner.run_debug(
            "从 Calendly 获取我最近安排的会议。",
            quiet=True,
        )
        # 提取智能体的最终文本回复
        for event in reversed(events):
            if event.content and event.content.parts:
                text_parts = [p.text for p in event.content.parts if p.text]
                if text_parts:
                    print("".join(text_parts))
                    break


asyncio.run(main())

import asyncio

from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from stackone_adk import StackOnePlugin


async def main():
    plugin = StackOnePlugin()
    # 或者指定特定账户：
    # plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

    tools = plugin.get_tools()
    print(f"发现 {len(tools)} 个工具")

    agent = Agent(
        model="gemini-flash-latest",
        name="scheduling_agent",
        description="通过 StackOne 管理日程安排、人力资源和 CRM。",
        instruction=(
            "你是一个由 StackOne 支持的得力助手。 "
            "你通过使用可用工具帮助用户管理其日常安排、人力资源和 CRM 任务。\n\n"
            "始终保持乐于助人，并提供清晰、有条理的回复。"
        ),
        tools=tools,
    )

    async with InMemoryRunner(
        app_name="scheduling_app", agent=agent
    ) as runner:
        events = await runner.run_debug(
            "从 Calendly 获取我最近安排的会议。",
            quiet=True,
        )
        # 提取智能体的最终文本回复
        for event in reversed(events):
            if event.content and event.content.parts:
                text_parts = [p.text for p in event.content.parts if p.text]
                if text_parts:
                    print("".join(text_parts))
                    break


asyncio.run(main())

搜索和执行模式¶

使用 mode="search_and_execute" 时，插件只注册两个工具：tool_search 和 tool_execute。模型在运行时使用它们来发现正确的 StackOne 工具并调用它，而不是预先查看完整的目录。

将每个工具定义注册到模型有三个代价：

令牌开销： 工具模式会消耗提示令牌，而这些令牌本可用于推理。
负载限制： 大型目录可能超出提供商的负载限制。例如，Gemini 对每个请求的函数声明的大小和数量施加了硬性限制。
选择准确性： 随着工具候选集增大，工具选择质量会下降，因为模型需要区分更多近似重复项。

此模式将注册的工具数量保持在两个，无论目录大小如何。模型通过运行时自然语言查询解析正确的工具。

此模式需要 stackone-adk>=0.2.0。

Python

import asyncio

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from stackone_adk import StackOnePlugin


async def main():
    plugin = StackOnePlugin(
        mode="search_and_execute",
        account_ids=["YOUR_ACCOUNT_ID"],
        search={"method": "auto", "top_k": 10},
    )

    agent = Agent(
        model="gemini-flash-latest",
        name="stackone_agent",
        description="Connects to multiple SaaS providers through StackOne.",
        instruction=(
            "You are an assistant powered by StackOne. To answer the "
            "user's request, first call tool_search with a short query "
            "to find the right action, then call tool_execute with the "
            "chosen tool name and parameters that match the schema "
            "returned by tool_search."
        ),
        tools=plugin.get_tools(),
    )

    app = App(
        name="stackone_app",
        root_agent=agent,
        plugins=[plugin],
    )

    async with InMemoryRunner(app=app) as runner:
        events = await runner.run_debug(
            "List the first 3 workers.",
            quiet=True,
        )
        for event in reversed(events):
            if event.content and event.content.parts:
                text_parts = [p.text for p in event.content.parts if p.text]
                if text_parts:
                    print("".join(text_parts))
                    break


asyncio.run(main())

模型首先使用自然语言查询调用 tool_search，接收一个简短的候选工具列表，每个工具带有名称、描述和参数模式。然后模型使用所选工具名称和与该模式匹配的参数调用 tool_execute。两次调用都通过 SDK 路由到 StackOne 的 AI 集成网关。

Available tools¶

与具有固定工具集的集成不同，StackOne 工具是通过 StackOne API 从你连接的提供商中动态发现的。可用工具取决于你在 StackOne 控制面板中连接了哪些 SaaS 提供商。

列出发现的工具：

plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID") # 可选：省略以使用所有连接的账户
for tool in plugin.get_tools():
    print(f"{tool.name}: {tool.description}")

支持的集成类别¶

类别	示例提供商
HRIS	HiBob, BambooHR, Workday, SAP SuccessFactors, Personio, Gusto
ATS	Greenhouse, Ashby, Lever, Bullhorn, SmartRecruiters, Teamtailor
CRM & 销售	Salesforce, HubSpot, Pipedrive, Zoho CRM, Close, Copper
营销	Mailchimp, Klaviyo, ActiveCampaign, Brevo, GetResponse
票务 & 支持	Zendesk, Freshdesk, Jira, ServiceNow, PagerDuty, Linear
生产力	Asana, ClickUp, Slack, Microsoft Teams, Notion, Confluence
日程安排	Calendly, Cal.com
LMS & 学习	360Learning, Docebo, Go1, Cornerstone, LinkedIn Learning
商务	Shopify, BigCommerce, WooCommerce, Etsy
开发工具	GitHub, GitLab, Twilio

有关 200+ 已支持提供商的完整列表，请访问 StackOne 集成页面。

配置¶

插件参数¶

参数	类型	默认值	描述
`api_key`	`str \| None`	`None`	StackOne API key. Falls back to `STACKONE_API_KEY` env var.
`account_id`	`str \| None`	`None`	Default account ID for all tools.
`base_url`	`str \| None`	`None`	API URL override (default: `https://api.stackone.com`).
`plugin_name`	`str`	`"stackone_plugin"`	Plugin identifier for ADK.
`providers`	`list[str] \| None`	`None`	Filter by provider names (e.g., `["calendly", "hibob"]`).
`actions`	`list[str] \| None`	`None`	Filter by action patterns using glob syntax.
`account_ids`	`list[str] \| None`	`None`	Scope tools to specific connected account IDs.
`mode`	`Literal["search_and_execute"] \| None`	`None`	Tool registration strategy. With `None`, every discovered tool is registered with the agent. With `"search_and_execute"`, the plugin registers two tools (`tool_search` and `tool_execute`), and the model selects and invokes tools at runtime.
`search`	`SearchConfig \| None`	`None`	Search backend configuration forwarded to `StackOneToolSet`. Takes effect when `mode="search_and_execute"`. Defaults to `{"method": "auto"}` in that mode.
`execute`	`ExecuteToolsConfig \| None`	`None`	Execution configuration forwarded to `StackOneToolSet`.
`timeout`	`float`	`180.0`	Per-request timeout in seconds for HTTP calls (account discovery and tool execution). Increase for slow connectors.

工具过滤¶

按提供商、操作模式、账户 ID 或任何组合过滤工具：

# 指定账户
plugin = StackOnePlugin(account_ids=["acct-hibob-1", "acct-bamboohr-1"])

# 只读操作
plugin = StackOnePlugin(actions=["*_list_*", "*_get_*"])

# 使用 glob 模式的特定操作
plugin = StackOnePlugin(actions=["calendly_list_events", "calendly_get_event_*"])

# 组合过滤器
plugin = StackOnePlugin(
    actions=["*_list_*", "*_get_*"],
    account_ids=["acct-hibob-1"],
)