> ## 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.
# LangChain
> Build AI agents with StackOne tools and LangChain framework
export const GitHubCode = ({url, lang, title, children}) => {
const urlMatch = url?.match(/https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/blob\/([^\/]+)\/(.+?)(?:#L(\d+)(?:-L(\d+))?)?$/);
const owner = urlMatch?.[1];
const repo = urlMatch?.[2];
const branch = urlMatch?.[3];
const filePath = urlMatch?.[4];
const startLine = urlMatch?.[5];
const endLine = urlMatch?.[6];
const getDisplayTitle = () => {
if (title) return title;
if (!filePath) return 'source';
const parts = filePath.split('/');
if (parts.length >= 2) {
return parts.slice(-2).join('/');
}
return parts[parts.length - 1];
};
const displayPath = filePath || 'source';
const displayTitle = getDisplayTitle();
const lineInfo = startLine ? endLine ? `#L${startLine}-L${endLine}` : `#L${startLine}` : '';
const fullUrl = url + (lineInfo && !url.includes('#L') ? lineInfo : '');
const encodedUrl = encodeURIComponent(fullUrl);
const iframeSrc = `https://emgithub.com/iframe.html?target=${encodedUrl}&style=github&type=code&showBorder=on&showLineNumbers=on&showFileMeta=on`;
return ;
};
Build AI agents using LangChain's framework with direct access to business data through StackOne's infrastructure of pre-built tools, RPC orchestration, and MCP/A2A interfaces.
**Supported languages:** Python.
* **ReAct and OpenAI Functions** agents with business tool access
* **Multi-step workflow** automation
* **Conversational agents** with memory
* **Advanced error handling** and resilience
## Calling actions
```bash theme={null}
# Requires Python 3.10 or higher
# uv or pip
# Using uv (recommended)
uv add 'stackone-ai[mcp]' langchain langchain-openai
# Using pip
pip install 'stackone-ai[mcp]' langchain langchain-openai
# Optional: install with example dependencies
uv add 'stackone-ai[mcp,examples]'
pip install 'stackone-ai[mcp,examples]'
export STACKONE_API_KEY=your_api_key_here
```
Two approaches to retrieving tools:
1. [Fetch Tools (with filtering)](/features/tool-discovery#tool-filtering) — fetch all tools upfront with optional filters applied.
2. [Search & Execute](/features/tool-discovery#search-and-execute) — hand the model just `tool_search` + `tool_execute` and let the agent discover what it needs at runtime.
See [Tool Discovery](/features/tool-discovery) for more details on which may be best in your scenario.
By default this fetches every tool enabled for the account. Narrow it by passing `providers` (specific connectors) or `actions` — exact names or glob patterns (e.g. `workday_*`, or `*_list_*` for read-only tools).
```python theme={null}
from stackone_ai import StackOneToolSet
# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"
# Initialize toolset
toolset = StackOneToolSet()
# Fetch tools dynamically for this account.
# Optionally narrow the fetch with filters:
# providers=["hibob", "workday"] — only these connectors
# actions=["*_list_*", "*_get_*"] — glob patterns, e.g. read-only actions
tools = toolset.fetch_tools(account_ids=[account_id])
# Convert to LangChain format
langchain_tools = tools.to_langchain()
```
The LLM receives only 2 tools and searches the catalog autonomously:
```python theme={null}
from stackone_ai import StackOneToolSet
toolset = StackOneToolSet(
search={"method": "semantic", "top_k": 3},
execute={"account_ids": ["your-account-id"]},
)
# LLM receives only 2 tools - framework handles execution.
# .langchain() returns LangChain tools directly, so no conversion is needed
langchain_tools = toolset.langchain(mode="search_and_execute")
```
Bind the tools to your model, invoke it, and execute any tool calls:
```python theme={null}
from langchain_openai import ChatOpenAI
# Create model with tools
model = ChatOpenAI(model="gpt-5.4")
model_with_tools = model.bind_tools(langchain_tools)
# Use the agent
response = model_with_tools.invoke("List all employees in engineering")
# Handle tool execution
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}")
```
Bind the two meta tools the same way — the model calls `tool_search` first, then `tool_execute`:
```python theme={null}
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-5.4").bind_tools(langchain_tools)
response = model.invoke("List my upcoming Calendly events for the next week.")
```
## Example
### Multi-account usage
Each tool execution runs against a specific customer account. Set account IDs once on the toolset, or pass them per request.
```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")
```
```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}")
```
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 the dict directly (it isn't wrapped in a result object), so read its values with dict keys like `result["content"]`.
```python theme={null}
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.
## Troubleshooting
### Execute a tool
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)
```
## Next steps
Diagnose failing calls and monitor what your agent runs.
Protect your agent from malicious content in tool results.