@devries-cameron20 / composio-1 / commits / eae717ac2
Fork 0

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 Upadhyay committed May 6, 2026 at 18:44 UTC eae717ac2023ec803e9a2bef2128779bac09bc9e
13 files changed +102 -79
python/composio/core/models/inline_custom_tools_payload.py new
+31
@@ -0,0 +1,31 @@
1 +from __future__ import annotations
2 +
3 +import typing as t
4 +
5 +from composio_client import Omit, omit
6 +from composio_client.types.tool_router import (
7 + session_execute_params,
8 + session_search_params,
9 +)
10 +
11 +from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
12 +
13 +
14 +def inline_custom_tools_execute_experimental(
15 + payload: t.Optional[InlineCustomToolsWirePayload],
16 +) -> t.Union[session_execute_params.Experimental, Omit]:
17 + if payload is None:
18 + return omit
19 + # The SDK wire payload is a structural subset of Stainless' endpoint-specific
20 + # experimental payloads, with input-only preload hints on custom definitions.
21 + return t.cast(session_execute_params.Experimental, payload)
22 +
23 +
24 +def inline_custom_tools_search_experimental(
25 + payload: t.Optional[InlineCustomToolsWirePayload],
26 +) -> t.Union[session_search_params.Experimental, Omit]:
27 + if payload is None:
28 + return omit
29 + # The SDK wire payload is a structural subset of Stainless' endpoint-specific
30 + # experimental payloads, with input-only preload hints on custom definitions.
31 + return t.cast(session_search_params.Experimental, payload)
python/composio/core/models/session_context.py
+6 -14
@@ -16,8 +16,6 @@ from composio_client.types.tool_router.session_execute_response import (
16 from composio_client.types.tool_router.session_proxy_execute_response import (
17 SessionProxyExecuteResponse,
18 )
19 -from composio_client.types.tool_router import session_execute_params
20 -
19 from composio.client import HttpClient
20 from composio.core.models.custom_tool_execution import (
21 execute_custom_tool,
@@ -27,6 +25,9 @@ from composio.core.models.custom_tool_types import (
25 CustomToolsMap,
26 InlineCustomToolsWirePayload,
27 )
28 +from composio.core.models.inline_custom_tools_payload import (
29 + inline_custom_tools_execute_experimental,
30 +)
31 from composio.core.models.tools import _serialize_arguments
32 from composio.exceptions import ValidationError
33
@@ -141,22 +142,13 @@ class SessionContextImpl:
142 # Serialize any Pydantic model instances before sending to remote API
143 serialized = _serialize_arguments(arguments)
144
144 - # Fall back to remote execution
145 - if self._inline_custom_tools_payload is not None:
146 - return self._client.tool_router.session.execute(
147 - session_id=self._session_id,
148 - tool_slug=tool_slug,
149 - arguments=serialized,
150 - experimental=t.cast(
151 - session_execute_params.Experimental,
152 - self._inline_custom_tools_payload,
153 - ),
154 - )
155 -
145 return self._client.tool_router.session.execute(
146 session_id=self._session_id,
147 tool_slug=tool_slug,
148 arguments=serialized,
149 + experimental=inline_custom_tools_execute_experimental(
150 + self._inline_custom_tools_payload
151 + ),
152 )
153
154 def proxy_execute(
python/composio/core/models/tool_router_session.py
+9 -24
@@ -28,10 +28,6 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
28 from composio_client.types.tool_router.session_search_response import (
29 SessionSearchResponse,
30 )
31 -from composio_client.types.tool_router import (
32 - session_execute_params,
33 - session_search_params,
34 -)
31
32 from composio.client import HttpClient
33 from composio.core.models.connected_accounts import ConnectionRequest
@@ -47,6 +43,10 @@ from composio.core.models.custom_tool_types import (
43 RegisteredCustomTool,
44 RegisteredCustomToolkit,
45 )
46 +from composio.core.models.inline_custom_tools_payload import (
47 + inline_custom_tools_execute_experimental,
48 + inline_custom_tools_search_experimental,
49 +)
50 from composio.core.models._modifiers import Modifiers, apply_modifier_by_type
51 from composio.core.models.session_context import SessionContextImpl, proxy_execute_impl
52 from composio.core.models.tools import ToolExecuteParams, ToolExecutionResponse
@@ -657,13 +657,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
657 session_id=self.session_id,
658 queries=[{"use_case": query}],
659 model=model if model else omit,
660 - experimental=(
661 - t.cast(
662 - session_search_params.Experimental,
663 - self._inline_custom_tools_payload,
664 - )
665 - if self._inline_custom_tools_payload is not None
666 - else omit
660 + experimental=inline_custom_tools_search_experimental(
661 + self._inline_custom_tools_payload
662 ),
663 )
664
@@ -702,24 +697,14 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
697 log_id="",
698 )
699
705 - # Remote execution
706 - if self._inline_custom_tools_payload is not None:
707 - return self._client.tool_router.session.execute(
708 - session_id=self.session_id,
709 - tool_slug=tool_slug,
710 - arguments=arguments if arguments is not None else omit,
711 - account=account if account is not None else omit,
712 - experimental=t.cast(
713 - session_execute_params.Experimental,
714 - self._inline_custom_tools_payload,
715 - ),
716 - )
717 -
700 return self._client.tool_router.session.execute(
701 session_id=self.session_id,
702 tool_slug=tool_slug,
703 arguments=arguments if arguments is not None else omit,
704 account=account if account is not None else omit,
705 + experimental=inline_custom_tools_execute_experimental(
706 + self._inline_custom_tools_payload
707 + ),
708 )
709
710 def custom_tools(
python/composio/core/models/tools.py
+14 -23
@@ -15,11 +15,13 @@ from composio.client.types import (
15 tool_proxy_params,
16 tool_proxy_response,
17 )
18 -from composio_client.types.tool_router import session_execute_params
18 from composio.core.models._files import FileHelper
19 from composio.core.models.base import Resource
20 from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
21 from composio.core.models.custom_tools import CustomTools
22 +from composio.core.models.inline_custom_tools_payload import (
23 + inline_custom_tools_execute_experimental,
24 +)
25 from composio.core.provider import TTool, TToolCollection
26 from composio.core.provider.agentic import AgenticProvider, AgenticProviderExecuteFn
27 from composio.core.provider.base import ExecuteToolFn
@@ -536,28 +538,17 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
538 # Serialize any Pydantic model instances before sending to the API
539 processed_arguments = _serialize_arguments(processed_arguments)
540
539 - if inline_custom_tools_payload is not None:
540 - response = self._client.tool_router.session.execute(
541 - session_id=session_id,
542 - tool_slug=slug,
543 - arguments=processed_arguments,
544 - # Provider-wrapped session tools are agentic calls, so they opt into
545 - # direct tool offload when the backend session workbench allows it.
546 - enable_auto_workbench_offload=True,
547 - experimental=t.cast(
548 - session_execute_params.Experimental,
549 - inline_custom_tools_payload,
550 - ),
551 - )
552 - else:
553 - response = self._client.tool_router.session.execute(
554 - session_id=session_id,
555 - tool_slug=slug,
556 - arguments=processed_arguments,
557 - # Provider-wrapped session tools are agentic calls, so they opt into
558 - # direct tool offload when the backend session workbench allows it.
559 - enable_auto_workbench_offload=True,
560 - )
541 + response = self._client.tool_router.session.execute(
542 + session_id=session_id,
543 + tool_slug=slug,
544 + arguments=processed_arguments,
545 + # Provider-wrapped session tools are agentic calls, so they opt into
546 + # direct tool offload when the backend session workbench allows it.
547 + enable_auto_workbench_offload=True,
548 + experimental=inline_custom_tools_execute_experimental(
549 + inline_custom_tools_payload
550 + ),
551 + )
552
553 # Convert response to standard format
554 result: ToolExecutionResponse = {
python/examples/tool_router/direct_tools_preset.py
+1 -1
@@ -49,7 +49,7 @@ agent = Agent(
49 "Use the provided direct tools. The session is configured without Tool "
50 "Router meta/helper tools."
51 ),
52 - model=os.environ.get("OPENAI_MODEL", "gpt-4.1-mini"),
52 + model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
53 tools=tools,
54 )
55
python/examples/tool_router/preload.py
+1 -1
@@ -153,7 +153,7 @@ agent = Agent(
153 "Use the provided direct tools. Do not search for tools first; the "
154 "needed tools are already loaded."
155 ),
156 - model=os.environ.get("OPENAI_MODEL", "gpt-4.1-mini"),
156 + model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
157 tools=tools,
158 )
159
python/tests/test_custom_tools.py
+2
@@ -16,6 +16,7 @@ from dataclasses import replace
16 from unittest.mock import MagicMock
17
18 import pytest
19 +from composio_client import omit
20 from composio_client.types.tool_router.session_execute_response import (
21 SessionExecuteResponse,
22 )
@@ -569,6 +570,7 @@ class TestSessionContextImpl:
570 session_id="s",
571 tool_slug="NONEXISTENT",
572 arguments={"arg": "val"},
573 + experimental=omit,
574 )
575
576 def test_remote_fallback_passes_inline_custom_tools(self):
python/tests/test_tool_router.py
+3
@@ -3,6 +3,7 @@
3 from unittest.mock import MagicMock, patch
4
5 import pytest
6 +from composio_client import omit
7 from pydantic import BaseModel, Field
8
9 from composio.exceptions import ValidationError
@@ -1003,6 +1004,7 @@ class TestToolRouter:
1004 tool_slug="GMAIL_FETCH_EMAILS",
1005 arguments={"max_results": 1},
1006 account="work",
1007 + experimental=omit,
1008 )
1009
1010 def test_authorize_function(self, tool_router, mock_client):
@@ -1576,6 +1578,7 @@ class TestToolRouterExecution:
1578 tool_slug="GMAIL_SEND_EMAIL",
1579 arguments={"to": "test@example.com"},
1580 enable_auto_workbench_offload=True,
1581 + experimental=omit,
1582 )
1583
1584 # Verify result format
ts/examples/tool-router/.env.example
+1 -1
@@ -5,7 +5,7 @@ COMPOSIO_API_KEY=your_composio_api_key_here
5 OPENAI_API_KEY=your_openai_api_key_here
6
7 # Optional: override the model used by OpenAI Agents examples
8 -# OPENAI_MODEL=gpt-5.1
8 +# OPENAI_MODEL=gpt-5.5
9
10 # Add other environment variables as needed for your example
11 # ANTHROPIC_API_KEY=your_anthropic_api_key_here
ts/examples/tool-router/src/custom-tools-agent.ts
+1 -1
@@ -184,7 +184,7 @@ const tools = await session.tools();
184 const agent = new Agent({
185 name: "Custom Tools Agent",
186 instructions: "You are a helpful assistant. Use Composio tools to execute tasks.",
187 - model: "gpt-5.2",
187 + model: "gpt-5.5",
188 tools,
189 });
190
ts/packages/core/src/models/SessionContext.ts
+6 -3
@@ -21,6 +21,7 @@ import { transformProxyParams } from './proxyParamsTransform';
21 import { findCustomTool, executeCustomTool } from './customToolExecution';
22 import { transformExecuteResponse } from '../utils/transformers/toolRouterResponseTransform';
23 import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
24 +import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
25
26 /**
27 * Concrete implementation of SessionContext.
@@ -71,9 +72,11 @@ export class SessionContextImpl implements SessionContext {
72 tool_slug: toolSlug,
73 arguments: arguments_,
74 };
74 - if (this.inlineCustomToolsPayload) {
75 - executeParams.experimental =
76 - this.inlineCustomToolsPayload as SessionExecuteParams.Experimental;
75 + const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
76 + this.inlineCustomToolsPayload
77 + );
78 + if (experimental) {
79 + executeParams.experimental = experimental;
80 }
81
82 const response = await this.client.toolRouter.session.execute(this.sessionId, executeParams);
ts/packages/core/src/models/ToolRouterSession.ts
+10 -11
@@ -48,6 +48,7 @@ import { SessionContextImpl } from './SessionContext';
48 import { findCustomTool, executeCustomTool } from './customToolExecution';
49 import { findCustomToolMapEntryByFinalSlug } from './CustomTool';
50 import { transformProxyParams } from './proxyParamsTransform';
51 +import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
52
53 const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
54 export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
@@ -370,7 +371,9 @@ export class ToolRouterSession<
371 query: string;
372 toolkits?: string[];
373 }): Promise<ToolRouterSessionSearchResponse> {
373 - const experimental = this.inlineSearchExperimental();
374 + const experimental = inlineCustomToolsExperimental<SessionSearchParams.Experimental>(
375 + this.inlineCustomToolsPayload
376 + );
377 const searchParams = {
378 queries: [{ use_case: params.query }],
379 ...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
@@ -418,7 +421,9 @@ export class ToolRouterSession<
421 if (options?.account) {
422 executeParams.account = options.account;
423 }
421 - const experimental = this.inlineExecuteExperimental();
424 + const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
425 + this.inlineCustomToolsPayload
426 + );
427 if (experimental) {
428 executeParams.experimental = experimental;
429 }
@@ -473,14 +478,6 @@ export class ToolRouterSession<
478 return (this.customToolsMap?.byFinalSlug.size ?? 0) > 0;
479 }
480
476 - private inlineExecuteExperimental(): SessionExecuteParams.Experimental | undefined {
477 - return this.inlineCustomToolsPayload as SessionExecuteParams.Experimental | undefined;
478 - }
479 -
480 - private inlineSearchExperimental(): SessionSearchParams.Experimental | undefined {
481 - return this.inlineCustomToolsPayload as SessionSearchParams.Experimental | undefined;
482 - }
483 -
481 private executeBackendSessionTool(
482 ToolsModel: Tools<TToolCollection, TTool, TProvider>,
483 toolSlug: string,
@@ -489,7 +486,9 @@ export class ToolRouterSession<
486 tool?: Tool
487 ): Promise<ToolExecuteResponse> {
488 const body = { sessionId: this.sessionId, arguments: input };
492 - const experimental = this.inlineExecuteExperimental();
489 + const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
490 + this.inlineCustomToolsPayload
491 + );
492 if (experimental) {
493 return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool, { experimental });
494 }
ts/packages/core/src/models/inlineCustomToolsPayload.ts new
+17
@@ -0,0 +1,17 @@
1 +import type {
2 + SessionExecuteParams,
3 + SessionSearchParams,
4 +} from '@composio/client/resources/tool-router/session/session.mjs';
5 +import type { InlineCustomToolsWirePayload } from '../types/customTool.types';
6 +
7 +type InlineCustomToolsExperimental =
8 + | SessionExecuteParams.Experimental
9 + | SessionSearchParams.Experimental;
10 +
11 +export function inlineCustomToolsExperimental<TExperimental extends InlineCustomToolsExperimental>(
12 + payload?: InlineCustomToolsWirePayload
13 +): TExperimental | undefined {
14 + // The SDK wire payload is a structural subset of Stainless' endpoint-specific
15 + // experimental payloads, with input-only preload hints on custom definitions.
16 + return payload as TExperimental | undefined;
17 +}