pip install 'stackone-ai[mcp]'
# Or with uv
uv add 'stackone-ai[mcp]'

# Install with CrewAI examples
pip install 'stackone-ai[mcp,examples]'
# or
uv add 'stackone-ai[mcp,examples]'

import os
from stackone_ai import StackOneToolSet
# Initialize — reads STACKONE_API_KEY from environment
toolset = StackOneToolSet()
# Fetch tools — pass account ID from STACKONE_ACCOUNT_ID env var
account_id = os.getenv("STACKONE_ACCOUNT_ID")
tools = toolset.fetch_tools(actions=["workday_*"], account_ids=[account_id])
# Use a specific tool with the call method
employee_tool = tools.get_tool("workday_get_worker")
# Call with keyword arguments
employee = employee_tool.call(id="employee-id")
# Or with traditional execute method
employee = employee_tool.execute({"id": "employee-id"})

from stackone_ai import StackOneToolSet
toolset = StackOneToolSet()
# Filter by account IDs
tools = toolset.fetch_tools(account_ids=["acc-123", "acc-456"])
# Filter by providers (case-insensitive)
tools = toolset.fetch_tools(providers=["hibob", "workday"])
# Filter by action patterns with glob support
tools = toolset.fetch_tools(actions=["*_list_employees"])
# Combine multiple filters
tools = toolset.fetch_tools(
    account_ids=["acc-123"],
    providers=["hibob"],
    actions=["*_list_*"]
)
# Use set_accounts() for chaining
toolset.set_accounts(["acc-123", "acc-456"])
tools = toolset.fetch_tools(providers=["hibob"])

tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=[account_id])
download = tools.get_tool("googledrive_unified_download_file")
result = download.execute({"id": "file-id"})
# `result` is a dict describing the file — write the bytes straight to disk:
with open(result["file_name"] or "download.bin", "wb") as f:
    f.write(result["content"])

from stackone_ai import configure_implicit_feedback
configure_implicit_feedback(
    api_key="/path/to/langsmith.key",
    project_name="stackone-agents",
    default_tags=["python-sdk"],
)

tool.execute(
    {"id": "employee-id"},
    options={
        "feedback_session_id": "chat-42",
        "feedback_user_id": "user-123",
        "feedback_metadata": {"conversation_id": "abc"},
    },
)

import os
from langchain_openai import ChatOpenAI
from stackone_ai import StackOneToolSet
# Initialize StackOne tools
toolset = StackOneToolSet()
account_id = os.getenv("STACKONE_ACCOUNT_ID")
tools = toolset.fetch_tools(actions=["workday_*"], account_ids=[account_id])
# Convert to LangChain format
langchain_tools = tools.to_langchain()
# Use with LangChain models
model = ChatOpenAI(model="gpt-5.4")
model_with_tools = model.bind_tools(langchain_tools)
# Execute AI-driven tool calls
response = model_with_tools.invoke("Get employee information for ID: emp123")
# Handle tool calls
for tool_call in response.tool_calls:
    tool = tools.get_tool(tool_call["name"])
    if tool:
        result = tool.execute(tool_call["args"])
        print(f"Result: {result}")

pip install 'stackone-ai[pydantic-ai]'

import os
from pydantic_ai import Agent
from stackone_ai import StackOneToolSet
toolset = StackOneToolSet()
tools = toolset.fetch_tools(
    actions=["workday_list_workers", "workday_get_worker"],
    account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
).to_pydantic_ai()
agent = Agent("openai:gpt-5.4", tools=tools)
result = agent.run_sync("List the first 5 employees")
print(result.output)

toolset = StackOneToolSet()
tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
# For agent-driven discovery, enable search on the constructor:
# toolset = StackOneToolSet(search={"method": "auto"})
# tools = toolset.pydantic_ai(mode="search_and_execute")

pip install langgraph langchain-openai

import os
from langchain_openai import ChatOpenAI
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import tools_condition
from stackone_ai import StackOneToolSet
from stackone_ai.integrations.langgraph import to_tool_node, bind_model_with_tools
# Prepare tools
toolset = StackOneToolSet()
account_id = os.getenv("STACKONE_ACCOUNT_ID")
tools = toolset.fetch_tools(actions=["workday_*"], account_ids=[account_id])
langchain_tools = tools.to_langchain()
class State(TypedDict):
    messages: Annotated[list, add_messages]
# Build a small agent loop: LLM -> maybe tools -> back to LLM
graph = StateGraph(State)
graph.add_node("tools", to_tool_node(langchain_tools))
def call_llm(state: dict):
    llm = ChatOpenAI(model="gpt-5.4")
    llm = bind_model_with_tools(llm, langchain_tools)
    resp = llm.invoke(state["messages"])  # returns AIMessage with optional tool_calls
    return {"messages": state["messages"] + [resp]}
graph.add_node("llm", call_llm)
graph.add_edge(START, "llm")
graph.add_conditional_edges("llm", tools_condition)
graph.add_edge("tools", "llm")
app = graph.compile()
_ = app.invoke({"messages": [("user", "Get employee with id emp123") ]})

import os
from crewai import Agent, Crew, Task
from stackone_ai import StackOneToolSet
# Get tools and convert to LangChain format
toolset = StackOneToolSet()
account_id = os.getenv("STACKONE_ACCOUNT_ID")
tools = toolset.fetch_tools(actions=["workday_*"], account_ids=[account_id])
langchain_tools = tools.to_langchain()
# Create CrewAI agent with StackOne tools
agent = Agent(
    role="HR Manager",
    goal="Analyze employee data and generate insights",
    backstory="Expert in HR analytics and employee management",
    tools=langchain_tools,
    llm="gpt-5.4"
)
# Define task and execute
task = Task(
    description="Find all employees in the engineering department",
    agent=agent,
    expected_output="List of engineering employees with their details"
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()

from stackone_ai import StackOneToolSet
toolset = StackOneToolSet()
# Get the feedback tool (included with "tool_*" pattern or all tools)
tools = toolset.fetch_tools(actions=["tool_*"])
feedback_tool = tools.get_tool("tool_feedback")
# Submit feedback (typically invoked by AI after user consent)
result = feedback_tool.call(
    feedback="The HRIS tools are working great! Very fast response times.",
    account_id="acc_123456",
    tool_names=["workday_list_workers", "workday_get_worker"]
)

import os
from stackone_ai import StackOneToolSet
# Get a callable search tool — search must be enabled on the toolset
toolset = StackOneToolSet(search={"method": "auto"})
account_id = os.getenv("STACKONE_ACCOUNT_ID")
search_tool = toolset.get_search_tool()
# Search for relevant tools — returns a Tools collection scoped to the account
tools = search_tool("manage employees", top_k=5, account_ids=[account_id])
# Execute a discovered tool directly
tools[0](limit=10)

import os
from stackone_ai import StackOneToolSet
# Search must be enabled on the constructor — pass `search={}` for defaults,
# or set a backend / top_k explicitly.
toolset = StackOneToolSet(search={"method": "auto"})
# Search by intent — returns Tools collection ready for any framework
account_id = os.getenv("STACKONE_ACCOUNT_ID")
tools = toolset.search_tools("manage employee records", account_ids=[account_id], top_k=5)
openai_tools = tools.to_openai()
# Lightweight: inspect results without fetching full tool definitions
results = toolset.search_action_names("time off requests", top_k=5)

# "auto" (default) — tries semantic search first, falls back to local
tools = toolset.search_tools("manage employees", search="auto")
# "semantic" — semantic API only, raises if unavailable
tools = toolset.search_tools("manage employees", search="semantic")
# "local" — local BM25+TF-IDF only, no semantic API call
tools = toolset.search_tools("manage employees", search="local")

# 1. Set up credentials
cp .env.example .env
# Edit .env with your API keys
# 2. Install dependencies
uv sync --all-extras
# 3. Run any example
uv run examples/search_tools.py

# Install Nix with flakes enabled (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
  sh -s -- install
# If flakes are not enabled, enable them with:
mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

# Automatic activation with direnv (recommended)
direnv allow
# Or manual activation
nix develop