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

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# 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](/agents/python/frameworks/openai-integration) for a full agent loop.

## Fetch Tools

When you need specific tools instead of search and execute:

```python theme={null}
tools = toolset.fetch_tools(account_ids=["your-account-id"])
openai_tools = tools.to_openai()
```

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

  <Accordion title="Multi-account usage">
    ```python theme={null}
    # 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")
    ```
  </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.

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

  <Accordion title="Error handling">
    ```python theme={null}
    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}")
    ```
  </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 `toolset.openai(mode="search_and_execute", account_ids=[...])`.

## Next Steps

* [OpenAI Integration](/agents/python/frameworks/openai-integration) for building agents with function calling
* [LangChain Integration](/agents/python/frameworks/langchain-integration) for framework-based workflows
* [Tool Search](/agents/python/tool-search) for natural language tool discovery
* [Tool Filtering](/agents/python/tool-filtering) for advanced filtering patterns