Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Clean up inline custom tools payload typing

Dhawal Upadhyayeae717ac2023
diff --git a/python/composio/core/models/inline_custom_tools_payload.py b/python/composio/core/models/inline_custom_tools_payload.py
new file mode 100644
index 000000000..23234caad
--- /dev/null
+++ b/python/composio/core/models/inline_custom_tools_payload.py
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import typing as t
+
+from composio_client import Omit, omit
+from composio_client.types.tool_router import (
+ session_execute_params,
+ session_search_params,
+)
+
+from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
+
+
+def inline_custom_tools_execute_experimental(
+ payload: t.Optional[InlineCustomToolsWirePayload],
+) -> t.Union[session_execute_params.Experimental, Omit]:
+ if payload is None:
+ return omit
+ # The SDK wire payload is a structural subset of Stainless' endpoint-specific
+ # experimental payloads, with input-only preload hints on custom definitions.
+ return t.cast(session_execute_params.Experimental, payload)
+
+
+def inline_custom_tools_search_experimental(
+ payload: t.Optional[InlineCustomToolsWirePayload],
+) -> t.Union[session_search_params.Experimental, Omit]:
+ if payload is None:
+ return omit
+ # The SDK wire payload is a structural subset of Stainless' endpoint-specific
+ # experimental payloads, with input-only preload hints on custom definitions.
+ return t.cast(session_search_params.Experimental, payload)
diff --git a/python/composio/core/models/session_context.py b/python/composio/core/models/session_context.py
index 18bbf4631..6c43489ad 100644
--- a/python/composio/core/models/session_context.py
+++ b/python/composio/core/models/session_context.py
@@ -16,8 +16,6 @@ from composio_client.types.tool_router.session_execute_response import (
from composio_client.types.tool_router.session_proxy_execute_response import (
SessionProxyExecuteResponse,
)
-from composio_client.types.tool_router import session_execute_params
-
from composio.client import HttpClient
from composio.core.models.custom_tool_execution import (
execute_custom_tool,
@@ -27,6 +25,9 @@ from composio.core.models.custom_tool_types import (
CustomToolsMap,
InlineCustomToolsWirePayload,
)
+from composio.core.models.inline_custom_tools_payload import (
+ inline_custom_tools_execute_experimental,
+)
from composio.core.models.tools import _serialize_arguments
from composio.exceptions import ValidationError
@@ -141,22 +142,13 @@ class SessionContextImpl:
# Serialize any Pydantic model instances before sending to remote API
serialized = _serialize_arguments(arguments)
- # Fall back to remote execution
- if self._inline_custom_tools_payload is not None:
- return self._client.tool_router.session.execute(
- session_id=self._session_id,
- tool_slug=tool_slug,
- arguments=serialized,
- experimental=t.cast(
- session_execute_params.Experimental,
- self._inline_custom_tools_payload,
- ),
- )
-
return self._client.tool_router.session.execute(
session_id=self._session_id,
tool_slug=tool_slug,
arguments=serialized,
+ experimental=inline_custom_tools_execute_experimental(
+ self._inline_custom_tools_payload
+ ),
)
def proxy_execute(
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index d259dd1a1..5c2d9514e 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -28,10 +28,6 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
from composio_client.types.tool_router.session_search_response import (
SessionSearchResponse,
)
-from composio_client.types.tool_router import (
- session_execute_params,
- session_search_params,
-)
from composio.client import HttpClient
from composio.core.models.connected_accounts import ConnectionRequest
@@ -47,6 +43,10 @@ from composio.core.models.custom_tool_types import (
RegisteredCustomTool,
RegisteredCustomToolkit,
)
+from composio.core.models.inline_custom_tools_payload import (
+ inline_custom_tools_execute_experimental,
+ inline_custom_tools_search_experimental,
+)
from composio.core.models._modifiers import Modifiers, apply_modifier_by_type
from composio.core.models.session_context import SessionContextImpl, proxy_execute_impl
from composio.core.models.tools import ToolExecuteParams, ToolExecutionResponse
@@ -657,13 +657,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
session_id=self.session_id,
queries=[{"use_case": query}],
model=model if model else omit,
- experimental=(
- t.cast(
- session_search_params.Experimental,
- self._inline_custom_tools_payload,
- )
- if self._inline_custom_tools_payload is not None
- else omit
+ experimental=inline_custom_tools_search_experimental(
+ self._inline_custom_tools_payload
),
)
@@ -702,24 +697,14 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
log_id="",
)
- # Remote execution
- if self._inline_custom_tools_payload is not None:
- return self._client.tool_router.session.execute(
- session_id=self.session_id,
- tool_slug=tool_slug,
- arguments=arguments if arguments is not None else omit,
- account=account if account is not None else omit,
- experimental=t.cast(
- session_execute_params.Experimental,
- self._inline_custom_tools_payload,
- ),
- )
-
return self._client.tool_router.session.execute(
session_id=self.session_id,
tool_slug=tool_slug,
arguments=arguments if arguments is not None else omit,
account=account if account is not None else omit,
+ experimental=inline_custom_tools_execute_experimental(
+ self._inline_custom_tools_payload
+ ),
)
def custom_tools(
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index a1045ef42..22b7a9d28 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -15,11 +15,13 @@ from composio.client.types import (
tool_proxy_params,
tool_proxy_response,
)
-from composio_client.types.tool_router import session_execute_params
from composio.core.models._files import FileHelper
from composio.core.models.base import Resource
from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
from composio.core.models.custom_tools import CustomTools
+from composio.core.models.inline_custom_tools_payload import (
+ inline_custom_tools_execute_experimental,
+)
from composio.core.provider import TTool, TToolCollection
from composio.core.provider.agentic import AgenticProvider, AgenticProviderExecuteFn
from composio.core.provider.base import ExecuteToolFn
@@ -536,28 +538,17 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
# Serialize any Pydantic model instances before sending to the API
processed_arguments = _serialize_arguments(processed_arguments)
- if inline_custom_tools_payload is not None:
- response = self._client.tool_router.session.execute(
- session_id=session_id,
- tool_slug=slug,
- arguments=processed_arguments,
- # Provider-wrapped session tools are agentic calls, so they opt into
- # direct tool offload when the backend session workbench allows it.
- enable_auto_workbench_offload=True,
- experimental=t.cast(
- session_execute_params.Experimental,
- inline_custom_tools_payload,
- ),
- )
- else:
- response = self._client.tool_router.session.execute(
- session_id=session_id,
- tool_slug=slug,
- arguments=processed_arguments,
- # Provider-wrapped session tools are agentic calls, so they opt into
- # direct tool offload when the backend session workbench allows it.
- enable_auto_workbench_offload=True,
- )
+ response = self._client.tool_router.session.execute(
+ session_id=session_id,
+ tool_slug=slug,
+ arguments=processed_arguments,
+ # Provider-wrapped session tools are agentic calls, so they opt into
+ # direct tool offload when the backend session workbench allows it.
+ enable_auto_workbench_offload=True,
+ experimental=inline_custom_tools_execute_experimental(
+ inline_custom_tools_payload
+ ),
+ )
# Convert response to standard format
result: ToolExecutionResponse = {
diff --git a/python/examples/tool_router/direct_tools_preset.py b/python/examples/tool_router/direct_tools_preset.py
index efaf49060..ce81b6a9f 100644
--- a/python/examples/tool_router/direct_tools_preset.py
+++ b/python/examples/tool_router/direct_tools_preset.py
@@ -49,7 +49,7 @@ agent = Agent(
"Use the provided direct tools. The session is configured without Tool "
"Router meta/helper tools."
),
- model=os.environ.get("OPENAI_MODEL", "gpt-4.1-mini"),
+ model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
tools=tools,
)
diff --git a/python/examples/tool_router/preload.py b/python/examples/tool_router/preload.py
index 0db8d8686..51b9bad66 100644
--- a/python/examples/tool_router/preload.py
+++ b/python/examples/tool_router/preload.py
@@ -153,7 +153,7 @@ agent = Agent(
"Use the provided direct tools. Do not search for tools first; the "
"needed tools are already loaded."
),
- model=os.environ.get("OPENAI_MODEL", "gpt-4.1-mini"),
+ model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
tools=tools,
)
diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.py
index de13718fa..7e402981c 100644
--- a/python/tests/test_custom_tools.py
+++ b/python/tests/test_custom_tools.py
@@ -16,6 +16,7 @@ from dataclasses import replace
from unittest.mock import MagicMock
import pytest
+from composio_client import omit
from composio_client.types.tool_router.session_execute_response import (
SessionExecuteResponse,
)
@@ -569,6 +570,7 @@ class TestSessionContextImpl:
session_id="s",
tool_slug="NONEXISTENT",
arguments={"arg": "val"},
+ experimental=omit,
)
def test_remote_fallback_passes_inline_custom_tools(self):
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index b0a9c1d4a..b64643f7a 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -3,6 +3,7 @@
from unittest.mock import MagicMock, patch
import pytest
+from composio_client import omit
from pydantic import BaseModel, Field
from composio.exceptions import ValidationError
@@ -1003,6 +1004,7 @@ class TestToolRouter:
tool_slug="GMAIL_FETCH_EMAILS",
arguments={"max_results": 1},
account="work",
+ experimental=omit,
)
def test_authorize_function(self, tool_router, mock_client):
@@ -1576,6 +1578,7 @@ class TestToolRouterExecution:
tool_slug="GMAIL_SEND_EMAIL",
arguments={"to": "[email protected]"},
enable_auto_workbench_offload=True,
+ experimental=omit,
)
# Verify result format
diff --git a/ts/examples/tool-router/.env.example b/ts/examples/tool-router/.env.example
index 8f647ad57..948ea444a 100644
--- a/ts/examples/tool-router/.env.example
+++ b/ts/examples/tool-router/.env.example
@@ -5,7 +5,7 @@ COMPOSIO_API_KEY=your_composio_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
# Optional: override the model used by OpenAI Agents examples
-# OPENAI_MODEL=gpt-5.1
+# OPENAI_MODEL=gpt-5.5
# Add other environment variables as needed for your example
# ANTHROPIC_API_KEY=your_anthropic_api_key_here
diff --git a/ts/examples/tool-router/src/custom-tools-agent.ts b/ts/examples/tool-router/src/custom-tools-agent.ts
index 00be15a0c..34951c173 100644
--- a/ts/examples/tool-router/src/custom-tools-agent.ts
+++ b/ts/examples/tool-router/src/custom-tools-agent.ts
@@ -184,7 +184,7 @@ const tools = await session.tools();
const agent = new Agent({
name: "Custom Tools Agent",
instructions: "You are a helpful assistant. Use Composio tools to execute tasks.",
- model: "gpt-5.2",
+ model: "gpt-5.5",
tools,
});
diff --git a/ts/packages/core/src/models/SessionContext.ts b/ts/packages/core/src/models/SessionContext.ts
index f59b135fe..045e12902 100644
--- a/ts/packages/core/src/models/SessionContext.ts
+++ b/ts/packages/core/src/models/SessionContext.ts
@@ -21,6 +21,7 @@ import { transformProxyParams } from './proxyParamsTransform';
import { findCustomTool, executeCustomTool } from './customToolExecution';
import { transformExecuteResponse } from '../utils/transformers/toolRouterResponseTransform';
import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
+import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
/**
* Concrete implementation of SessionContext.
@@ -71,9 +72,11 @@ export class SessionContextImpl implements SessionContext {
tool_slug: toolSlug,
arguments: arguments_,
};
- if (this.inlineCustomToolsPayload) {
- executeParams.experimental =
- this.inlineCustomToolsPayload as SessionExecuteParams.Experimental;
+ const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
+ this.inlineCustomToolsPayload
+ );
+ if (experimental) {
+ executeParams.experimental = experimental;
}
const response = await this.client.toolRouter.session.execute(this.sessionId, executeParams);
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 6b9ee0bb4..b0b352110 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -48,6 +48,7 @@ import { SessionContextImpl } from './SessionContext';
import { findCustomTool, executeCustomTool } from './customToolExecution';
import { findCustomToolMapEntryByFinalSlug } from './CustomTool';
import { transformProxyParams } from './proxyParamsTransform';
+import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
@@ -370,7 +371,9 @@ export class ToolRouterSession<
query: string;
toolkits?: string[];
}): Promise<ToolRouterSessionSearchResponse> {
- const experimental = this.inlineSearchExperimental();
+ const experimental = inlineCustomToolsExperimental<SessionSearchParams.Experimental>(
+ this.inlineCustomToolsPayload
+ );
const searchParams = {
queries: [{ use_case: params.query }],
...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
@@ -418,7 +421,9 @@ export class ToolRouterSession<
if (options?.account) {
executeParams.account = options.account;
}
- const experimental = this.inlineExecuteExperimental();
+ const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
+ this.inlineCustomToolsPayload
+ );
if (experimental) {
executeParams.experimental = experimental;
}
@@ -473,14 +478,6 @@ export class ToolRouterSession<
return (this.customToolsMap?.byFinalSlug.size ?? 0) > 0;
}
- private inlineExecuteExperimental(): SessionExecuteParams.Experimental | undefined {
- return this.inlineCustomToolsPayload as SessionExecuteParams.Experimental | undefined;
- }
-
- private inlineSearchExperimental(): SessionSearchParams.Experimental | undefined {
- return this.inlineCustomToolsPayload as SessionSearchParams.Experimental | undefined;
- }
-
private executeBackendSessionTool(
ToolsModel: Tools<TToolCollection, TTool, TProvider>,
toolSlug: string,
@@ -489,7 +486,9 @@ export class ToolRouterSession<
tool?: Tool
): Promise<ToolExecuteResponse> {
const body = { sessionId: this.sessionId, arguments: input };
- const experimental = this.inlineExecuteExperimental();
+ const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
+ this.inlineCustomToolsPayload
+ );
if (experimental) {
return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool, { experimental });
}
diff --git a/ts/packages/core/src/models/inlineCustomToolsPayload.ts b/ts/packages/core/src/models/inlineCustomToolsPayload.ts
new file mode 100644
index 000000000..78ed4cc66
--- /dev/null
+++ b/ts/packages/core/src/models/inlineCustomToolsPayload.ts
@@ -0,0 +1,17 @@
+import type {
+ SessionExecuteParams,
+ SessionSearchParams,
+} from '@composio/client/resources/tool-router/session/session.mjs';
+import type { InlineCustomToolsWirePayload } from '../types/customTool.types';
+
+type InlineCustomToolsExperimental =
+ | SessionExecuteParams.Experimental
+ | SessionSearchParams.Experimental;
+
+export function inlineCustomToolsExperimental<TExperimental extends InlineCustomToolsExperimental>(
+ payload?: InlineCustomToolsWirePayload
+): TExperimental | undefined {
+ // The SDK wire payload is a structural subset of Stainless' endpoint-specific
+ // experimental payloads, with input-only preload hints on custom definitions.
+ return payload as TExperimental | undefined;
+}