From ed744e4f63391da72259786a5b4345a1869786ec Mon Sep 17 00:00:00 2001 From: S2D2 Date: Tue, 10 Nov 2026 20:41:02 +0000 Subject: [PATCH 1/3] fix(examples): exit non-zero when credentials are missing or nothing is listed CLAUDE.md says each example must fail loudly rather than succeed with an empty catalog. Four examples printed "Set X" and returned, exiting 0, and none checked for an empty tool list. They now raise SystemExit, as openai_integration.py already does, and langchain_integration.py reports StackOne errors like the other examples instead of a traceback. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- examples/auth_management.py | 6 ++---- examples/langchain_integration.py | 25 ++++++++++++++----------- examples/langgraph_integration.py | 16 ++++++---------- examples/pydantic_ai_integration.py | 8 +++++--- 4 files changed, 27 insertions(+), 28 deletions(-) diff --git a/examples/auth_management.py b/examples/auth_management.py index 983a14cc..2d616bcc 100644 --- a/examples/auth_management.py +++ b/examples/auth_management.py @@ -81,13 +81,11 @@ def per_tool_override(account_id: str) -> None: def main() -> None: api_key = os.getenv("STACKONE_API_KEY") if not api_key: - print("STACKONE_API_KEY is not set. Please export it or add it to .env") - return + raise SystemExit("STACKONE_API_KEY is not set. Please export it or add it to .env") account_id = os.getenv("STACKONE_ACCOUNT_ID") if not account_id: - print("Set STACKONE_ACCOUNT_ID to run this example.") - return + raise SystemExit("Set STACKONE_ACCOUNT_ID to run this example.") api_key_setup() single_account(account_id) diff --git a/examples/langchain_integration.py b/examples/langchain_integration.py index 7f87b30f..1be93620 100644 --- a/examples/langchain_integration.py +++ b/examples/langchain_integration.py @@ -9,6 +9,7 @@ from __future__ import annotations import os +import sys try: from dotenv import load_dotenv @@ -20,25 +21,22 @@ from langchain_openai import ChatOpenAI from stackone_ai import StackOneToolSet +from stackone_ai.types import StackOneAPIError, ToolsetError def langchain_integration() -> None: - account_id = os.getenv("STACKONE_ACCOUNT_ID") - if not os.getenv("STACKONE_API_KEY"): - print("Set STACKONE_API_KEY to run this example.") - return - if not account_id: - print("Set STACKONE_ACCOUNT_ID to run this example.") - return - if not os.getenv("OPENAI_API_KEY"): - print("Set OPENAI_API_KEY to run this example.") - return + for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]: + if not os.getenv(var): + raise SystemExit(f"Set {var} to run this example.") + account_id = os.environ["STACKONE_ACCOUNT_ID"] toolset = StackOneToolSet() tools = toolset.fetch_tools( actions=["*_list_*"], account_ids=[account_id], ) + if not tools: + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") # Convert to LangChain format langchain_tools = tools.to_langchain() @@ -66,4 +64,9 @@ def langchain_integration() -> None: if __name__ == "__main__": - langchain_integration() + try: + langchain_integration() + except ToolsetError as exc: + sys.exit(f"Could not load tools: {exc}") + except StackOneAPIError as exc: + sys.exit(f"Tool call rejected with {exc.status_code}: {exc.response_body}") diff --git a/examples/langgraph_integration.py b/examples/langgraph_integration.py index 9a899322..649c0baa 100644 --- a/examples/langgraph_integration.py +++ b/examples/langgraph_integration.py @@ -28,22 +28,18 @@ def langgraph_integration() -> None: - account_id = os.getenv("STACKONE_ACCOUNT_ID") - if not os.getenv("STACKONE_API_KEY"): - print("Set STACKONE_API_KEY to run this example.") - return - if not account_id: - print("Set STACKONE_ACCOUNT_ID to run this example.") - return - if not os.getenv("OPENAI_API_KEY"): - print("Set OPENAI_API_KEY to run this example.") - return + for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]: + if not os.getenv(var): + raise SystemExit(f"Set {var} to run this example.") + account_id = os.environ["STACKONE_ACCOUNT_ID"] toolset = StackOneToolSet() tools = toolset.fetch_tools( actions=["*_list_*"], account_ids=[account_id], ) + if not tools: + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") # LangGraph uses LangChain tools natively langchain_tools = tools.to_langchain() diff --git a/examples/pydantic_ai_integration.py b/examples/pydantic_ai_integration.py index 1ebe5d74..7c30d5e9 100644 --- a/examples/pydantic_ai_integration.py +++ b/examples/pydantic_ai_integration.py @@ -30,7 +30,10 @@ def individual_tools(account_id: str) -> None: """One Pydantic AI tool per action: suits a handful of actions.""" - tools = StackOneToolSet().fetch_tools(actions=["*_list_*"], account_ids=[account_id]).to_pydantic_ai() + listed = StackOneToolSet().fetch_tools(actions=["*_list_*"], account_ids=[account_id]) + if not listed: + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") + tools = listed.to_pydantic_ai() agent = Agent( "openai:gpt-5.4", @@ -62,8 +65,7 @@ def search_and_execute(account_id: str) -> None: def pydantic_ai_integration() -> None: for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]: if not os.getenv(var): - print(f"Set {var} to run this example.") - return + raise SystemExit(f"Set {var} to run this example.") account_id = os.environ["STACKONE_ACCOUNT_ID"] individual_tools(account_id) From 9fb20a8e4bdfedc5bdfb514a10861e4ff3565e9e Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 00:35:10 +0000 Subject: [PATCH 2/3] refactor(examples): keep one name for the fetched tools and align the env guards pydantic_ai_integration.py renamed the fetched tools to `listed` only so it could rebind `tools` to the converted list; converting inline at the Agent call keeps a single name, as the other examples do. The LangChain and LangGraph guards now leave the same blank line before reading the account id as the Pydantic AI one, so the three env checks read identically. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- examples/langchain_integration.py | 1 + examples/langgraph_integration.py | 1 + examples/pydantic_ai_integration.py | 7 +++---- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/examples/langchain_integration.py b/examples/langchain_integration.py index 1be93620..2a1b0f4b 100644 --- a/examples/langchain_integration.py +++ b/examples/langchain_integration.py @@ -28,6 +28,7 @@ def langchain_integration() -> None: for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]: if not os.getenv(var): raise SystemExit(f"Set {var} to run this example.") + account_id = os.environ["STACKONE_ACCOUNT_ID"] toolset = StackOneToolSet() diff --git a/examples/langgraph_integration.py b/examples/langgraph_integration.py index 649c0baa..4c1a3590 100644 --- a/examples/langgraph_integration.py +++ b/examples/langgraph_integration.py @@ -31,6 +31,7 @@ def langgraph_integration() -> None: for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]: if not os.getenv(var): raise SystemExit(f"Set {var} to run this example.") + account_id = os.environ["STACKONE_ACCOUNT_ID"] toolset = StackOneToolSet() diff --git a/examples/pydantic_ai_integration.py b/examples/pydantic_ai_integration.py index 7c30d5e9..1db35cd8 100644 --- a/examples/pydantic_ai_integration.py +++ b/examples/pydantic_ai_integration.py @@ -30,15 +30,14 @@ def individual_tools(account_id: str) -> None: """One Pydantic AI tool per action: suits a handful of actions.""" - listed = StackOneToolSet().fetch_tools(actions=["*_list_*"], account_ids=[account_id]) - if not listed: + tools = StackOneToolSet().fetch_tools(actions=["*_list_*"], account_ids=[account_id]) + if not tools: raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") - tools = listed.to_pydantic_ai() agent = Agent( "openai:gpt-5.4", system_prompt="You are a helpful assistant that answers by calling tools.", - tools=tools, + tools=tools.to_pydantic_ai(), ) result = agent.run_sync("Use one of your tools to list a few records, then summarise them.") print(f"Individual tools:\n{result.output}\n") From 31f4c6ed0e57d355482c59ae6361d45d065b8331 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 00:52:02 +0000 Subject: [PATCH 3/3] fix(examples): fail loudly on every empty catalog and StackOne error The search and execute half of the Pydantic AI example and the first two auth_management sections carried on with no tools. The Pydantic AI example had no StackOne error handling, the LangChain and LangGraph handlers missed ToolArgumentsError and labelled listing failures as rejected tool calls, and an unknown tool name in a LangChain tool call was skipped without a word. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- examples/auth_management.py | 6 +++++- examples/langchain_integration.py | 13 +++++++------ examples/langgraph_integration.py | 6 +++--- examples/pydantic_ai_integration.py | 15 ++++++++++++--- 4 files changed, 27 insertions(+), 13 deletions(-) diff --git a/examples/auth_management.py b/examples/auth_management.py index 2d616bcc..573453cf 100644 --- a/examples/auth_management.py +++ b/examples/auth_management.py @@ -44,6 +44,8 @@ def single_account(account_id: str) -> None: toolset = StackOneToolSet() tools = toolset.fetch_tools(actions=["*_list_*"], account_ids=[account_id]) + if not tools: + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") print(f"Fetched {len(tools)} tools for configured account") @@ -56,6 +58,8 @@ def set_accounts_globally(account_id: str) -> None: print("Set global accounts via set_accounts()") tools = toolset.fetch_tools(actions=["*_list_*"]) + if not tools: + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") print(f"Fetched {len(tools)} tools (account inherited from toolset)") @@ -66,7 +70,7 @@ def per_tool_override(account_id: str) -> None: toolset = StackOneToolSet() tools = toolset.fetch_tools(actions=["*_list_*"], account_ids=[account_id]) if not tools: - raise SystemExit(f"Account {account_id} served no list tools — nothing to demonstrate.") + raise SystemExit(f"Account {account_id} served no list tools, so the example would prove nothing.") # Override on the entire tools collection tools.set_account_id("overridden-account") diff --git a/examples/langchain_integration.py b/examples/langchain_integration.py index 2a1b0f4b..750d5d6a 100644 --- a/examples/langchain_integration.py +++ b/examples/langchain_integration.py @@ -21,7 +21,7 @@ from langchain_openai import ChatOpenAI from stackone_ai import StackOneToolSet -from stackone_ai.types import StackOneAPIError, ToolsetError +from stackone_ai.types import StackOneError, ToolsetError def langchain_integration() -> None: @@ -57,9 +57,10 @@ def langchain_integration() -> None: for tool_call in result.tool_calls: print(f" - {tool_call['name']}({tool_call['args']})") tool = tools.get_tool(tool_call["name"]) - if tool: - call_result = tool.execute(tool_call["args"]) - print(f" Result: {str(call_result)[:200]}...") + if tool is None: + raise SystemExit(f"The model called {tool_call['name']}, which is not a fetched tool.") + call_result = tool.execute(tool_call["args"]) + print(f" Result: {str(call_result)[:200]}...") else: print("No tool calls were made by the model.") @@ -69,5 +70,5 @@ def langchain_integration() -> None: langchain_integration() except ToolsetError as exc: sys.exit(f"Could not load tools: {exc}") - except StackOneAPIError as exc: - sys.exit(f"Tool call rejected with {exc.status_code}: {exc.response_body}") + except StackOneError as exc: + sys.exit(f"StackOne API error: {exc}") diff --git a/examples/langgraph_integration.py b/examples/langgraph_integration.py index 4c1a3590..be9df6c8 100644 --- a/examples/langgraph_integration.py +++ b/examples/langgraph_integration.py @@ -24,7 +24,7 @@ from langchain_openai import ChatOpenAI from stackone_ai import StackOneToolSet -from stackone_ai.types import StackOneAPIError, ToolsetError +from stackone_ai.types import StackOneError, ToolsetError def langgraph_integration() -> None: @@ -77,5 +77,5 @@ def langgraph_integration() -> None: langgraph_integration() except ToolsetError as exc: sys.exit(f"Could not load tools: {exc}") - except StackOneAPIError as exc: - sys.exit(f"Tool call rejected with {exc.status_code}: {exc.response_body}") + except StackOneError as exc: + sys.exit(f"StackOne API error: {exc}") diff --git a/examples/pydantic_ai_integration.py b/examples/pydantic_ai_integration.py index 1db35cd8..eee9c909 100644 --- a/examples/pydantic_ai_integration.py +++ b/examples/pydantic_ai_integration.py @@ -11,6 +11,7 @@ from __future__ import annotations import os +import sys try: from dotenv import load_dotenv @@ -26,6 +27,7 @@ raise SystemExit(1) from None from stackone_ai import StackOneToolSet +from stackone_ai.types import StackOneError, ToolsetError def individual_tools(account_id: str) -> None: @@ -46,7 +48,9 @@ def individual_tools(account_id: str) -> None: def search_and_execute(account_id: str) -> None: """StackOne's search and execute tools: the model finds an action, then runs it.""" toolset = StackOneToolSet(tool_mode="search_execute") - tools = toolset.fetch_tools(account_ids=[account_id]).to_pydantic_ai() + tools = toolset.fetch_tools(account_ids=[account_id]) + if not tools: + raise SystemExit(f"Account {account_id} served no search and execute tools.") agent = Agent( "openai:gpt-5.4", @@ -55,7 +59,7 @@ def search_and_execute(account_id: str) -> None: "then call stackone_execute_action with its action_id and arguments built from its " "example_request." ), - tools=tools, + tools=tools.to_pydantic_ai(), ) result = agent.run_sync("List a few records from any of my connected apps, then summarise them.") print(f"Search and execute:\n{result.output}") @@ -72,4 +76,9 @@ def pydantic_ai_integration() -> None: if __name__ == "__main__": - pydantic_ai_integration() + try: + pydantic_ai_integration() + except ToolsetError as exc: + sys.exit(f"Could not load tools: {exc}") + except StackOneError as exc: + sys.exit(f"StackOne API error: {exc}")