LangGraph Agent Integration

Relevant source files

The following files were used as context for generating this wiki page:

• examples/langgraph_integration.py
• README.md
• CLAUDE.md
• stackone_ai/types.py
• tests/test_models.py
• tests/test_fetch_tools.py

LangGraph Agent Integration enables StackOne tools to operate within LangGraph's circular agent workflows. It converts StackOne's unified SaaS action catalog into LangChain-compatible tools that LangGraph agents consume natively.

This integration allows AI agents to discover, list, and execute actions across multiple SaaS providers (like BambooHR or Workday) using a single unified interface. The system ensures that the JSON Schema provided to the agent exactly matches the schema required by the StackOne API.

Sources: examples/langgraph_integration.py:1-13, README.md:12-25, CLAUDE.md:10-15

Integration Workflow

The integration follows a structured flow from tool discovery to agent execution. You initialize a toolset, fetch specific tools via filters, convert them to the LangChain format, and bind them to a LangGraph ReAct agent.

The diagram shows the transformation of StackOne tools into executable LangGraph agent tools.
Sources: examples/langgraph_integration.py:39-56, README.md:100-112

1. Tool Discovery and Fetching

The StackOneToolSet class manages account discovery and tool retrieval. It identifies active accounts using the STACKONE_API_KEY and allows filtering by provider or action patterns.

• fetch_tools(actions, account_ids): Retrieves a filtered collection of tools from the StackOne MCP (Model Context Protocol) server.
• Filtering: Supports case-sensitive globs for actions (e.g., *_list_*) and case-insensitive provider prefixes.

Sources: examples/langgraph_integration.py:40-44, README.md:120-135, CLAUDE.md:25-30

2. Framework Conversion

Because LangGraph uses LangChain tools natively, the SDK provides the to_langchain() method. This converter passes the served schema through verbatim, preserving constraints, enums, and nested fields.

• Schema Fidelity: The conversion strips internal markers like nullable and translates them to standard JSON Schema required lists.
• Argument Shaping: LangChain tools generated this way use flat-prefixed argument shapes (e.g., body_variables, path_id).

Sources: tests/test_models.py:340-365, CLAUDE.md:140-148, README.md:155-165

Robust Error Handling

In agentic workflows, model-generated arguments often contain errors. The integration handles these by passing execution failures back to the agent rather than terminating the graph.

The sequence diagram illustrates how the handle_tool_error property enables agent self-correction during tool execution.
Sources: examples/langgraph_integration.py:47-53, tests/test_fetch_tools.py:490-505

Error Configuration

Feature	Implementation	Description
handle_tool_error	tool.handle_tool_error = True	Returns the server's error message to the model for retries.
StackOneAPIError	types.StackOneAPIError	Contains status_code and response_body for diagnostics.
Retry Logic	Native to ReAct agent	Agent interprets the 400 error and fixes the offending field.

Sources: examples/langgraph_integration.py:47-53, stackone_ai/types.py:53-60

Implementation Example

The following snippet demonstrates the standard setup for a LangGraph agent using StackOne tools.

# Initialize toolset
toolset = StackOneToolSet()
tools = toolset.fetch_tools(actions=["*_list_*"], account_ids=[account_id])

# Convert and configure for LangGraph
langchain_tools = tools.to_langchain()
for tool in langchain_tools:
    tool.handle_tool_error = True

# Create ReAct agent
model = ChatOpenAI(model="gpt-5.4")
agent = create_agent(model, langchain_tools)

Sources: examples/langgraph_integration.py:39-56

Summary of Components

Component	Role	Source File
StackOneToolSet	Manages auth, accounts, and catalog caching.	toolset.py / CLAUDE.md
Tools	Container for retrieved actions; provides conversion methods.	tools.py / tests/test_models.py
to_langchain()	Converts StackOne tools to langchain_core.tools.BaseTool.	tests/test_models.py
ParameterLocation	Defines where arguments (PATH, QUERY, BODY) reside.	stackone_ai/types.py

Sources: CLAUDE.md:18-24, stackone_ai/types.py:89-96, tests/test_models.py:126-140

LangGraph Agent Integration provides a resilient path for LLMs to interact with complex SaaS ecosystems. By maintaining schema integrity and enabling error-driven retries, it ensures agents can navigate diverse API requirements without manual hardcoding of tool definitions.

Sources: README.md:15-25, examples/langgraph_integration.py:70-75