Basic Usage

Quick Start

The most common pattern: create a toolset and give your agent search and execute tools. The agent discovers and runs tools on demand.

from stackone_ai import StackOneToolSet

# search_and_execute returns the tool_search + tool_execute meta tools, so search
# must be enabled on the toolset (pass search={} for defaults).
toolset = StackOneToolSet(search={"method": "auto"})

# Your agent gets 2 tools: tool_search + tool_execute
tools = toolset.openai(mode="search_and_execute", account_ids=["your-account-id"])

Pass tools to any OpenAI-compatible model and the agent will search for relevant tools, then execute them automatically. See the OpenAI integration guide for a full agent loop.

Fetch Tools

When you need specific tools instead of search and execute:

tools = toolset.fetch_tools(account_ids=["your-account-id"])
openai_tools = tools.to_openai()

Filtering by provider, action, or pattern

# Filter by providers
tools = toolset.fetch_tools(
    providers=["hibob", "workday"],
    account_ids=["your-account-id"],
)

# Filter by actions with exact match
tools = toolset.fetch_tools(
    actions=["hibob_list_employees", "hibob_create_employees"],
    account_ids=["your-account-id"],
)

# Filter by actions with glob patterns
tools = toolset.fetch_tools(
    actions=["*_list_*"],
    account_ids=["your-account-id"],
)

# Combine multiple filters
tools = toolset.fetch_tools(
    providers=["hibob"],
    actions=["*_list_*"],
    account_ids=["your-account-id"],
)

See Tool Filtering for the full reference.

Multi-account usage

# Set accounts on the toolset for all subsequent calls
toolset.set_accounts(["account-123", "account-456"])
tools = toolset.fetch_tools()

# Or pass account IDs per request
tools = toolset.fetch_tools(account_ids=["account-123", "account-456"])

# Loop over customer accounts dynamically
customer_accounts = ["account-1", "account-2", "account-3"]

for account_id in customer_accounts:
    tools = toolset.fetch_tools(
        actions=["workday_list_workers"],
        account_ids=[account_id],
    )
    employee_tool = tools.get_tool("workday_list_workers")
    if employee_tool:
        employees = employee_tool.call()
        print(f"Found {len(employees['data'])} employees")

Tool Execution

Direct tool execution (for debugging)

Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

tools = toolset.fetch_tools(account_ids=["your-account-id"])
employee_tool = tools.get_tool("workday_list_workers")

# call() with keyword arguments
result = employee_tool.call(id="employee-123", include_details=True)
print(result["data"])

# execute() with dictionary payloads
result = employee_tool.execute({"id": "employee-123", "include_details": True})

# execute() with OpenAI-style arguments
payload = {"arguments": {"id": "employee-123"}}
result = employee_tool.execute(payload)

Error handling

from stackone_ai.models import StackOneError, StackOneAPIError

try:
    result = employee_tool.call(id="employee-123")
    print("Success:", result)
except StackOneAPIError as e:
    print(f"API error: {e.message}")
except StackOneError as e:
    print(f"StackOne error: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

File downloads (binary responses)

Actions that download a file (for example googledrive_unified_download_file, documents_download_file, or any *_unified_download_file) return raw bytes plus metadata, not parsed JSON. The SDK decides from the response Content-Type: JSON is parsed as usual, and anything else is treated as a file download. call() and execute() both return this dict directly (it isn’t wrapped in a result object), so read its values with dict keys like result["content"].

tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=["your-account-id"])
download = tools.get_tool("googledrive_unified_download_file")

result = download.execute({"id": "file-id"})

# result describes the file. Write the bytes straight to disk:
with open(result["file_name"] or "download.bin", "wb") as f:
    f.write(result["content"])

The returned dict, from both call() and execute():

Key	Type	Description
`content`	`bytes`	Raw file bytes. Not JSON-serializable (see note).
`content_type`	`str`	File MIME type (for example `application/pdf`), or `application/octet-stream`.
`status_code`	`int`	HTTP status of the download response.
`headers`	`dict`	Response headers.
`file_name`	`str \| None`	Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `None`.

content is raw bytes and is not JSON-serializable. If you forward tool results to an LLM (or anything that re-serializes to JSON), handle or strip the content key. For example, base64-encode it on the LLM-facing path.

Environment Configuration

export STACKONE_API_KEY=your_api_key

Account IDs are passed per-request when fetching tools or via toolset.openai(mode="search_and_execute", account_ids=[...]).

Next Steps

OpenAI Integration for building agents with function calling
LangChain Integration for framework-based workflows
Tool Search for natural language tool discovery
Tool Filtering for advanced filtering patterns

Overview

Getting Started

Frameworks

API Behavior

Quick Start

Fetch Tools

Tool Execution

Environment Configuration

Next Steps

​Quick Start

​Fetch Tools

​Tool Execution

​Environment Configuration

​Next Steps

Quick Start

Fetch Tools

Tool Execution

Environment Configuration

Next Steps