StackOneRpcTool API

Relevant source files

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

• stackone_ai/tools.py
• stackone_ai/types.py
• tests/test_tool_calling.py
• CLAUDE.md
• README.md

The StackOneRpcTool class provides a Python interface for executing SaaS actions through the StackOne RPC (/actions/rpc) endpoint. It translates flat-prefixed arguments provided by AI models into a structured RPC envelope containing body, path, query, and header parameters.

Sources: stackone_ai/tools.py:489-490, README.md:144-149

Architecture and Inheritance

StackOneRpcTool inherits from StackOneTool. It uses pydantic.BaseModel for schema validation and attribute management. While StackOneTool handles generic execution logic and framework conversions (OpenAI, LangChain, Pydantic AI), StackOneRpcTool specifically implements the logic required to communicate with the StackOne RPC surface.

Sources: stackone_ai/tools.py:489, stackone_ai/tools.py:406

Class Relationship Diagram

The diagram shows the inheritance hierarchy where StackOneRpcTool specializes the generic StackOneTool for RPC-based execution.

Sources: stackone_ai/tools.py:406-489

Initialization and Configuration

You initialize a StackOneRpcTool with specific configuration for an action. The internal ExecuteConfig is automatically set to use the POST method targeting the {base_url}/actions/rpc endpoint.

Sources: stackone_ai/tools.py:492-509

Constructor Parameters

Parameter	Type	Description
name	str	The unique identifier for the action.
description	str	A text description of what the tool does.
parameters	ToolParameters	The JSON Schema defining expected inputs.
api_key	str	The StackOne API key for authentication.
base_url	str	The base URL of the StackOne API.
account_id	str | None	The linked account ID to scope the action.
timeout	float	Request timeout in seconds (default: 60.0).

Sources: stackone_ai/tools.py:493-500

Execution Data Flow

Execution follows a pipeline that transforms AI-generated flat arguments into a structured HTTP request.

Execution Flow Diagram

This flowchart illustrates the transformation of input arguments into the final RPC request and the subsequent response handling.

Sources: stackone_ai/tools.py:511-540

The RPC Envelope

The tool buckets arguments into an "envelope" structure required by the server. This structure ensures that parameters reach their intended destination (URL path, query string, or request body) in the downstream SaaS provider.

Envelope Key	Source Prefix	Destination
path	path_	URL Path parameters
query	query_	URL Query string parameters
headers	headers_	Action-specific HTTP headers
body	body_	Request body parameters

Sources: stackone_ai/tools.py:553-560, tests/test_tool_calling.py:230-241

Parameter Mapping Logic

The _split_envelope_params method determines how to route each key. It is "schema-aware," meaning it uses the served tool schema to distinguish between intended location prefixes and actual field names that happen to start with reserved prefixes (e.g., a field named path_to_file in the body).

1. flat_prefixed Mapping: If the schema indicates parameters are prefixed, a key like path_id is split into buckets["path"]["id"].
2. Nested Mapping: If the input already contains objects keyed as path, query, body, or headers, these are merged into the respective buckets.
3. Bare Mapping: Any key that does not match a prefix and is not a reserved container key is placed in the body bucket.

Sources: stackone_ai/tools.py:553-594, tests/test_tool_calling.py:321-360

Security and Sanitization

The tool implements several security guards to prevent prompt injection and unauthorized access:

• Header Allowlist: Only headers explicitly declared in the served schema's headers_* properties are passed to the RPC envelope.
• Reserved Header Stripping: Headers like Authorization are stripped case-insensitively to prevent credential smuggling.
• Account Locking: The x-account-id header is enforced based on the tool's configuration. Model-supplied headers cannot override the x-account-id assigned to the tool instance.
• CRLF Protection: Header values are validated against a strict pattern to prevent HTTP header injection.

Sources: stackone_ai/tools.py:449-472, tests/test_tool_calling.py:417-470

Response Handling

StackOneRpcTool handles two primary response types:

JSON Responses

For standard API responses (where Content-Type is application/json or *+json), the tool returns a parsed dictionary or the raw result wrapped in a dictionary.
Sources: stackone_ai/tools.py:529-536, stackone_ai/types.py:112-120

Binary and File Downloads

For actions like file downloads (e.g., googledrive_unified_download_file), the tool detects non-JSON content types. It returns a metadata dictionary instead of attempting to parse JSON.

{
    "content": b"...",        # Raw bytes of the file
    "content_type": "...",    # MIME type from the server
    "status_code": 200,       # HTTP status code
    "headers": {...},         # Original response headers
    "file_name": "report.pdf" # Sanitized filename from Content-Disposition
}

Sources: stackone_ai/tools.py:539-545, tests/test_tool_calling.py:536-554

The filename is safely extracted and reduced to a bare, writable basename to prevent directory traversal attacks.
Sources: stackone_ai/types.py:123-146