@devries-cameron20 / composio Mirror · read-only / commits / 760f8d036
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 16:00 UTC

fix(sdk): route provider tool calls through sessions (#4098)

## Problem Provider tool-call helpers always used the globally injected direct `Tools.execute` function. When a model received tools from `session.tools()`, calling `handleToolCalls` or `handle_tool_calls` therefore discarded the Tool Router session context and caused session meta-tools such as `COMPOSIO_SEARCH_TOOLS` to fail. Calling `session.execute()` manually preserved the session, but bypassed provider behavior such as Anthropic input normalization and schema-alias restoration. ## Root fix - Add an explicit execution target to the non-agentic provider helpers: - TypeScript: `handleToolCalls(session, response)` and `executeToolCall(session, call)` - Python: `handle_tool_calls(response=response, session=session)` and `execute_tool_call(tool_call=call, session=session)` - Route normalized provider arguments through the supplied Tool Router session. - Map session responses back to each helper's existing result shape. - Keep provider-specific normalization before execution, including Anthropic schema-alias restoration. - Reject direct-only options and modifiers when the selected target is a session, including plain JavaScript calls that bypass the TypeScript overloads. - Update OpenAI and Anthropic examples to use the session-aware helpers. - Harden the docs policy test so setup and execution split across fences in one sample are still detected. ## Docs review follow-ups - Reword the concepts-page prohibition so it forbids user-ID-bound helper calls, not the helpers themselves, matching the provider pages in this PR. - Add minimum-version callouts to the OpenAI and Anthropic provider pages (Python `composio` newer than 0.19.0; TypeScript `@composio/core` ≥ 0.17.0 with `@composio/openai` ≥ 0.12.0 / `@composio/anthropic` ≥ 0.11.0), pointing older versions at `session.execute()`. - Bump `docs/package.json` to `@composio/core` `^0.15.0` and `@composio/openai` `^0.11.0` (the published majors at the time of the bump; `@composio/core` 0.16.0 and `composio` 0.19.0 have since released from `next` without this PR, so its changeset will publish core 0.17.0 and the next Python minor) and annotate each `@errors: 2345` Twoslash marker with a TODO naming the minor version that retires it; since this changeset releases minors, all three pins need a manual range bump to retire the markers. This version of twoslash only throws on *unlisted* errors, so a stale marker cannot break the build — it would only mask future TS2345s, which the TODOs now track. - Update `SESSION_GUARDRAILS` (the block appended to `.md` responses for agents): add a session-execution bullet (scoped to the OpenAI and Anthropic helpers, with `session.execute()` for every other provider) and qualify the direct-execution list with "with a user ID". The session-execution static test now scans the guardrail blocks like the execute-version test already did. - Tighten the docs detector: the Python branch is bounded to the helper call's argument list (tolerating one level of nested calls) instead of running past the closing paren, and the TypeScript branch catches whole user-ID identifiers (`userId`, `user_id`, `uid`) without flagging session variables like `userSession` — each edge has a regression test. - Note on the Google provider page that its `executeToolCall` is not session-aware yet. ## Compatibility and release Existing user-ID calls remain unchanged and continue to use direct tool execution. The new session call forms are additive. The changeset applies minor releases to `@composio/core`, `@composio/openai`, and `@composio/anthropic` — the new session overloads are a type-level break for provider subclasses, so patch was too small. The configured fixed group also includes `@composio/slim`. The docs site intentionally checks examples against currently published SDK declarations. The three new TypeScript calls therefore carry exact Twoslash `TS2345` release-skew annotations; remove them (per the inline TODOs) once `docs/package.json` picks up `@composio/core` ≥ 0.17.0, `@composio/openai` ≥ 0.12.0, and `@composio/anthropic` ≥ 0.11.0. ## Verification - `@composio/core`: 1,061 tests passed; typecheck passed - `@composio/openai`: 34 tests passed; typecheck passed - `@composio/anthropic`: 53 tests passed; typecheck passed - Python provider and aliasing suites: 40 passed, 4 skipped - Focused Python mypy and Ruff checks passed - Docs static suite: 208 tests passed (including the new guardrail-scan and detector cases) - Docs production build passed with the bumped `@composio/core` 0.15.0 / `@composio/openai` 0.11.0, including Twoslash, TypeScript, and all generated pages - Docs lint passed; lint reports only existing warnings - Changeset status reports the expected minor packages --------- Co-authored-by: Soumya Medapati <soumyamedapati@soumyas-air.local.meter> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: jkomyno <alberto@composio.dev>

Soumya Medapati committed Aug 18, 2026 at 14:55 UTC 760f8d03673ad0f85f25bb428246fcc929f5b186
30 files changed +1136 -151
.changeset/route-provider-session-tools.md new
+7
@@ -0,0 +1,7 @@
1 +---
2 +'@composio/core': minor
3 +'@composio/openai': minor
4 +'@composio/anthropic': minor
5 +---
6 +
7 +Allow OpenAI and Anthropic provider tool-call helpers to execute through a supplied Tool Router session. Session meta-tools now retain their session context while provider argument normalization remains intact; existing user-ID calls continue to use direct execution. Anthropic helper failures now preserve their error text in `{ error }` results without changing successful payloads. Custom provider subclasses overriding `executeToolCall` or `handleToolCalls` may require updates because these methods now accept session targets.
docs/bun.lock
+9 -5
@@ -49,12 +49,12 @@
49 "@anthropic-ai/sdk": "^0.115.0",
50 "@composio/anthropic": "^0.10.1",
51 "@composio/claude-agent-sdk": "^0.10.1",
52 - "@composio/core": "^0.14.1",
52 + "@composio/core": "^0.15.0",
53 "@composio/google": "^0.10.1",
54 "@composio/langchain": "^0.10.1",
55 "@composio/llamaindex": "^0.10.1",
56 "@composio/mastra": "^0.10.3",
57 - "@composio/openai": "^0.10.1",
57 + "@composio/openai": "^0.11.0",
58 "@composio/openai-agents": "^0.10.1",
59 "@composio/vercel": "^0.11.1",
60 "@google/genai": "^2.13.0",
@@ -205,11 +205,11 @@
205
206 "@composio/client": ["@composio/client@0.1.0-alpha.76", "", {}, "sha512-MXC5JGRVdiQ4EgLricy9o/mqBa1+1T7wHFZ6Q4ZJkrjzZqOMvxTgy21Zlb5J/1oGkB2bg9UDzpH8PkXCp/D4zA=="],
207
208 - "@composio/core": ["@composio/core@0.14.1", "", { "dependencies": { "@composio/client": "0.1.0-alpha.76", "@composio/json-schema-to-zod": "0.2.1", "@types/json-schema": "^7.0.15", "openai": "^6.49.0", "picocolors": "^1.1.1", "pusher-js": "^8.6.0", "semver": "^7.8.5", "zod-to-json-schema": "^3.25.2" }, "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-MumO81kU9ZwHELrN7b/ju9Ke7il/xz0d65yeSsbtp5V11LA4efLKgE4hKPxif55NK97pApBOj4UkQB+knzue9Q=="],
208 + "@composio/core": ["@composio/core@0.15.0", "", { "dependencies": { "@composio/client": "0.1.0-alpha.76", "@composio/json-schema-to-zod": "0.2.2", "@types/json-schema": "^7.0.15", "is-fs-case-sensitive": "^2.0.0", "openai": "^7.2.0", "picocolors": "^1.1.1", "pusher-js": "^8.6.0", "semver": "^7.8.5", "zod-to-json-schema": "^3.25.2" }, "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-8uJlWH/R4ZZDaua5eJGlwsMQJ9G4Ip76OYozaAt1yjibJ19MmW0m7dzp2Wji/M3ePoKGKaZDyQhSmXHluTNnig=="],
209
210 "@composio/google": ["@composio/google@0.10.1", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@google/genai": "^1.1.0" } }, "sha512-jfkYG+aNboBmYbVr2H4IcZ1JwrZ5OpY+ZM4UsNPOx+16hzMcGzaQqAWZhPw1vrPNRQBR68pevthhktP3vKGqZA=="],
211
212 - "@composio/json-schema-to-zod": ["@composio/json-schema-to-zod@0.2.1", "", { "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-ezIaQoXdqWJXFaI8+gTShpj8YZcRdSnLkA1hgzx1+kn2Bi1SXOtXjghoQDy2ZBYIOCefRXGmyaPl52+idjS9wA=="],
212 + "@composio/json-schema-to-zod": ["@composio/json-schema-to-zod@0.2.2", "", { "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-2af93I0oKBy9otwPjyoGy8+qYlB3Fgb/P1EHkbXdh2UmUQE1ynr8Syoio4otgJssRxrUImKOz2DgyDTKThMATw=="],
213
214 "@composio/langchain": ["@composio/langchain@0.10.1", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@langchain/core": "^1.1.4" } }, "sha512-egOjlDOX6xnpIppfy/xOhETVfqwIL+YopzcXd6JecuTVYyQ2pfAq9ns/evc0X0q47HVSSy0BM3a0DTwZhnea7Q=="],
215
@@ -217,7 +217,7 @@
217
218 "@composio/mastra": ["@composio/mastra@0.10.3", "", { "dependencies": { "@mastra/schema-compat": "^1.3.4" }, "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@mastra/core": "^1.46.0", "zod": "^3.25 || ^4" } }, "sha512-aHsM3UFbxGrCSD7Iy/fnuFgnzxLeEyiK14tkTBCf7MGgCObhZ++1yNLOH9eTH4/3DIBzSiymP4G3WOiyGdOPDw=="],
219
220 - "@composio/openai": ["@composio/openai@0.10.1", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "openai": "^6.45.0" } }, "sha512-ioCRe7ddQWTip1vP4jCVqM1Jwu2KnzwK20ssZ1qrpVb+aFjIczJErs/fJp1t1fPnd4YcV1EyRpNjVfp7dTWHxg=="],
220 + "@composio/openai": ["@composio/openai@0.11.0", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "openai": "^6.49.0 || ^7.0.0" } }, "sha512-Fk02kiz499dvgLbDcv+frsxmeQGN1+sy4iZPsSA5spdlanQ9O9Jd5TuKLzrwrGP7HNddXvnycUxXCkXhYEsQaQ=="],
221
222 "@composio/openai-agents": ["@composio/openai-agents@0.10.1", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@openai/agents": "^0.1.3", "zod": "^4.4.3" } }, "sha512-yCTbHAlK9BCzruAhyrZv/TwOOlwa/DF11XWfCNlnIP5a6P53jp0qA2crGCWSH8e3blxJ+ihhbmp8QS0pDCzW3g=="],
223
@@ -1349,6 +1349,8 @@
1349
1350 "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
1351
1352 + "is-fs-case-sensitive": ["is-fs-case-sensitive@2.0.0", "", {}, "sha512-JoCsyGITdYPM+pUbeMQ4IiEuQ4wjPdeWORlG7n644isewbcxiQIr+9gmF5k7UabTP/jLBRkbgydEamR7JZBKHA=="],
1353 +
1354 "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
1355
1356 "is-hexadecimal": ["is-hexadecimal@2.0.1", "", {}, "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg=="],
@@ -2029,6 +2031,8 @@
2031
2032 "@base-ui/utils/@babel/runtime": ["@babel/runtime@7.29.7", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
2033
2034 + "@composio/core/openai": ["openai@7.4.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "ws", "zod"] }, "sha512-+C9Muit5x8j9R8ej8ZzVgKcrVDtqFqTy9gxFdov0EItLgU68zrJtF9ZeT0cyqJQW9S3PCJkdFgADtRGquRBtew=="],
2035 +
2036 "@floating-ui/core/@floating-ui/utils": ["@floating-ui/utils@0.2.10", "", {}, "sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ=="],
2037
2038 "@floating-ui/react-dom/@floating-ui/dom": ["@floating-ui/dom@1.8.0", "", { "dependencies": { "@floating-ui/core": "^1.8.0", "@floating-ui/utils": "^0.2.12" } }, "sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg=="],
docs/content/docs/how-composio-works.mdx
+23
@@ -70,6 +70,29 @@ The agent searches for relevant tools, authenticates if needed, and executes the
70
71 Know the exact tools upfront? The [direct tools preset](/docs/configuring-sessions#direct-tools-preset) returns them directly from `session.tools()` with no search step, while keeping session auth, connected accounts, and the workbench.
72
73 +## Executing session tools
74 +
75 +When your model asks to call a session tool, execute it with `session.execute()`. It routes the call through the session's tool router, which is the only place session meta-tools run:
76 +
77 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
78 +<Tab value="Python">
79 +```python
80 +result = session.execute("COMPOSIO_SEARCH_TOOLS", arguments={"queries": [{"use_case": "send an email"}]})
81 +```
82 +</Tab>
83 +<Tab value="TypeScript">
84 +```typescript
85 +import { Composio } from '@composio/core';
86 +const composio = new Composio({ apiKey: 'your_api_key' });
87 +const session = await composio.create("user_123");
88 +// ---cut---
89 +const result = await session.execute("COMPOSIO_SEARCH_TOOLS", { queries: [{ use_case: "send an email" }] });
90 +```
91 +</Tab>
92 +</Tabs>
93 +
94 +Do not execute session tools with `tools.execute()`, or by passing a user ID to a provider's `handle_tool_calls` helper — both take the direct execution path, which does not carry your session, and meta-tools fail there with `"can only be called inside a tool-router session"`. The [OpenAI](/docs/providers/openai) and [Anthropic](/docs/providers/anthropic) helpers also accept the session itself (`handle_tool_calls(response=response, session=session)` in Python, `handleToolCalls(session, response)` in TypeScript), which routes through the session while keeping provider argument normalization.
95 +
96 ## Authentication
97
98 When a tool needs a connection, the session generates a Connect Link with `session.authorize()`, or the agent handles the flow through `COMPOSIO_MANAGE_CONNECTIONS`.
docs/content/docs/providers/anthropic.mdx
+13 -6
@@ -50,10 +50,15 @@ ANTHROPIC_API_KEY=xxxxxxxxx
50 <Step>
51 **Create session and run**
52
53 +<Callout type="info">
54 +Passing a session to `handle_tool_calls` / `handleToolCalls` requires `composio` newer than 0.19.0 (Python) or `@composio/core` ≥ 0.17.0 with `@composio/anthropic` ≥ 0.11.0 (TypeScript). On earlier versions, execute session tools with [`session.execute()`](/docs/how-composio-works#executing-session-tools).
55 +</Callout>
56 +
57 <Tabs groupId="language" items={["Python", "TypeScript"]} persist>
58 <Tab value="Python">
59 ```python
60 import json
61 +
62 import anthropic
63 from composio import Composio
64 from composio_anthropic import AnthropicProvider
@@ -79,14 +84,14 @@ response = client.messages.create(
84 # Agentic loop: keep executing tool calls until the model responds with text
85 while response.stop_reason == "tool_use":
86 tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
82 - results = composio.provider.handle_tool_calls(user_id="user_123", response=response)
87 + results = composio.provider.handle_tool_calls(response=response, session=session)
88 messages.append({"role": "assistant", "content": response.content})
89 messages.append({
90 "role": "user",
91 "content": [
92 {"type": "tool_result", "tool_use_id": tool_use_blocks[i].id, "content": json.dumps(result)}
93 for i, result in enumerate(results)
89 - ]
94 + ],
95 })
96 response = client.messages.create(
97 model="claude-opus-4-6",
@@ -102,7 +107,9 @@ for block in response.content:
107 ```
108 </Tab>
109 <Tab value="TypeScript">
110 +{/* TODO: remove the `@errors: 2345` twoslash marker below once docs/package.json resolves @composio/core >= 0.17.0 and @composio/anthropic >= 0.11.0 (session-aware handleToolCalls). Both pins need a manual range bump — ^0.15.0 / ^0.10.1 do not admit these minor releases. */}
111 ```typescript
112 +// @errors: 2345
113 import Anthropic from '@anthropic-ai/sdk';
114 import { Composio } from '@composio/core';
115 import { AnthropicProvider } from '@composio/anthropic';
@@ -132,7 +139,7 @@ let response = await client.messages.create({
139
140 // Agentic loop: keep executing tool calls until the model responds with text
141 while (response.stop_reason === "tool_use") {
135 - const toolResults = await composio.provider.handleToolCalls("user_123", response);
142 + const toolResults = await composio.provider.handleToolCalls(session, response);
143 messages.push({ role: "assistant", content: response.content });
144 messages.push(...toolResults);
145 response = await client.messages.create({
@@ -156,7 +163,7 @@ for (const block of response.content) {
163 </Steps>
164
165 <Callout type="info">
159 -`handleToolCalls` does the loop body for you. It extracts every `tool_use` block from the response, executes the matching Composio tools, and returns a ready-to-append array of Messages API content (a `user` message holding `tool_result` blocks). That is why the TypeScript example spreads the result straight into `messages` with `messages.push(...toolResults)`. In Python it returns the raw result list, which the example wraps into `tool_result` blocks by hand.
166 +Pass the session to `handleToolCalls` / `handle_tool_calls` when the model received tools from `session.tools()`. The helper preserves Anthropic input normalization and restored schema aliases before executing every call through that session. For tools fetched via [`tools.get`](/docs/tools-direct/executing-tools), pass the user ID instead.
167 </Callout>
168
169 </IntegrationContent>
@@ -272,8 +279,8 @@ The provider registers each tool's complete object schema. Object arguments that
279 A few things are specific to the Anthropic provider:
280
281 - **Tool caching.** Pass `cacheTools: true` to the constructor (`new AnthropicProvider({ cacheTools: true })`) to attach Anthropic's ephemeral `cache_control` to every tool definition and tool-result block. This lets Claude reuse cached tool schemas across requests and can cut prompt cost when you send the same large tool set on every turn.
275 -- **`handleToolCalls` returns Messages API content, not raw strings.** On the TypeScript side it returns `Anthropic.Messages.MessageParam[]` (a `user` message of `tool_result` blocks) that you append directly to your message list. This is why the loop above does not build `tool_result` blocks by hand.
276 -- **String-encoded tool inputs are handled for you.** Claude occasionally emits a tool's `input` as a JSON string instead of an object. The provider normalizes this before execution, so you do not have to parse it yourself.
282 +- **`handleToolCalls` returns Messages API content, not raw strings.** TypeScript returns a ready-to-append `user` message of `tool_result` blocks. Python returns raw results in model-call order, which the sample wraps into `tool_result` blocks.
283 +- **String-encoded tool inputs are handled for you.** Claude occasionally emits a tool's `input` as a JSON string instead of an object. The provider normalizes it before both direct and session execution.
284 - **`cacheTools` only.** The constructor takes no other options. There is no agentic execution in this provider; you run the loop (Messages API) or hand the loop to the Claude Agent SDK (Agent SDK tab).
285
286 ## Next
docs/content/docs/providers/custom-providers/typescript.mdx
+24 -32
@@ -242,60 +242,52 @@ export class StatefulProvider extends BaseNonAgenticProvider<ToolCollection, Too
242 }
243 ```
244
245 -## Advanced: compose providers
245 +## Add behavior with composition
246
247 -You don't have to start from a base class. Extend an existing provider to add behavior like analytics or retries, and call `super` to reuse its logic.
247 +Don't subclass a concrete provider to add analytics, retries, or other cross-cutting behavior. Hold a provider instance and delegate to it instead. This avoids making your class satisfy every overload that the provider exposes.
248
249 ```typescript
250 -// @noErrors
250 +import { Composio } from '@composio/core';
251 +import type { ExecuteToolFnOptions, ExecuteToolModifiers } from '@composio/core';
252 import { OpenAIProvider } from '@composio/openai';
253 +import type OpenAI from 'openai';
254
253 -// Extend the OpenAI provider with custom functionality
254 -export class EnhancedOpenAIProvider extends OpenAIProvider {
255 - // Add properties
256 - private analytics = {
255 +class InstrumentedOpenAIToolExecutor {
256 + private readonly analytics = {
257 toolCalls: 0,
258 errors: 0,
259 };
260
261 - // Override methods to add functionality
262 - override async executeToolCall(userId, tool, options, modifiers) {
261 + constructor(private readonly provider: OpenAIProvider) {}
262 +
263 + async executeToolCall(
264 + userId: string,
265 + tool: OpenAI.ChatCompletionMessageFunctionToolCall,
266 + options?: ExecuteToolFnOptions,
267 + modifiers?: ExecuteToolModifiers
268 + ): Promise<string> {
269 this.analytics.toolCalls++;
270
271 try {
266 - // Call the parent implementation
267 - const result = await super.executeToolCall(userId, tool, options, modifiers);
268 - return result;
272 + return await this.provider.executeToolCall(userId, tool, options, modifiers);
273 } catch (error) {
274 this.analytics.errors++;
275 throw error;
276 }
277 }
278
275 - // Add new methods
276 - getAnalytics() {
277 - return this.analytics;
278 - }
279 -
280 - async executeWithRetry(userId, tool, options, modifiers, maxRetries = 3) {
281 - let attempts = 0;
282 - let lastError;
283 -
284 - while (attempts < maxRetries) {
285 - try {
286 - return await this.executeToolCall(userId, tool, options, modifiers);
287 - } catch (error) {
288 - lastError = error;
289 - attempts++;
290 - await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
291 - }
292 - }
293 -
294 - throw lastError;
279 + getAnalytics(): Readonly<{ toolCalls: number; errors: number }> {
280 + return { ...this.analytics };
281 }
282 }
283 +
284 +const provider = new OpenAIProvider();
285 +const composio = new Composio({ provider });
286 +const toolExecutor = new InstrumentedOpenAIToolExecutor(provider);
287 ```
288
289 +Pass the underlying provider to `Composio`, then call the wrapper from your manual tool-call loop.
290 +
291 ## Best practices
292
293 - **Keep providers focused**: each provider should target one platform.
docs/content/docs/providers/google.mdx
+8 -7
@@ -13,7 +13,7 @@ The Google provider formats Composio tools for [Gemini](https://ai.google.dev/)
13
14 <IntegrationContent value="gemini">
15
16 -In Python, the Gemini provider (`composio_gemini`) wraps Composio tools as typed callables, and the `google-genai` SDK's Automatic Function Calling executes tool calls inside the chat loop for you. In TypeScript, the Google provider transforms Composio tools into Gemini function declarations, and you run the loop: execute each call with `composio.provider.executeToolCall`, feed the result back, and repeat until the model replies with text.
16 +In Python, the Gemini provider (`composio_gemini`) wraps Composio tools as typed callables, and the `google-genai` SDK's Automatic Function Calling executes tool calls inside the chat loop for you. In TypeScript, the Google provider transforms Composio tools into Gemini function declarations, and you run the loop: execute each call with `session.execute`, feed the result back, and repeat until the model replies with text.
17
18 Object arguments that declare no properties preserve arbitrary nested keys in both providers. The TypeScript provider also adds `type: "object"` to schema nodes that declare `properties` without a type, which is the shape Gemini expects for object schemas.
19
@@ -98,19 +98,16 @@ let response = await chat.sendMessage({
98 message: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
99 });
100
101 -// Agentic loop: keep executing tool calls until the model responds with text
101 +// Agentic loop: run each tool call with session.execute() until the model responds with text
102 while (response.functionCalls && response.functionCalls.length > 0) {
103 const parts: Part[] = [];
104 for (const fc of response.functionCalls) {
105 - const result = await composio.provider.executeToolCall("user_123", {
106 - name: fc.name || '',
107 - args: (fc.args || {}) as Record<string, unknown>,
108 - });
105 + const result = await session.execute(fc.name || '', (fc.args || {}) as Record<string, unknown>);
106 parts.push({
107 functionResponse: {
108 id: fc.id,
109 name: fc.name,
113 - response: JSON.parse(result),
110 + response: result.error ? { error: result.error } : result.data,
111 },
112 });
113 }
@@ -124,6 +121,10 @@ console.log(response.text);
121 </Step>
122 </Steps>
123
124 +<Callout type="warn">
125 +In TypeScript, execute session tools with `session.execute(toolSlug, arguments)`, as shown above. The provider's `executeToolCall` helper executes tools through the direct path, which does not carry your session — session meta-tools (`COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, …) are rejected there with `"can only be called inside a tool-router session"`. Use `executeToolCall` only with tools fetched via [`tools.get`](/docs/tools-direct/executing-tools), not with `session.tools()`. Unlike the [OpenAI](/docs/providers/openai) and [Anthropic](/docs/providers/anthropic) helpers, the Google provider's `executeToolCall` does not yet accept a session. (The Python Gemini tab is unaffected: Automatic Function Calling runs provider-wrapped callables, which carry the session.)
126 +</Callout>
127 +
128 </IntegrationContent>
129
130 <IntegrationContent value="adk">
docs/content/docs/providers/openai.mdx
+30 -20
@@ -54,6 +54,10 @@ OPENAI_API_KEY=xxxxxxxxx
54
55 The [Responses API](https://platform.openai.com/docs/api-reference/responses) is the recommended way to build agentic flows with OpenAI. You pass `previous_response_id` on each turn so the model keeps the prior context, and you send back only the new `function_call_output` items.
56
57 +<Callout type="info">
58 +Passing a session to `handle_tool_calls` / `handleToolCalls` requires `composio` newer than 0.19.0 (Python) or `@composio/core` ≥ 0.17.0 with `@composio/openai` ≥ 0.12.0 (TypeScript). On earlier versions, execute session tools with [`session.execute()`](/docs/how-composio-works#executing-session-tools).
59 +</Callout>
60 +
61 <Tabs groupId="language" items={["Python", "TypeScript"]} persist>
62 <Tab value="Python">
63 ```python
@@ -85,14 +89,18 @@ while True:
89 tool_calls = [o for o in response.output if o.type == "function_call"]
90 if not tool_calls:
91 break
88 - results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
92 + results = composio.provider.handle_tool_calls(response=response, session=session)
93 response = client.responses.create(
94 model="gpt-5.2",
95 tools=tools,
96 previous_response_id=response.id,
97 input=[
94 - {"type": "function_call_output", "call_id": tool_calls[i].call_id, "output": json.dumps(result)}
95 - for i, result in enumerate(results)
98 + {
99 + "type": "function_call_output",
100 + "call_id": call.call_id,
101 + "output": json.dumps(results[i]),
102 + }
103 + for i, call in enumerate(tool_calls)
104 ]
105 )
106
@@ -103,7 +111,9 @@ for item in response.output:
111 ```
112 </Tab>
113 <Tab value="TypeScript">
114 +{/* TODO: remove the `@errors: 2345` twoslash marker below once docs/package.json resolves @composio/core >= 0.17.0 and @composio/openai >= 0.12.0 (session-aware handleToolCalls). Both pins need a manual range bump — ^0.15.0 / ^0.11.0 do not admit these minor releases. */}
115 ```typescript
116 +// @errors: 2345
117 import OpenAI from 'openai';
118 import { Composio } from '@composio/core';
119 import { OpenAIResponsesProvider } from '@composio/openai';
@@ -133,16 +143,12 @@ while (true) {
143 const toolCalls = response.output.filter((o) => o.type === "function_call");
144 if (toolCalls.length === 0) break;
145
136 - const results = await composio.provider.handleToolCalls("user_123", response.output);
146 + const outputs = await composio.provider.handleToolCalls(session, response.output);
147 response = await client.responses.create({
148 model: "gpt-5.2",
149 tools: tools,
150 previous_response_id: response.id,
141 - input: results.map((result, i) => ({
142 - type: "function_call_output" as const,
143 - call_id: toolCalls[i].call_id,
144 - output: JSON.stringify(result),
145 - })),
151 + input: outputs,
152 });
153 }
154
@@ -198,6 +204,10 @@ OPENAI_API_KEY=xxxxxxxxx
204
205 The [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) generates a model response from a list of messages. You keep the full message list yourself and append each assistant message and its `tool` results before the next call.
206
207 +<Callout type="info">
208 +Passing a session to `handle_tool_calls` / `handleToolCalls` requires `composio` newer than 0.19.0 (Python) or `@composio/core` ≥ 0.17.0 with `@composio/openai` ≥ 0.12.0 (TypeScript). On earlier versions, execute session tools with [`session.execute()`](/docs/how-composio-works#executing-session-tools).
209 +</Callout>
210 +
211 <Tabs groupId="language" items={["Python", "TypeScript"]} persist>
212 <Tab value="Python">
213 ```python
@@ -225,7 +235,7 @@ response = client.chat.completions.create(
235
236 # Agentic loop: keep executing tool calls until the model responds with text
237 while response.choices[0].message.tool_calls:
228 - results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
238 + results = composio.provider.handle_tool_calls(response=response, session=session)
239 messages.append(response.choices[0].message)
240 for i, tc in enumerate(response.choices[0].message.tool_calls):
241 messages.append({
@@ -243,7 +253,9 @@ print(response.choices[0].message.content)
253 ```
254 </Tab>
255 <Tab value="TypeScript">
256 +{/* TODO: remove the `@errors: 2345` twoslash marker below once docs/package.json resolves @composio/core >= 0.17.0 and @composio/openai >= 0.12.0 (session-aware handleToolCalls). Both pins need a manual range bump — ^0.15.0 / ^0.11.0 do not admit these minor releases. */}
257 ```typescript
258 +// @errors: 2345
259 import OpenAI from 'openai';
260 import { Composio } from '@composio/core';
261 import { OpenAIProvider } from '@composio/openai';
@@ -272,15 +284,9 @@ let response = await client.chat.completions.create({
284
285 // Agentic loop: keep executing tool calls until the model responds with text
286 while (response.choices[0].message.tool_calls) {
275 - const results = await composio.provider.handleToolCalls("user_123", response);
287 + const results = await composio.provider.handleToolCalls(session, response);
288 messages.push(response.choices[0].message);
277 - for (const [i, tc] of response.choices[0].message.tool_calls.entries()) {
278 - messages.push({
279 - role: "tool",
280 - tool_call_id: tc.id,
281 - content: JSON.stringify(results[i]),
282 - });
283 - }
289 + messages.push(...results);
290 response = await client.chat.completions.create({
291 model: "gpt-5.2",
292 tools: tools,
@@ -400,9 +406,13 @@ console.log(result.finalOutput);
406
407 The OpenAI integration ships three providers, one per API surface:
408
403 -- **`OpenAIResponsesProvider`** for the Responses API. `handleToolCalls` executes the tool calls and returns `function_call_output` items keyed by `call_id`. You pair it with `previous_response_id` so you only resend new outputs each turn.
409 +- **`OpenAIResponsesProvider`** for the Responses API. `handleToolCalls` executes each `function_call` and returns `function_call_output` items keyed by `call_id`, paired with `previous_response_id` so you only resend new outputs each turn.
410 - **`OpenAIProvider`** for the Chat Completions API. This is the SDK default, so `new Composio()` with no provider uses it. You keep the full message list and append each assistant message plus its `tool` results yourself.
405 -- **`OpenAIAgentsProvider`** for the Agents SDK. Tools come with execution wired in, so the SDK runs the loop and you do not call `handleToolCalls` at all.
411 +- **`OpenAIAgentsProvider`** for the Agents SDK. Tools come with execution wired in, so the SDK runs the loop for you.
412 +
413 +<Callout type="info">
414 +Pass the session to `handleToolCalls` / `handle_tool_calls` when the model received tools from `session.tools()`. The helper preserves the provider's argument normalization and executes every call through that session. For tools fetched via [`tools.get`](/docs/tools-direct/executing-tools), pass the user ID instead.
415 +</Callout>
416
417 Use the Responses or Agents provider for new agentic flows; reach for Chat Completions when you are extending an existing Chat Completions codebase.
418
docs/lib/llm-guardrails/session.ts
+2 -1
@@ -63,9 +63,10 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
63 ## 2. Integration Notes
64
65 - \`composio.create(user_id)\` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; \`user_id\` goes to \`composio.create()\` — individual tool calls in session mode don't take one.
66 +- Execute session tool calls through the session, never through a user ID: either \`session.execute(tool_slug, arguments=...)\` / \`session.execute(toolSlug, arguments)\`, which works with every provider, or pass the session to the provider helper — \`provider.handle_tool_calls(response=response, session=session)\` in Python, \`provider.handleToolCalls(session, response)\` in TypeScript. Only the OpenAI and Anthropic helpers accept a session; with other providers, use \`session.execute()\`. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with \`"can only be called inside a tool-router session"\`.
67 - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
68 - Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is \`composio_openai_agents\` / \`@composio/openai-agents\` (importing \`composio_openai\` / \`@composio/openai\` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API).
68 -- **Direct execution** (\`composio.tools.get()\`, \`composio.tools.execute()\`, \`provider.handle_tool_calls()\`) is a fully supported lower-level interface: your code picks the tool, no runtime discovery. It fits deterministic workflows and scripts; sessions fit agents that decide at runtime. The tradeoffs are documented at https://docs.composio.dev/docs/sessions-vs-direct-execution. Note that direct execution requires a toolkit version (https://docs.composio.dev/docs/tools-direct/toolkit-versioning).
69 +- **Direct execution** (\`composio.tools.get()\`, \`composio.tools.execute()\`, \`provider.handle_tool_calls()\` with a user ID) is a fully supported lower-level interface: your code picks the tool, no runtime discovery. It fits deterministic workflows and scripts; sessions fit agents that decide at runtime. The tradeoffs are documented at https://docs.composio.dev/docs/sessions-vs-direct-execution. Note that direct execution requires a toolkit version (https://docs.composio.dev/docs/tools-direct/toolkit-versioning).
70
71 ---
72
docs/package.json
+2 -2
@@ -73,12 +73,12 @@
73 "@anthropic-ai/sdk": "^0.115.0",
74 "@composio/anthropic": "^0.10.1",
75 "@composio/claude-agent-sdk": "^0.10.1",
76 - "@composio/core": "^0.14.1",
76 + "@composio/core": "^0.15.0",
77 "@composio/google": "^0.10.1",
78 "@composio/langchain": "^0.10.1",
79 "@composio/llamaindex": "^0.10.1",
80 "@composio/mastra": "^0.10.3",
81 - "@composio/openai": "^0.10.1",
81 + "@composio/openai": "^0.11.0",
82 "@composio/openai-agents": "^0.10.1",
83 "@composio/vercel": "^0.11.1",
84 "@google/genai": "^2.13.0",
docs/tests/static/session-execution.test.ts new
+248
@@ -0,0 +1,248 @@
1 +/**
2 + * Session tool-execution policy for docs samples.
3 + *
4 + * Provider helpers must receive the Tool Router session that produced the
5 + * model-visible tools. Passing a user ID chooses direct execution instead,
6 + * so session meta-tools fail at runtime.
7 + *
8 + * A 102-run agent eval of the docs (August 2026, two-phase build+probe)
9 + * found 58/102 runs hit that rejection by copying provider-page samples
10 + * that paired `session.tools()` with `handle_tool_calls`. All recovering
11 + * runs converged on `session.execute()`, discovered from SDK source. The SDK
12 + * helpers now accept the session directly and retain provider normalization.
13 + *
14 + * Rule: no authored MDX page may pair session tools (`session.tools()` /
15 + * `sessions.create` / `composio.create(`) with a provider helper explicitly
16 + * bound to a user ID. Session-bound helper calls and direct-path (`tools.get`)
17 + * samples are valid.
18 + *
19 + * Scope: content/docs and content/examples. Excluded: content/reference
20 + * (generated upstream), changelog (historical), docs/migration-guide
21 + * (point-in-time documents that may show old APIs).
22 + * The LLM guardrail blocks appended to .md responses are checked too —
23 + * they are samples agents copy verbatim.
24 + */
25 +import { describe, test, expect } from "bun:test";
26 +import { readdir, readFile } from "fs/promises";
27 +import { join, relative } from "path";
28 +
29 +import {
30 + SESSION_GUARDRAILS,
31 + DIRECT_EXECUTION_GUARDRAILS,
32 +} from "../../lib/llm-guardrails";
33 +
34 +const CONTENT_DIRS = ["docs", "examples"].map((dir) =>
35 + join(import.meta.dir, "../../content", dir),
36 +);
37 +const CONTENT_ROOT = join(import.meta.dir, "../../content");
38 +const EXCLUDED_PATH_SEGMENTS = ["docs/migration-guide/"];
39 +
40 +const SESSION_TOKEN_RE =
41 + /session\.tools\s*\(|sessions\.create\s*\(|composio\.create\s*\(/;
42 +// Python branch: user_id= must appear inside the helper's argument list —
43 +// the bound tolerates one level of nested calls (`response=build_response()`)
44 +// but never runs past the helper's closing paren into later code. TS branch:
45 +// a string-literal first argument, or a whole identifier that names a user ID
46 +// (`userId`, `user_id`, `uid`) — a session argument never does.
47 +const DIRECT_HELPER_TOKEN_RE =
48 + /(?:handle_tool_calls|execute_tool_call)\s*\((?:[^()]*\([^()]*\))*[^()]*\buser_id\s*=|(?:handleToolCalls|executeToolCall)\s*\(\s*(?:["'`]|(?:user_?[iI]d|uid)\b)/;
49 +const SAMPLE_BOUNDARY_RE = /^\s*(?:<\/?(?:Tab|Step)\b|#{1,6}\s)/;
50 +const FENCE_OPEN_RE = /^\s*(`{3,}|~{3,})/;
51 +const FENCE_CLOSE_RE = /^\s*(`{3,}|~{3,})\s*$/;
52 +
53 +async function findMdxFiles(dir: string): Promise<string[]> {
54 + const results: string[] = [];
55 + let entries;
56 + try {
57 + entries = await readdir(dir, { withFileTypes: true });
58 + } catch {
59 + return results;
60 + }
61 +
62 + for (const entry of entries) {
63 + const fullPath = join(dir, entry.name);
64 + if (entry.isDirectory()) {
65 + results.push(...(await findMdxFiles(fullPath)));
66 + } else if (entry.name.endsWith(".mdx")) {
67 + results.push(fullPath);
68 + }
69 + }
70 + return results;
71 +}
72 +
73 +function codeSampleGroups(source: string): string[] {
74 + const groups: string[] = [];
75 + let current: string[] = [];
76 + let fenceMarker: string | undefined;
77 +
78 + const flush = () => {
79 + if (current.length > 0) groups.push(current.join("\n"));
80 + current = [];
81 + };
82 +
83 + for (const line of source.split(/\r?\n/)) {
84 + if (fenceMarker === undefined && SAMPLE_BOUNDARY_RE.test(line)) flush();
85 +
86 + if (fenceMarker === undefined) {
87 + const opening = line.match(FENCE_OPEN_RE)?.[1];
88 + if (opening !== undefined) {
89 + fenceMarker = opening;
90 + current.push(line);
91 + }
92 + continue;
93 + }
94 +
95 + current.push(line);
96 + const closing = line.match(FENCE_CLOSE_RE)?.[1];
97 + if (
98 + closing !== undefined &&
99 + closing[0] === fenceMarker[0] &&
100 + closing.length >= fenceMarker.length
101 + ) {
102 + fenceMarker = undefined;
103 + }
104 + }
105 +
106 + flush();
107 + return groups;
108 +}
109 +
110 +function hasDirectHelperBoundToSessionTools(source: string): boolean {
111 + return codeSampleGroups(source).some(
112 + (sample) => SESSION_TOKEN_RE.test(sample) && DIRECT_HELPER_TOKEN_RE.test(sample),
113 + );
114 +}
115 +
116 +describe("session execution samples", () => {
117 + test("detects a direct helper split from session setup within one sample", () => {
118 + const source = `
119 +<Tab value="Python">
120 +~~~python
121 +session = composio.create(user_id="user_123")
122 +tools = session.tools()
123 +~~~
124 +
125 +Run the model, then execute its calls:
126 +
127 +~~~python
128 +results = composio.provider.handle_tool_calls(
129 + response=response,
130 + user_id="user_123",
131 +)
132 +~~~
133 +</Tab>`;
134 +
135 + expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
136 + });
137 +
138 + test("allows session targets and keeps separate tab samples independent", () => {
139 + const sessionTarget = `
140 +<Tab value="Python">
141 +\`\`\`python
142 +session = composio.create(user_id="user_123")
143 +tools = session.tools()
144 +\`\`\`
145 +\`\`\`python
146 +results = composio.provider.handle_tool_calls(response=response, session=session)
147 +\`\`\`
148 +</Tab>`;
149 + const separateTargets = `
150 +<Tab value="Session">
151 +\`\`\`typescript
152 +const tools = await session.tools();
153 +\`\`\`
154 +</Tab>
155 +<Tab value="Direct">
156 +\`\`\`typescript
157 +const results = await composio.provider.handleToolCalls("user_123", response);
158 +\`\`\`
159 +</Tab>`;
160 +
161 + expect(hasDirectHelperBoundToSessionTools(sessionTarget)).toBe(false);
162 + expect(hasDirectHelperBoundToSessionTools(separateTargets)).toBe(false);
163 + });
164 +
165 + test("session-bound helper is not flagged by a later unrelated user_id", () => {
166 + const source = `
167 +<Tab value="Python">
168 +\`\`\`python
169 +session = composio.create(user_id="user_123")
170 +tools = session.tools()
171 +results = composio.provider.handle_tool_calls(response=response, session=session)
172 +\`\`\`
173 +\`\`\`python
174 +other_session = composio.create(user_id="user_456")
175 +\`\`\`
176 +</Tab>`;
177 +
178 + expect(hasDirectHelperBoundToSessionTools(source)).toBe(false);
179 + });
180 +
181 + test("detects a user_id hidden behind a nested call in the same argument list", () => {
182 + const source = `
183 +<Tab value="Python">
184 +\`\`\`python
185 +session = composio.create(user_id="user_123")
186 +tools = session.tools()
187 +results = composio.provider.handle_tool_calls(response=build_response(), user_id="user_123")
188 +\`\`\`
189 +</Tab>`;
190 +
191 + expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
192 + });
193 +
194 + test("session variables that merely start with 'user' are not flagged", () => {
195 + const source = `
196 +<Tab value="TypeScript">
197 +\`\`\`typescript
198 +const userSession = await composio.create("user_123");
199 +const tools = await userSession.tools();
200 +const results = await composio.provider.handleToolCalls(userSession, response);
201 +\`\`\`
202 +</Tab>`;
203 +
204 + expect(hasDirectHelperBoundToSessionTools(source)).toBe(false);
205 + });
206 +
207 + test("detects a TypeScript helper bound to a user-ID variable", () => {
208 + const source = `
209 +<Tab value="TypeScript">
210 +\`\`\`typescript
211 +const userId = "user_123";
212 +const session = await composio.create(userId);
213 +const tools = await session.tools();
214 +const results = await composio.provider.handleToolCalls(userId, response);
215 +\`\`\`
216 +</Tab>`;
217 +
218 + expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
219 + });
220 +
221 + test("LLM guardrail blocks never bind provider helpers to a user ID", () => {
222 + for (const guardrails of [SESSION_GUARDRAILS, DIRECT_EXECUTION_GUARDRAILS]) {
223 + expect(hasDirectHelperBoundToSessionTools(guardrails)).toBe(false);
224 + }
225 + });
226 +
227 + test("session samples do not bind provider helpers to a user ID", async () => {
228 + const offenders: string[] = [];
229 +
230 + for (const dir of CONTENT_DIRS) {
231 + for (const file of await findMdxFiles(dir)) {
232 + const rel = relative(CONTENT_ROOT, file);
233 + if (EXCLUDED_PATH_SEGMENTS.some((seg) => rel.includes(seg))) continue;
234 +
235 + const source = await readFile(file, "utf8");
236 + if (hasDirectHelperBoundToSessionTools(source)) {
237 + offenders.push(rel);
238 + }
239 + }
240 + }
241 +
242 + expect(
243 + offenders,
244 + `These pages bind session tools to a direct user-ID execution target. ` +
245 + `Pass the session to the provider helper instead:\n ${offenders.join("\n ")}`,
246 + ).toEqual([]);
247 + });
248 +});
python/composio/core/provider/__init__.py
+3 -1
@@ -1,12 +1,14 @@
1 from __future__ import annotations
2
3 from .agentic import AgenticProvider, AgenticProviderExecuteFn
4 -from .base import TTool, TToolCollection
4 +from .base import TTool, TToolCollection, ToolCallExecutionTarget, ToolCallSession
5 from .none_agentic import NonAgenticProvider
6
7 __all__ = [
8 "TTool",
9 "TToolCollection",
10 + "ToolCallExecutionTarget",
11 + "ToolCallSession",
12 "AgenticProvider",
13 "NonAgenticProvider",
14 "AgenticProviderExecuteFn",
python/composio/core/provider/_openai.py
+66 -8
@@ -19,7 +19,7 @@ from openai.types.chat.chat_completion_tool_param import ChatCompletionToolParam
19 from openai.types.shared_params.function_definition import FunctionDefinition
20 from openai.types.shared_params.function_parameters import FunctionParameters
21
22 -from composio.core.provider import NonAgenticProvider
22 +from composio.core.provider import NonAgenticProvider, ToolCallSession
23 from composio.types import Modifiers, Tool, ToolExecutionResponse
24 from composio.utils.shared import normalize_tool_arguments
25
@@ -46,41 +46,92 @@ class OpenAIProvider(
46 def wrap_tools(self, tools: t.Sequence[Tool]) -> OpenAIToolCollection:
47 return [self.wrap_tool(tool) for tool in tools]
48
49 + @t.overload
50 def execute_tool_call(
51 self,
52 user_id: str,
53 tool_call: ChatCompletionMessageToolCall,
54 modifiers: t.Optional[Modifiers] = None,
55 + ) -> ToolExecutionResponse: ...
56 +
57 + @t.overload
58 + def execute_tool_call(
59 + self,
60 + *,
61 + session: ToolCallSession,
62 + tool_call: ChatCompletionMessageToolCall,
63 + ) -> ToolExecutionResponse: ...
64 +
65 + def execute_tool_call(
66 + self,
67 + user_id: t.Optional[str] = None,
68 + tool_call: t.Optional[ChatCompletionMessageToolCall] = None,
69 + modifiers: t.Optional[Modifiers] = None,
70 + *,
71 + session: t.Optional[ToolCallSession] = None,
72 ) -> ToolExecutionResponse:
73 """Execute a tool call.
74
75 :param tool_call: Tool call metadata.
58 - :param user_id: User ID to use for executing the function call.
76 + :param user_id: User ID for direct tool execution.
77 + :param session: Tool Router session that produced session tools.
78 :return: Object containing output data from the tool call.
79 """
80 + if tool_call is None:
81 + raise TypeError("tool_call is required")
82 + target = self.resolve_tool_call_execution_target(
83 + user_id=user_id, session=session
84 + )
85 +
86 # OpenAI always serializes tool arguments as a JSON string; normalize
87 # tolerates empty / object-shaped payloads too (issue #2406).
63 - return self.execute_tool(
88 + return self.execute_tool_for_target(
89 + target=target,
90 slug=tool_call.function.name,
91 arguments=normalize_tool_arguments(tool_call.function.arguments),
92 modifiers=modifiers,
67 - user_id=user_id,
93 )
94
95 + @t.overload
96 def handle_tool_calls(
97 self,
98 user_id: str,
99 response: ChatCompletion,
100 modifiers: t.Optional[Modifiers] = None,
101 + ) -> t.List[ToolExecutionResponse]: ...
102 +
103 + @t.overload
104 + def handle_tool_calls(
105 + self,
106 + *,
107 + session: ToolCallSession,
108 + response: ChatCompletion,
109 + ) -> t.List[ToolExecutionResponse]: ...
110 +
111 + def handle_tool_calls(
112 + self,
113 + user_id: t.Optional[str] = None,
114 + response: t.Optional[ChatCompletion] = None,
115 + modifiers: t.Optional[Modifiers] = None,
116 + *,
117 + session: t.Optional[ToolCallSession] = None,
118 ) -> t.List[ToolExecutionResponse]:
119 """
120 Handle tool calls from OpenAI chat completion object.
121
122 :param response: Chat completion object from
123 openai.OpenAI.chat.completions.create function call
81 - :param user_id: User ID to use for executing the function call.
124 + :param user_id: User ID for direct tool execution.
125 + :param session: Tool Router session that produced session tools.
126 :return: A list of output objects from the function calls.
127 """
128 + if response is None:
129 + raise TypeError("response is required")
130 + self.resolve_tool_call_execution_target(user_id=user_id, session=session)
131 + if session is not None and modifiers is not None:
132 + raise ValueError(
133 + "Direct execution modifiers cannot be used with a Tool Router session"
134 + )
135 outputs = []
136 # Only the first choice is actionable: its tool results feed back into a
137 # single assistant turn. With n > 1, iterating every choice would run each
@@ -91,13 +142,20 @@ class OpenAIProvider(
142 # calls, on by default); each one needs its own tool result.
143 if choice is not None and choice.message.tool_calls is not None:
144 for tool_call in choice.message.tool_calls:
94 - outputs.append(
145 + call = t.cast(ChatCompletionMessageToolCall, tool_call)
146 + result = (
147 self.execute_tool_call(
96 - user_id=user_id,
97 - tool_call=t.cast(ChatCompletionMessageToolCall, tool_call),
148 + session=session,
149 + tool_call=call,
150 + )
151 + if session is not None
152 + else self.execute_tool_call(
153 + user_id=t.cast(str, user_id),
154 + tool_call=call,
155 modifiers=modifiers,
156 )
157 )
158 + outputs.append(result)
159 return outputs
160
161 def handle_assistant_tool_calls(
python/composio/core/provider/_openai_responses.py
+67 -9
@@ -9,7 +9,7 @@ import typing as t
9 from openai.types.responses.response import Response
10 from openai.types.responses.response_output_item import ResponseFunctionToolCall
11
12 -from composio.core.provider import NonAgenticProvider
12 +from composio.core.provider import NonAgenticProvider, ToolCallSession
13 from composio.types import Modifiers, Tool, ToolExecutionResponse
14 from composio.utils.shared import normalize_tool_arguments
15
@@ -36,54 +36,112 @@ class OpenAIResponsesProvider(
36 """Wrap multiple tools for the Responses API format."""
37 return [self.wrap_tool(tool) for tool in tools]
38
39 + @t.overload
40 def execute_tool_call(
41 self,
42 user_id: str,
43 tool_call: t.Union[ResponseFunctionToolCall],
44 modifiers: t.Optional[Modifiers] = None,
45 + ) -> ToolExecutionResponse: ...
46 +
47 + @t.overload
48 + def execute_tool_call(
49 + self,
50 + *,
51 + session: ToolCallSession,
52 + tool_call: ResponseFunctionToolCall,
53 + ) -> ToolExecutionResponse: ...
54 +
55 + def execute_tool_call(
56 + self,
57 + user_id: t.Optional[str] = None,
58 + tool_call: t.Optional[ResponseFunctionToolCall] = None,
59 + modifiers: t.Optional[Modifiers] = None,
60 + *,
61 + session: t.Optional[ToolCallSession] = None,
62 ) -> ToolExecutionResponse:
63 """Execute a tool call from the Responses API.
64
65 :param tool_call: Tool call metadata from Responses API.
48 - :param user_id: User ID to use for executing the function call.
66 + :param user_id: User ID for direct tool execution.
67 + :param session: Tool Router session that produced session tools.
68 :param modifiers: Optional modifiers for tool execution.
69 :return: Object containing output data from the tool call.
70 """
71 + if tool_call is None:
72 + raise TypeError("tool_call is required")
73 + target = self.resolve_tool_call_execution_target(
74 + user_id=user_id, session=session
75 + )
76 +
77 # OpenAI always serializes tool arguments as a JSON string; normalize
78 # tolerates empty / object-shaped payloads too (issue #2406).
79 slug = tool_call.name
80 arguments = normalize_tool_arguments(tool_call.arguments)
81
57 - return self.execute_tool(
82 + return self.execute_tool_for_target(
83 + target=target,
84 slug=slug,
85 arguments=arguments,
86 modifiers=modifiers,
61 - user_id=user_id,
87 )
88
89 + @t.overload
90 def handle_tool_calls(
91 self,
92 user_id: str,
93 response: Response,
94 modifiers: t.Optional[Modifiers] = None,
95 + ) -> t.List[ToolExecutionResponse]: ...
96 +
97 + @t.overload
98 + def handle_tool_calls(
99 + self,
100 + *,
101 + session: ToolCallSession,
102 + response: Response,
103 + ) -> t.List[ToolExecutionResponse]: ...
104 +
105 + def handle_tool_calls(
106 + self,
107 + user_id: t.Optional[str] = None,
108 + response: t.Optional[Response] = None,
109 + modifiers: t.Optional[Modifiers] = None,
110 + *,
111 + session: t.Optional[ToolCallSession] = None,
112 ) -> t.List[ToolExecutionResponse]:
113 """
114 Handle tool calls from OpenAI Responses API.
115
116 :param response: Response object from openai.OpenAI.beta.responses.create
74 - :param user_id: User ID to use for executing the function call.
117 + :param user_id: User ID for direct tool execution.
118 + :param session: Tool Router session that produced session tools.
119 :param modifiers: Optional modifiers for tool execution
120 :return: List[ToolExecutionResponse] with tool execution results
121 """
122 + if response is None:
123 + raise TypeError("response is required")
124 + self.resolve_tool_call_execution_target(user_id=user_id, session=session)
125 + if session is not None and modifiers is not None:
126 + raise ValueError(
127 + "Direct execution modifiers cannot be used with a Tool Router session"
128 + )
129 outputs = []
130
131 if response.output:
132 for item in response.output:
133 if isinstance(item, ResponseFunctionToolCall):
83 - result = self.execute_tool_call(
84 - user_id=user_id,
85 - tool_call=item,
86 - modifiers=modifiers,
134 + result = (
135 + self.execute_tool_call(
136 + session=session,
137 + tool_call=item,
138 + )
139 + if session is not None
140 + else self.execute_tool_call(
141 + user_id=t.cast(str, user_id),
142 + tool_call=item,
143 + modifiers=modifiers,
144 + )
145 )
146 outputs.append(result)
147
python/composio/core/provider/base.py
+56
@@ -37,6 +37,20 @@ class ExecuteToolFn(t.Protocol):
37 ...
38
39
40 +class ToolCallSession(t.Protocol):
41 + """Execution contract implemented by ToolRouterSession."""
42 +
43 + def execute(
44 + self,
45 + tool_slug: str,
46 + *,
47 + arguments: t.Optional[t.Dict[str, t.Any]] = None,
48 + ) -> t.Any: ...
49 +
50 +
51 +ToolCallExecutionTarget: t.TypeAlias = t.Union[str, ToolCallSession]
52 +
53 +
54 class SchemaConfig(te.TypedDict):
55 skip_defaults: te.NotRequired[bool]
56
@@ -71,3 +85,45 @@ class BaseProvider(t.Generic[TTool, TToolCollection]):
85
86 def set_execute_tool_fn(self, execute_tool_fn: ExecuteToolFn) -> None:
87 self.execute_tool = execute_tool_fn
88 +
89 + def resolve_tool_call_execution_target(
90 + self,
91 + *,
92 + user_id: t.Optional[str],
93 + session: t.Optional[ToolCallSession],
94 + ) -> ToolCallExecutionTarget:
95 + """Resolve exactly one direct user or Tool Router session target."""
96 + if (user_id is None) == (session is None):
97 + raise ValueError("Provide exactly one of user_id or session")
98 + if session is not None:
99 + return session
100 + return t.cast(str, user_id)
101 +
102 + def execute_tool_for_target(
103 + self,
104 + *,
105 + target: ToolCallExecutionTarget,
106 + slug: str,
107 + arguments: t.Dict[str, t.Any],
108 + modifiers: t.Optional[Modifiers] = None,
109 + ) -> ToolExecutionResponse:
110 + """Execute normalized arguments through the matching SDK boundary."""
111 + if isinstance(target, str):
112 + return self.execute_tool(
113 + slug=slug,
114 + arguments=arguments,
115 + modifiers=modifiers,
116 + user_id=target,
117 + )
118 +
119 + if modifiers is not None:
120 + raise ValueError(
121 + "Direct execution modifiers cannot be used with a Tool Router session"
122 + )
123 +
124 + result = target.execute(tool_slug=slug, arguments=arguments)
125 + return {
126 + "data": t.cast(t.Dict, result.data),
127 + "error": result.error,
128 + "successful": result.error is None,
129 + }
python/providers/anthropic/README.md
+2 -2
@@ -41,7 +41,7 @@ response = client.messages.create(
41 # Agentic loop: keep executing tool calls until the model responds with text
42 while response.stop_reason == "tool_use":
43 tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
44 - results = composio.provider.handle_tool_calls(user_id="user_123", response=response)
44 + results = composio.provider.handle_tool_calls(session=session, response=response)
45 messages.append({"role": "assistant", "content": response.content})
46 messages.append({
47 "role": "user",
@@ -63,7 +63,7 @@ for block in response.content:
63 print(block.text)
64 ```
65
66 -`handle_tool_calls` extracts every `tool_use` block from the response, executes the matching Composio tools, and returns the raw results in order. Claude occasionally emits tool input as a JSON string instead of an object; the provider normalizes this before execution.
66 +`handle_tool_calls` extracts every `tool_use` block from the response, executes the matching Composio tools through the supplied session, and returns the raw results in order. Pass `user_id` instead for tools fetched with `tools.get()`. Claude occasionally emits tool input as a JSON string instead of an object; the provider normalizes this before execution.
67
68 Building on the Claude Agent SDK instead of the Messages API? Use [`composio-claude-agent-sdk`](../claude_agent_sdk).
69
python/providers/anthropic/composio_anthropic/provider.py
+64 -7
@@ -5,7 +5,7 @@ from anthropic.types.message import Message as ToolsBetaMessage
5 from anthropic.types.tool_param import ToolParam
6 from anthropic.types.tool_use_block import ToolUseBlock
7
8 -from composio.core.provider import NonAgenticProvider
8 +from composio.core.provider import NonAgenticProvider, ToolCallSession
9 from composio.types import Modifiers, Tool, ToolExecutionResponse
10 from composio.utils.shared import (
11 ToolSchemaAliases,
@@ -38,58 +38,115 @@ class AnthropicProvider(
38 def wrap_tools(self, tools: t.Sequence[Tool]) -> list[ToolParam]:
39 return [self.wrap_tool(tool) for tool in tools]
40
41 + @t.overload
42 def execute_tool_call(
43 self,
44 user_id: str,
45 tool_call: ToolUseBlock,
46 modifiers: t.Optional[Modifiers] = None,
47 + ) -> ToolExecutionResponse: ...
48 +
49 + @t.overload
50 + def execute_tool_call(
51 + self,
52 + *,
53 + session: ToolCallSession,
54 + tool_call: ToolUseBlock,
55 + ) -> ToolExecutionResponse: ...
56 +
57 + def execute_tool_call(
58 + self,
59 + user_id: t.Optional[str] = None,
60 + tool_call: t.Optional[ToolUseBlock] = None,
61 + modifiers: t.Optional[Modifiers] = None,
62 + *,
63 + session: t.Optional[ToolCallSession] = None,
64 ) -> ToolExecutionResponse:
65 """
66 Execute a tool call.
67
50 - :param user_id: User ID to use for executing function calls.
68 + :param user_id: User ID for direct tool execution.
69 + :param session: Tool Router session that produced session tools.
70 :param tool_call: Tool call metadata.
71 :param modifiers: Modifiers to use for executing function calls.
72 :return: Object containing output data from the tool call.
73 """
74 + if tool_call is None:
75 + raise TypeError("tool_call is required")
76 + target = self.resolve_tool_call_execution_target(
77 + user_id=user_id, session=session
78 + )
79 +
80 # Models occasionally emit tool input as a JSON string rather than a dict (issue #2406).
81 arguments = normalize_tool_arguments(tool_call.input)
82 aliases = self._aliases.get(tool_call.name)
83 if aliases is not None:
84 arguments = aliases.restore_arguments(arguments)
60 - return self.execute_tool(
85 + return self.execute_tool_for_target(
86 + target=target,
87 slug=tool_call.name,
88 arguments=arguments,
89 modifiers=modifiers,
64 - user_id=user_id,
90 )
91
92 + @t.overload
93 def handle_tool_calls(
94 self,
95 user_id: str,
96 response: t.Union[dict, ToolsBetaMessage],
97 modifiers: t.Optional[Modifiers] = None,
98 + ) -> t.List[ToolExecutionResponse]: ...
99 +
100 + @t.overload
101 + def handle_tool_calls(
102 + self,
103 + *,
104 + session: ToolCallSession,
105 + response: t.Union[dict, ToolsBetaMessage],
106 + ) -> t.List[ToolExecutionResponse]: ...
107 +
108 + def handle_tool_calls(
109 + self,
110 + user_id: t.Optional[str] = None,
111 + response: t.Optional[t.Union[dict, ToolsBetaMessage]] = None,
112 + modifiers: t.Optional[Modifiers] = None,
113 + *,
114 + session: t.Optional[ToolCallSession] = None,
115 ) -> t.List[ToolExecutionResponse]:
116 """
117 Handle tool calls from Anthropic Claude chat completion object.
118
119 :param response: Chat completion object from
120 `anthropic.Anthropic.beta.tools.messages.create` function call.
78 - :param user_id: User ID to use for executing function calls.
121 + :param user_id: User ID for direct tool execution.
122 + :param session: Tool Router session that produced session tools.
123 :param modifiers: Modifiers to use for executing function calls.
124 :return: A list of output objects from the tool calls.
125 """
126 + if response is None:
127 + raise TypeError("response is required")
128 + self.resolve_tool_call_execution_target(user_id=user_id, session=session)
129 + if session is not None and modifiers is not None:
130 + raise ValueError(
131 + "Direct execution modifiers cannot be used with a Tool Router session"
132 + )
133 if isinstance(response, dict):
134 response = ToolsBetaMessage(**response)
135
136 outputs = []
137 for content in response.content:
138 if isinstance(content, (ToolUseBlock, BetaToolUseBlock)):
88 - outputs.append(
139 + result = (
140 self.execute_tool_call(
90 - user_id=user_id,
141 + session=session,
142 + tool_call=content,
143 + )
144 + if session is not None
145 + else self.execute_tool_call(
146 + user_id=t.cast(str, user_id),
147 tool_call=content,
148 modifiers=modifiers,
149 )
150 )
151 + outputs.append(result)
152 return outputs
python/providers/openai/README.md
+2 -2
@@ -43,7 +43,7 @@ while True:
43 tool_calls = [o for o in response.output if o.type == "function_call"]
44 if not tool_calls:
45 break
46 - results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
46 + results = composio.provider.handle_tool_calls(response=response, session=session)
47 response = client.responses.create(
48 model="gpt-5.2",
49 tools=tools,
@@ -62,7 +62,7 @@ for item in response.output:
62
63 ## Chat Completions
64
65 -`OpenAIProvider` targets `client.chat.completions.create` and is the Composio SDK default, so `Composio()` with no provider uses it. The loop is the same shape: call `handle_tool_calls` on each response, append the results as `tool` messages, and call the API again. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the full example.
65 +`OpenAIProvider` targets `client.chat.completions.create` and is the Composio SDK default, so `Composio()` with no provider uses it. The loop is the same shape: call `handle_tool_calls(response=response, session=session)`, append the results as `tool` messages, and call the API again. Pass `user_id` instead for tools fetched with `tools.get()`. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the full example.
66
67 ## Links
68
python/tests/test_provider.py
+127 -1
@@ -7,7 +7,8 @@ This test module verifies provider functionality including:
7 - Both agentic and non-agentic provider behavior
8 """
9
10 -from unittest.mock import Mock
10 +from types import SimpleNamespace
11 +from unittest.mock import Mock, call
12
13 import pytest
14
@@ -503,6 +504,131 @@ class TestNonAgenticProviderHelperMethods:
504 assert results[0]["successful"] is True
505 assert results[0]["data"]["starred"] is True
506
507 + def test_openai_provider_routes_tool_calls_through_session(self):
508 + """Session tools execute through their Tool Router session, not tools.execute."""
509 + mock_client = mock_http_client()
510 + from composio.core.provider._openai import OpenAIProvider
511 +
512 + provider = OpenAIProvider()
513 + Tools(client=mock_client, provider=provider)
514 + session = Mock()
515 + session.execute.return_value = SimpleNamespace(
516 + data={"tools": ["GMAIL_SEND_EMAIL"]},
517 + error=None,
518 + log_id="log-session",
519 + )
520 + completion = SimpleNamespace(
521 + choices=[
522 + SimpleNamespace(
523 + message=SimpleNamespace(
524 + tool_calls=[
525 + SimpleNamespace(
526 + id="call-search",
527 + type="function",
528 + function=SimpleNamespace(
529 + name="COMPOSIO_SEARCH_TOOLS",
530 + arguments='{"queries":[{"use_case":"send email"}]}',
531 + ),
532 + )
533 + ],
534 + ),
535 + )
536 + ],
537 + )
538 +
539 + results = provider.handle_tool_calls(response=completion, session=session)
540 +
541 + session.execute.assert_called_once_with(
542 + tool_slug="COMPOSIO_SEARCH_TOOLS",
543 + arguments={"queries": [{"use_case": "send email"}]},
544 + )
545 + mock_client.tools.execute.assert_not_called()
546 + assert results == [
547 + {
548 + "data": {"tools": ["GMAIL_SEND_EMAIL"]},
549 + "error": None,
550 + "successful": True,
551 + }
552 + ]
553 +
554 + def test_openai_responses_provider_preserves_session_result_order(self):
555 + """Responses helpers keep provider order and result shape for session calls."""
556 + from openai.types.responses.response import Response
557 + from openai.types.responses.response_function_tool_call import (
558 + ResponseFunctionToolCall,
559 + )
560 +
561 + from composio.core.provider._openai_responses import OpenAIResponsesProvider
562 +
563 + mock_client = mock_http_client()
564 + provider = OpenAIResponsesProvider()
565 + Tools(client=mock_client, provider=provider)
566 + session = Mock()
567 + session.execute.side_effect = [
568 + SimpleNamespace(data={"index": 1}, error=None, log_id="log-1"),
569 + SimpleNamespace(data={"index": 2}, error="failed", log_id="log-2"),
570 + ]
571 + response = Response.model_construct(
572 + output=[
573 + ResponseFunctionToolCall(
574 + arguments='{"queries":[{"use_case":"first"}]}',
575 + call_id="call-1",
576 + name="COMPOSIO_SEARCH_TOOLS",
577 + type="function_call",
578 + ),
579 + ResponseFunctionToolCall(
580 + arguments='{"queries":[{"use_case":"second"}]}',
581 + call_id="call-2",
582 + name="COMPOSIO_SEARCH_TOOLS",
583 + type="function_call",
584 + ),
585 + ]
586 + )
587 +
588 + results = provider.handle_tool_calls(response=response, session=session)
589 +
590 + assert session.execute.call_args_list == [
591 + call(
592 + tool_slug="COMPOSIO_SEARCH_TOOLS",
593 + arguments={"queries": [{"use_case": "first"}]},
594 + ),
595 + call(
596 + tool_slug="COMPOSIO_SEARCH_TOOLS",
597 + arguments={"queries": [{"use_case": "second"}]},
598 + ),
599 + ]
600 + mock_client.tools.execute.assert_not_called()
601 + assert results == [
602 + {"data": {"index": 1}, "error": None, "successful": True},
603 + {"data": {"index": 2}, "error": "failed", "successful": False},
604 + ]
605 +
606 + def test_openai_responses_provider_propagates_session_exceptions(self):
607 + """Responses helpers preserve their existing exception propagation behavior."""
608 + from openai.types.responses.response import Response
609 + from openai.types.responses.response_function_tool_call import (
610 + ResponseFunctionToolCall,
611 + )
612 +
613 + from composio.core.provider._openai_responses import OpenAIResponsesProvider
614 +
615 + provider = OpenAIResponsesProvider()
616 + session = Mock()
617 + session.execute.side_effect = RuntimeError("session execution failed")
618 + response = Response.model_construct(
619 + output=[
620 + ResponseFunctionToolCall(
621 + arguments="{}",
622 + call_id="call-1",
623 + name="COMPOSIO_SEARCH_TOOLS",
624 + type="function_call",
625 + )
626 + ]
627 + )
628 +
629 + with pytest.raises(RuntimeError, match="session execution failed"):
630 + provider.handle_tool_calls(response=response, session=session)
631 +
632 def test_openai_provider_handle_tool_calls_only_first_choice(self):
633 """Only the first choice runs; n > 1 alternatives would orphan tool_call_ids."""
634 from openai.types.chat import ChatCompletion
python/tests/test_tool_schema_aliasing.py
+18
@@ -351,6 +351,24 @@ def test_anthropic_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
351 user_id="user",
352 )
353
354 + session = Mock()
355 + session.execute.return_value = SimpleNamespace(
356 + data={"ok": True}, error=None, log_id="log-session"
357 + )
358 + provider.execute_tool.reset_mock()
359 + result = provider.execute_tool_call(session=session, tool_call=tool_call)
360 +
361 + session.execute.assert_called_once_with(
362 + tool_slug="TOOL_WITH_ODATA",
363 + arguments={
364 + "$top": 10,
365 + "@microsoft.graph.conflictBehavior": "rename",
366 + long_name: "value",
367 + },
368 + )
369 + provider.execute_tool.assert_not_called()
370 + assert result == {"data": {"ok": True}, "error": None, "successful": True}
371 +
372
373 def test_claude_agent_sdk_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
374 claude_agent_sdk_module = types.ModuleType("claude_agent_sdk")
ts/packages/core/src/provider/BaseProvider.ts
+53 -1
@@ -1,7 +1,12 @@
1 import { ComposioGlobalExecuteToolFnNotSetError } from '../errors/ToolErrors';
2 import { ExecuteToolModifiers } from '../types/modifiers.types';
3 import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '../types/tool.types';
4 -import { ExecuteToolFn, GlobalExecuteToolFn } from '../types/provider.types';
4 +import {
5 + ExecuteToolFn,
6 + ExecuteToolFnOptions,
7 + GlobalExecuteToolFn,
8 + ToolCallExecutionTarget,
9 +} from '../types/provider.types';
10 import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
11
12 /**
@@ -60,6 +65,53 @@ abstract class BaseProvider<TMcpResponse> {
65 return this._globalExecuteToolFn(toolSlug, body, modifers);
66 }
67
68 + /** Reject direct-only configuration when execution is bound to a session. */
69 + protected assertToolCallExecutionOptions(
70 + target: ToolCallExecutionTarget,
71 + options?: ExecuteToolFnOptions,
72 + modifiers?: ExecuteToolModifiers
73 + ): void {
74 + if (typeof target !== 'string' && (options !== undefined || modifiers !== undefined)) {
75 + throw new TypeError(
76 + 'Direct execution options and modifiers cannot be used with a Tool Router session'
77 + );
78 + }
79 + }
80 +
81 + /**
82 + * Execute normalized provider arguments against either the direct tools API or
83 + * the Tool Router session that produced the model-visible tools.
84 + */
85 + protected async executeToolForTarget(
86 + target: ToolCallExecutionTarget,
87 + toolSlug: string,
88 + arguments_: Record<string, unknown>,
89 + options?: ExecuteToolFnOptions,
90 + modifiers?: ExecuteToolModifiers
91 + ): Promise<ToolExecuteResponse> {
92 + this.assertToolCallExecutionOptions(target, options, modifiers);
93 +
94 + if (typeof target === 'string') {
95 + return this.executeTool(
96 + toolSlug,
97 + {
98 + arguments: arguments_,
99 + connectedAccountId: options?.connectedAccountId,
100 + customAuthParams: options?.customAuthParams,
101 + customConnectionData: options?.customConnectionData,
102 + userId: target,
103 + },
104 + modifiers
105 + );
106 + }
107 +
108 + const result = await target.execute(toolSlug, arguments_);
109 + return {
110 + ...result,
111 + successful: result.error === null,
112 + };
113 + }
114 +
115 /**
116 * @public
117 * @deprecated: Will be removed in a future version, once the `experimental.mcp` flag is stabilized. Use `wrapMcpServers` instead.
ts/packages/core/src/provider/OpenAIProvider.ts
+43 -15
@@ -10,10 +10,14 @@
10 import { OpenAI } from 'openai';
11 import { Stream } from 'openai/streaming';
12 import { BaseNonAgenticProvider } from './BaseProvider';
13 -import { Tool, ToolExecuteParams } from '../types/tool.types';
13 +import { Tool } from '../types/tool.types';
14 import logger from '../utils/logger';
15 import { ExecuteToolModifiers } from '../types/modifiers.types';
16 -import { ExecuteToolFnOptions } from '../types/provider.types';
16 +import {
17 + ExecuteToolFnOptions,
18 + ToolCallExecutionTarget,
19 + ToolCallSession,
20 +} from '../types/provider.types';
21 import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
22 import { normalizeToolArguments } from '../utils/toolArguments';
23 import { deduplicateJsonSchemaRequiredArrays } from '../utils/jsonSchema';
@@ -153,7 +157,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
157 * This method processes a tool call from OpenAI's chat completion API,
158 * executes the corresponding Composio tool, and returns the result.
159 *
156 - * @param {string} userId - The user ID for authentication and tracking
160 + * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
161 * @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
162 * @param {ExecuteToolFnOptions} [options] - Optional execution options
163 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -179,22 +183,32 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
183 * console.log(JSON.parse(result));
184 * ```
185 */
186 + async executeToolCall(
187 + session: ToolCallSession,
188 + tool: OpenAI.ChatCompletionMessageFunctionToolCall
189 + ): Promise<string>;
190 async executeToolCall(
191 userId: string,
192 tool: OpenAI.ChatCompletionMessageFunctionToolCall,
193 options?: ExecuteToolFnOptions,
194 modifiers?: ExecuteToolModifiers
195 + ): Promise<string>;
196 + async executeToolCall(
197 + executionTarget: ToolCallExecutionTarget,
198 + tool: OpenAI.ChatCompletionMessageFunctionToolCall,
199 + options?: ExecuteToolFnOptions,
200 + modifiers?: ExecuteToolModifiers
201 ): Promise<string> {
188 - const payload: ToolExecuteParams = {
189 - // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
190 - // empty / object-shaped payloads too (issue #2406).
191 - arguments: normalizeToolArguments(tool.function.arguments, tool.function.name),
192 - connectedAccountId: options?.connectedAccountId,
193 - customAuthParams: options?.customAuthParams,
194 - customConnectionData: options?.customConnectionData,
195 - userId: userId,
196 - };
197 - const result = await this.executeTool(tool.function.name, payload, modifiers);
202 + // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
203 + // empty / object-shaped payloads too (issue #2406).
204 + const arguments_ = normalizeToolArguments(tool.function.arguments, tool.function.name);
205 + const result = await this.executeToolForTarget(
206 + executionTarget,
207 + tool.function.name,
208 + arguments_,
209 + options,
210 + modifiers
211 + );
212 return JSON.stringify(result);
213 }
214
@@ -204,7 +218,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
218 * This method processes tool calls from an OpenAI chat completion response,
219 * executes each tool call, and returns the results.
220 *
207 - * @param {string} userId - The user ID for authentication and tracking
221 + * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
222 * @param {OpenAI.ChatCompletion} chatCompletion - The chat completion response from OpenAI
223 * @param {ExecuteToolFnOptions} [options] - Optional execution options
224 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -240,12 +254,23 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
254 * console.log(results); // Array of tool execution results
255 * ```
256 */
257 + async handleToolCalls(
258 + session: ToolCallSession,
259 + chatCompletion: OpenAI.ChatCompletion
260 + ): Promise<OpenAI.ChatCompletionToolMessageParam[]>;
261 async handleToolCalls(
262 userId: string,
263 chatCompletion: OpenAI.ChatCompletion,
264 options?: ExecuteToolFnOptions,
265 modifiers?: ExecuteToolModifiers
266 + ): Promise<OpenAI.ChatCompletionToolMessageParam[]>;
267 + async handleToolCalls(
268 + executionTarget: ToolCallExecutionTarget,
269 + chatCompletion: OpenAI.ChatCompletion,
270 + options?: ExecuteToolFnOptions,
271 + modifiers?: ExecuteToolModifiers
272 ): Promise<OpenAI.ChatCompletionToolMessageParam[]> {
273 + this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
274 const outputs: OpenAI.ChatCompletionToolMessageParam[] = [];
275 // Only the first choice is actionable: its tool results feed back into a
276 // single assistant turn. With n > 1, iterating every choice would run each
@@ -259,7 +284,10 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
284 if (toolCall.type !== 'function') {
285 continue;
286 }
262 - const toolResult = await this.executeToolCall(userId, toolCall, options, modifiers);
287 + const toolResult =
288 + typeof executionTarget === 'string'
289 + ? await this.executeToolCall(executionTarget, toolCall, options, modifiers)
290 + : await this.executeToolCall(executionTarget, toolCall);
291 outputs.push({
292 role: 'tool',
293 tool_call_id: toolCall.id,
ts/packages/core/src/types/provider.types.ts
+15
@@ -8,6 +8,7 @@ import {
8 ToolListParams,
9 } from './tool.types';
10 import { CustomConnectionData } from './connectedAccountAuthStates.types';
11 +import type { ToolRouterSessionExecuteResponse } from './toolRouter.types';
12
13 /**
14 * Base provider implementation, which needs to be implemented by the extended class.
@@ -25,6 +26,20 @@ export type ExecuteToolFnOptions = {
26 customConnectionData?: CustomConnectionData;
27 };
28
29 +/**
30 + * Minimal public contract required to execute model tool calls through a Tool Router session.
31 + * {@link ToolRouterSession} satisfies this interface.
32 + */
33 +export interface ToolCallSession {
34 + execute(
35 + toolSlug: string,
36 + arguments_?: Record<string, unknown>
37 + ): Promise<ToolRouterSessionExecuteResponse>;
38 +}
39 +
40 +/** Direct user execution or execution bound to a Tool Router session. */
41 +export type ToolCallExecutionTarget = string | ToolCallSession;
42 +
43 /**
44 * This type is used to infer the wrapped tool type from the provider.
45 * It checks if the provider has a method `_wrapTool` and infers the return type.
ts/packages/core/test/provider/openai-provider.test.ts
+68
@@ -200,6 +200,74 @@ describe('OpenAIProvider', () => {
200 });
201
202 describe('handleToolCalls', () => {
203 + it('routes session tool calls through the session executor', async () => {
204 + const session = {
205 + execute: vi.fn().mockResolvedValue({
206 + data: { tools: ['GMAIL_SEND_EMAIL'] },
207 + error: null,
208 + logId: 'log-session',
209 + }),
210 + };
211 + const chatCompletion = {
212 + choices: [
213 + {
214 + message: {
215 + tool_calls: [
216 + {
217 + id: 'call-search',
218 + type: 'function',
219 + function: {
220 + name: 'COMPOSIO_SEARCH_TOOLS',
221 + arguments: JSON.stringify({ queries: [{ use_case: 'send email' }] }),
222 + },
223 + },
224 + ],
225 + },
226 + },
227 + ],
228 + } as OpenAI.ChatCompletion;
229 +
230 + const results = await provider.handleToolCalls(session, chatCompletion);
231 +
232 + expect(session.execute).toHaveBeenCalledWith('COMPOSIO_SEARCH_TOOLS', {
233 + queries: [{ use_case: 'send email' }],
234 + });
235 + expect(mockExecuteToolFn).not.toHaveBeenCalled();
236 + expect(results).toEqual([
237 + {
238 + role: 'tool',
239 + tool_call_id: 'call-search',
240 + content: JSON.stringify({
241 + data: { tools: ['GMAIL_SEND_EMAIL'] },
242 + error: null,
243 + logId: 'log-session',
244 + successful: true,
245 + }),
246 + },
247 + ]);
248 + });
249 +
250 + it('rejects direct execution options for session tool calls', async () => {
251 + const session = {
252 + execute: vi.fn(),
253 + };
254 + const chatCompletion = { choices: [] } as unknown as OpenAI.ChatCompletion;
255 + const handleToolCallsWithOptions = provider.handleToolCalls as unknown as (
256 + executionTarget: typeof session,
257 + response: OpenAI.ChatCompletion,
258 + options: { connectedAccountId: string }
259 + ) => ReturnType<OpenAIProvider['handleToolCalls']>;
260 +
261 + await expect(
262 + handleToolCallsWithOptions.call(provider, session, chatCompletion, {
263 + connectedAccountId: 'conn-123',
264 + })
265 + ).rejects.toThrow(
266 + 'Direct execution options and modifiers cannot be used with a Tool Router session'
267 + );
268 + expect(session.execute).not.toHaveBeenCalled();
269 + });
270 +
271 it('should handle tool calls from chat completion', async () => {
272 const userId = 'test-user';
273 const chatCompletion = {
ts/packages/providers/anthropic/README.md
+2 -2
@@ -45,7 +45,7 @@ let response = await client.messages.create({
45
46 // Agentic loop: keep executing tool calls until the model responds with text
47 while (response.stop_reason === 'tool_use') {
48 - const toolResults = await composio.provider.handleToolCalls('user_123', response);
48 + const toolResults = await composio.provider.handleToolCalls(session, response);
49 messages.push({ role: 'assistant', content: response.content });
50 messages.push(...toolResults);
51 response = await client.messages.create({
@@ -69,7 +69,7 @@ Building on the Claude Agent SDK instead? Use [`@composio/claude-agent-sdk`](../
69 ## Provider options
70
71 - `cacheTools`: pass `new AnthropicProvider({ cacheTools: true })` to attach Anthropic's ephemeral `cache_control` to every tool definition and tool-result block. This lets Claude reuse cached tool schemas across requests and can cut prompt cost when you send the same large tool set on every turn. It is the only constructor option.
72 -- `handleToolCalls(userId, message)` returns `Anthropic.Messages.MessageParam[]`, not raw strings, so you append the result directly to your message list. For finer control, `executeToolCall(userId, toolUseBlock)` runs a single `tool_use` block and returns the result as a JSON string.
72 +- `handleToolCalls(session, message)` returns `Anthropic.Messages.MessageParam[]`, not raw strings, so you append the result directly to your message list. Pass a user ID instead of a session for tools fetched with `tools.get()`. For finer control, `executeToolCall(session, toolUseBlock)` runs a single `tool_use` block and returns the result as a JSON string.
73 - Claude occasionally emits a tool's `input` as a JSON string instead of an object; the provider normalizes this before execution.
74
75 ## Links
ts/packages/providers/anthropic/src/index.ts
+34 -13
@@ -12,7 +12,8 @@ import {
12 Tool as ComposioTool,
13 ExecuteToolModifiers,
14 ExecuteToolFnOptions,
15 - ToolExecuteParams,
15 + ToolCallExecutionTarget,
16 + ToolCallSession,
17 logger,
18 McpUrlResponse,
19 normalizeToolArguments,
@@ -243,7 +244,7 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
244 * This method processes a tool call from Anthropic's Claude API,
245 * executes the corresponding Composio tool, and returns the result.
246 *
246 - * @param userId - The user ID for authentication and tracking
247 + * @param executionTarget - A user ID for direct tools or the session that produced session tools
248 * @param toolUse - The tool use object from Anthropic
249 * @param options - Additional options for tool execution
250 * @param modifiers - Modifiers for tool execution
@@ -269,11 +270,18 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
270 * console.log(JSON.parse(result));
271 * ```
272 */
273 + async executeToolCall(session: ToolCallSession, toolUse: AnthropicToolUseBlock): Promise<string>;
274 async executeToolCall(
275 userId: string,
276 toolUse: AnthropicToolUseBlock,
277 options?: ExecuteToolFnOptions,
278 modifiers?: ExecuteToolModifiers
279 + ): Promise<string>;
280 + async executeToolCall(
281 + executionTarget: ToolCallExecutionTarget,
282 + toolUse: AnthropicToolUseBlock,
283 + options?: ExecuteToolFnOptions,
284 + modifiers?: ExecuteToolModifiers
285 ): Promise<string> {
286 // Models occasionally emit tool input as a JSON string rather than an object
287 // (issue #2406). Normalize to a plain object first so key restoration below can
@@ -291,15 +299,14 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
299 logger.debug(`AnthropicProvider restored original argument keys for tool "${toolUse.name}"`);
300 }
301
294 - const payload: ToolExecuteParams = {
295 - arguments: toolArguments,
296 - connectedAccountId: options?.connectedAccountId,
297 - customAuthParams: options?.customAuthParams,
298 - customConnectionData: options?.customConnectionData,
299 - userId: userId,
300 - };
301 - const result = await this.executeTool(toolUse.name, payload, modifiers);
302 - return JSON.stringify(result.data);
302 + const result = await this.executeToolForTarget(
303 + executionTarget,
304 + toolUse.name,
305 + toolArguments,
306 + options,
307 + modifiers
308 + );
309 + return JSON.stringify(result.error === null ? result.data : { error: result.error });
310 }
311
312 /**
@@ -308,7 +315,7 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
315 * This method processes tool calls from an Anthropic message response,
316 * extracts the tool use blocks, executes each tool call, and returns the results.
317 *
311 - * @param userId - The user ID for authentication and tracking
318 + * @param executionTarget - A user ID for direct tools or the session that produced session tools
319 * @param message - The message response from Anthropic
320 * @param options - Additional options for tool execution
321 * @param modifiers - Modifiers for tool execution
@@ -342,12 +349,23 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
349 * console.log(results);
350 * ```
351 */
352 + async handleToolCalls(
353 + session: ToolCallSession,
354 + message: Anthropic.Message
355 + ): Promise<Anthropic.Messages.MessageParam[]>;
356 async handleToolCalls(
357 userId: string,
358 message: Anthropic.Message,
359 options?: ExecuteToolFnOptions,
360 modifiers?: ExecuteToolModifiers
361 + ): Promise<Anthropic.Messages.MessageParam[]>;
362 + async handleToolCalls(
363 + executionTarget: ToolCallExecutionTarget,
364 + message: Anthropic.Message,
365 + options?: ExecuteToolFnOptions,
366 + modifiers?: ExecuteToolModifiers
367 ): Promise<Anthropic.Messages.MessageParam[]> {
368 + this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
369 const outputs: Anthropic.Messages.ToolResultBlockParam[] = [];
370
371 // Filter and map tool use blocks from message content
@@ -374,7 +392,10 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
392 }
393
394 for (const toolUse of toolUseBlocks) {
377 - const toolResult = await this.executeToolCall(userId, toolUse, options, modifiers);
395 + const toolResult =
396 + typeof executionTarget === 'string'
397 + ? await this.executeToolCall(executionTarget, toolUse, options, modifiers)
398 + : await this.executeToolCall(executionTarget, toolUse);
399 outputs.push({
400 type: 'tool_result',
401 tool_use_id: toolUse.id,
ts/packages/providers/anthropic/test/anthropic.test.ts
+29
@@ -203,6 +203,35 @@ describe('AnthropicProvider', () => {
203 expect(result).toBe(JSON.stringify({ result: 'success' }));
204 });
205
206 + it('should expose session execution errors without changing successful results', async () => {
207 + const toolUse: AnthropicToolUseBlock = {
208 + type: 'tool_use',
209 + id: 'tu_123',
210 + name: 'test-tool',
211 + input: { input: 'test-value' },
212 + };
213 + const session = {
214 + execute: vi
215 + .fn()
216 + .mockResolvedValueOnce({
217 + data: { result: 'success' },
218 + error: null,
219 + logId: 'log-success',
220 + })
221 + .mockResolvedValueOnce({
222 + data: {},
223 + error: 'Tool execution failed',
224 + logId: 'log-failure',
225 + }),
226 + };
227 +
228 + const successfulResult = await provider.executeToolCall(session, toolUse);
229 + const failedResult = await provider.executeToolCall(session, toolUse);
230 +
231 + expect(successfulResult).toBe(JSON.stringify({ result: 'success' }));
232 + expect(failedResult).toBe(JSON.stringify({ error: 'Tool execution failed' }));
233 + });
234 +
235 it('should normalize a stringified-JSON input to an object before executing (issue #2406)', async () => {
236 const params = { input: 'test-value' };
237 const toolUse: AnthropicToolUseBlock = {
ts/packages/providers/anthropic/test/sanitize-keys.test.ts
+25
@@ -617,6 +617,31 @@ describe('AnthropicProvider key sanitization', () => {
617 expect(payload.arguments).toEqual({ $top: 25 });
618 });
619
620 + it('restores sanitized keys before executing through a tool router session', async () => {
621 + const provider = new AnthropicProvider();
622 + const directExecute = vi.fn();
623 + const session = {
624 + execute: vi.fn().mockResolvedValue({
625 + data: { ok: true },
626 + error: null,
627 + logId: 'log-session',
628 + }),
629 + };
630 + provider._setExecuteToolFn(directExecute);
631 + provider.wrapTool(odataTool);
632 +
633 + const result = await provider.executeToolCall(session, {
634 + type: 'tool_use',
635 + id: 'tu_session',
636 + name: 'list_drive_item_activities',
637 + input: '{"dollar_top": 25}' as unknown as Record<string, unknown>,
638 + });
639 +
640 + expect(session.execute).toHaveBeenCalledWith('list_drive_item_activities', { $top: 25 });
641 + expect(directExecute).not.toHaveBeenCalled();
642 + expect(result).toBe(JSON.stringify({ ok: true }));
643 + });
644 +
645 it('normalizes a JSON-string input for tools without sanitized keys (issue #2406)', async () => {
646 const provider = new AnthropicProvider();
647 const executeToolFn = vi
ts/packages/providers/openai/README.md
+3 -3
@@ -42,7 +42,7 @@ let response = await client.responses.create({
42
43 // Agentic loop: keep executing tool calls until the model responds with text
44 while (response.output.some(o => o.type === 'function_call')) {
45 - const results = await composio.provider.handleToolCalls('user_123', response.output);
45 + const results = await composio.provider.handleToolCalls(session, response.output);
46 response = await client.responses.create({
47 model: 'gpt-5.2',
48 tools,
@@ -63,8 +63,8 @@ for (const item of response.output) {
63
64 The package exports one provider per API surface:
65
66 -- `OpenAIResponsesProvider` targets the Responses API. `handleToolCalls(userId, response.output)` returns `function_call_output` items keyed by `call_id`; pair it with `previous_response_id` so you only resend new outputs each turn. The constructor accepts `{ strict?: boolean }` to enforce strict function schemas (default `false`).
67 -- `OpenAIProvider` targets the Chat Completions API and is the Composio SDK default, so `new Composio()` with no provider uses it. `handleToolCalls(userId, chatCompletion)` returns ready-to-append `tool` messages; you keep the full message list yourself.
66 +- `OpenAIResponsesProvider` targets the Responses API. `handleToolCalls(session, response.output)` returns `function_call_output` items keyed by `call_id`; pair it with `previous_response_id` so you only resend new outputs each turn. Pass a user ID instead of a session for tools fetched with `tools.get()`. The constructor accepts `{ strict?: boolean }` to enforce strict function schemas (default `false`).
67 +- `OpenAIProvider` targets the Chat Completions API and is the Composio SDK default, so `new Composio()` with no provider uses it. `handleToolCalls(session, chatCompletion)` returns ready-to-append `tool` messages; you keep the full message list yourself.
68
69 Use the Responses provider for new agentic flows; reach for Chat Completions when extending an existing Chat Completions codebase. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the Chat Completions loop.
70
ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
+39 -14
@@ -13,9 +13,10 @@ import { OpenAI } from 'openai';
13 import {
14 BaseNonAgenticProvider,
15 Tool,
16 - ToolExecuteParams,
16 ExecuteToolModifiers,
17 ExecuteToolFnOptions,
18 + ToolCallExecutionTarget,
19 + ToolCallSession,
20 removeNonRequiredProperties,
21 McpUrlResponse,
22 normalizeToolArguments,
@@ -190,7 +191,7 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
191 * This method processes a tool call from OpenAI's chat completion API,
192 * executes the corresponding Composio tool, and returns the result.
193 *
193 - * @param {string} userId - The user ID for authentication and tracking
194 + * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
195 * @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
196 * @param {ExecuteToolFnOptions} [options] - Optional execution options
197 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -216,22 +217,32 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
217 * console.log(JSON.parse(result));
218 * ```
219 */
220 + async executeToolCall(
221 + session: ToolCallSession,
222 + tool: OpenAI.Responses.ResponseFunctionToolCall
223 + ): Promise<string>;
224 async executeToolCall(
225 userId: string,
226 tool: OpenAI.Responses.ResponseFunctionToolCall,
227 options?: ExecuteToolFnOptions,
228 modifiers?: ExecuteToolModifiers
229 + ): Promise<string>;
230 + async executeToolCall(
231 + executionTarget: ToolCallExecutionTarget,
232 + tool: OpenAI.Responses.ResponseFunctionToolCall,
233 + options?: ExecuteToolFnOptions,
234 + modifiers?: ExecuteToolModifiers
235 ): Promise<string> {
225 - const payload: ToolExecuteParams = {
226 - // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
227 - // empty / object-shaped payloads too (issue #2406).
228 - arguments: normalizeToolArguments(tool.arguments, tool.name),
229 - connectedAccountId: options?.connectedAccountId,
230 - customAuthParams: options?.customAuthParams,
231 - customConnectionData: options?.customConnectionData,
232 - userId: userId,
233 - };
234 - const result = await this.executeTool(tool.name, payload, modifiers);
236 + // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
237 + // empty / object-shaped payloads too (issue #2406).
238 + const arguments_ = normalizeToolArguments(tool.arguments, tool.name);
239 + const result = await this.executeToolForTarget(
240 + executionTarget,
241 + tool.name,
242 + arguments_,
243 + options,
244 + modifiers
245 + );
246 return JSON.stringify(result);
247 }
248
@@ -241,7 +252,7 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
252 * This method processes tool calls from an OpenAI response,
253 * executes each tool call, and returns the results.
254 *
244 - * @param {string} userId - The user ID for authentication and tracking
255 + * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
256 * @param {OpenAI.ChatCompletion} chatCompletion - The response from OpenAI
257 * @param {ExecuteToolFnOptions} [options] - Optional execution options
258 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -271,12 +282,23 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
282 * ```
283 * ```
284 */
285 + async handleToolCalls(
286 + session: ToolCallSession,
287 + toolCalls: OpenAI.Responses.ResponseOutputItem[]
288 + ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
289 async handleToolCalls(
290 userId: string,
291 toolCalls: OpenAI.Responses.ResponseOutputItem[],
292 options?: ExecuteToolFnOptions,
293 modifiers?: ExecuteToolModifiers
294 + ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
295 + async handleToolCalls(
296 + executionTarget: ToolCallExecutionTarget,
297 + toolCalls: OpenAI.Responses.ResponseOutputItem[],
298 + options?: ExecuteToolFnOptions,
299 + modifiers?: ExecuteToolModifiers
300 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]> {
301 + this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
302 const toolOutputs: OpenAI.Responses.ResponseInputItem.FunctionCallOutput[] = [];
303 for (const output of toolCalls) {
304 if (output.type === 'function_call') {
@@ -286,7 +308,10 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
308 arguments: output.arguments,
309 } as OpenAI.Responses.ResponseFunctionToolCall;
310 try {
289 - const toolOutput = await this.executeToolCall(userId, tool_call, options, modifiers);
311 + const toolOutput =
312 + typeof executionTarget === 'string'
313 + ? await this.executeToolCall(executionTarget, tool_call, options, modifiers)
314 + : await this.executeToolCall(executionTarget, tool_call);
315 toolOutputs.push({
316 call_id: output.call_id ?? '',
317 type: 'function_call_output',
ts/packages/providers/openai/test/opeanai-responses.test.ts
+54
@@ -253,6 +253,60 @@ describe('OpenAIResponsesProvider', () => {
253 });
254
255 describe('handleToolCalls', () => {
256 + it('preserves Responses output order and errors when executing through a session', async () => {
257 + const session = {
258 + execute: vi
259 + .fn()
260 + .mockResolvedValueOnce({ data: { index: 1 }, error: null, logId: 'log-1' })
261 + .mockRejectedValueOnce(new Error('session execution failed')),
262 + };
263 + const toolCalls = [
264 + {
265 + id: 'item-1',
266 + type: 'function_call',
267 + name: 'COMPOSIO_SEARCH_TOOLS',
268 + arguments: JSON.stringify({ queries: [{ use_case: 'first' }] }),
269 + call_id: 'call-1',
270 + },
271 + {
272 + id: 'item-2',
273 + type: 'function_call',
274 + name: 'COMPOSIO_SEARCH_TOOLS',
275 + arguments: JSON.stringify({ queries: [{ use_case: 'second' }] }),
276 + call_id: 'call-2',
277 + },
278 + ] as OpenAI.Responses.ResponseOutputItem[];
279 +
280 + const results = await provider.handleToolCalls(session, toolCalls);
281 +
282 + expect(session.execute).toHaveBeenNthCalledWith(1, 'COMPOSIO_SEARCH_TOOLS', {
283 + queries: [{ use_case: 'first' }],
284 + });
285 + expect(session.execute).toHaveBeenNthCalledWith(2, 'COMPOSIO_SEARCH_TOOLS', {
286 + queries: [{ use_case: 'second' }],
287 + });
288 + expect(mockExecuteToolFn).not.toHaveBeenCalled();
289 + expect(results).toEqual([
290 + {
291 + call_id: 'call-1',
292 + type: 'function_call_output',
293 + output: JSON.stringify({
294 + data: { index: 1 },
295 + error: null,
296 + logId: 'log-1',
297 + successful: true,
298 + }),
299 + status: 'completed',
300 + },
301 + {
302 + call_id: 'call-2',
303 + type: 'function_call_output',
304 + output: 'session execution failed',
305 + status: 'incomplete',
306 + },
307 + ]);
308 + });
309 +
310 it('should handle tool calls from OpenAI response', async () => {
311 const userId = 'test-user';
312 const toolCalls = [