refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback()
refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback()
main
Brings the Python SDK to parity with node #383. Every tool call goes over MCP tools/call, and GET /accounts is the only request outside MCP. The migration guide covers every breaking change since 2.10.1, including those from #199.
Changes
MCP-only execution
- Per-action tools execute over
tools/callon the endpoint and account that listed them, with the model's arguments sent unchanged. The server maps them itself. - Removed:
- the
/actions/rpcclient; - the envelope splitting;
- the base httpx executor;
- binary download handling and filename cleanup;
- the
param-style=flat_prefixedpin.
- the
- A tool returns the server's result exactly as the server wrote it:
{isError: false, result, defenderMetadata?, policyMetadata?}for action tools, bare JSON for search.isErrorstill raisesStackOneAPIErrorwith the status from its payload. - A file action returns UCA's single-use download link as
result, or raises with status 501 when no link can be issued. tools/callis now sent without themcpclient's extratools/list. Its output-schema check relisted the whole catalog before every call, and the Node SDK never did that.- The transport uses
streamable_http_client; the deprecatedstreamablehttp_clientwarned on every call.
Header arguments
- A header argument is an entry of a nested
headersobject or a top-levelheaders_<name>. Each is forwarded only if the served schema declares it in the same form. An openheadersobject (noproperties, as*_execute_actionserves it) declares every name. Authorization,x-account-idandUser-Agentare never forwarded. The warning says whether a header was undeclared or set by the SDK. Every other argument is sent unchanged.- As a result,
toolset.execute()now forwards host-set headers through the openheadersobject.
Feedback and sessions
stackone_submit_feedbackgoes overtools/callonly, and is listed once however many accounts serve it.submit_feedback()lists one account insearch_executemode and makes onetools/call, through the lowest account id in scope (not the first given, norGET /accountsorder). It takes an optionalaction_run_id, sent only when given.- The search
session_idis on every hit, and is forwarded byexecute(..., session_id=)andsubmit_feedback(). A pinnedaction_id/session_idis moved to the end of the arguments.
Matches Node exactly
- The served
requiredis emitted verbatim and in the served order, and an empty one is omitted. - A
tools/callresult with onlystructuredContentis returned instead of coming back as{}. Tools.get_tool()returns the first tool listed under a duplicated name, like Node'sgetTool().- The test mock serves schemas verbatim from a low-level MCP
Server. The old one listedproperties: {}for every per-action tool.
Also
FeedbackRating,FeedbackCategory,FeedbackSourceandStackOneMcpToolare exported fromstackone_ai.submit_feedback(tool_names=)takes any sequence of strings, but not a barestr.- The base
StackOneToolno longer requires_api_key. - A PR-title check mirrors the Node SDK's.
Review fixes
- A 429 is retried only when the wait ends before the request's deadline: the MCP exchange's
timeout, or the toolsettimeoutfrom the first attempt forGET /accounts. Otherwise the 429 is raised at once, so a multi-account call can't time out a throttled account into a partial catalog. - An MCP timeout says "timed out after Ns" instead of "RuntimeError: no running event loop".
- Nested header values are written as Node's
headerTextwrites them (true,1, compact JSON). Header names are trimmed as JavaScript'strim()trims them. - Unusable arguments raise the new
ToolArgumentsError, aStackOneErrorand aValueError.ToolParameters.requiredis declared. An account id that is not a string is rejected. An account list fetched acrossclear_catalog_cache()is discarded. ARetry-Afterdate that overflows falls back to the backoff.
Second review round (decided once with node #383 and sdk-conformance)
KeyboardInterruptandSystemExitpropagate out of an MCP request; onlyExceptionbecomes aToolsetLoadError.- The
langchainextra requireslangchain-core>=0.3.36, the first that takes a dictargs_schema. - A root
typethat is not a string, such as["object", "null"], is read as"object", as Node does, instead of"['object', 'null']". - A timeout on a request retried after a 429 is that 429 (
StackOneAPIError429, fatal to a multi-account call), on MCP andGET /accounts, worded as Node words it. - Non-text content parts (image, audio, resource) are returned under
content_partsas plain JSON, sojson.dumpsandexecute_openai_tool_calls()work. - Search hits carry the
account_idthat found them;top_klimits the merged, globally sorted list; the same action on two accounts is two hits. execute()raisesToolsetConfigErrorwhen the action's connector is linked on more than one account in scope; a hit'saccount_idinaccount_idsroutes to it.to_openai(),to_langchain()andto_pydantic_ai()keep the first tool of each name (the lowest account id) and warn once.- When some accounts fail to list, the healthy accounts' listings are cached and a failed account is retried only after
FAILED_ACCOUNT_RETRY_SECONDS(30). When every account fails, the sharedStackOneAPIErroris raised if they all have one status, else aToolsetLoadErrorraised from anExceptionGroupof the failures, which it also keeps in.failures. - Constructing a toolset with no account while
STACKONE_ACCOUNT_IDis set warns that it is ignored. - Every
GET /accounts(discovery orfetch_accounts()) records theorigin_usernameof each account withshared: false, and every MCP request for that account carries it asx-end-user-id, set after caller headers. Explicit account ids make noGET /accounts. A model-suppliedx-end-user-idheader argument is dropped as set by the SDK. - Tests pin the partial-failure caching, the move of a pinned
session_idto the end inexecute()and the SDK-owned-name filter onheaders=in_prepare_headers; each fails under its mutation.
CI: the conformance pin moves to sdk-conformance ec4dcfb (StackOneHQ/sdk-conformance#5), which grades all of the above, and the conformance job now runs the full suite with the Node SDK (NODE_SDK_REF, refactor/mcp-only-toolset until node #383 merges) beside this one.
Verification
- 815 tests pass;
ruff check,ruff format --checkandty(package and examples) are clean, anduv lock --lockedpasses. The MIGRATION.md hand-built-tool recipe passestyand pyright. tests/vectors/is byte-identical to sdk-conformance7347926, the pinned commit, and every shared vector case passes.- The full conformance suite at
7347926(pnpm test -- --strict-schema, both SDKs, with Node atc2b8736) passes: 139 checks, and all 68 scenarios give identical results in Python and Node, warnings included. CI runs the same full suite against a pinned Node commit. - The override block below was run through release-please 17.11.2's
parseConventionalCommits: 45 entries, 23 breaking, eachBREAKING CHANGEnote on its own entry and none on the others, no junk entries, and next version 3.0.0 from 2.10.1. It covers #199's breaking changes too, except the removal ofStackOneTool.connectorandTools.get_connectors(), which #199's own squash commit already carries as aBREAKING CHANGEfooter.
BEGIN_COMMIT_OVERRIDE
refactor: execute every tool over MCP tools/call
BREAKING CHANGE: StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation, validate_method, is_json_content_type and filename_from_content_disposition are removed. Every tool fetch_tools() returns is a StackOneMcpTool that executes over MCP tools/call on the endpoint and account that listed it, with its arguments sent unchanged; nothing posts to /actions/rpc.
refactor(tools): remove the HTTP executor from the base StackOneTool
BREAKING CHANGE: StackOneTool.execute() no longer makes HTTP requests. On the base class it raises StackOneError, so a hand-built tool must override execute().
refactor(types): reduce ExecuteConfig to name, headers and timeout
BREAKING CHANGE: ExecuteConfig is extra="forbid" and keeps only name, headers and timeout. Passing method, url, body_type or parameter_locations raises a pydantic ValidationError.
refactor(toolset): return every result exactly as the server wrote it
BREAKING CHANGE: StackOneToolSet.execute() and tool.execute() return the server's {isError, result, defenderMetadata?, policyMetadata?} object rather than the unwrapped payload or the /actions/rpc body, so result["data"] becomes result["result"]["data"].
refactor(tools): return a download link from file actions
BREAKING CHANGE: a file action returns {download_url, expires_at, file} as result instead of {content, content_type, status_code, headers, file_name}, and raises StackOneAPIError with status 501 when no link can be issued. Tools.execute_openai_tool_calls() no longer base64-encodes bytes.
refactor(toolset): stop pinning param-style=flat_prefixed on the MCP endpoint
BREAKING CHANGE: the /mcp URL no longer carries ?param-style=flat_prefixed, so per-action tools from fetch_tools() take whichever argument style the server serves by default instead of flat, prefixed keys such as body_variables.
refactor(tools): treat StackOneMcpTool headers as extra headers
BREAKING CHANGE: StackOneMcpTool(headers=...) is now optional and means extra request headers, not the full header set. The SDK always sets Authorization, x-account-id and User-Agent itself, after them.
fix(tools): emit the served required list in served order
BREAKING CHANGE: to_openai_function() no longer derives required from the per-property nullable markers. It emits the served root required list verbatim, in the served order, and omits it when absent or empty, so a hand-built ToolParameters without required now has no required fields.
fix(toolset): route stackone_submit_feedback over MCP and list it once
BREAKING CHANGE: fetch_tools(), openai(), langchain() and pydantic_ai() include the stackone_submit_feedback tool, once, whenever the server serves it.
fix(tools): guard every header argument by its own declaration
BREAKING CHANGE: a top-level headers_<name> argument is dropped unless the tool's schema declares that property, and always for Authorization, x-account-id and User-Agent. A declared flat headers_<name> property no longer admits the same name inside a nested headers object. An open headers object, as *_execute_action serves it, forwards any other header, so StackOneToolSet.execute(..., {"headers": {...}}) passes host-set headers through where it previously dropped them all. A top-level headers argument that isn't a plain object is dropped too, unless the schema declares headers itself as a non-object field, in which case it is an ordinary argument sent as given. A declared flat headers_<name> argument whose value is a list or dict is dropped as well; only a string, number or boolean can be a header value.
fix(tools): return the first listing from get_tool(), as Node does
BREAKING CHANGE: when more than one account serves a tool name, Tools.get_tool() returns the first one listed (listings merge in sorted account order) rather than the last.
build: require Python 3.11 or later
BREAKING CHANGE: Python 3.10 is no longer supported. stackone-ai requires Python 3.11 or later.
build: make mcp a core dependency and remove the mcp extra
BREAKING CHANGE: the stackone-ai[mcp] extra no longer exists. mcp is a core dependency, so install plain stackone-ai.
build: make langchain-core an optional dependency
BREAKING CHANGE: langchain-core is no longer installed with stackone-ai. StackOneTool.to_langchain(), Tools.to_langchain() and StackOneToolSet.langchain() need the stackone-ai[langchain] extra, which requires langchain-core 0.3.36 or later, and raise an ImportError that names it without it.
refactor: split stackone_ai.models into stackone_ai.tools and stackone_ai.types
BREAKING CHANGE: stackone_ai.models, stackone_ai.constants and stackone_ai.utils no longer exist. Import StackOneTool and Tools from stackone_ai.tools; ToolParameters, ExecuteConfig, DEFAULT_BASE_URL and the errors from stackone_ai.types; or any public name from stackone_ai. ToolDefinition and DEFAULT_HYBRID_ALPHA are removed.
refactor(toolset): remove client-side search
BREAKING CHANGE: client-side search is removed: SearchConfig, SearchMode, SearchTool, SemanticSearchClient, SemanticSearchResult, SemanticSearchResponse and SemanticSearchError, the search= constructor argument, search_tools(), search_action_names(), get_search_tool(), semantic_client, the tool_search and tool_execute meta tools, and the bm25s and numpy dependencies. StackOneToolSet.search() runs the server's *_search_actions tools instead.
refactor: remove stackone_ai.integrations
BREAKING CHANGE: stackone_ai.integrations, with to_tool_node(), to_tool_executor(), bind_model_with_tools() and create_react_agent(), is removed. Pass tools.to_langchain() to LangGraph's own ToolNode and bind_tools().
refactor(tools): remove the client-side feedback tool
BREAKING CHANGE: the tool_feedback tool, stackone_ai.feedback, create_feedback_tool() and the implicit feedback_* execution options are removed, and StackOneTool.execute() and call() no longer take options=. Use StackOneToolSet.submit_feedback() and a search hit's session_id instead.
refactor(toolset): run an action by id with execute()
BREAKING CHANGE: StackOneToolSet.execute() takes (action_id, arguments=None, *, account_ids=None, session_id=None) instead of a meta tool name with arguments as a JSON string or dict. arguments must be a dict in the nested form an action's example_request shows, and a failure raises (ToolsetConfigError, ToolArgumentsError, ToolsetLoadError or StackOneAPIError) instead of returning {"error": ...}.
refactor(tools): pass the served schema through to every adapter
BREAKING CHANGE: to_openai_function(), to_langchain() and to_pydantic_ai_tool() give the model the served JSON Schema instead of only type, description, enum and a shallow copy of items and properties, so format, pattern, default, bounds, oneOf/anyOf and nested required reach it. to_langchain() sets that schema as args_schema instead of a pydantic model built from it.
refactor(toolset): remove mode= from openai(), langchain() and pydantic_ai()
BREAKING CHANGE: openai(), langchain() and pydantic_ai() no longer take mode=. Set tool_mode="search_execute" on StackOneToolSet to give a model the server's search and execute tools.
fix(toolset): reject an empty or non-string account id
BREAKING CHANGE: StackOneToolSet(account_id="") raises ToolsetConfigError instead of being treated as no account, which now lists every active account, so an account id read from an environment variable that is set but empty raises. An empty or non-string entry in account_ids, set_accounts() or execute={"account_ids": [...]} raises too, instead of being sent with no x-account-id.
feat(toolset): link calls with session_id and add submit_feedback()
fix(toolset): send feedback once, through the first account
fix(toolset): move a pinned action_id and session_id to the end of the arguments
fix(tools): return structuredContent from a tools/call result with no text
fix(tools): send tools/call without relisting the catalog first
feat: export the feedback types and StackOneMcpTool, and take any sequence of tool names
refactor(tools): make the base StackOneTool's API key optional
feat: retry HTTP 429 on every request, honouring Retry-After, and raise a 429 that outlasts the retries or the timeout instead of skipping the account
feat(tools): raise ToolArgumentsError, a StackOneError and a ValueError, for unusable tool arguments
fix(types): declare ToolParameters.required so a hand-built tool type-checks
fix(tools): write nested header values as Node writes them
fix(tools): report an MCP timeout as a timeout
feat(toolset): read STACKONE_BASE_URL
fix(toolset): accept account ids only as a list
BREAKING CHANGE: account_ids, set_accounts() and execute={"account_ids": ...} accept only a list of strings. A tuple or any other non-list, which 2.10.1 accepted, raises ToolsetConfigError; pass list(ids) instead.
feat(toolset): tag each search hit with its account_id and apply top_k to the merged ranking
fix(toolset): refuse an action whose connector is linked on more than one account
fix(tools): build every adapter from the first tool of each name
fix(toolset): cache the healthy accounts when one fails, and retry a failed one after 30 seconds
fix(toolset): raise the shared error when every account fails, and keep each failure
feat(toolset): add action_run_id to submit_feedback(), and send feedback through the lowest account id
feat(toolset): warn when STACKONE_ACCOUNT_ID is set but ignored
feat(toolset): send x-end-user-id for non-shared accounts
feat(toolset): add a headers option sent on every request
feat(toolset): skip non-shared accounts during discovery unless include_non_shared
fix(toolset): refuse to execute while a matching account failed to list
fix(toolset): look up a non-shared account's end user when the API asks for it
fix(toolset): re-list only the failed accounts that could serve the action in execute()
fix(toolset): learn a failed account's provider with one GET /accounts before execute() refuses
fix(toolset): chain a failed end-user lookup onto the 400 it was looking up for
fix(toolset): raise when every active account on the key is non-shared and not opted in
fix(toolset): name shared accounts in the STACKONE_ACCOUNT_ID warning
fix(tools): keep a retried 429 on record while another request in the exchange is answered
A timeout on a tools/list retried after a 429 is reported as that 429, even when another request in the MCP exchange is answered meanwhile, rather than as a plain timeout that skips the account.
fix(toolset): hold a provider lookup's miss for the failed-account window in execute()
When GET /accounts fails to name a failed account, execute() neither looks it up again nor lists it again early for 30 seconds, and still refuses with the cached failure.
END_COMMIT_OVERRIDE
Summary by cubic
Brings the Python SDK to parity with the Node SDK (#383): every tool now executes over MCP tools/call on the endpoint and account that listed it, with GET /accounts the only non-MCP request. This is the 3.0 release; MIGRATION.md (linked from README, shipped in the sdist) covers every change since 2.10.1.
Behavior changes
- Tools return the server's result verbatim; a no-text result falls back to
structuredContent, non-text parts come back as plain JSON, andisErrorraisesStackOneAPIError. Adapters emit the servedrequiredlist verbatim and in order. - File actions return the download link or raise 501; download filenames are reduced exactly as Node's
TextDecoderdoes.NaN,Infinity, and unencodable arguments raiseToolArgumentsError; JSON integers above 2^53 keep their exact value. tools/callgoes throughsend_requestoverstreamable_http_client, buffering the server's error body on failure; MCP timeouts are reported as timeouts andKeyboardInterrupt/SystemExitpropagate. A call never relists the catalog first.- Only HTTP 429 is retried (up to three), honoring
Retry-Afteras seconds or a strict RFC 9110 HTTP-date (capped at 30s, else jittered backoff); a retry that would overrun the deadline is skipped and a 429 that outlasts retries aborts the call. Failed accounts retry after 30s; when every account fails, the sharedStackOneAPIErroris raised if they all share one status, else aToolsetLoadErrorraised from anExceptionGroupkept in.failures. Concurrentfetch_tools()/search()share one in-flightGET /accounts. - Header arguments are forwarded only when the schema declares them;
Authorization,x-account-id,User-Agent, andx-end-user-idnever are. A non-objectheadersargument is dropped unless the schema declaresheadersitself as an ordinary field; a flat list/dict header or a self-referential value is refused. A toolset-levelheaders=option goes on every request; non-shared accounts carry anx-end-user-id. - Base URL resolves argument →
STACKONE_BASE_URL→ default, and a set-but-unusedSTACKONE_ACCOUNT_IDwarns. submit_feedback()is served overtools/callonly, in every mode, listed once regardless of how many accounts serve it, and goes through the lowest account id in scope with an optionalaction_run_id. Search hits carrysession_idandaccount_id;top_klimits the merged ranking;execute(..., session_id=)forwards the hit's session id. An action linked on more than one account raises unless a hit'saccount_idroutes it.- New exports:
FeedbackRating,FeedbackCategory,FeedbackSource,StackOneMcpTool,ToolArgumentsError.fetch_tools(tool_names=...)accepts any sequence; thelangchainextra requireslangchain-core>=0.3.36. - CI pins sdk-conformance, runs the full suite against this and the Node SDK side by side, vendors shared test vectors byte-for-byte, and adds a PR-title check. The mock serves per-action schemas verbatim from a low-level MCP
Server.
Breaking changes
- Removed
StackOneRpcTool,MCP_PARAM_STYLE,ParameterLocation,validate_method,is_json_content_type, andfilename_from_content_disposition.StackOneTool.execute()no longer makes HTTP requests; the base class raisesStackOneErrorand_api_keyis optional. ExecuteConfigkeeps onlyname,headers,timeout; other fields raiseValidationError. Action results are the server's{isError, result, ...}object; downloads return a link, not bytes.- An empty or non-string account id, or a non-list
account_ids, raisesToolsetConfigError. A top-levelheaders_<name>argument is dropped unless declared; with duplicate tool names,get_tool(),to_openai(),to_langchain(), andto_pydantic_ai()return the first listing. - Python 3.11 or later is required, and
mcpis now a core dependency (thestackone-ai[mcp]extra is gone).