Skip to main content

​
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. 
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();

// Your agent gets 2 tools: tool_search + tool_execute
const tools = toolset.getTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();
Pass openaiTools 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: 
const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();

// Filter by providers
const byProviders = await toolset.fetchTools({
  providers: ["hibob", "workday"],
  accountIds: ["your-account-id"],
});

// Filter by actions with exact match
const byActions = await toolset.fetchTools({
  actions: ["hibob_list_employees", "hibob_create_employees"],
  accountIds: ["your-account-id"],
});

// Filter by actions with glob patterns
const byGlob = await toolset.fetchTools({
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});

// Combine multiple filters
const combined = await toolset.fetchTools({
  providers: ["hibob"],
  actions: ["*_list_*"],
  accountIds: ["your-account-id"],
});
See Tool Filtering for the full reference.
// Set accounts on the toolset for all subsequent calls
toolset.setAccounts(["account-123", "account-456"]);
const tools = await toolset.fetchTools();

// Or pass account IDs per request
const toolsDirect = await toolset.fetchTools({
  accountIds: ["account-123", "account-456"],
});

// Loop over customer accounts dynamically
const customerAccounts = ["account-1", "account-2", "account-3"];

for (const accountId of customerAccounts) {
  const tools = await toolset.fetchTools({
    actions: ["workday_list_workers"],
    accountIds: [accountId],
  });
  const employeeTool = tools.getTool("workday_list_workers");
  if (employeeTool) {
    const employees = await employeeTool.execute({});
    console.log(`Found employees for ${accountId}`);
  }
}

​
Tool Execution

Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.
const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const employeeTool = tools.getTool("workday_list_workers");

if (employeeTool) {
  const result = await employeeTool.execute({
    query: { limit: 10 },
  });
  console.log(result);
}

​
Environment Configuration

export STACKONE_API_KEY=your_api_key
Account IDs are passed per-request when fetching tools or via getTools({ accountIds: [...] }).

​
Next Steps