LangChain Integration
Relevant source files
The following files were used as context for generating this wiki page:
LangChain Integration provides a mechanism to convert StackOne tools into native LangChain tool objects. This allows developers to incorporate SaaS functionality into LangChain agents and chains using Large Language Models (LLMs) like OpenAI. The integration ensures that complex schemas, including nested objects and enums, remain intact during the conversion process to provide the LLM with accurate tool descriptions.
Sources: README.md:104-106, CLAUDE.md:15-20, tests/test_models.py:397-400
Integration Workflow
The integration follows a structured flow from tool discovery to execution. You first fetch tools from the StackOne catalog and then convert them for use within the LangChain ecosystem.
Integration Lifecycle
The following diagram illustrates the lifecycle of a tool from the StackOne catalog through LangChain conversion and final execution by an LLM.
The flow shows how tools move from the initial StackOne discovery phase into the LangChain framework for model interaction.
Sources: examples/langchain_integration.py:38-66, README.md:108-120
Execution Sequence
This sequence diagram details the communication between the developer's application, the LangChain model, and the StackOne SDK during a tool call.
The sequence demonstrates the separation of tool definition (handled by the SDK) and tool invocation (driven by the LLM).
Sources: examples/langchain_integration.py:46-64, CLAUDE.md:27-35
Key Components and Methods
The integration relies on specific methods within the Tools container and individual StackOneTool objects to facilitate compatibility.
Essential Methods
| Method | Actor | Purpose |
|---|---|---|
fetch_tools() | StackOneToolSet | Retrieves a filtered set of tools from the MCP server. |
to_langchain() | Tools | Converts the entire collection of fetched tools into a list of LangChain BaseTool objects. |
get_tool(name) | Tools | Retrieves a specific StackOneTool from the container by its string identifier. |
execute(args) | StackOneTool | Performs the actual API request to StackOne using the arguments provided by the LLM. |
Sources: CLAUDE.md:27-32, examples/langchain_integration.py:47-59, README.md:112-115
Schema Preservation Logic
The integration ensures that the LLM receives the full schema served by the StackOne API. Unlike generic converters that might lose detail, StackOne's implementation preserves:
- Nested Objects: Fields within nested structures remain visible to the model.
- Constraints: Minimums, maximums, and patterns are passed through.
- Enums: Valid string options are explicitly defined in the LangChain tool schema.
- Requiredness: The SDK's internal
nullablemarkers are correctly translated into JSON Schemarequiredlists.
Sources: tests/test_models.py:408-425, CLAUDE.md:129-135
Error Handling in LangChain
When integrating with LangChain or LangGraph, robust error handling prevents a single malformed tool call from terminating the entire process.
Tool Error Handling
LangChain tools created by the SDK can be configured to return errors to the model rather than raising exceptions. By setting handle_tool_error = True on a converted tool, the LLM can receive the error message (such as a missing required field) and attempt to fix the arguments in a subsequent turn.
langchain_tools = tools.to_langchain()
for tool in langchain_tools:
# Allows the agent to read the error and retry
tool.handle_tool_error = True
Sources: examples/langgraph_integration.py:53-57, tests/test_models.py:520-525
Error Hierarchy
The SDK uses a specific hierarchy for exceptions that may occur during LangChain operations.
| Exception | Cause |
|---|---|
StackOneAPIError | Raised when the StackOne API returns a non-200 status code (e.g., 400 Bad Request). |
ToolsetLoadError | Raised if tool discovery fails (e.g., no accounts returned tools). |
StackOneError | The base class for all SDK-related exceptions; use this to catch all integration errors. |
Sources: stackone_ai/types.py:40-66, tests/test_fetch_tools.py:645-655
LangGraph Compatibility
LangGraph consumes LangChain tools natively. The to_langchain() adapter allows StackOne tools to be used directly within LangGraph ReAct agents. Because models may guess arguments incorrectly, providing the full served schema is critical for the agent's reasoning capabilities within a graph.
Sources: examples/langgraph_integration.py:47-65, README.md:143-156
Summary
LangChain Integration maps the StackOne SaaS tool catalog to the LangChain ecosystem. By using fetch_tools() followed by to_langchain(), developers can provide LLMs with hundreds of SaaS actions. The integration prioritizes schema fidelity, ensuring that the model understands complex parameter requirements, while offering error handling mechanisms that allow agents to recover from invalid API calls.
Sources: README.md:11-20, CLAUDE.md:129-138