stackone-adk

Google ADK plugin for connecting agents to 200+ SaaS providers via StackOne.

StackOne provides a unified API gateway for HRIS, ATS, CRM, scheduling, and more. This plugin dynamically discovers available tools from StackOne's API and exposes them as native Google ADK tools, no hardcoded tool definitions needed.

Installation

pip install stackone-adk

Or with uv:

uv add stackone-adk

Configuration

StackOne API Key

Get your API key from the StackOne Dashboard.

# Environment variable (recommended)
export STACKONE_API_KEY="your-stackone-api-key"

Or pass directly:

plugin = StackOnePlugin(api_key="your-stackone-api-key")

Google API Key

Get your API key from Google AI Studio. This key is required to access Google's Gemini models.

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

Quick Start

In standard ADK, you define tools as Python functions:

# Standard ADK — manual tool functions
def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    tools=[get_current_time],
)

With StackOne, tools are discovered dynamically from your connected providers — no manual tool definitions needed:

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():
    # StackOne replaces manual tool functions
    # Reads STACKONE_API_KEY from env and uses the specified account_id
    plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

    agent = Agent(
        model="gemini-2.5-flash",
        name="calendly_agent",  # replace with your agent name
        instruction="You are a scheduling assistant with access to Calendly.",
        tools=plugin.get_tools(),  # instead of: tools=[get_current_time]
    )

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

    async with InMemoryRunner(app=app) as runner:
        response = await runner.run_debug("What event types do I have?")
        print(response)

asyncio.run(main())

Usage Patterns

With App (Recommended)

from google.adk.apps import App
from google.adk.runners import InMemoryRunner

plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

agent = Agent(
    model="gemini-2.5-flash",
    name="calendly_agent",  # replace with your agent name
    tools=plugin.get_tools(),
)

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

async with InMemoryRunner(app=app) as runner:
    response = await runner.run_debug("List my events")

With Runner Directly

from google.adk.runners import InMemoryRunner

plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

agent = Agent(
    model="gemini-2.5-flash",
    name="calendly_agent",  # replace with your agent name
    tools=plugin.get_tools(),
)

async with InMemoryRunner(app_name="calendly_app", agent=agent) as runner:
    response = await runner.run_debug("List my events")

Plugin Configuration

Parameter	Type	Default	Description
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.
actions	list[str] | None	None	Filter by action patterns (supports globs).
account_ids	list[str] | None	None	Scope tools to specific account IDs.

Tool Filtering

By Account ID (Recommended)

Scope tools to specific connected accounts. This is the recommended approach to ensure your agent only accesses the intended accounts:

# Single account
plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID")

# Multiple accounts
plugin = StackOnePlugin(account_ids=["acct-hibob-1", "acct-bamboohr-1"])

By Provider

Filter tools to specific SaaS providers:

# Single provider
plugin = StackOnePlugin(providers=["calendly"])

# Multiple providers
plugin = StackOnePlugin(providers=["hibob", "bamboohr"])

By Action Pattern

Use glob patterns to filter specific actions:

# Read-only operations
plugin = StackOnePlugin(actions=["*_list_*", "*_get_*"])

# Specific actions
plugin = StackOnePlugin(actions=["calendly_list_events", "calendly_get_event_*"])

Combining Filters

plugin = StackOnePlugin(
    providers=["hibob", "bamboohr"],
    actions=["*_list_*", "*_get_*"],
    account_ids=["acct-hibob-1", "acct-bamboohr-1"],
)

Available Tools

Unlike plugins with a fixed set of tools, StackOne tools are dynamically discovered from your connected providers via the StackOne API. The available tools depend on which SaaS providers you have connected in your StackOne Dashboard. Print discovered tools:

plugin = StackOnePlugin(account_id="YOUR_ACCOUNT_ID", providers=["calendly"])
for tool in plugin.get_tools():
    print(f"{tool.name}: {tool.description}")

Examples

See the examples/ directory:

Example	Description
calendly_agent.py	Calendly scheduling agent — single provider

Development

git clone https://github.com/StackOneHQ/stackone-adk-plugin.git
cd stackone-adk-plugin
pip install -e ".[dev]"

Run tests:

pytest

Lint and type check:

ruff check stackone_adk/ tests/
mypy stackone_adk/

Try an example (requires a Calendly account connected in your StackOne Dashboard):

export STACKONE_API_KEY="your-stackone-api-key"
export GOOGLE_API_KEY="your-google-api-key"
python examples/calendly_agent.py

License

Apache 2.0 — see LICENSE.

References

• StackOne Documentation
• StackOne Python SDK
• Google ADK Documentation