Skip to content

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

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

Soumya Medapati760f8d03673a
diff --git a/.changeset/route-provider-session-tools.md b/.changeset/route-provider-session-tools.md
new file mode 100644
index 000000000..d072c9946
--- /dev/null
+++ b/.changeset/route-provider-session-tools.md
@@ -0,0 +1,7 @@
+---
+'@composio/core': minor
+'@composio/openai': minor
+'@composio/anthropic': minor
+---
+
+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.
diff --git a/docs/bun.lock b/docs/bun.lock
index 5020f1a8d..bbffc5f66 100644
--- a/docs/bun.lock
+++ b/docs/bun.lock
@@ -49,12 +49,12 @@
"@anthropic-ai/sdk": "^0.115.0",
"@composio/anthropic": "^0.10.1",
"@composio/claude-agent-sdk": "^0.10.1",
- "@composio/core": "^0.14.1",
+ "@composio/core": "^0.15.0",
"@composio/google": "^0.10.1",
"@composio/langchain": "^0.10.1",
"@composio/llamaindex": "^0.10.1",
"@composio/mastra": "^0.10.3",
- "@composio/openai": "^0.10.1",
+ "@composio/openai": "^0.11.0",
"@composio/openai-agents": "^0.10.1",
"@composio/vercel": "^0.11.1",
"@google/genai": "^2.13.0",
@@ -205,11 +205,11 @@
"@composio/client": ["@composio/[email protected]", "", {}, "sha512-MXC5JGRVdiQ4EgLricy9o/mqBa1+1T7wHFZ6Q4ZJkrjzZqOMvxTgy21Zlb5J/1oGkB2bg9UDzpH8PkXCp/D4zA=="],
- "@composio/core": ["@composio/[email protected]", "", { "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=="],
+ "@composio/core": ["@composio/[email protected]", "", { "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=="],
"@composio/google": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@google/genai": "^1.1.0" } }, "sha512-jfkYG+aNboBmYbVr2H4IcZ1JwrZ5OpY+ZM4UsNPOx+16hzMcGzaQqAWZhPw1vrPNRQBR68pevthhktP3vKGqZA=="],
- "@composio/json-schema-to-zod": ["@composio/[email protected]", "", { "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-ezIaQoXdqWJXFaI8+gTShpj8YZcRdSnLkA1hgzx1+kn2Bi1SXOtXjghoQDy2ZBYIOCefRXGmyaPl52+idjS9wA=="],
+ "@composio/json-schema-to-zod": ["@composio/[email protected]", "", { "peerDependencies": { "zod": ">=3.25.76 <5" } }, "sha512-2af93I0oKBy9otwPjyoGy8+qYlB3Fgb/P1EHkbXdh2UmUQE1ynr8Syoio4otgJssRxrUImKOz2DgyDTKThMATw=="],
"@composio/langchain": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@langchain/core": "^1.1.4" } }, "sha512-egOjlDOX6xnpIppfy/xOhETVfqwIL+YopzcXd6JecuTVYyQ2pfAq9ns/evc0X0q47HVSSy0BM3a0DTwZhnea7Q=="],
@@ -217,7 +217,7 @@
"@composio/mastra": ["@composio/[email protected]", "", { "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=="],
- "@composio/openai": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "openai": "^6.45.0" } }, "sha512-ioCRe7ddQWTip1vP4jCVqM1Jwu2KnzwK20ssZ1qrpVb+aFjIczJErs/fJp1t1fPnd4YcV1EyRpNjVfp7dTWHxg=="],
+ "@composio/openai": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "openai": "^6.49.0 || ^7.0.0" } }, "sha512-Fk02kiz499dvgLbDcv+frsxmeQGN1+sy4iZPsSA5spdlanQ9O9Jd5TuKLzrwrGP7HNddXvnycUxXCkXhYEsQaQ=="],
"@composio/openai-agents": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": ">=0.10.0 <1.0.0", "@openai/agents": "^0.1.3", "zod": "^4.4.3" } }, "sha512-yCTbHAlK9BCzruAhyrZv/TwOOlwa/DF11XWfCNlnIP5a6P53jp0qA2crGCWSH8e3blxJ+ihhbmp8QS0pDCzW3g=="],
@@ -1349,6 +1349,8 @@
"is-extendable": ["[email protected]", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
+ "is-fs-case-sensitive": ["[email protected]", "", {}, "sha512-JoCsyGITdYPM+pUbeMQ4IiEuQ4wjPdeWORlG7n644isewbcxiQIr+9gmF5k7UabTP/jLBRkbgydEamR7JZBKHA=="],
+
"is-fullwidth-code-point": ["[email protected]", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
"is-hexadecimal": ["[email protected]", "", {}, "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg=="],
@@ -2029,6 +2031,8 @@
"@base-ui/utils/@babel/runtime": ["@babel/[email protected]", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
+ "@composio/core/openai": ["[email protected]", "", { "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=="],
+
"@floating-ui/core/@floating-ui/utils": ["@floating-ui/[email protected]", "", {}, "sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ=="],
"@floating-ui/react-dom/@floating-ui/dom": ["@floating-ui/[email protected]", "", { "dependencies": { "@floating-ui/core": "^1.8.0", "@floating-ui/utils": "^0.2.12" } }, "sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg=="],
diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdx
index dd7f1e9f3..5544f724a 100644
--- a/docs/content/docs/how-composio-works.mdx
+++ b/docs/content/docs/how-composio-works.mdx
@@ -70,6 +70,29 @@ The agent searches for relevant tools, authenticates if needed, and executes the
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.
+## Executing session tools
+
+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:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+result = session.execute("COMPOSIO_SEARCH_TOOLS", arguments={"queries": [{"use_case": "send an email"}]})
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const result = await session.execute("COMPOSIO_SEARCH_TOOLS", { queries: [{ use_case: "send an email" }] });
+```
+</Tab>
+</Tabs>
+
+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.
+
## Authentication
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`.
diff --git a/docs/content/docs/providers/anthropic.mdx b/docs/content/docs/providers/anthropic.mdx
index 656ee7155..33c14c73c 100644
--- a/docs/content/docs/providers/anthropic.mdx
+++ b/docs/content/docs/providers/anthropic.mdx
@@ -50,10 +50,15 @@ ANTHROPIC_API_KEY=xxxxxxxxx
<Step>
**Create session and run**
+<Callout type="info">
+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).
+</Callout>
+
<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```python
import json
+
import anthropic
from composio import Composio
from composio_anthropic import AnthropicProvider
@@ -79,14 +84,14 @@ response = client.messages.create(
# Agentic loop: keep executing tool calls until the model responds with text
while response.stop_reason == "tool_use":
tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
- results = composio.provider.handle_tool_calls(user_id="user_123", response=response)
+ results = composio.provider.handle_tool_calls(response=response, session=session)
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": tool_use_blocks[i].id, "content": json.dumps(result)}
for i, result in enumerate(results)
- ]
+ ],
})
response = client.messages.create(
model="claude-opus-4-6",
@@ -102,7 +107,9 @@ for block in response.content:
```
</Tab>
<Tab value="TypeScript">
+{/* 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. */}
```typescript
+// @errors: 2345
import Anthropic from '@anthropic-ai/sdk';
import { Composio } from '@composio/core';
import { AnthropicProvider } from '@composio/anthropic';
@@ -132,7 +139,7 @@ let response = await client.messages.create({
// Agentic loop: keep executing tool calls until the model responds with text
while (response.stop_reason === "tool_use") {
- const toolResults = await composio.provider.handleToolCalls("user_123", response);
+ const toolResults = await composio.provider.handleToolCalls(session, response);
messages.push({ role: "assistant", content: response.content });
messages.push(...toolResults);
response = await client.messages.create({
@@ -156,7 +163,7 @@ for (const block of response.content) {
</Steps>
<Callout type="info">
-`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.
+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.
</Callout>
</IntegrationContent>
@@ -272,8 +279,8 @@ The provider registers each tool's complete object schema. Object arguments that
A few things are specific to the Anthropic provider:
- **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.
-- **`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.
-- **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.
+- **`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.
+- **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.
- **`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).
## Next
diff --git a/docs/content/docs/providers/custom-providers/typescript.mdx b/docs/content/docs/providers/custom-providers/typescript.mdx
index 123ba5cf1..9b31e4173 100644
--- a/docs/content/docs/providers/custom-providers/typescript.mdx
+++ b/docs/content/docs/providers/custom-providers/typescript.mdx
@@ -242,60 +242,52 @@ export class StatefulProvider extends BaseNonAgenticProvider<ToolCollection, Too
}
```
-## Advanced: compose providers
+## Add behavior with composition
-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.
+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.
```typescript
-// @noErrors
+import { Composio } from '@composio/core';
+import type { ExecuteToolFnOptions, ExecuteToolModifiers } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
+import type OpenAI from 'openai';
-// Extend the OpenAI provider with custom functionality
-export class EnhancedOpenAIProvider extends OpenAIProvider {
- // Add properties
- private analytics = {
+class InstrumentedOpenAIToolExecutor {
+ private readonly analytics = {
toolCalls: 0,
errors: 0,
};
- // Override methods to add functionality
- override async executeToolCall(userId, tool, options, modifiers) {
+ constructor(private readonly provider: OpenAIProvider) {}
+
+ async executeToolCall(
+ userId: string,
+ tool: OpenAI.ChatCompletionMessageFunctionToolCall,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): Promise<string> {
this.analytics.toolCalls++;
try {
- // Call the parent implementation
- const result = await super.executeToolCall(userId, tool, options, modifiers);
- return result;
+ return await this.provider.executeToolCall(userId, tool, options, modifiers);
} catch (error) {
this.analytics.errors++;
throw error;
}
}
- // Add new methods
- getAnalytics() {
- return this.analytics;
- }
-
- async executeWithRetry(userId, tool, options, modifiers, maxRetries = 3) {
- let attempts = 0;
- let lastError;
-
- while (attempts < maxRetries) {
- try {
- return await this.executeToolCall(userId, tool, options, modifiers);
- } catch (error) {
- lastError = error;
- attempts++;
- await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
- }
- }
-
- throw lastError;
+ getAnalytics(): Readonly<{ toolCalls: number; errors: number }> {
+ return { ...this.analytics };
}
}
+
+const provider = new OpenAIProvider();
+const composio = new Composio({ provider });
+const toolExecutor = new InstrumentedOpenAIToolExecutor(provider);
```
+Pass the underlying provider to `Composio`, then call the wrapper from your manual tool-call loop.
+
## Best practices
- **Keep providers focused**: each provider should target one platform.
diff --git a/docs/content/docs/providers/google.mdx b/docs/content/docs/providers/google.mdx
index 34ca600a1..de2843244 100644
--- a/docs/content/docs/providers/google.mdx
+++ b/docs/content/docs/providers/google.mdx
@@ -13,7 +13,7 @@ The Google provider formats Composio tools for [Gemini](https://ai.google.dev/)
<IntegrationContent value="gemini">
-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.
+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.
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.
@@ -98,19 +98,16 @@ let response = await chat.sendMessage({
message: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
});
-// Agentic loop: keep executing tool calls until the model responds with text
+// Agentic loop: run each tool call with session.execute() until the model responds with text
while (response.functionCalls && response.functionCalls.length > 0) {
const parts: Part[] = [];
for (const fc of response.functionCalls) {
- const result = await composio.provider.executeToolCall("user_123", {
- name: fc.name || '',
- args: (fc.args || {}) as Record<string, unknown>,
- });
+ const result = await session.execute(fc.name || '', (fc.args || {}) as Record<string, unknown>);
parts.push({
functionResponse: {
id: fc.id,
name: fc.name,
- response: JSON.parse(result),
+ response: result.error ? { error: result.error } : result.data,
},
});
}
@@ -124,6 +121,10 @@ console.log(response.text);
</Step>
</Steps>
+<Callout type="warn">
+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.)
+</Callout>
+
</IntegrationContent>
<IntegrationContent value="adk">
diff --git a/docs/content/docs/providers/openai.mdx b/docs/content/docs/providers/openai.mdx
index a8cf8f701..9397e2e57 100644
--- a/docs/content/docs/providers/openai.mdx
+++ b/docs/content/docs/providers/openai.mdx
@@ -54,6 +54,10 @@ OPENAI_API_KEY=xxxxxxxxx
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.
+<Callout type="info">
+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).
+</Callout>
+
<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```python
@@ -85,14 +89,18 @@ while True:
tool_calls = [o for o in response.output if o.type == "function_call"]
if not tool_calls:
break
- results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
+ results = composio.provider.handle_tool_calls(response=response, session=session)
response = client.responses.create(
model="gpt-5.2",
tools=tools,
previous_response_id=response.id,
input=[
- {"type": "function_call_output", "call_id": tool_calls[i].call_id, "output": json.dumps(result)}
- for i, result in enumerate(results)
+ {
+ "type": "function_call_output",
+ "call_id": call.call_id,
+ "output": json.dumps(results[i]),
+ }
+ for i, call in enumerate(tool_calls)
]
)
@@ -103,7 +111,9 @@ for item in response.output:
```
</Tab>
<Tab value="TypeScript">
+{/* 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. */}
```typescript
+// @errors: 2345
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIResponsesProvider } from '@composio/openai';
@@ -133,16 +143,12 @@ while (true) {
const toolCalls = response.output.filter((o) => o.type === "function_call");
if (toolCalls.length === 0) break;
- const results = await composio.provider.handleToolCalls("user_123", response.output);
+ const outputs = await composio.provider.handleToolCalls(session, response.output);
response = await client.responses.create({
model: "gpt-5.2",
tools: tools,
previous_response_id: response.id,
- input: results.map((result, i) => ({
- type: "function_call_output" as const,
- call_id: toolCalls[i].call_id,
- output: JSON.stringify(result),
- })),
+ input: outputs,
});
}
@@ -198,6 +204,10 @@ OPENAI_API_KEY=xxxxxxxxx
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.
+<Callout type="info">
+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).
+</Callout>
+
<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```python
@@ -225,7 +235,7 @@ response = client.chat.completions.create(
# Agentic loop: keep executing tool calls until the model responds with text
while response.choices[0].message.tool_calls:
- results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
+ results = composio.provider.handle_tool_calls(response=response, session=session)
messages.append(response.choices[0].message)
for i, tc in enumerate(response.choices[0].message.tool_calls):
messages.append({
@@ -243,7 +253,9 @@ print(response.choices[0].message.content)
```
</Tab>
<Tab value="TypeScript">
+{/* 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. */}
```typescript
+// @errors: 2345
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
@@ -272,15 +284,9 @@ let response = await client.chat.completions.create({
// Agentic loop: keep executing tool calls until the model responds with text
while (response.choices[0].message.tool_calls) {
- const results = await composio.provider.handleToolCalls("user_123", response);
+ const results = await composio.provider.handleToolCalls(session, response);
messages.push(response.choices[0].message);
- for (const [i, tc] of response.choices[0].message.tool_calls.entries()) {
- messages.push({
- role: "tool",
- tool_call_id: tc.id,
- content: JSON.stringify(results[i]),
- });
- }
+ messages.push(...results);
response = await client.chat.completions.create({
model: "gpt-5.2",
tools: tools,
@@ -400,9 +406,13 @@ console.log(result.finalOutput);
The OpenAI integration ships three providers, one per API surface:
-- **`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.
+- **`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.
- **`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.
-- **`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.
+- **`OpenAIAgentsProvider`** for the Agents SDK. Tools come with execution wired in, so the SDK runs the loop for you.
+
+<Callout type="info">
+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.
+</Callout>
Use the Responses or Agents provider for new agentic flows; reach for Chat Completions when you are extending an existing Chat Completions codebase.
diff --git a/docs/lib/llm-guardrails/session.ts b/docs/lib/llm-guardrails/session.ts
index 5f1ae5be7..bd8afd500 100644
--- a/docs/lib/llm-guardrails/session.ts
+++ b/docs/lib/llm-guardrails/session.ts
@@ -63,9 +63,10 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
## 2. Integration Notes
- \`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.
+- 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"\`.
- 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.
- 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).
-- **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).
+- **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).
---
diff --git a/docs/package.json b/docs/package.json
index 5a0510b46..3e82b3897 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -73,12 +73,12 @@
"@anthropic-ai/sdk": "^0.115.0",
"@composio/anthropic": "^0.10.1",
"@composio/claude-agent-sdk": "^0.10.1",
- "@composio/core": "^0.14.1",
+ "@composio/core": "^0.15.0",
"@composio/google": "^0.10.1",
"@composio/langchain": "^0.10.1",
"@composio/llamaindex": "^0.10.1",
"@composio/mastra": "^0.10.3",
- "@composio/openai": "^0.10.1",
+ "@composio/openai": "^0.11.0",
"@composio/openai-agents": "^0.10.1",
"@composio/vercel": "^0.11.1",
"@google/genai": "^2.13.0",
diff --git a/docs/tests/static/session-execution.test.ts b/docs/tests/static/session-execution.test.ts
new file mode 100644
index 000000000..fd29bcfb6
--- /dev/null
+++ b/docs/tests/static/session-execution.test.ts
@@ -0,0 +1,248 @@
+/**
+ * Session tool-execution policy for docs samples.
+ *
+ * Provider helpers must receive the Tool Router session that produced the
+ * model-visible tools. Passing a user ID chooses direct execution instead,
+ * so session meta-tools fail at runtime.
+ *
+ * A 102-run agent eval of the docs (August 2026, two-phase build+probe)
+ * found 58/102 runs hit that rejection by copying provider-page samples
+ * that paired `session.tools()` with `handle_tool_calls`. All recovering
+ * runs converged on `session.execute()`, discovered from SDK source. The SDK
+ * helpers now accept the session directly and retain provider normalization.
+ *
+ * Rule: no authored MDX page may pair session tools (`session.tools()` /
+ * `sessions.create` / `composio.create(`) with a provider helper explicitly
+ * bound to a user ID. Session-bound helper calls and direct-path (`tools.get`)
+ * samples are valid.
+ *
+ * Scope: content/docs and content/examples. Excluded: content/reference
+ * (generated upstream), changelog (historical), docs/migration-guide
+ * (point-in-time documents that may show old APIs).
+ * The LLM guardrail blocks appended to .md responses are checked too —
+ * they are samples agents copy verbatim.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile } from "fs/promises";
+import { join, relative } from "path";
+
+import {
+ SESSION_GUARDRAILS,
+ DIRECT_EXECUTION_GUARDRAILS,
+} from "../../lib/llm-guardrails";
+
+const CONTENT_DIRS = ["docs", "examples"].map((dir) =>
+ join(import.meta.dir, "../../content", dir),
+);
+const CONTENT_ROOT = join(import.meta.dir, "../../content");
+const EXCLUDED_PATH_SEGMENTS = ["docs/migration-guide/"];
+
+const SESSION_TOKEN_RE =
+ /session\.tools\s*\(|sessions\.create\s*\(|composio\.create\s*\(/;
+// Python branch: user_id= must appear inside the helper's argument list —
+// the bound tolerates one level of nested calls (`response=build_response()`)
+// but never runs past the helper's closing paren into later code. TS branch:
+// a string-literal first argument, or a whole identifier that names a user ID
+// (`userId`, `user_id`, `uid`) — a session argument never does.
+const DIRECT_HELPER_TOKEN_RE =
+ /(?:handle_tool_calls|execute_tool_call)\s*\((?:[^()]*\([^()]*\))*[^()]*\buser_id\s*=|(?:handleToolCalls|executeToolCall)\s*\(\s*(?:["'`]|(?:user_?[iI]d|uid)\b)/;
+const SAMPLE_BOUNDARY_RE = /^\s*(?:<\/?(?:Tab|Step)\b|#{1,6}\s)/;
+const FENCE_OPEN_RE = /^\s*(`{3,}|~{3,})/;
+const FENCE_CLOSE_RE = /^\s*(`{3,}|~{3,})\s*$/;
+
+async function findMdxFiles(dir: string): Promise<string[]> {
+ const results: string[] = [];
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ results.push(...(await findMdxFiles(fullPath)));
+ } else if (entry.name.endsWith(".mdx")) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+function codeSampleGroups(source: string): string[] {
+ const groups: string[] = [];
+ let current: string[] = [];
+ let fenceMarker: string | undefined;
+
+ const flush = () => {
+ if (current.length > 0) groups.push(current.join("\n"));
+ current = [];
+ };
+
+ for (const line of source.split(/\r?\n/)) {
+ if (fenceMarker === undefined && SAMPLE_BOUNDARY_RE.test(line)) flush();
+
+ if (fenceMarker === undefined) {
+ const opening = line.match(FENCE_OPEN_RE)?.[1];
+ if (opening !== undefined) {
+ fenceMarker = opening;
+ current.push(line);
+ }
+ continue;
+ }
+
+ current.push(line);
+ const closing = line.match(FENCE_CLOSE_RE)?.[1];
+ if (
+ closing !== undefined &&
+ closing[0] === fenceMarker[0] &&
+ closing.length >= fenceMarker.length
+ ) {
+ fenceMarker = undefined;
+ }
+ }
+
+ flush();
+ return groups;
+}
+
+function hasDirectHelperBoundToSessionTools(source: string): boolean {
+ return codeSampleGroups(source).some(
+ (sample) => SESSION_TOKEN_RE.test(sample) && DIRECT_HELPER_TOKEN_RE.test(sample),
+ );
+}
+
+describe("session execution samples", () => {
+ test("detects a direct helper split from session setup within one sample", () => {
+ const source = `
+<Tab value="Python">
+~~~python
+session = composio.create(user_id="user_123")
+tools = session.tools()
+~~~
+
+Run the model, then execute its calls:
+
+~~~python
+results = composio.provider.handle_tool_calls(
+ response=response,
+ user_id="user_123",
+)
+~~~
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
+ });
+
+ test("allows session targets and keeps separate tab samples independent", () => {
+ const sessionTarget = `
+<Tab value="Python">
+\`\`\`python
+session = composio.create(user_id="user_123")
+tools = session.tools()
+\`\`\`
+\`\`\`python
+results = composio.provider.handle_tool_calls(response=response, session=session)
+\`\`\`
+</Tab>`;
+ const separateTargets = `
+<Tab value="Session">
+\`\`\`typescript
+const tools = await session.tools();
+\`\`\`
+</Tab>
+<Tab value="Direct">
+\`\`\`typescript
+const results = await composio.provider.handleToolCalls("user_123", response);
+\`\`\`
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(sessionTarget)).toBe(false);
+ expect(hasDirectHelperBoundToSessionTools(separateTargets)).toBe(false);
+ });
+
+ test("session-bound helper is not flagged by a later unrelated user_id", () => {
+ const source = `
+<Tab value="Python">
+\`\`\`python
+session = composio.create(user_id="user_123")
+tools = session.tools()
+results = composio.provider.handle_tool_calls(response=response, session=session)
+\`\`\`
+\`\`\`python
+other_session = composio.create(user_id="user_456")
+\`\`\`
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(source)).toBe(false);
+ });
+
+ test("detects a user_id hidden behind a nested call in the same argument list", () => {
+ const source = `
+<Tab value="Python">
+\`\`\`python
+session = composio.create(user_id="user_123")
+tools = session.tools()
+results = composio.provider.handle_tool_calls(response=build_response(), user_id="user_123")
+\`\`\`
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
+ });
+
+ test("session variables that merely start with 'user' are not flagged", () => {
+ const source = `
+<Tab value="TypeScript">
+\`\`\`typescript
+const userSession = await composio.create("user_123");
+const tools = await userSession.tools();
+const results = await composio.provider.handleToolCalls(userSession, response);
+\`\`\`
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(source)).toBe(false);
+ });
+
+ test("detects a TypeScript helper bound to a user-ID variable", () => {
+ const source = `
+<Tab value="TypeScript">
+\`\`\`typescript
+const userId = "user_123";
+const session = await composio.create(userId);
+const tools = await session.tools();
+const results = await composio.provider.handleToolCalls(userId, response);
+\`\`\`
+</Tab>`;
+
+ expect(hasDirectHelperBoundToSessionTools(source)).toBe(true);
+ });
+
+ test("LLM guardrail blocks never bind provider helpers to a user ID", () => {
+ for (const guardrails of [SESSION_GUARDRAILS, DIRECT_EXECUTION_GUARDRAILS]) {
+ expect(hasDirectHelperBoundToSessionTools(guardrails)).toBe(false);
+ }
+ });
+
+ test("session samples do not bind provider helpers to a user ID", async () => {
+ const offenders: string[] = [];
+
+ for (const dir of CONTENT_DIRS) {
+ for (const file of await findMdxFiles(dir)) {
+ const rel = relative(CONTENT_ROOT, file);
+ if (EXCLUDED_PATH_SEGMENTS.some((seg) => rel.includes(seg))) continue;
+
+ const source = await readFile(file, "utf8");
+ if (hasDirectHelperBoundToSessionTools(source)) {
+ offenders.push(rel);
+ }
+ }
+ }
+
+ expect(
+ offenders,
+ `These pages bind session tools to a direct user-ID execution target. ` +
+ `Pass the session to the provider helper instead:\n ${offenders.join("\n ")}`,
+ ).toEqual([]);
+ });
+});
diff --git a/python/composio/core/provider/__init__.py b/python/composio/core/provider/__init__.py
index 7d90f97b3..f936a6572 100644
--- a/python/composio/core/provider/__init__.py
+++ b/python/composio/core/provider/__init__.py
@@ -1,12 +1,14 @@
from __future__ import annotations
from .agentic import AgenticProvider, AgenticProviderExecuteFn
-from .base import TTool, TToolCollection
+from .base import TTool, TToolCollection, ToolCallExecutionTarget, ToolCallSession
from .none_agentic import NonAgenticProvider
__all__ = [
"TTool",
"TToolCollection",
+ "ToolCallExecutionTarget",
+ "ToolCallSession",
"AgenticProvider",
"NonAgenticProvider",
"AgenticProviderExecuteFn",
diff --git a/python/composio/core/provider/_openai.py b/python/composio/core/provider/_openai.py
index dded2cb25..86bf00780 100644
--- a/python/composio/core/provider/_openai.py
+++ b/python/composio/core/provider/_openai.py
@@ -19,7 +19,7 @@ from openai.types.chat.chat_completion_tool_param import ChatCompletionToolParam
from openai.types.shared_params.function_definition import FunctionDefinition
from openai.types.shared_params.function_parameters import FunctionParameters
-from composio.core.provider import NonAgenticProvider
+from composio.core.provider import NonAgenticProvider, ToolCallSession
from composio.types import Modifiers, Tool, ToolExecutionResponse
from composio.utils.shared import normalize_tool_arguments
@@ -46,41 +46,92 @@ class OpenAIProvider(
def wrap_tools(self, tools: t.Sequence[Tool]) -> OpenAIToolCollection:
return [self.wrap_tool(tool) for tool in tools]
+ @t.overload
def execute_tool_call(
self,
user_id: str,
tool_call: ChatCompletionMessageToolCall,
modifiers: t.Optional[Modifiers] = None,
+ ) -> ToolExecutionResponse: ...
+
+ @t.overload
+ def execute_tool_call(
+ self,
+ *,
+ session: ToolCallSession,
+ tool_call: ChatCompletionMessageToolCall,
+ ) -> ToolExecutionResponse: ...
+
+ def execute_tool_call(
+ self,
+ user_id: t.Optional[str] = None,
+ tool_call: t.Optional[ChatCompletionMessageToolCall] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> ToolExecutionResponse:
"""Execute a tool call.
:param tool_call: Tool call metadata.
- :param user_id: User ID to use for executing the function call.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:return: Object containing output data from the tool call.
"""
+ if tool_call is None:
+ raise TypeError("tool_call is required")
+ target = self.resolve_tool_call_execution_target(
+ user_id=user_id, session=session
+ )
+
# OpenAI always serializes tool arguments as a JSON string; normalize
# tolerates empty / object-shaped payloads too (issue #2406).
- return self.execute_tool(
+ return self.execute_tool_for_target(
+ target=target,
slug=tool_call.function.name,
arguments=normalize_tool_arguments(tool_call.function.arguments),
modifiers=modifiers,
- user_id=user_id,
)
+ @t.overload
def handle_tool_calls(
self,
user_id: str,
response: ChatCompletion,
modifiers: t.Optional[Modifiers] = None,
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ @t.overload
+ def handle_tool_calls(
+ self,
+ *,
+ session: ToolCallSession,
+ response: ChatCompletion,
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ def handle_tool_calls(
+ self,
+ user_id: t.Optional[str] = None,
+ response: t.Optional[ChatCompletion] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> t.List[ToolExecutionResponse]:
"""
Handle tool calls from OpenAI chat completion object.
:param response: Chat completion object from
openai.OpenAI.chat.completions.create function call
- :param user_id: User ID to use for executing the function call.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:return: A list of output objects from the function calls.
"""
+ if response is None:
+ raise TypeError("response is required")
+ self.resolve_tool_call_execution_target(user_id=user_id, session=session)
+ if session is not None and modifiers is not None:
+ raise ValueError(
+ "Direct execution modifiers cannot be used with a Tool Router session"
+ )
outputs = []
# Only the first choice is actionable: its tool results feed back into a
# single assistant turn. With n > 1, iterating every choice would run each
@@ -91,13 +142,20 @@ class OpenAIProvider(
# calls, on by default); each one needs its own tool result.
if choice is not None and choice.message.tool_calls is not None:
for tool_call in choice.message.tool_calls:
- outputs.append(
+ call = t.cast(ChatCompletionMessageToolCall, tool_call)
+ result = (
self.execute_tool_call(
- user_id=user_id,
- tool_call=t.cast(ChatCompletionMessageToolCall, tool_call),
+ session=session,
+ tool_call=call,
+ )
+ if session is not None
+ else self.execute_tool_call(
+ user_id=t.cast(str, user_id),
+ tool_call=call,
modifiers=modifiers,
)
)
+ outputs.append(result)
return outputs
def handle_assistant_tool_calls(
diff --git a/python/composio/core/provider/_openai_responses.py b/python/composio/core/provider/_openai_responses.py
index 2e3b72917..72f87ccec 100644
--- a/python/composio/core/provider/_openai_responses.py
+++ b/python/composio/core/provider/_openai_responses.py
@@ -9,7 +9,7 @@ import typing as t
from openai.types.responses.response import Response
from openai.types.responses.response_output_item import ResponseFunctionToolCall
-from composio.core.provider import NonAgenticProvider
+from composio.core.provider import NonAgenticProvider, ToolCallSession
from composio.types import Modifiers, Tool, ToolExecutionResponse
from composio.utils.shared import normalize_tool_arguments
@@ -36,54 +36,112 @@ class OpenAIResponsesProvider(
"""Wrap multiple tools for the Responses API format."""
return [self.wrap_tool(tool) for tool in tools]
+ @t.overload
def execute_tool_call(
self,
user_id: str,
tool_call: t.Union[ResponseFunctionToolCall],
modifiers: t.Optional[Modifiers] = None,
+ ) -> ToolExecutionResponse: ...
+
+ @t.overload
+ def execute_tool_call(
+ self,
+ *,
+ session: ToolCallSession,
+ tool_call: ResponseFunctionToolCall,
+ ) -> ToolExecutionResponse: ...
+
+ def execute_tool_call(
+ self,
+ user_id: t.Optional[str] = None,
+ tool_call: t.Optional[ResponseFunctionToolCall] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> ToolExecutionResponse:
"""Execute a tool call from the Responses API.
:param tool_call: Tool call metadata from Responses API.
- :param user_id: User ID to use for executing the function call.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:param modifiers: Optional modifiers for tool execution.
:return: Object containing output data from the tool call.
"""
+ if tool_call is None:
+ raise TypeError("tool_call is required")
+ target = self.resolve_tool_call_execution_target(
+ user_id=user_id, session=session
+ )
+
# OpenAI always serializes tool arguments as a JSON string; normalize
# tolerates empty / object-shaped payloads too (issue #2406).
slug = tool_call.name
arguments = normalize_tool_arguments(tool_call.arguments)
- return self.execute_tool(
+ return self.execute_tool_for_target(
+ target=target,
slug=slug,
arguments=arguments,
modifiers=modifiers,
- user_id=user_id,
)
+ @t.overload
def handle_tool_calls(
self,
user_id: str,
response: Response,
modifiers: t.Optional[Modifiers] = None,
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ @t.overload
+ def handle_tool_calls(
+ self,
+ *,
+ session: ToolCallSession,
+ response: Response,
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ def handle_tool_calls(
+ self,
+ user_id: t.Optional[str] = None,
+ response: t.Optional[Response] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> t.List[ToolExecutionResponse]:
"""
Handle tool calls from OpenAI Responses API.
:param response: Response object from openai.OpenAI.beta.responses.create
- :param user_id: User ID to use for executing the function call.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:param modifiers: Optional modifiers for tool execution
:return: List[ToolExecutionResponse] with tool execution results
"""
+ if response is None:
+ raise TypeError("response is required")
+ self.resolve_tool_call_execution_target(user_id=user_id, session=session)
+ if session is not None and modifiers is not None:
+ raise ValueError(
+ "Direct execution modifiers cannot be used with a Tool Router session"
+ )
outputs = []
if response.output:
for item in response.output:
if isinstance(item, ResponseFunctionToolCall):
- result = self.execute_tool_call(
- user_id=user_id,
- tool_call=item,
- modifiers=modifiers,
+ result = (
+ self.execute_tool_call(
+ session=session,
+ tool_call=item,
+ )
+ if session is not None
+ else self.execute_tool_call(
+ user_id=t.cast(str, user_id),
+ tool_call=item,
+ modifiers=modifiers,
+ )
)
outputs.append(result)
diff --git a/python/composio/core/provider/base.py b/python/composio/core/provider/base.py
index ef0e80082..e69ff0295 100644
--- a/python/composio/core/provider/base.py
+++ b/python/composio/core/provider/base.py
@@ -37,6 +37,20 @@ class ExecuteToolFn(t.Protocol):
...
+class ToolCallSession(t.Protocol):
+ """Execution contract implemented by ToolRouterSession."""
+
+ def execute(
+ self,
+ tool_slug: str,
+ *,
+ arguments: t.Optional[t.Dict[str, t.Any]] = None,
+ ) -> t.Any: ...
+
+
+ToolCallExecutionTarget: t.TypeAlias = t.Union[str, ToolCallSession]
+
+
class SchemaConfig(te.TypedDict):
skip_defaults: te.NotRequired[bool]
@@ -71,3 +85,45 @@ class BaseProvider(t.Generic[TTool, TToolCollection]):
def set_execute_tool_fn(self, execute_tool_fn: ExecuteToolFn) -> None:
self.execute_tool = execute_tool_fn
+
+ def resolve_tool_call_execution_target(
+ self,
+ *,
+ user_id: t.Optional[str],
+ session: t.Optional[ToolCallSession],
+ ) -> ToolCallExecutionTarget:
+ """Resolve exactly one direct user or Tool Router session target."""
+ if (user_id is None) == (session is None):
+ raise ValueError("Provide exactly one of user_id or session")
+ if session is not None:
+ return session
+ return t.cast(str, user_id)
+
+ def execute_tool_for_target(
+ self,
+ *,
+ target: ToolCallExecutionTarget,
+ slug: str,
+ arguments: t.Dict[str, t.Any],
+ modifiers: t.Optional[Modifiers] = None,
+ ) -> ToolExecutionResponse:
+ """Execute normalized arguments through the matching SDK boundary."""
+ if isinstance(target, str):
+ return self.execute_tool(
+ slug=slug,
+ arguments=arguments,
+ modifiers=modifiers,
+ user_id=target,
+ )
+
+ if modifiers is not None:
+ raise ValueError(
+ "Direct execution modifiers cannot be used with a Tool Router session"
+ )
+
+ result = target.execute(tool_slug=slug, arguments=arguments)
+ return {
+ "data": t.cast(t.Dict, result.data),
+ "error": result.error,
+ "successful": result.error is None,
+ }
diff --git a/python/providers/anthropic/README.md b/python/providers/anthropic/README.md
index 60c47d833..c44bdf2c3 100644
--- a/python/providers/anthropic/README.md
+++ b/python/providers/anthropic/README.md
@@ -41,7 +41,7 @@ response = client.messages.create(
# Agentic loop: keep executing tool calls until the model responds with text
while response.stop_reason == "tool_use":
tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
- results = composio.provider.handle_tool_calls(user_id="user_123", response=response)
+ results = composio.provider.handle_tool_calls(session=session, response=response)
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
@@ -63,7 +63,7 @@ for block in response.content:
print(block.text)
```
-`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.
+`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.
Building on the Claude Agent SDK instead of the Messages API? Use [`composio-claude-agent-sdk`](../claude_agent_sdk).
diff --git a/python/providers/anthropic/composio_anthropic/provider.py b/python/providers/anthropic/composio_anthropic/provider.py
index f0234f227..17ec1dacb 100644
--- a/python/providers/anthropic/composio_anthropic/provider.py
+++ b/python/providers/anthropic/composio_anthropic/provider.py
@@ -5,7 +5,7 @@ from anthropic.types.message import Message as ToolsBetaMessage
from anthropic.types.tool_param import ToolParam
from anthropic.types.tool_use_block import ToolUseBlock
-from composio.core.provider import NonAgenticProvider
+from composio.core.provider import NonAgenticProvider, ToolCallSession
from composio.types import Modifiers, Tool, ToolExecutionResponse
from composio.utils.shared import (
ToolSchemaAliases,
@@ -38,58 +38,115 @@ class AnthropicProvider(
def wrap_tools(self, tools: t.Sequence[Tool]) -> list[ToolParam]:
return [self.wrap_tool(tool) for tool in tools]
+ @t.overload
def execute_tool_call(
self,
user_id: str,
tool_call: ToolUseBlock,
modifiers: t.Optional[Modifiers] = None,
+ ) -> ToolExecutionResponse: ...
+
+ @t.overload
+ def execute_tool_call(
+ self,
+ *,
+ session: ToolCallSession,
+ tool_call: ToolUseBlock,
+ ) -> ToolExecutionResponse: ...
+
+ def execute_tool_call(
+ self,
+ user_id: t.Optional[str] = None,
+ tool_call: t.Optional[ToolUseBlock] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> ToolExecutionResponse:
"""
Execute a tool call.
- :param user_id: User ID to use for executing function calls.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:param tool_call: Tool call metadata.
:param modifiers: Modifiers to use for executing function calls.
:return: Object containing output data from the tool call.
"""
+ if tool_call is None:
+ raise TypeError("tool_call is required")
+ target = self.resolve_tool_call_execution_target(
+ user_id=user_id, session=session
+ )
+
# Models occasionally emit tool input as a JSON string rather than a dict (issue #2406).
arguments = normalize_tool_arguments(tool_call.input)
aliases = self._aliases.get(tool_call.name)
if aliases is not None:
arguments = aliases.restore_arguments(arguments)
- return self.execute_tool(
+ return self.execute_tool_for_target(
+ target=target,
slug=tool_call.name,
arguments=arguments,
modifiers=modifiers,
- user_id=user_id,
)
+ @t.overload
def handle_tool_calls(
self,
user_id: str,
response: t.Union[dict, ToolsBetaMessage],
modifiers: t.Optional[Modifiers] = None,
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ @t.overload
+ def handle_tool_calls(
+ self,
+ *,
+ session: ToolCallSession,
+ response: t.Union[dict, ToolsBetaMessage],
+ ) -> t.List[ToolExecutionResponse]: ...
+
+ def handle_tool_calls(
+ self,
+ user_id: t.Optional[str] = None,
+ response: t.Optional[t.Union[dict, ToolsBetaMessage]] = None,
+ modifiers: t.Optional[Modifiers] = None,
+ *,
+ session: t.Optional[ToolCallSession] = None,
) -> t.List[ToolExecutionResponse]:
"""
Handle tool calls from Anthropic Claude chat completion object.
:param response: Chat completion object from
`anthropic.Anthropic.beta.tools.messages.create` function call.
- :param user_id: User ID to use for executing function calls.
+ :param user_id: User ID for direct tool execution.
+ :param session: Tool Router session that produced session tools.
:param modifiers: Modifiers to use for executing function calls.
:return: A list of output objects from the tool calls.
"""
+ if response is None:
+ raise TypeError("response is required")
+ self.resolve_tool_call_execution_target(user_id=user_id, session=session)
+ if session is not None and modifiers is not None:
+ raise ValueError(
+ "Direct execution modifiers cannot be used with a Tool Router session"
+ )
if isinstance(response, dict):
response = ToolsBetaMessage(**response)
outputs = []
for content in response.content:
if isinstance(content, (ToolUseBlock, BetaToolUseBlock)):
- outputs.append(
+ result = (
self.execute_tool_call(
- user_id=user_id,
+ session=session,
+ tool_call=content,
+ )
+ if session is not None
+ else self.execute_tool_call(
+ user_id=t.cast(str, user_id),
tool_call=content,
modifiers=modifiers,
)
)
+ outputs.append(result)
return outputs
diff --git a/python/providers/openai/README.md b/python/providers/openai/README.md
index 4e017726c..405056921 100644
--- a/python/providers/openai/README.md
+++ b/python/providers/openai/README.md
@@ -43,7 +43,7 @@ while True:
tool_calls = [o for o in response.output if o.type == "function_call"]
if not tool_calls:
break
- results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
+ results = composio.provider.handle_tool_calls(response=response, session=session)
response = client.responses.create(
model="gpt-5.2",
tools=tools,
@@ -62,7 +62,7 @@ for item in response.output:
## Chat Completions
-`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.
+`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.
## Links
diff --git a/python/tests/test_provider.py b/python/tests/test_provider.py
index b3c5dc16e..a4756b8b9 100644
--- a/python/tests/test_provider.py
+++ b/python/tests/test_provider.py
@@ -7,7 +7,8 @@ This test module verifies provider functionality including:
- Both agentic and non-agentic provider behavior
"""
-from unittest.mock import Mock
+from types import SimpleNamespace
+from unittest.mock import Mock, call
import pytest
@@ -503,6 +504,131 @@ class TestNonAgenticProviderHelperMethods:
assert results[0]["successful"] is True
assert results[0]["data"]["starred"] is True
+ def test_openai_provider_routes_tool_calls_through_session(self):
+ """Session tools execute through their Tool Router session, not tools.execute."""
+ mock_client = mock_http_client()
+ from composio.core.provider._openai import OpenAIProvider
+
+ provider = OpenAIProvider()
+ Tools(client=mock_client, provider=provider)
+ session = Mock()
+ session.execute.return_value = SimpleNamespace(
+ data={"tools": ["GMAIL_SEND_EMAIL"]},
+ error=None,
+ log_id="log-session",
+ )
+ completion = SimpleNamespace(
+ choices=[
+ SimpleNamespace(
+ message=SimpleNamespace(
+ tool_calls=[
+ SimpleNamespace(
+ id="call-search",
+ type="function",
+ function=SimpleNamespace(
+ name="COMPOSIO_SEARCH_TOOLS",
+ arguments='{"queries":[{"use_case":"send email"}]}',
+ ),
+ )
+ ],
+ ),
+ )
+ ],
+ )
+
+ results = provider.handle_tool_calls(response=completion, session=session)
+
+ session.execute.assert_called_once_with(
+ tool_slug="COMPOSIO_SEARCH_TOOLS",
+ arguments={"queries": [{"use_case": "send email"}]},
+ )
+ mock_client.tools.execute.assert_not_called()
+ assert results == [
+ {
+ "data": {"tools": ["GMAIL_SEND_EMAIL"]},
+ "error": None,
+ "successful": True,
+ }
+ ]
+
+ def test_openai_responses_provider_preserves_session_result_order(self):
+ """Responses helpers keep provider order and result shape for session calls."""
+ from openai.types.responses.response import Response
+ from openai.types.responses.response_function_tool_call import (
+ ResponseFunctionToolCall,
+ )
+
+ from composio.core.provider._openai_responses import OpenAIResponsesProvider
+
+ mock_client = mock_http_client()
+ provider = OpenAIResponsesProvider()
+ Tools(client=mock_client, provider=provider)
+ session = Mock()
+ session.execute.side_effect = [
+ SimpleNamespace(data={"index": 1}, error=None, log_id="log-1"),
+ SimpleNamespace(data={"index": 2}, error="failed", log_id="log-2"),
+ ]
+ response = Response.model_construct(
+ output=[
+ ResponseFunctionToolCall(
+ arguments='{"queries":[{"use_case":"first"}]}',
+ call_id="call-1",
+ name="COMPOSIO_SEARCH_TOOLS",
+ type="function_call",
+ ),
+ ResponseFunctionToolCall(
+ arguments='{"queries":[{"use_case":"second"}]}',
+ call_id="call-2",
+ name="COMPOSIO_SEARCH_TOOLS",
+ type="function_call",
+ ),
+ ]
+ )
+
+ results = provider.handle_tool_calls(response=response, session=session)
+
+ assert session.execute.call_args_list == [
+ call(
+ tool_slug="COMPOSIO_SEARCH_TOOLS",
+ arguments={"queries": [{"use_case": "first"}]},
+ ),
+ call(
+ tool_slug="COMPOSIO_SEARCH_TOOLS",
+ arguments={"queries": [{"use_case": "second"}]},
+ ),
+ ]
+ mock_client.tools.execute.assert_not_called()
+ assert results == [
+ {"data": {"index": 1}, "error": None, "successful": True},
+ {"data": {"index": 2}, "error": "failed", "successful": False},
+ ]
+
+ def test_openai_responses_provider_propagates_session_exceptions(self):
+ """Responses helpers preserve their existing exception propagation behavior."""
+ from openai.types.responses.response import Response
+ from openai.types.responses.response_function_tool_call import (
+ ResponseFunctionToolCall,
+ )
+
+ from composio.core.provider._openai_responses import OpenAIResponsesProvider
+
+ provider = OpenAIResponsesProvider()
+ session = Mock()
+ session.execute.side_effect = RuntimeError("session execution failed")
+ response = Response.model_construct(
+ output=[
+ ResponseFunctionToolCall(
+ arguments="{}",
+ call_id="call-1",
+ name="COMPOSIO_SEARCH_TOOLS",
+ type="function_call",
+ )
+ ]
+ )
+
+ with pytest.raises(RuntimeError, match="session execution failed"):
+ provider.handle_tool_calls(response=response, session=session)
+
def test_openai_provider_handle_tool_calls_only_first_choice(self):
"""Only the first choice runs; n > 1 alternatives would orphan tool_call_ids."""
from openai.types.chat import ChatCompletion
diff --git a/python/tests/test_tool_schema_aliasing.py b/python/tests/test_tool_schema_aliasing.py
index c3186032c..9fe8d3b2f 100644
--- a/python/tests/test_tool_schema_aliasing.py
+++ b/python/tests/test_tool_schema_aliasing.py
@@ -351,6 +351,24 @@ def test_anthropic_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
user_id="user",
)
+ session = Mock()
+ session.execute.return_value = SimpleNamespace(
+ data={"ok": True}, error=None, log_id="log-session"
+ )
+ provider.execute_tool.reset_mock()
+ result = provider.execute_tool_call(session=session, tool_call=tool_call)
+
+ session.execute.assert_called_once_with(
+ tool_slug="TOOL_WITH_ODATA",
+ arguments={
+ "$top": 10,
+ "@microsoft.graph.conflictBehavior": "rename",
+ long_name: "value",
+ },
+ )
+ provider.execute_tool.assert_not_called()
+ assert result == {"data": {"ok": True}, "error": None, "successful": True}
+
def test_claude_agent_sdk_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
claude_agent_sdk_module = types.ModuleType("claude_agent_sdk")
diff --git a/ts/packages/core/src/provider/BaseProvider.ts b/ts/packages/core/src/provider/BaseProvider.ts
index 703619f8c..ff95a2a87 100644
--- a/ts/packages/core/src/provider/BaseProvider.ts
+++ b/ts/packages/core/src/provider/BaseProvider.ts
@@ -1,7 +1,12 @@
import { ComposioGlobalExecuteToolFnNotSetError } from '../errors/ToolErrors';
import { ExecuteToolModifiers } from '../types/modifiers.types';
import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '../types/tool.types';
-import { ExecuteToolFn, GlobalExecuteToolFn } from '../types/provider.types';
+import {
+ ExecuteToolFn,
+ ExecuteToolFnOptions,
+ GlobalExecuteToolFn,
+ ToolCallExecutionTarget,
+} from '../types/provider.types';
import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
/**
@@ -60,6 +65,53 @@ abstract class BaseProvider<TMcpResponse> {
return this._globalExecuteToolFn(toolSlug, body, modifers);
}
+ /** Reject direct-only configuration when execution is bound to a session. */
+ protected assertToolCallExecutionOptions(
+ target: ToolCallExecutionTarget,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): void {
+ if (typeof target !== 'string' && (options !== undefined || modifiers !== undefined)) {
+ throw new TypeError(
+ 'Direct execution options and modifiers cannot be used with a Tool Router session'
+ );
+ }
+ }
+
+ /**
+ * Execute normalized provider arguments against either the direct tools API or
+ * the Tool Router session that produced the model-visible tools.
+ */
+ protected async executeToolForTarget(
+ target: ToolCallExecutionTarget,
+ toolSlug: string,
+ arguments_: Record<string, unknown>,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): Promise<ToolExecuteResponse> {
+ this.assertToolCallExecutionOptions(target, options, modifiers);
+
+ if (typeof target === 'string') {
+ return this.executeTool(
+ toolSlug,
+ {
+ arguments: arguments_,
+ connectedAccountId: options?.connectedAccountId,
+ customAuthParams: options?.customAuthParams,
+ customConnectionData: options?.customConnectionData,
+ userId: target,
+ },
+ modifiers
+ );
+ }
+
+ const result = await target.execute(toolSlug, arguments_);
+ return {
+ ...result,
+ successful: result.error === null,
+ };
+ }
+
/**
* @public
* @deprecated: Will be removed in a future version, once the `experimental.mcp` flag is stabilized. Use `wrapMcpServers` instead.
diff --git a/ts/packages/core/src/provider/OpenAIProvider.ts b/ts/packages/core/src/provider/OpenAIProvider.ts
index 6646c8287..9ded64540 100644
--- a/ts/packages/core/src/provider/OpenAIProvider.ts
+++ b/ts/packages/core/src/provider/OpenAIProvider.ts
@@ -10,10 +10,14 @@
import { OpenAI } from 'openai';
import { Stream } from 'openai/streaming';
import { BaseNonAgenticProvider } from './BaseProvider';
-import { Tool, ToolExecuteParams } from '../types/tool.types';
+import { Tool } from '../types/tool.types';
import logger from '../utils/logger';
import { ExecuteToolModifiers } from '../types/modifiers.types';
-import { ExecuteToolFnOptions } from '../types/provider.types';
+import {
+ ExecuteToolFnOptions,
+ ToolCallExecutionTarget,
+ ToolCallSession,
+} from '../types/provider.types';
import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
import { normalizeToolArguments } from '../utils/toolArguments';
import { deduplicateJsonSchemaRequiredArrays } from '../utils/jsonSchema';
@@ -153,7 +157,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
* This method processes a tool call from OpenAI's chat completion API,
* executes the corresponding Composio tool, and returns the result.
*
- * @param {string} userId - The user ID for authentication and tracking
+ * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
* @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -179,22 +183,32 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
* console.log(JSON.parse(result));
* ```
*/
+ async executeToolCall(
+ session: ToolCallSession,
+ tool: OpenAI.ChatCompletionMessageFunctionToolCall
+ ): Promise<string>;
async executeToolCall(
userId: string,
tool: OpenAI.ChatCompletionMessageFunctionToolCall,
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<string>;
+ async executeToolCall(
+ executionTarget: ToolCallExecutionTarget,
+ tool: OpenAI.ChatCompletionMessageFunctionToolCall,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<string> {
- const payload: ToolExecuteParams = {
- // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
- // empty / object-shaped payloads too (issue #2406).
- arguments: normalizeToolArguments(tool.function.arguments, tool.function.name),
- connectedAccountId: options?.connectedAccountId,
- customAuthParams: options?.customAuthParams,
- customConnectionData: options?.customConnectionData,
- userId: userId,
- };
- const result = await this.executeTool(tool.function.name, payload, modifiers);
+ // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
+ // empty / object-shaped payloads too (issue #2406).
+ const arguments_ = normalizeToolArguments(tool.function.arguments, tool.function.name);
+ const result = await this.executeToolForTarget(
+ executionTarget,
+ tool.function.name,
+ arguments_,
+ options,
+ modifiers
+ );
return JSON.stringify(result);
}
@@ -204,7 +218,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
* This method processes tool calls from an OpenAI chat completion response,
* executes each tool call, and returns the results.
*
- * @param {string} userId - The user ID for authentication and tracking
+ * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
* @param {OpenAI.ChatCompletion} chatCompletion - The chat completion response from OpenAI
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -240,12 +254,23 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
* console.log(results); // Array of tool execution results
* ```
*/
+ async handleToolCalls(
+ session: ToolCallSession,
+ chatCompletion: OpenAI.ChatCompletion
+ ): Promise<OpenAI.ChatCompletionToolMessageParam[]>;
async handleToolCalls(
userId: string,
chatCompletion: OpenAI.ChatCompletion,
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<OpenAI.ChatCompletionToolMessageParam[]>;
+ async handleToolCalls(
+ executionTarget: ToolCallExecutionTarget,
+ chatCompletion: OpenAI.ChatCompletion,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<OpenAI.ChatCompletionToolMessageParam[]> {
+ this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
const outputs: OpenAI.ChatCompletionToolMessageParam[] = [];
// Only the first choice is actionable: its tool results feed back into a
// single assistant turn. With n > 1, iterating every choice would run each
@@ -259,7 +284,10 @@ export class OpenAIProvider extends BaseNonAgenticProvider<
if (toolCall.type !== 'function') {
continue;
}
- const toolResult = await this.executeToolCall(userId, toolCall, options, modifiers);
+ const toolResult =
+ typeof executionTarget === 'string'
+ ? await this.executeToolCall(executionTarget, toolCall, options, modifiers)
+ : await this.executeToolCall(executionTarget, toolCall);
outputs.push({
role: 'tool',
tool_call_id: toolCall.id,
diff --git a/ts/packages/core/src/types/provider.types.ts b/ts/packages/core/src/types/provider.types.ts
index 0d62b473d..d808e37ed 100644
--- a/ts/packages/core/src/types/provider.types.ts
+++ b/ts/packages/core/src/types/provider.types.ts
@@ -8,6 +8,7 @@ import {
ToolListParams,
} from './tool.types';
import { CustomConnectionData } from './connectedAccountAuthStates.types';
+import type { ToolRouterSessionExecuteResponse } from './toolRouter.types';
/**
* Base provider implementation, which needs to be implemented by the extended class.
@@ -25,6 +26,20 @@ export type ExecuteToolFnOptions = {
customConnectionData?: CustomConnectionData;
};
+/**
+ * Minimal public contract required to execute model tool calls through a Tool Router session.
+ * {@link ToolRouterSession} satisfies this interface.
+ */
+export interface ToolCallSession {
+ execute(
+ toolSlug: string,
+ arguments_?: Record<string, unknown>
+ ): Promise<ToolRouterSessionExecuteResponse>;
+}
+
+/** Direct user execution or execution bound to a Tool Router session. */
+export type ToolCallExecutionTarget = string | ToolCallSession;
+
/**
* This type is used to infer the wrapped tool type from the provider.
* It checks if the provider has a method `_wrapTool` and infers the return type.
diff --git a/ts/packages/core/test/provider/openai-provider.test.ts b/ts/packages/core/test/provider/openai-provider.test.ts
index e9c0a94be..386714b36 100644
--- a/ts/packages/core/test/provider/openai-provider.test.ts
+++ b/ts/packages/core/test/provider/openai-provider.test.ts
@@ -200,6 +200,74 @@ describe('OpenAIProvider', () => {
});
describe('handleToolCalls', () => {
+ it('routes session tool calls through the session executor', async () => {
+ const session = {
+ execute: vi.fn().mockResolvedValue({
+ data: { tools: ['GMAIL_SEND_EMAIL'] },
+ error: null,
+ logId: 'log-session',
+ }),
+ };
+ const chatCompletion = {
+ choices: [
+ {
+ message: {
+ tool_calls: [
+ {
+ id: 'call-search',
+ type: 'function',
+ function: {
+ name: 'COMPOSIO_SEARCH_TOOLS',
+ arguments: JSON.stringify({ queries: [{ use_case: 'send email' }] }),
+ },
+ },
+ ],
+ },
+ },
+ ],
+ } as OpenAI.ChatCompletion;
+
+ const results = await provider.handleToolCalls(session, chatCompletion);
+
+ expect(session.execute).toHaveBeenCalledWith('COMPOSIO_SEARCH_TOOLS', {
+ queries: [{ use_case: 'send email' }],
+ });
+ expect(mockExecuteToolFn).not.toHaveBeenCalled();
+ expect(results).toEqual([
+ {
+ role: 'tool',
+ tool_call_id: 'call-search',
+ content: JSON.stringify({
+ data: { tools: ['GMAIL_SEND_EMAIL'] },
+ error: null,
+ logId: 'log-session',
+ successful: true,
+ }),
+ },
+ ]);
+ });
+
+ it('rejects direct execution options for session tool calls', async () => {
+ const session = {
+ execute: vi.fn(),
+ };
+ const chatCompletion = { choices: [] } as unknown as OpenAI.ChatCompletion;
+ const handleToolCallsWithOptions = provider.handleToolCalls as unknown as (
+ executionTarget: typeof session,
+ response: OpenAI.ChatCompletion,
+ options: { connectedAccountId: string }
+ ) => ReturnType<OpenAIProvider['handleToolCalls']>;
+
+ await expect(
+ handleToolCallsWithOptions.call(provider, session, chatCompletion, {
+ connectedAccountId: 'conn-123',
+ })
+ ).rejects.toThrow(
+ 'Direct execution options and modifiers cannot be used with a Tool Router session'
+ );
+ expect(session.execute).not.toHaveBeenCalled();
+ });
+
it('should handle tool calls from chat completion', async () => {
const userId = 'test-user';
const chatCompletion = {
diff --git a/ts/packages/providers/anthropic/README.md b/ts/packages/providers/anthropic/README.md
index c1865e2f8..479ad4f01 100644
--- a/ts/packages/providers/anthropic/README.md
+++ b/ts/packages/providers/anthropic/README.md
@@ -45,7 +45,7 @@ let response = await client.messages.create({
// Agentic loop: keep executing tool calls until the model responds with text
while (response.stop_reason === 'tool_use') {
- const toolResults = await composio.provider.handleToolCalls('user_123', response);
+ const toolResults = await composio.provider.handleToolCalls(session, response);
messages.push({ role: 'assistant', content: response.content });
messages.push(...toolResults);
response = await client.messages.create({
@@ -69,7 +69,7 @@ Building on the Claude Agent SDK instead? Use [`@composio/claude-agent-sdk`](../
## Provider options
- `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.
-- `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.
+- `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.
- Claude occasionally emits a tool's `input` as a JSON string instead of an object; the provider normalizes this before execution.
## Links
diff --git a/ts/packages/providers/anthropic/src/index.ts b/ts/packages/providers/anthropic/src/index.ts
index 204b23348..5b1af9e90 100644
--- a/ts/packages/providers/anthropic/src/index.ts
+++ b/ts/packages/providers/anthropic/src/index.ts
@@ -12,7 +12,8 @@ import {
Tool as ComposioTool,
ExecuteToolModifiers,
ExecuteToolFnOptions,
- ToolExecuteParams,
+ ToolCallExecutionTarget,
+ ToolCallSession,
logger,
McpUrlResponse,
normalizeToolArguments,
@@ -243,7 +244,7 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
* This method processes a tool call from Anthropic's Claude API,
* executes the corresponding Composio tool, and returns the result.
*
- * @param userId - The user ID for authentication and tracking
+ * @param executionTarget - A user ID for direct tools or the session that produced session tools
* @param toolUse - The tool use object from Anthropic
* @param options - Additional options for tool execution
* @param modifiers - Modifiers for tool execution
@@ -269,11 +270,18 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
* console.log(JSON.parse(result));
* ```
*/
+ async executeToolCall(session: ToolCallSession, toolUse: AnthropicToolUseBlock): Promise<string>;
async executeToolCall(
userId: string,
toolUse: AnthropicToolUseBlock,
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<string>;
+ async executeToolCall(
+ executionTarget: ToolCallExecutionTarget,
+ toolUse: AnthropicToolUseBlock,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<string> {
// Models occasionally emit tool input as a JSON string rather than an object
// (issue #2406). Normalize to a plain object first so key restoration below can
@@ -291,15 +299,14 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
logger.debug(`AnthropicProvider restored original argument keys for tool "${toolUse.name}"`);
}
- const payload: ToolExecuteParams = {
- arguments: toolArguments,
- connectedAccountId: options?.connectedAccountId,
- customAuthParams: options?.customAuthParams,
- customConnectionData: options?.customConnectionData,
- userId: userId,
- };
- const result = await this.executeTool(toolUse.name, payload, modifiers);
- return JSON.stringify(result.data);
+ const result = await this.executeToolForTarget(
+ executionTarget,
+ toolUse.name,
+ toolArguments,
+ options,
+ modifiers
+ );
+ return JSON.stringify(result.error === null ? result.data : { error: result.error });
}
/**
@@ -308,7 +315,7 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
* This method processes tool calls from an Anthropic message response,
* extracts the tool use blocks, executes each tool call, and returns the results.
*
- * @param userId - The user ID for authentication and tracking
+ * @param executionTarget - A user ID for direct tools or the session that produced session tools
* @param message - The message response from Anthropic
* @param options - Additional options for tool execution
* @param modifiers - Modifiers for tool execution
@@ -342,12 +349,23 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
* console.log(results);
* ```
*/
+ async handleToolCalls(
+ session: ToolCallSession,
+ message: Anthropic.Message
+ ): Promise<Anthropic.Messages.MessageParam[]>;
async handleToolCalls(
userId: string,
message: Anthropic.Message,
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<Anthropic.Messages.MessageParam[]>;
+ async handleToolCalls(
+ executionTarget: ToolCallExecutionTarget,
+ message: Anthropic.Message,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<Anthropic.Messages.MessageParam[]> {
+ this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
const outputs: Anthropic.Messages.ToolResultBlockParam[] = [];
// Filter and map tool use blocks from message content
@@ -374,7 +392,10 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
}
for (const toolUse of toolUseBlocks) {
- const toolResult = await this.executeToolCall(userId, toolUse, options, modifiers);
+ const toolResult =
+ typeof executionTarget === 'string'
+ ? await this.executeToolCall(executionTarget, toolUse, options, modifiers)
+ : await this.executeToolCall(executionTarget, toolUse);
outputs.push({
type: 'tool_result',
tool_use_id: toolUse.id,
diff --git a/ts/packages/providers/anthropic/test/anthropic.test.ts b/ts/packages/providers/anthropic/test/anthropic.test.ts
index 1e6b69d5c..711984a32 100644
--- a/ts/packages/providers/anthropic/test/anthropic.test.ts
+++ b/ts/packages/providers/anthropic/test/anthropic.test.ts
@@ -203,6 +203,35 @@ describe('AnthropicProvider', () => {
expect(result).toBe(JSON.stringify({ result: 'success' }));
});
+ it('should expose session execution errors without changing successful results', async () => {
+ const toolUse: AnthropicToolUseBlock = {
+ type: 'tool_use',
+ id: 'tu_123',
+ name: 'test-tool',
+ input: { input: 'test-value' },
+ };
+ const session = {
+ execute: vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: { result: 'success' },
+ error: null,
+ logId: 'log-success',
+ })
+ .mockResolvedValueOnce({
+ data: {},
+ error: 'Tool execution failed',
+ logId: 'log-failure',
+ }),
+ };
+
+ const successfulResult = await provider.executeToolCall(session, toolUse);
+ const failedResult = await provider.executeToolCall(session, toolUse);
+
+ expect(successfulResult).toBe(JSON.stringify({ result: 'success' }));
+ expect(failedResult).toBe(JSON.stringify({ error: 'Tool execution failed' }));
+ });
+
it('should normalize a stringified-JSON input to an object before executing (issue #2406)', async () => {
const params = { input: 'test-value' };
const toolUse: AnthropicToolUseBlock = {
diff --git a/ts/packages/providers/anthropic/test/sanitize-keys.test.ts b/ts/packages/providers/anthropic/test/sanitize-keys.test.ts
index 4e1d01ca2..e9b7025b8 100644
--- a/ts/packages/providers/anthropic/test/sanitize-keys.test.ts
+++ b/ts/packages/providers/anthropic/test/sanitize-keys.test.ts
@@ -617,6 +617,31 @@ describe('AnthropicProvider key sanitization', () => {
expect(payload.arguments).toEqual({ $top: 25 });
});
+ it('restores sanitized keys before executing through a tool router session', async () => {
+ const provider = new AnthropicProvider();
+ const directExecute = vi.fn();
+ const session = {
+ execute: vi.fn().mockResolvedValue({
+ data: { ok: true },
+ error: null,
+ logId: 'log-session',
+ }),
+ };
+ provider._setExecuteToolFn(directExecute);
+ provider.wrapTool(odataTool);
+
+ const result = await provider.executeToolCall(session, {
+ type: 'tool_use',
+ id: 'tu_session',
+ name: 'list_drive_item_activities',
+ input: '{"dollar_top": 25}' as unknown as Record<string, unknown>,
+ });
+
+ expect(session.execute).toHaveBeenCalledWith('list_drive_item_activities', { $top: 25 });
+ expect(directExecute).not.toHaveBeenCalled();
+ expect(result).toBe(JSON.stringify({ ok: true }));
+ });
+
it('normalizes a JSON-string input for tools without sanitized keys (issue #2406)', async () => {
const provider = new AnthropicProvider();
const executeToolFn = vi
diff --git a/ts/packages/providers/openai/README.md b/ts/packages/providers/openai/README.md
index 943fd45f8..edfd0d15a 100644
--- a/ts/packages/providers/openai/README.md
+++ b/ts/packages/providers/openai/README.md
@@ -42,7 +42,7 @@ let response = await client.responses.create({
// Agentic loop: keep executing tool calls until the model responds with text
while (response.output.some(o => o.type === 'function_call')) {
- const results = await composio.provider.handleToolCalls('user_123', response.output);
+ const results = await composio.provider.handleToolCalls(session, response.output);
response = await client.responses.create({
model: 'gpt-5.2',
tools,
@@ -63,8 +63,8 @@ for (const item of response.output) {
The package exports one provider per API surface:
-- `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`).
-- `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.
+- `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`).
+- `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.
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.
diff --git a/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts b/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
index b15e1a328..027f81fbb 100644
--- a/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
+++ b/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
@@ -13,9 +13,10 @@ import { OpenAI } from 'openai';
import {
BaseNonAgenticProvider,
Tool,
- ToolExecuteParams,
ExecuteToolModifiers,
ExecuteToolFnOptions,
+ ToolCallExecutionTarget,
+ ToolCallSession,
removeNonRequiredProperties,
McpUrlResponse,
normalizeToolArguments,
@@ -190,7 +191,7 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
* This method processes a tool call from OpenAI's chat completion API,
* executes the corresponding Composio tool, and returns the result.
*
- * @param {string} userId - The user ID for authentication and tracking
+ * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
* @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -216,22 +217,32 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
* console.log(JSON.parse(result));
* ```
*/
+ async executeToolCall(
+ session: ToolCallSession,
+ tool: OpenAI.Responses.ResponseFunctionToolCall
+ ): Promise<string>;
async executeToolCall(
userId: string,
tool: OpenAI.Responses.ResponseFunctionToolCall,
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<string>;
+ async executeToolCall(
+ executionTarget: ToolCallExecutionTarget,
+ tool: OpenAI.Responses.ResponseFunctionToolCall,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<string> {
- const payload: ToolExecuteParams = {
- // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
- // empty / object-shaped payloads too (issue #2406).
- arguments: normalizeToolArguments(tool.arguments, tool.name),
- connectedAccountId: options?.connectedAccountId,
- customAuthParams: options?.customAuthParams,
- customConnectionData: options?.customConnectionData,
- userId: userId,
- };
- const result = await this.executeTool(tool.name, payload, modifiers);
+ // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
+ // empty / object-shaped payloads too (issue #2406).
+ const arguments_ = normalizeToolArguments(tool.arguments, tool.name);
+ const result = await this.executeToolForTarget(
+ executionTarget,
+ tool.name,
+ arguments_,
+ options,
+ modifiers
+ );
return JSON.stringify(result);
}
@@ -241,7 +252,7 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
* This method processes tool calls from an OpenAI response,
* executes each tool call, and returns the results.
*
- * @param {string} userId - The user ID for authentication and tracking
+ * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
* @param {OpenAI.ChatCompletion} chatCompletion - The response from OpenAI
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
@@ -271,12 +282,23 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
* ```
* ```
*/
+ async handleToolCalls(
+ session: ToolCallSession,
+ toolCalls: OpenAI.Responses.ResponseOutputItem[]
+ ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
async handleToolCalls(
userId: string,
toolCalls: OpenAI.Responses.ResponseOutputItem[],
options?: ExecuteToolFnOptions,
modifiers?: ExecuteToolModifiers
+ ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
+ async handleToolCalls(
+ executionTarget: ToolCallExecutionTarget,
+ toolCalls: OpenAI.Responses.ResponseOutputItem[],
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]> {
+ this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
const toolOutputs: OpenAI.Responses.ResponseInputItem.FunctionCallOutput[] = [];
for (const output of toolCalls) {
if (output.type === 'function_call') {
@@ -286,7 +308,10 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
arguments: output.arguments,
} as OpenAI.Responses.ResponseFunctionToolCall;
try {
- const toolOutput = await this.executeToolCall(userId, tool_call, options, modifiers);
+ const toolOutput =
+ typeof executionTarget === 'string'
+ ? await this.executeToolCall(executionTarget, tool_call, options, modifiers)
+ : await this.executeToolCall(executionTarget, tool_call);
toolOutputs.push({
call_id: output.call_id ?? '',
type: 'function_call_output',
diff --git a/ts/packages/providers/openai/test/opeanai-responses.test.ts b/ts/packages/providers/openai/test/opeanai-responses.test.ts
index 63b1ab58e..2accb8bbe 100644
--- a/ts/packages/providers/openai/test/opeanai-responses.test.ts
+++ b/ts/packages/providers/openai/test/opeanai-responses.test.ts
@@ -253,6 +253,60 @@ describe('OpenAIResponsesProvider', () => {
});
describe('handleToolCalls', () => {
+ it('preserves Responses output order and errors when executing through a session', async () => {
+ const session = {
+ execute: vi
+ .fn()
+ .mockResolvedValueOnce({ data: { index: 1 }, error: null, logId: 'log-1' })
+ .mockRejectedValueOnce(new Error('session execution failed')),
+ };
+ const toolCalls = [
+ {
+ id: 'item-1',
+ type: 'function_call',
+ name: 'COMPOSIO_SEARCH_TOOLS',
+ arguments: JSON.stringify({ queries: [{ use_case: 'first' }] }),
+ call_id: 'call-1',
+ },
+ {
+ id: 'item-2',
+ type: 'function_call',
+ name: 'COMPOSIO_SEARCH_TOOLS',
+ arguments: JSON.stringify({ queries: [{ use_case: 'second' }] }),
+ call_id: 'call-2',
+ },
+ ] as OpenAI.Responses.ResponseOutputItem[];
+
+ const results = await provider.handleToolCalls(session, toolCalls);
+
+ expect(session.execute).toHaveBeenNthCalledWith(1, 'COMPOSIO_SEARCH_TOOLS', {
+ queries: [{ use_case: 'first' }],
+ });
+ expect(session.execute).toHaveBeenNthCalledWith(2, 'COMPOSIO_SEARCH_TOOLS', {
+ queries: [{ use_case: 'second' }],
+ });
+ expect(mockExecuteToolFn).not.toHaveBeenCalled();
+ expect(results).toEqual([
+ {
+ call_id: 'call-1',
+ type: 'function_call_output',
+ output: JSON.stringify({
+ data: { index: 1 },
+ error: null,
+ logId: 'log-1',
+ successful: true,
+ }),
+ status: 'completed',
+ },
+ {
+ call_id: 'call-2',
+ type: 'function_call_output',
+ output: 'session execution failed',
+ status: 'incomplete',
+ },
+ ]);
+ });
+
it('should handle tool calls from OpenAI response', async () => {
const userId = 'test-user';
const toolCalls = [