Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
python-version: ["3.11", "3.12", "3.13"]
steps:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 0.3.0 (unreleased)

Built on StackOne AI SDK 3.0, which lists and runs every tool over StackOne's MCP endpoint.

### Breaking changes

* **python:** requires Python 3.11 or later, as `stackone-ai` 3.0 does.
* **dependencies:** depends on `stackone-ai>=3.0.0,<4.0.0`. The `[mcp]` extra is gone: MCP is a core dependency of the SDK.
* **plugin:** `search=` is removed, and with it the `SearchConfig` and `SearchMode` exports. Search runs on StackOne's server, so there is no backend to configure.
* **plugin:** in `mode="search_and_execute"` the tools are StackOne's `stackone_search_actions` and `stackone_execute_action` (with `stackone_list_accounts` when more than one account is in scope), spanning every account in scope, at most 50, in place of `tool_search` and `tool_execute`. Update prompts that name the old tools. `stackone_execute_action` takes `action_id` and arguments nested under `path`, `query` and `body`, plus `stackone_account_id` when the connector is linked on more than one account.
* **tools:** a tool returns the server's result as it wrote it, `{"isError": false, "result": ...}`, not the unwrapped payload.
* **tools:** a tool's declared `required` list is the one StackOne served, not one derived from each property's `nullable` marker.

### Changes

* **plugin:** account discovery is the SDK's. With no account given, the plugin uses every active shared account on the API key. If the tools cannot be loaded, it still logs a warning and registers no tools.
* **plugin:** `base_url` falls back to `STACKONE_BASE_URL` before the default.
* **ci:** the matrix runs Python 3.11 to 3.13.

## [0.2.0](https://github.com/StackOneHQ/stackone-adk-plugin/compare/stackone-adk-v0.1.0...stackone-adk-v0.2.0) (2026-05-05)


Expand Down
33 changes: 17 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,12 @@

Google ADK plugin that gives your agents [StackOne](https://stackone.com)'s 540+ connectors and 33,000+ actions as native ADK tools.

StackOne is integration infrastructure for AI agents. Use this plugin when you're building an ADK agent that acts in your customers' applications as part of your product, or an agent for your own company's systems. When you create the plugin, it loads the actions available to your StackOne account and gives them to your agent as ADK tools: one tool per action by default, or two tools that search for and run actions on demand in `search_and_execute` mode. You don't write or maintain any tool definitions.
StackOne is integration infrastructure for AI agents. Use this plugin when you're building an ADK agent that acts in your customers' applications as part of your product, or an agent for your own company's systems. When you create the plugin, it loads the actions available to your StackOne account and gives them to your agent as ADK tools: one tool per action by default, or StackOne's search and execute tools, which find and run actions on demand, in `search_and_execute` mode. You don't write or maintain any tool definitions.

## Installation

Requires Python 3.11 or later.

```bash
pip install stackone-adk
```
Expand Down Expand Up @@ -133,27 +135,23 @@ async with InMemoryRunner(app_name="stackone_app", agent=agent) as runner:
|-----------|------|---------|-------------|
| `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`). |
| `base_url` | `str \| None` | `None` | API URL override. Falls back to `STACKONE_BASE_URL`, then `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). |
| `actions` | `list[str] \| None` | `None` | Filter by action patterns (supports globs). Ignored in search and execute mode. |
| `account_ids` | `list[str] \| None` | `None` | Scope tools to specific account IDs. |
| `mode` | `Literal["search_and_execute"] \| None` | `None` | Tool registration strategy. See [Search and Execute mode](#search-and-execute-mode). |
| `search` | `SearchConfig \| None` | `None` | Search backend config. Only used when `mode="search_and_execute"`. |
| `execute` | `ExecuteToolsConfig \| None` | `None` | Execution config (account scoping, timeout). Only used when `mode="search_and_execute"`. |
| `timeout` | `float \| None` | `None` | Per-request timeout in seconds for tool execution. |
| `execute` | `ExecuteToolsConfig \| None` | `None` | Execution config (account scoping, timeout), forwarded to `StackOneToolSet`. |
| `timeout` | `float` | `180.0` | Per-request timeout in seconds for listing and executing tools. |

## Search and Execute Mode

By default, `StackOnePlugin` registers every discovered tool with the agent — fine for one or two providers, but the LLM context balloons quickly when many SaaS accounts are connected. With `mode="search_and_execute"`, the plugin registers exactly **two meta tools** (`tool_search` and `tool_execute`) and lets the model discover and invoke real tools on demand:
By default, `StackOnePlugin` registers every discovered tool with the agent — fine for one or two providers, but the LLM context balloons quickly when many SaaS accounts are connected. With `mode="search_and_execute"`, the plugin registers StackOne's **search and execute tools** and lets the model find and run actions on demand:

```python
from stackone_adk import StackOnePlugin

plugin = StackOnePlugin(
mode="search_and_execute",
search={"method": "auto", "top_k": 5},
)
plugin = StackOnePlugin(mode="search_and_execute")

agent = Agent(
model="gemini-3.1-pro-preview",
Expand All @@ -164,12 +162,15 @@ agent = Agent(

**When to use:** more than ~5 connected providers, or whenever the full tool list would dominate the model's context window.

**How it works:** the LLM calls `tool_search("...")` to get a short list of candidate tools (name, description, parameter schema), then calls `tool_execute(tool_name, parameters)` with the chosen one. `tool_execute` runs the action through StackOne. `tool_search` uses StackOne's semantic search or a local search, depending on the `search` method (see the notes below).
**How it works:** the plugin registers the same tools however many accounts are in scope (at most 50):

- `stackone_search_actions` takes a natural-language `query` and returns ranked actions, each with its `action_id`, `input_schema`, an `example_request` and the `available_accounts` it can run on.
- `stackone_execute_action` runs one by `action_id`, with arguments nested under `path`, `query` and `body` as the `example_request` shows. When the action's connector is linked on more than one account, the model passes the chosen one as `stackone_account_id`.
- `stackone_list_accounts`, registered only when more than one account is in scope, lists them, so the model can resolve an account name to its id.

**Notes:**
- `providers` and `actions` filters are ignored in this mode (scoping happens via `account_ids` and the LLM's search query). A warning is logged if you pass them.
- Search defaults to `{"method": "auto"}` (semantic search with local BM25+TF-IDF fallback). Pass `search={"method": "semantic"}` or `search={"method": "local"}` to force one backend.
- The connector list embedded in the meta tools' descriptions is captured at plugin construction time. If you link new accounts after the plugin starts, restart the agent to pick them up.
- `actions` is ignored in this mode (the LLM's search query selects actions); a warning is logged if you pass it. `providers` and `account_ids` scope the accounts the tools span.
- The connectors named in the tools' descriptions are captured at plugin construction time. If you link new accounts after the plugin starts, restart the agent to pick them up.

See [`examples/search_and_execute_agent.py`](examples/search_and_execute_agent.py) for a complete runnable example.

Expand Down Expand Up @@ -239,7 +240,7 @@ See the [`examples/`](examples/) directory:
| Example | Description |
|---------|-------------|
| [`workday_agent.py`](examples/workday_agent.py) | Default mode (registers all matching tools); demo uses `actions=[...]` to scope to 3 Workday actions |
| [`search_and_execute_agent.py`](examples/search_and_execute_agent.py) | LLM-driven discovery via `mode="search_and_execute"`, registers 2 tools |
| [`search_and_execute_agent.py`](examples/search_and_execute_agent.py) | LLM-driven discovery via `mode="search_and_execute"`, registers StackOne's search and execute tools |

## Development

Expand Down
31 changes: 13 additions & 18 deletions examples/search_and_execute_agent.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""Workday agent using StackOne search-and-execute mode with Google ADK.

The plugin exposes only ``tool_search`` and ``tool_execute``; the agent
The plugin exposes ``stackone_search_actions`` and ``stackone_execute_action``
(with ``stackone_list_accounts`` when several accounts are in scope); the agent
discovers and invokes Workday actions on demand. Use this when many SaaS
accounts are linked and the full tool catalog would dominate the model's
context window.
Expand Down Expand Up @@ -43,12 +44,11 @@ def _print_tool_call(name: str, args: dict) -> None:


def _print_tool_response(name: str, response: dict) -> None:
if name == "tool_search":
tools = response.get("tools", [])
total = response.get("total", len(tools))
print(f" ← tool_search: total={total}")
for t in tools:
print(f" • {t.get('name')}")
if name == "stackone_search_actions":
actions = response.get("actions", [])
Comment thread
willleeney marked this conversation as resolved.
Resolved
print(f" ← {name}: {len(actions)} action(s)")
for action in actions:
print(f" • {action.get('action_id')}")
return
summary = str(response)
if len(summary) > 400:
Expand All @@ -65,12 +65,7 @@ async def main() -> None:
if not os.getenv("GOOGLE_API_KEY"):
sys.exit("Set GOOGLE_API_KEY to run this example.")

plugin = StackOnePlugin(
mode="search_and_execute",
account_ids=[account_id],
search={"method": "auto", "top_k": 10},
execute={"account_ids": [account_id]},
)
plugin = StackOnePlugin(mode="search_and_execute", account_ids=[account_id])

tools = plugin.get_tools()
print(f"Registered {len(tools)} meta tool(s): {[t.name for t in tools]}\n")
Expand All @@ -81,11 +76,11 @@ async def main() -> None:
description="StackOne search-and-execute assistant, discovers and invokes tools on demand.",
instruction=(
"You are an assistant powered by StackOne (e.g. Workday). To "
"answer the user's request, first call tool_search with a short "
"natural-language 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. Keep answers concise and "
"reference real data."
"answer the user's request, first call stackone_search_actions with "
"a short natural-language query to find the right action, then call "
"stackone_execute_action with its action_id and arguments built from "
"the action's example_request and input_schema (nested under path, "
"query and body). Keep answers concise and reference real data."
),
tools=tools,
)
Expand Down
11 changes: 5 additions & 6 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ build-backend = "hatchling.build"

[project]
name = "stackone-adk"
version = "0.2.1"
version = "0.3.0"
description = "Google ADK plugin that gives agents StackOne's 540+ connectors and 33,000+ actions as native ADK tools"
readme = "README.md"
requires-python = ">=3.10"
requires-python = ">=3.11"
license = {text = "Apache-2.0"}
authors = [
{name = "StackOne", email = "support@stackone.com"},
Expand All @@ -18,15 +18,14 @@ classifiers = [
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
]

dependencies = [
"google-adk>=1.31.1",
"stackone-ai[mcp]>=2.8.0,<3.0.0",
"stackone-ai>=3.0.0,<4.0.0",
]

[project.optional-dependencies]
Expand All @@ -47,15 +46,15 @@ packages = ["stackone_adk"]

[tool.ruff]
line-length = 110
target-version = "py310"
target-version = "py311"

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP"]

# python_version is deliberately unset so mypy targets the running interpreter.
# Pinning it to 3.10 made mypy parse dependency stubs with 3.10 grammar while the
# environment could hold 3.12-only packages (numpy >=2.5 uses `type` statements),
# which fails on a syntax error. The CI matrix covers 3.10-3.13 instead.
# which fails on a syntax error. The CI matrix covers 3.11-3.13 instead.
[tool.mypy]
warn_return_any = true
warn_unused_configs = true
Expand Down
6 changes: 2 additions & 4 deletions stackone_adk/__init__.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
from stackone_ai import ExecuteToolsConfig, SearchConfig, SearchMode
from stackone_ai import ExecuteToolsConfig

from stackone_adk.plugin import StackOnePlugin
from stackone_adk.tools import StackOneAdkTool

__version__ = "0.2.1"
__version__ = "0.3.0"
__all__ = [
"StackOnePlugin",
"StackOneAdkTool",
"SearchConfig",
"SearchMode",
"ExecuteToolsConfig",
]
Loading
Loading