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(tool-router): tighten annotation routing and e2e retries
Dhawal Upadhyay committed
Mar 24, 2026 at 15:29 UTC
db8f08ba9529d85f3bbcf8c9c193b27ea55a7c3e
6 files changed
+190
-26
python/composio/core/models/custom_tool.py
+67
-6
@@ -221,6 +221,35 @@ def _create_tool(
221
)
222
223
224
+def _get_caller_locals(depth: int = 2) -> t.Optional[t.Mapping[str, t.Any]]:
225
+ """Best-effort lookup of a caller frame's locals."""
226
+ frame = inspect.currentframe()
227
+ try:
228
+ caller = frame
229
+ for _ in range(depth):
230
+ caller = caller.f_back if caller is not None else None
231
+ return caller.f_locals if caller is not None else None
232
+ finally:
233
+ del frame
234
+
235
+
236
+def _resolve_function_annotations(
237
+ fn: t.Callable[..., t.Any],
238
+ *,
239
+ localns: t.Optional[t.Mapping[str, t.Any]] = None,
240
+) -> t.Dict[str, t.Any]:
241
+ """Resolve annotations, including postponed string annotations when possible."""
242
+ try:
243
+ return t.get_type_hints(
244
+ fn,
245
+ globalns=getattr(fn, "__globals__", {}),
246
+ localns=dict(localns) if localns is not None else None,
247
+ include_extras=True,
248
+ )
249
+ except Exception:
250
+ return {}
251
+
252
+
253
def _infer_tool_from_function(
254
fn: t.Callable[..., t.Any],
255
*,
@@ -229,6 +258,7 @@ def _infer_tool_from_function(
258
description: t.Optional[str] = None,
259
extends_toolkit: t.Optional[str] = None,
260
output_params: t.Optional[t.Type[BaseModel]] = None,
261
+ annotation_locals: t.Optional[t.Mapping[str, t.Any]] = None,
262
) -> CustomTool:
263
"""Create a CustomTool by inferring metadata from a decorated function.
264
@@ -263,6 +293,10 @@ def _infer_tool_from_function(
293
294
sig = inspect.signature(fn)
295
params = list(sig.parameters.values())
296
+ resolved_annotations = _resolve_function_annotations(
297
+ fn,
298
+ localns=annotation_locals,
299
+ )
300
301
if not params:
302
raise ValidationError(
@@ -280,15 +314,16 @@ def _infer_tool_from_function(
314
315
# First param must be the input model
316
first = params[0]
283
- if first.annotation is inspect.Parameter.empty or not (
284
- isinstance(first.annotation, type) and issubclass(first.annotation, BaseModel)
317
+ first_annotation = resolved_annotations.get(first.name, first.annotation)
318
+ if first_annotation is inspect.Parameter.empty or not (
319
+ isinstance(first_annotation, type) and issubclass(first_annotation, BaseModel)
320
):
321
raise ValidationError(
322
f'experimental.tool: first parameter of "{fn.__name__}" must be annotated '
288
- f"with a Pydantic BaseModel subclass. Got: {first.annotation!r}. "
323
+ f"with a Pydantic BaseModel subclass. Got: {first_annotation!r}. "
324
f"Expected: def {fn.__name__}(input: MyInput, ctx): ..."
325
)
291
- input_params: t.Type[BaseModel] = first.annotation
326
+ input_params: t.Type[BaseModel] = first_annotation
327
328
# Wrap function to match CustomToolExecuteFn: (input, ctx) -> dict
329
if len(params) == 1:
@@ -383,12 +418,14 @@ class ExperimentalToolkit:
418
"""
419
420
def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
421
+ annotation_locals = _get_caller_locals()
422
custom_tool = _infer_tool_from_function(
423
f,
424
slug=slug,
425
name=name,
426
description=description,
427
output_params=output_params,
428
+ annotation_locals=annotation_locals,
429
# No extends_toolkit for toolkit tools
430
)
431
_validate_slug_length(
@@ -398,7 +435,21 @@ class ExperimentalToolkit:
435
return custom_tool
436
437
if fn is not None:
401
- return decorator(fn)
438
+ custom_tool = _infer_tool_from_function(
439
+ fn,
440
+ slug=slug,
441
+ name=name,
442
+ description=description,
443
+ output_params=output_params,
444
+ annotation_locals=_get_caller_locals(),
445
+ )
446
+ _validate_slug_length(
447
+ custom_tool.slug,
448
+ self.slug,
449
+ f'experimental.Toolkit("{self.slug}").tool',
450
+ )
451
+ self._tools.append(custom_tool)
452
+ return custom_tool
453
return decorator
454
455
@@ -467,6 +518,7 @@ class ExperimentalAPI:
518
"""
519
520
def decorator(f: t.Callable[..., t.Any]) -> CustomTool:
521
+ annotation_locals = _get_caller_locals()
522
return _infer_tool_from_function(
523
f,
524
slug=slug,
@@ -474,10 +526,19 @@ class ExperimentalAPI:
526
description=description,
527
extends_toolkit=extends_toolkit,
528
output_params=output_params,
529
+ annotation_locals=annotation_locals,
530
)
531
532
if fn is not None:
480
- return decorator(fn)
533
+ return _infer_tool_from_function(
534
+ fn,
535
+ slug=slug,
536
+ name=name,
537
+ description=description,
538
+ extends_toolkit=extends_toolkit,
539
+ output_params=output_params,
540
+ annotation_locals=_get_caller_locals(),
541
+ )
542
return decorator
543
544
python/composio/core/models/tool_router_session.py
+10
-2
@@ -336,6 +336,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
336
{**entry, "index": i}
337
for i, entry in enumerate([*remote_results_list, *local_entries])
338
]
339
+ failed = sum(1 for r in all_results if r.get("error"))
340
+ merged_data = {**remote_data, "results": all_results}
341
+ if local_entries and any(
342
+ key in remote_data
343
+ for key in ("total_count", "success_count", "error_count")
344
+ ):
345
+ merged_data["total_count"] = len(all_results)
346
+ merged_data["success_count"] = len(all_results) - failed
347
+ merged_data["error_count"] = failed
348
349
remote_error = (
350
str(remote_result.get("error"))
@@ -345,7 +354,6 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
354
has_any_error = any(r.get("error") for _, r in local_results) or bool(
355
remote_error
356
)
348
- failed = sum(1 for r in all_results if r.get("error"))
357
error_message = None
358
if has_any_error:
359
error_message = (
@@ -355,7 +363,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
363
)
364
365
return {
358
- "data": {**remote_data, "results": all_results},
366
+ "data": merged_data,
367
"error": error_message,
368
"successful": not has_any_error,
369
}
python/tests/test_custom_tools.py
+49
-2
@@ -241,6 +241,47 @@ class TestDecoratorTool:
241
"""Swapped order — ctx first, input second."""
242
return {}
243
244
+ def test_future_annotations_are_resolved(self):
245
+ namespace = {"exp": exp}
246
+ exec(
247
+ """
248
+from __future__ import annotations
249
+
250
+from pydantic import BaseModel, Field
251
+
252
+
253
+class FutureInput(BaseModel):
254
+ pattern: str = Field(description="Pattern to search for")
255
+
256
+
257
+@exp.tool()
258
+def future_tool(input: FutureInput, ctx):
259
+ '''Resolved from postponed annotations.'''
260
+ return {}
261
+""",
262
+ namespace,
263
+ )
264
+
265
+ future_tool = namespace["future_tool"]
266
+ future_input = namespace["FutureInput"]
267
+
268
+ assert future_tool.input_params is future_input
269
+
270
+ def test_local_string_annotations_are_resolved(self):
271
+ def build_tool():
272
+ class LocalInput(BaseModel):
273
+ pattern: str = Field(description="Pattern to search for")
274
+
275
+ @exp.tool
276
+ def nested_search(input: "LocalInput", ctx):
277
+ """Resolved from local string annotations."""
278
+ return {}
279
+
280
+ return nested_search, LocalInput
281
+
282
+ local_tool, local_input = build_tool()
283
+ assert local_tool.input_params is local_input
284
+
285
def test_async_function_rejected(self):
286
with pytest.raises(ValidationError, match="async"):
287
@@ -655,8 +696,11 @@ class TestMultiExecuteRouting:
696
remote = {
697
"data": {
698
"results": [
658
- {"tool_slug": "R", "response": {"successful": True, "data": {}}}
659
- ]
699
+ {"tool_slug": "R", "response": {"successful": True, "data": {}}},
700
+ ],
701
+ "total_count": 1,
702
+ "success_count": 1,
703
+ "error_count": 0,
704
},
705
"error": None,
706
"successful": True,
@@ -676,6 +720,9 @@ class TestMultiExecuteRouting:
720
# Remotes first, locals appended (matches TS)
721
assert results[0]["tool_slug"] == "R"
722
assert results[1]["tool_slug"] == "GREP"
723
+ assert result["data"]["total_count"] == 2
724
+ assert result["data"]["success_count"] == 2
725
+ assert result["data"]["error_count"] == 0
726
727
def test_failure_propagated(self):
728
@exp.tool()
ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjs
+30
-14
@@ -32,7 +32,9 @@ async function main() {
32
if (!uploaded.mountRelativePath || !uploaded.downloadUrl) {
33
throw new Error('Upload failed: missing mountRelativePath or downloadUrl');
34
}
35
- const storedPath = uploaded.mountRelativePath.replace(/^\//, '');
35
+ const candidatePaths = Array.from(
36
+ new Set([uploaded.mountRelativePath, uploaded.mountRelativePath.replace(/^\/+/, '')]).values()
37
+ ).filter(Boolean);
38
console.log('UPLOAD_OK');
39
40
// List files (retry for eventual consistency; omit path for root - SDK normalizes)
@@ -40,8 +42,8 @@ async function main() {
42
for (let attempt = 0; attempt < 5; attempt++) {
43
const listResult = await files.list();
44
const found = listResult.items?.some(
43
- (item) =>
44
- item.mountRelativePath === storedPath ||
45
+ item =>
46
+ candidatePaths.includes(item.mountRelativePath) ||
47
item.mountRelativePath === testPath ||
48
item.mountRelativePath?.endsWith(testPath) ||
49
item.mountRelativePath?.includes(testPath)
@@ -50,36 +52,50 @@ async function main() {
52
listOk = true;
53
break;
54
}
53
- await new Promise((r) => setTimeout(r, 1000));
55
+ await new Promise(r => setTimeout(r, 1000));
56
}
57
if (listOk) console.log('LIST_OK');
58
else console.log('LIST_SKIP'); // eventual consistency
59
60
// Download the file (retry for eventual consistency, same as list above)
61
let downloaded;
62
+ let lastDownloadError;
63
+ let resolvedPath;
64
for (let attempt = 0; attempt < 5; attempt++) {
61
- try {
62
- downloaded = await files.download(storedPath);
65
+ for (const candidatePath of candidatePaths) {
66
+ try {
67
+ const remoteFile = await files.download(candidatePath);
68
+ const content = await remoteFile.text();
69
+ if (content !== testContent) {
70
+ throw new Error(`Download failed: expected "${testContent}", got "${content}"`);
71
+ }
72
+ downloaded = remoteFile;
73
+ resolvedPath = candidatePath;
74
+ break;
75
+ } catch (err) {
76
+ lastDownloadError = err;
77
+ }
78
+ }
79
+ if (downloaded) {
80
break;
64
- } catch (err) {
65
- if (attempt === 4) throw err;
66
- await new Promise((r) => setTimeout(r, 1000));
81
+ }
82
+ if (attempt < 4) {
83
+ await new Promise(r => setTimeout(r, 1000));
84
}
85
}
69
- const content = await downloaded.text();
70
- if (content !== testContent) {
71
- throw new Error(`Download failed: expected "${testContent}", got "${content}"`);
86
+ if (!downloaded) {
87
+ throw lastDownloadError ?? new Error('Download failed after retries');
88
}
89
console.log('DOWNLOAD_OK');
90
91
// Delete the file (use path from API response)
76
- await files.delete(storedPath);
92
+ await files.delete(resolvedPath ?? candidatePaths[0]);
93
console.log('DELETE_OK');
94
95
console.log('ALL_OK');
96
}
97
82
-main().catch((err) => {
98
+main().catch(err => {
99
console.log('ERROR:', err?.message || err);
100
process.exit(1);
101
});
ts/packages/core/src/models/ToolRouterSession.ts
+14
-2
@@ -469,12 +469,24 @@ export class ToolRouterSession<
469
index: i,
470
})
471
);
472
+ const failedCount = allResults.filter(r => r.error).length;
473
+ const mergedData: Record<string, unknown> = {
474
+ ...remoteData,
475
+ results: allResults,
476
+ };
477
+ if (
478
+ localEntries.length > 0 &&
479
+ ['total_count', 'success_count', 'error_count'].some(key => key in remoteData)
480
+ ) {
481
+ mergedData.total_count = allResults.length;
482
+ mergedData.success_count = allResults.length - failedCount;
483
+ mergedData.error_count = failedCount;
484
+ }
485
const remoteError = typeof remoteResult?.error === 'string' ? remoteResult.error : null;
486
const hasAnyError = localResults.some(r => r.result.error) || !!remoteError;
474
- const failedCount = allResults.filter(r => r.error).length;
487
488
return {
477
- data: { ...remoteData, results: allResults },
489
+ data: mergedData,
490
error: hasAnyError
491
? remoteError && failedCount === 0
492
? remoteError
ts/packages/core/test/models/customToolRouting.test.ts
+20
@@ -671,6 +671,26 @@ describe('ToolRouterSession execution routing', () => {
671
expect(result.successful).toBe(true);
672
});
673
674
+ it('should recompute remote counters when local results are merged', async () => {
675
+ const { executeFn, toolsInstance } = await setupMultiExecute(mockClient, [customToolHandle]);
676
+
677
+ toolsInstance.executeMetaTool.mockResolvedValueOnce(
678
+ backendResponse([{ tool_slug: 'GMAIL_SEND_EMAIL', data: { sent: true } }])
679
+ );
680
+
681
+ const result = await executeFn('COMPOSIO_MULTI_EXECUTE_TOOL', {
682
+ tools: [
683
+ { tool_slug: 'LOCAL_GET_USER_CONTEXT', arguments: { category: 'counts' } },
684
+ { tool_slug: 'GMAIL_SEND_EMAIL', arguments: { to: 'a@b.com' } },
685
+ ],
686
+ sync_response_to_workbench: false,
687
+ });
688
+
689
+ expect(result.data.total_count).toBe(2);
690
+ expect(result.data.success_count).toBe(2);
691
+ expect(result.data.error_count).toBe(0);
692
+ });
693
+
694
it('should handle remote null data without crashing', async () => {
695
const { executeFn, toolsInstance } = await setupMultiExecute(mockClient, [customToolHandle]);
696