1
---
2
title: Executing tools directly
3
description: Maintain legacy integrations that call composio.tools.execute(); prefer sessions for new integrations
4
-keywords: [execute, run, tool calling, function calling, direct execution]
4
+keywords: [execute, run, tool calling, function calling, direct execution, version, pin version]
5
llmGuardrails: "direct-execution"
6
legacy: true
7
---
14
15
In Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.
16
17
+To run a specific tool version, pass `version` directly to `composio.tools.execute()`. See [Pin a version](#pin-a-version) for complete Python and TypeScript examples.
18
+
19
## Canceling TypeScript requests
20
21
TypeScript SDK methods accept an `AbortSignal` in their trailing request options. Aborted requests throw `ComposioRequestCancelledError`, so cancellation can be handled separately from execution failures:
229
**CLI**: For Python and TypeScript projects, run `composio generate` to generate types. [Learn more →](/docs/cli#generate-type-definitions)
230
</Callout>
231
232
+### Pin a version
233
+
234
+Pass `version` on the `tools.execute()` call to select a specific tool version. This overrides SDK initialization and environment defaults for that call without changing other executions.
235
+
236
+Choose an available version from the [GitHub toolkit page](/toolkits/github) or [look it up with the SDK](/docs/tools-direct/toolkit-versioning#managing-versions). The examples below use `20250909_00`. Replace it with the version you have tested, and keep that string in your code or configuration.
237
+
238
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
239
<Tab value="Python">
240
```python
241
from composio import Composio
242
235
-user_id = "user-k7334"
236
-# Configure toolkit versions at SDK level for every toolkit you execute.
237
-# Use "latest", or pin a version (see "Pin a version" below)
238
-composio = Composio(
239
- api_key="your_composio_key",
240
- toolkit_versions={"github": "latest"}
241
-)
243
+composio = Composio(api_key="your_composio_key")
244
243
-# Find available arguments for any tool in the Composio dashboard
245
result = composio.tools.execute(
246
"GITHUB_LIST_STARGAZERS",
246
- user_id=user_id,
247
+ user_id="user-k7334",
248
+ version="20250909_00",
249
arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
248
- # "latest" requires this opt-in; to pin instead, pass version (see "Pin a version" below)
249
- dangerously_skip_version_check=True,
250
)
251
print(result)
252
```
255
```typescript
256
import { Composio } from "@composio/core";
257
258
-const userId = "user-k7334";
259
-// Configure toolkit versions at SDK level for every toolkit you execute.
260
-// Use "latest", or pin a version (see "Pin a version" below)
261
-const composio = new Composio({
262
- apiKey: "your_composio_key",
263
- toolkitVersions: { github: "latest" }
264
-});
258
+const composio = new Composio({ apiKey: "your_composio_key" });
259
266
-// Find available arguments for any tool in the Composio dashboard
260
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
268
- userId,
269
- arguments: {
270
- "owner": "ComposioHQ",
271
- "repo": "composio",
272
- "page": 1,
273
- "per_page": 5
274
- },
275
- // "latest" requires this opt-in; to pin instead, pass `version` (see "Pin a version" below)
276
- dangerouslySkipVersionCheck: true,
261
+ userId: "user-k7334",
262
+ version: "20250909_00",
263
+ arguments: { owner: "ComposioHQ", repo: "composio", page: 1, per_page: 5 },
264
});
278
-console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
265
+console.log(result);
266
```
267
</Tab>
268
</Tabs>
269
283
-### Pin a version
270
+A dated `version` satisfies the direct-execution version check. To set a default for all calls to a toolkit, configure [SDK initialization or environment variables](/docs/tools-direct/toolkit-versioning#configuration-methods).
271
+
272
+### Use the latest version
273
285
-When your code parses tool outputs, look up the current version once, then pass that dated string as `version` on every call. Hard-code the string (or keep it in config) rather than looking it up at runtime, so a new release can't change the output shape without you noticing.
274
+If an LLM consumes the output and can handle schema changes, you can use `latest`. Direct execution requires the explicit opt-in shown below.
275
276
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
277
<Tab value="Python">
278
```python
279
from composio import Composio
280
292
-composio = Composio(api_key="your_composio_key")
293
-
294
-# One-off lookup: prints something like "20250909_00"
295
-print(composio.toolkits.get(slug="github").meta.version)
281
+user_id = "user-k7334"
282
+# Configure toolkit versions at SDK level for every toolkit you execute.
283
+# Use "latest", or pin a version (see "Pin a version" above)
284
+composio = Composio(
285
+ api_key="your_composio_key",
286
+ toolkit_versions={"github": "latest"}
287
+)
288
289
+# Find available arguments for any tool in the Composio dashboard
290
result = composio.tools.execute(
291
"GITHUB_LIST_STARGAZERS",
299
- user_id="user-k7334",
300
- version="20250909_00",
292
+ user_id=user_id,
293
arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
294
+ # "latest" requires this opt-in; to pin instead, pass version (see "Pin a version" above)
295
+ dangerously_skip_version_check=True,
296
)
297
+print(result)
298
```
299
</Tab>
300
<Tab value="TypeScript">
301
```typescript
302
import { Composio } from "@composio/core";
303
309
-const composio = new Composio({ apiKey: "your_composio_key" });
310
-
311
-// One-off lookup: prints something like "20250909_00"
312
-const tool = await composio.tools.getRawComposioToolBySlug("GITHUB_LIST_STARGAZERS");
313
-console.log(tool.version);
304
+const userId = "user-k7334";
305
+// Configure toolkit versions at SDK level for every toolkit you execute.
306
+// Use "latest", or pin a version (see "Pin a version" above)
307
+const composio = new Composio({
308
+ apiKey: "your_composio_key",
309
+ toolkitVersions: { github: "latest" }
310
+});
311
312
+// Find available arguments for any tool in the Composio dashboard
313
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
316
- userId: "user-k7334",
317
- version: "20250909_00",
318
- arguments: { owner: "ComposioHQ", repo: "composio", page: 1, per_page: 5 },
314
+ userId,
315
+ arguments: {
316
+ "owner": "ComposioHQ",
317
+ "repo": "composio",
318
+ "page": 1,
319
+ "per_page": 5
320
+ },
321
+ // "latest" requires this opt-in; to pin instead, pass `version` (see "Pin a version" above)
322
+ dangerouslySkipVersionCheck: true,
323
});
324
+console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
325
```
326
</Tab>
327
</Tabs>
328
324
-<Callout>
325
-The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for all configuration options.
326
-</Callout>
327
-
328
-<Callout type="info">
329
-**Choosing a version strategy:** Use `latest` when tool outputs are consumed by an LLM or AI agent — agents adapt to schema changes dynamically. Pin to a specific version when your code parses outputs programmatically. See [choosing between `latest` and a pinned version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version).
330
-</Callout>
331
-
329
### Proxy Execute
330
331
You can proxy requests to any supported toolkit API and let Composio inject the authentication state. This is useful when you need an API endpoint that isn't available as a predefined tool.