> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Usage

> Learn the fundamentals of using the StackOne TypeScript SDK for AI agents

## 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.

```typescript theme={null}
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](/agents/typescript/frameworks/openai-integration) for a full agent loop.

## Fetch Tools

When you need specific tools instead of search and execute:

```typescript theme={null}
const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();
```

<AccordionGroup>
  <Accordion title="Filtering by provider, action, or pattern">
    ```typescript theme={null}
    // 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](/agents/typescript/tool-filtering) for the full reference.
  </Accordion>

  <Accordion title="Multi-account usage">
    ```typescript theme={null}
    // 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}`);
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Tool Execution

<AccordionGroup>
  <Accordion title="Direct tool execution (for debugging)">
    Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

    ```typescript theme={null}
    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);
    }
    ```
  </Accordion>
</AccordionGroup>

## Environment Configuration

```bash theme={null}
export STACKONE_API_KEY=your_api_key
```

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

## Next Steps

* [OpenAI Integration](/agents/typescript/frameworks/openai-integration) for building agents with function calling
* [Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk) for streaming workflows
* [Tool Search](/agents/typescript/tool-search) for natural language tool discovery
* [Tool Filtering](/agents/typescript/tool-filtering) for advanced filtering patterns