@devries-cameron20 / composio Mirror · read-only / commits / 55d8924e2
Fork 0

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

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

Synced Nov 21, 06:00 UTC

fix(python): preserve Anthropic tool result correlation (#5230)

Linear: [DEVREL-306](https://linear.app/composio/issue/DEVREL-306/tool-execution-response-shapes-are-inconsistent) ## Problem Gauge recommendation `cmvfzize507i30it0t33stivf` identifies missing Anthropic call/result correlation and confusion between session, modifier, and provider-helper contracts. The regression reproduced against published `composio==0.31.0` / `composio-anthropic==0.31.0` and the worktree's origin/next baseline: both session-backed and direct helper batches raised `KeyError: tool_use_id` when consumers tried to correlate two calls. Source evidence: runs `cmvtk2xiq000401fydrgbbdd1` seq 113/122, `cmvtk2xiq000601fy0gevtted` seq 92/95/101, `cmvfzawkc00av01nuxmosc2vx` seq 161/165/171, and `cmvfzamhp00ad01nus00np06n` seq 90/96/101/107/112/113. Live inspection of https://docs.composio.dev/docs/providers/anthropic.md confirmed that its Python example already pairs results with original tool-use IDs; that existing adaptation is correct, not the package fix. Related recommendation `cmvhl2427013q0ippyvciudqo` supplies advisory outcome-checking evidence, not an observed successful or failed provider-side send. **Root cause.** Owned by ComposioHQ/composio. Python `AnthropicProvider.execute_tool_call` returned the execution dictionary unchanged, discarding the originating `ToolUseBlock.id`; batch handling inherited that loss. `BaseProvider.execute_tool_for_target` also projected session results down to data/error/successful, dropping log ID, explicit session status, and returned Instant charges. The separate session-tool wrapper performed another conversion. Session and modifier contracts intentionally differ: Python uses `tool_slug` and a Pydantic model with `result_type`, direct execution uses `slug` and dictionaries with `successful`, and TypeScript uses positional tool slugs plus `resultType` or `successful` at different boundaries. TypeScript Anthropic helpers already correlate native message blocks but serialize a payload projection rather than a full execution response. ## Change Committed as `eac0839b8` on the assigned branch. Exported `AnthropicToolExecutionResponse` from `composio_anthropic`; single-call and batch helpers now return the existing dictionary fields plus the originating `tool_use_id`, without mutating the executor's dictionary. Consolidated Python session-result adaptation to retain `log_id`, `result_type`, and any returned `instant_charge`, while continuing to derive successful only from completed status. Migrated affected provider contract assertions and valid response fixtures, and added repeated-tool-name correlation, explicit success/failure, empty-error failure, serialization, public typing, and raised-auth-error coverage. Updated Python session/modifier docstrings, both SDK package READMEs, both Anthropic package READMEs, and TypeScript helper return documentation. Python still explicitly constructs Anthropic content blocks, including the correct tool-use ID mapping; the existing web guide remains unchanged and compatible. Routing, account selection, auth provisioning, dependency ranges, discovery layout, retry/idempotency behavior, generated outputs, and Gauge criteria are unchanged. TypeScript changes are documentation only; no TypeScript changeset is needed. ## Verification exercised - Published-package and baseline-source reproduction: both direct and session helper batches failed with missing tool_use_id; the independent authentication-error case passed before the fix. - Final rerunnable execution-contract suite: 327 passed, 11 skipped, with 59 deprecation warnings; covers provider helpers, session execution, modifiers, explicit null/empty-error failures, schema alias restoration, Google consumers, and Anthropic regressions. - Scoped Ruff check passed for all changed Python implementation and test files. - Mypy with the repository-locked pydantic 2.12.5 and json-schema-to-pydantic 0.4.11 passed all seven selected source files, including public single-call and batch response inference for both execution targets. - Built core and Anthropic wheels, installed non-editable artifacts outside the source tree, and ran all nine Anthropic provider tests against the installed distributions: nine passed. - Rebuilt and reinstalled final Python distributions without the package cache. A throwaway consumer used a real local HTTP socket with a synthetic service: two calls to the same tool retained distinct IDs, completed/failed statuses, log IDs, and returned Instant charge; empty-error failure remained unsuccessful; both Pydantic serializers worked; authentication failure raised. Anthropic client request serialization accepted the explicit Python tool_result adaptation, and its IDs matched the unchanged web-guide adaptation. - Installed @composio/core 0.28.0, @composio/anthropic 0.11.7, and @anthropic-ai/sdk 0.135.0 in an isolated TypeScript consumer. A local synthetic HTTP service verified resultType/logId serialization, multiple correlated native result blocks, JSON payload projection, and the documented absence of is_error on those helper blocks. - Extracted the new TypeScript core README example and typechecked it against installed public package types using tsc with strict checking: passed. - Rendered all four changed package READMEs from Markdown to HTML and checked the execution contract sections. Inspected installed Python package metadata/docstrings for the documented correlation, outcome, and serialization contracts. - Committed only the 17 intended files as eac0839b8; git status --porcelain was empty. Removed build scaffolding and throwaway consumers; local smoke servers stopped. No push or external product write was performed. Rerun by the Agent Experience Factory on the pushed commit before opening this PR: - `NODE_OPTIONS=--max-old-space-size=4096 UV_CONCURRENT_BUILDS=1 uv run --no-project --with ./python --with ./python/providers/anthropic --with ./python/providers/google --with pytest==9.2.0 --with pytest-mock==3.17.0 --with pytest-timeout==2.4.0 python -m pytest python/tests/test_provider.py python/tests/test_tool_router.py python/tests/test_tool_execution.py python/tests/test_google_provider.py python/tests/test_tool_schema_aliasing.py python/providers/anthropic/tests -q` in `.` — exit 0 - `NODE_OPTIONS=--max-old-space-size=4096 UV_CONCURRENT_BUILDS=1 uv run --no-project --with ruff==0.17.3 ruff check --config python/config/ruff.toml python/composio/core/models/tools.py python/composio/core/models/tool_router_session.py python/composio/core/models/_modifiers.py python/composio/core/provider/base.py python/providers/anthropic/composio_anthropic python/providers/anthropic/tests python/tests/test_type_inference_anthropic.py python/tests/test_provider.py python/tests/test_tool_router.py python/tests/test_google_provider.py python/tests/test_tool_schema_aliasing.py` in `.` — exit 0 - `NODE_OPTIONS=--max-old-space-size=4096 UV_CONCURRENT_BUILDS=1 uv run --no-project --with . --with ./providers/anthropic --with mypy==2.3.1 --with types-requests==2.33.0.20261030 --with types-jsonschema==4.26.0.20260518 --with pydantic==2.12.5 --with json-schema-to-pydantic==0.4.11 mypy --config-file config/mypy.ini composio/core/models/tools.py composio/core/models/tool_router_session.py composio/core/models/_modifiers.py composio/core/provider/base.py providers/anthropic/composio_anthropic tests/test_type_inference_anthropic.py` in `python` — exit 0 ## Remaining validation - SDK/provider publication is pending; the candidate contract is not claimed to be shipped on PyPI or deployed to production. - An artifact-exposed matched Gauge rerun of the cited source sessions remains pending after publication/deployment, with unchanged criteria. No paid runs, evaluations, optimizations, deployments, or criterion changes were started; original-finding removal and absence of new Gauge findings are not claimed. - All execution smoke responses were synthetic and local. No credentialed Composio/Anthropic action, provider-side send, auth recovery, exactly-once execution, or live side effect was attempted or established. - The full monorepo and every provider suite were not run; the selected regression run included 11 existing skipped tests. - An unpinned mypy environment using pydantic 2.14.2 / json-schema-to-pydantic 0.5.0 reported a transitive TypeAdapter typing error in unchanged python/composio/utils/schema_converter.py:813. The recorded rerunnable typecheck uses the repository's locked versions and passes; dependency ranges and that unrelated source were left unchanged. - The TypeScript Anthropic helper's existing payload-only serialization and lack of is_error remain unchanged and are now explicitly documented; application outcome decisions must use the session/direct execution contract rather than infer success from helper content. Not merged or deployed. A matched Gauge retest can only run after deployment. <sub>Opened by the Agent Experience Factory to improve agent preference across docs and landing pages (queue `2026-11-04-next`).</sub> ## Python CI follow-up The TypeSafe session test expected the old three-field execution response. It now supplies an explicit log ID and checks that the adapter preserves `log_id` and `result_type`. Validation at `518459ae2`: - `uv run --no-project --with ./python --with ./python/providers/typesafe --with hypothesis --with pytest --with pytest-mock pytest python/tests/test_typesafe_provider.py -q --no-header`: 141 passed. - Ruff lint and format checks for `python/tests/test_typesafe_provider.py`: passed. - `git diff --check`: passed. The TypeScript E2E jobs also reported OpenAI 401 `invalid_organization` errors. Their CI credential issue remains unresolved by this test-only change.

Brendan O'Leary committed Nov 12, 2026 at 10:19 UTC 55d8924e2fef750aad6943261fed04daaca74a99
19 files changed +422 -64
.changeset/anthropic-tool-result-correlation.md new
+6
@@ -0,0 +1,6 @@
1 +---
2 +'@composio/python-sdk': patch
3 +'@composio/anthropic': patch
4 +---
5 +
6 +Preserve the originating `tool_use_id` in Python Anthropic tool results and retain session execution status, log IDs, and returned Instant charges in provider execution results. Clarify the TypeScript Anthropic helpers' existing result projection and message correlation in their API documentation.
python/README.md
+23
@@ -61,6 +61,29 @@ session = composio.use(session_id)
61
62 See [how Composio works](https://docs.composio.dev/docs/how-composio-works) for sessions and meta tools, and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting `toolkits`, `tools`, `auth_configs`, and `connected_accounts` on `composio.create()`.
63
64 +## Execution results
65 +
66 +Python session execution takes `tool_slug`, not the direct Tools API's `slug`:
67 +
68 +```python
69 +result = session.execute(
70 + tool_slug="COMPOSIO_SEARCH_TOOLS",
71 + arguments={"queries": [{"use_case": "find recent emails"}]},
72 +)
73 +if result.result_type == "completed":
74 + print(result.data)
75 +else: # "failed" or "blocked", even if error is empty
76 + print(result.result_type, result.error)
77 +```
78 +
79 +`session.execute` returns a Pydantic `ToolRouterSessionExecuteResponse` with `data`, `error`, `log_id`, and `result_type` attributes. Serialize it with `result.model_dump(mode="json")` or `result.model_dump_json()`. It has no `successful` key or model tool-call ID.
80 +
81 +In contrast, `composio.tools.execute(slug=..., arguments=..., user_id=...)` and `after_execute` modifiers use `ToolExecutionResponse` dictionaries: check `response["successful"]` and serialize with `json.dumps(response)`. Provider adapters for session execution derive that flag from `result_type == "completed"` and retain `result_type`, `log_id`, and any returned `instant_charge`. Modifiers receive `(tool, toolkit, response)` and must return the dictionary. Calling `session.execute` directly doesn't invoke callbacks supplied to `session.tools(modifiers=...)`.
82 +
83 +Provider helpers have provider-specific return contracts. The [Python Anthropic helper](providers/anthropic) returns execution dictionaries with `tool_use_id`; you still build and serialize Anthropic `tool_result` blocks yourself. Don't assume Python returns TypeScript-native message blocks.
84 +
85 +Transport/authentication errors and requests for user input can raise instead of returning a result. Keep authentication recovery separate from returned tool failures. A non-throwing call, empty `error`, or execution-log ID isn't proof of a provider-side action. Check the explicit outcome and tool-specific `data`; your application owns retry and idempotency decisions.
86 +
87 ## Use with an agent framework
88
89 Provider packages adapt `session.tools()` to your framework's native tool format. With [OpenAI Agents](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai_agents):
python/composio/core/models/_modifiers.py
+10
@@ -242,6 +242,16 @@ def after_execute(
242 tools: t.Optional[t.List[str]] = None,
243 toolkits: t.Optional[t.List[str]] = None,
244 ) -> Modifier | t.Callable[[AfterExecute], Modifier]:
245 + """Build an execution-result modifier.
246 +
247 + Your callback receives ``(tool, toolkit, response)`` and returns a
248 + ``ToolExecutionResponse`` dictionary. Check ``response["successful"]``,
249 + not the session model's ``result_type`` attribute. Session adapters
250 + retain ``log_id`` and ``result_type`` as dictionary keys. Serialize
251 + with ``json.dumps(response)`` if needed; it is not a provider message.
252 + Register this on tool execution or ``session.tools(modifiers=[...])``.
253 + Calling ``session.execute`` directly does not invoke it.
254 + """
255 if modifier is not None:
256 return Modifier(
257 modifier=modifier,
python/composio/core/models/tool_router_session.py
+14
@@ -1018,6 +1018,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1018 """
1019 Execute a tool within the session.
1020
1021 + Use ``tool_slug=...`` (not the direct Tools API's ``slug=...``) and
1022 + ``arguments={...}``. The return value is a Pydantic model: read
1023 + ``result.result_type == "completed"`` for execution success,
1024 + ``result.model_dump(mode="json")`` for a JSON-compatible dictionary,
1025 + or ``result.model_dump_json()`` for a JSON string. Unlike provider
1026 + helper results and ``after_execute`` modifier dictionaries, it has
1027 + no ``successful`` key. This call has no model tool-call ID; retain
1028 + that ID separately when building provider messages.
1029 +
1030 For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the
1031 original slug (e.g. "GREP") when that original slug is unique across
1032 the session's custom tools and toolkits. Custom tools are executed
@@ -1042,6 +1051,11 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1051 call (a session hook blocked it) has empty ``data``, the hook's message
1052 in ``error``, and ``block_reason`` (``type`` and ``hook_id``).
1053 ``hook_results`` lists every session hook that applied.
1054 + A log ID correlates an execution; it does not prove that a provider
1055 + performed a side effect. Inspect the tool-specific ``data`` as well.
1056 + Transport and authentication errors raise instead of returning an
1057 + execution result. Handle authentication recovery separately from
1058 + returned tool failures; retry/idempotency decisions belong to you.
1059
1060 :raises ToolInputRequiredError: If the tool needs input from the user
1061 (for example an approval) before it can run. Nothing was executed.
python/composio/core/models/tools.py
+28 -11
@@ -299,14 +299,41 @@ class InstantCharge(te.TypedDict):
299
300
301 class ToolExecutionResponse(te.TypedDict):
302 + """Dictionary returned by direct tools and provider execution adapters.
303 +
304 + Read ``successful``, not ``error`` or the presence of a log ID. Session
305 + adapters derive it from ``result_type == "completed"`` and retain the
306 + session's ``result_type`` and ``log_id``. This is not a provider message;
307 + serialize it with ``json.dumps`` when building message content.
308 + """
309 +
310 data: t.Dict
311 error: t.Optional[str]
312 successful: bool
313 + log_id: te.NotRequired[str]
314 + result_type: te.NotRequired[str]
315 instant_charge: te.NotRequired[InstantCharge]
316 """Present only when the Session sets
317 ``instant.return_instant_charge`` and a charge is available."""
318
319
320 +def tool_execution_response_from_session(
321 + response: ToolRouterSessionExecuteResponse,
322 +) -> ToolExecutionResponse:
323 + """Adapt a validated session result without losing its outcome or log ID."""
324 + result: ToolExecutionResponse = {
325 + "data": response.data if hasattr(response, "data") else {},
326 + "error": response.error if hasattr(response, "error") else None,
327 + "successful": is_execution_successful(response.result_type),
328 + "log_id": response.log_id,
329 + "result_type": t.cast(str, response.result_type),
330 + }
331 + instant_charge = getattr(response, "instant_charge", None)
332 + if isinstance(instant_charge, PydanticBaseModel):
333 + result["instant_charge"] = t.cast(InstantCharge, instant_charge.model_dump())
334 + return result
335 +
336 +
337 class Tools(Resource, t.Generic[TTool, TToolCollection]):
338 """
339 Tools class definition
@@ -760,17 +787,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
787 slug,
788 )
789
763 - # Convert response to standard format
764 - result: ToolExecutionResponse = {
765 - "data": response.data if hasattr(response, "data") else {},
766 - "error": response.error if hasattr(response, "error") else None,
767 - "successful": is_execution_successful(response.result_type),
768 - }
769 - instant_charge = getattr(response, "instant_charge", None)
770 - if isinstance(instant_charge, PydanticBaseModel):
771 - result["instant_charge"] = t.cast(
772 - InstantCharge, instant_charge.model_dump()
773 - )
790 + result = tool_execution_response_from_session(response)
791
792 # Apply after_execute modifiers
793 if modifiers is not None:
python/composio/core/provider/base.py
+2 -6
@@ -122,11 +122,7 @@ class BaseProvider(t.Generic[TTool, TToolCollection]):
122 )
123
124 # Imported here: the tools module imports this one.
125 - from composio.core.models.tools import is_execution_successful
125 + from composio.core.models.tools import tool_execution_response_from_session
126
127 result = target.execute(tool_slug=slug, arguments=arguments)
128 - return {
129 - "data": t.cast(t.Dict, result.data),
130 - "error": result.error,
131 - "successful": is_execution_successful(result.result_type),
132 - }
128 + return tool_execution_response_from_session(result)
python/providers/anthropic/README.md
+30 -4
@@ -40,14 +40,19 @@ response = client.messages.create(
40
41 # Agentic loop: keep executing tool calls until the model responds with text
42 while response.stop_reason == "tool_use":
43 - tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
43 + # Results retain each tool_use ID; Python still needs explicit content blocks.
44 results = composio.provider.handle_tool_calls(session=session, response=response)
45 messages.append({"role": "assistant", "content": response.content})
46 messages.append({
47 "role": "user",
48 "content": [
49 - {"type": "tool_result", "tool_use_id": tool_use_blocks[i].id, "content": json.dumps(result)}
50 - for i, result in enumerate(results)
49 + {
50 + "type": "tool_result",
51 + "tool_use_id": result["tool_use_id"],
52 + "content": json.dumps(result),
53 + "is_error": not result["successful"],
54 + }
55 + for result in results
56 ]
57 })
58 response = client.messages.create(
@@ -63,7 +68,28 @@ for block in response.content:
68 print(block.text)
69 ```
70
66 -`handle_tool_calls` extracts every `tool_use` block from the response, executes the matching Composio tools through the supplied session, and returns the raw results in order. Pass `user_id` instead for tools fetched with `tools.get()`. Claude occasionally emits tool input as a JSON string instead of an object; the provider normalizes this before execution.
71 +`handle_tool_calls` extracts every `tool_use` block, executes the matching Composio tools through the supplied session, and returns execution dictionaries in tool-use 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.
72 +
73 +## Execution contracts
74 +
75 +`execute_tool_call(session=session, tool_call=block)` returns one `AnthropicToolExecutionResponse`; `handle_tool_calls(session=session, response=response)` returns a list. Import both the provider and the response type from `composio_anthropic`.
76 +
77 +Each result contains `tool_use_id`, `data`, `error`, and `successful`. Session-backed results also retain `result_type`, `log_id`, and `instant_charge` when returned. Check `result["successful"]` explicitly. A failed execution can have an empty or `None` error, and a log ID is only for correlation.
78 +
79 +These are Python dictionaries, **not** Anthropic `tool_result` blocks. Serialize with `json.dumps(result)`, pair each block with `result["tool_use_id"]`, and set `is_error` from `not result["successful"]`, as above. Existing code that pairs the ordered results with the original `tool_use` blocks still works. TypeScript's `handleToolCalls` instead returns ready-to-append messages; don't use that contract in Python.
80 +
81 +On older provider releases without `tool_use_id`, keep pairing the ordered results with the original `tool_use` blocks, as in the web guide. The correlation field is additive; the helper still returns execution dictionaries rather than native messages.
82 +
83 +| Entry point | Arguments | Result and outcome check |
84 +| --- | --- | --- |
85 +| Python `session.execute` | `tool_slug=...`, `arguments={...}` | Pydantic model; `result.result_type == "completed"`. Use `model_dump(mode="json")` or `model_dump_json()` for serialization. No model call ID. |
86 +| Python `composio.tools.execute` | `slug=...`, `arguments={...}`, `user_id=...` | `ToolExecutionResponse` dictionary; `result["successful"]`. |
87 +| Python `after_execute` modifier | `(tool, toolkit, response)` | Receives and returns a `ToolExecutionResponse` dictionary; check `response["successful"]`, not an attribute. |
88 +| Python Anthropic helpers | `session=...` **or** `user_id=...`; `tool_call=...` or `response=...` | Correlated execution dictionaries; `result["successful"]`. |
89 +
90 +Session adapters derive `successful` from `result_type == "completed"`; `"failed"` and `"blocked"` are not successful. `session.execute` itself doesn't run `session.tools(modifiers=...)` callbacks. Direct-execution modifiers can't be passed alongside a session to a provider helper.
91 +
92 +Transport, authentication, and input errors can raise instead of returning a tool result. Handle credential/connection recovery separately from an ordinary returned failure. If a batch raises, earlier calls may already have executed. Don't replay the batch blindly. The execution status, an empty error, or a log ID alone doesn't establish a provider-side side effect; inspect the tool-specific `data`. Retry and idempotency policy stays in your application.
93
94 Building on the Claude Agent SDK instead of the Messages API? Use [`composio-claude-agent-sdk`](../claude_agent_sdk).
95
python/providers/anthropic/composio_anthropic/__init__.py
+5 -2
@@ -1,3 +1,6 @@
1 -from composio_anthropic.provider import AnthropicProvider
1 +from composio_anthropic.provider import (
2 + AnthropicProvider,
3 + AnthropicToolExecutionResponse,
4 +)
5
3 -__all__ = ("AnthropicProvider",)
6 +__all__ = ("AnthropicProvider", "AnthropicToolExecutionResponse")
python/providers/anthropic/composio_anthropic/provider.py
+36 -13
@@ -15,6 +15,18 @@ from composio.utils.shared import (
15 )
16
17
18 +class AnthropicToolExecutionResponse(ToolExecutionResponse):
19 + """Execution dictionary correlated with the originating Anthropic tool use.
20 +
21 + Not a ``tool_result`` block. Use ``tool_use_id`` for the block's ID,
22 + ``json.dumps(result)`` for its content, and ``not result["successful"]``
23 + for ``is_error``. Session execution also retains ``result_type``,
24 + ``log_id``, and any returned ``instant_charge``.
25 + """
26 +
27 + tool_use_id: str
28 +
29 +
30 class AnthropicProvider(
31 NonAgenticProvider[ToolParam, list[ToolParam]],
32 name="anthropic",
@@ -86,7 +98,7 @@ class AnthropicProvider(
98 user_id: str,
99 tool_call: ToolUseBlock,
100 modifiers: t.Optional[Modifiers] = None,
89 - ) -> ToolExecutionResponse: ...
101 + ) -> AnthropicToolExecutionResponse: ...
102
103 @t.overload
104 def execute_tool_call(
@@ -94,7 +106,7 @@ class AnthropicProvider(
106 *,
107 session: ToolCallSession,
108 tool_call: ToolUseBlock,
97 - ) -> ToolExecutionResponse: ...
109 + ) -> AnthropicToolExecutionResponse: ...
110
111 def execute_tool_call(
112 self,
@@ -103,15 +115,20 @@ class AnthropicProvider(
115 modifiers: t.Optional[Modifiers] = None,
116 *,
117 session: t.Optional[ToolCallSession] = None,
106 - ) -> ToolExecutionResponse:
118 + ) -> AnthropicToolExecutionResponse:
119 """
108 - Execute a tool call.
120 + Execute one tool use and retain its ID with the execution result.
121
122 :param user_id: User ID for direct tool execution.
123 :param session: Tool Router session that produced session tools.
124 :param tool_call: Tool call metadata.
125 :param modifiers: Modifiers to use for executing function calls.
114 - :return: Object containing output data from the tool call.
126 + :return: A dictionary with ``tool_use_id``, ``data``, ``error``, and
127 + ``successful``. Session calls also retain ``result_type``,
128 + ``log_id``, and any returned ``instant_charge``. Check
129 + ``successful`` explicitly, even if ``error`` is empty.
130 + Transport/auth/input exceptions propagate, rather than becoming
131 + returned tool failures.
132 """
133 if tool_call is None:
134 raise TypeError("tool_call is required")
@@ -124,12 +141,13 @@ class AnthropicProvider(
141 aliases = self._aliases.get(tool_call.name)
142 if aliases is not None:
143 arguments = aliases.restore_arguments(arguments)
127 - return self.execute_tool_for_target(
144 + result = self.execute_tool_for_target(
145 target=target,
146 slug=tool_call.name,
147 arguments=arguments,
148 modifiers=modifiers,
149 )
150 + return {**result, "tool_use_id": tool_call.id}
151
152 @t.overload
153 def handle_tool_calls(
@@ -137,7 +155,7 @@ class AnthropicProvider(
155 user_id: str,
156 response: t.Union[dict, ToolsBetaMessage],
157 modifiers: t.Optional[Modifiers] = None,
140 - ) -> t.List[ToolExecutionResponse]: ...
158 + ) -> t.List[AnthropicToolExecutionResponse]: ...
159
160 @t.overload
161 def handle_tool_calls(
@@ -145,7 +163,7 @@ class AnthropicProvider(
163 *,
164 session: ToolCallSession,
165 response: t.Union[dict, ToolsBetaMessage],
148 - ) -> t.List[ToolExecutionResponse]: ...
166 + ) -> t.List[AnthropicToolExecutionResponse]: ...
167
168 def handle_tool_calls(
169 self,
@@ -154,16 +172,21 @@ class AnthropicProvider(
172 modifiers: t.Optional[Modifiers] = None,
173 *,
174 session: t.Optional[ToolCallSession] = None,
157 - ) -> t.List[ToolExecutionResponse]:
175 + ) -> t.List[AnthropicToolExecutionResponse]:
176 """
177 Handle tool calls from Anthropic Claude chat completion object.
178
161 - :param response: Chat completion object from
162 - `anthropic.Anthropic.beta.tools.messages.create` function call.
179 + :param response: Message returned by ``anthropic.Anthropic.messages.create``.
180 :param user_id: User ID for direct tool execution.
181 :param session: Tool Router session that produced session tools.
182 :param modifiers: Modifiers to use for executing function calls.
166 - :return: A list of output objects from the tool calls.
183 + :return: Execution dictionaries in tool-use order, each retaining the
184 + matching ``tool_use_id``. These are not Anthropic content blocks.
185 + Build each block with ``type="tool_result"``, the result's
186 + ``tool_use_id``, ``content=json.dumps(result)``, and
187 + ``is_error=not result["successful"]``. Unlike the TypeScript
188 + helper, this method does not return ready-to-append messages.
189 + Exceptions stop the batch; earlier calls may already have run.
190 """
191 if response is None:
192 raise TypeError("response is required")
@@ -175,7 +198,7 @@ class AnthropicProvider(
198 if isinstance(response, dict):
199 response = ToolsBetaMessage(**response)
200
178 - outputs = []
201 + outputs: t.List[AnthropicToolExecutionResponse] = []
202 for content in response.content:
203 if isinstance(content, (ToolUseBlock, BetaToolUseBlock)):
204 result = (
python/providers/anthropic/tests/test_anthropic_provider.py
+117
@@ -1,8 +1,16 @@
1 """Tests for the Anthropic provider."""
2
3 +import json
4 from unittest.mock import MagicMock
5
6 +import httpx
7 +import pytest
8 +from anthropic.types import Message, ToolUseBlock
9 from composio_anthropic.provider import AnthropicProvider
10 +from composio_client import AuthenticationError, ProjectAuth
11 +
12 +from composio.client import HttpClient
13 +from composio.core.models.tool_router_session import ToolRouterSession
14
15
16 def _tool(slug="SEARCH_TOOL", description="Search for information"):
@@ -77,3 +85,112 @@ def test_wrap_tool_still_preserves_schema_and_metadata_with_caching_enabled():
85 assert wrapped["name"] == tool.slug
86 assert wrapped["description"] == tool.description
87 assert wrapped["input_schema"] == tool.input_parameters
88 +
89 +
90 +@pytest.mark.parametrize("target", ["session", "direct"])
91 +def test_tool_results_preserve_call_ids_and_explicit_outcomes(target):
92 + """Repeated tool names must remain correlated, even when failure has no error."""
93 + provider = AnthropicProvider()
94 + payloads = iter(
95 + [
96 + {
97 + "data": {"value": "found"},
98 + "error": None,
99 + "result_type": "completed",
100 + "log_id": "log-first",
101 + "instant_charge": {
102 + "amount": "0.01",
103 + "currency": "USD",
104 + "charged_by": "composio",
105 + },
106 + },
107 + {
108 + "data": {},
109 + "error": "",
110 + "result_type": "failed",
111 + "log_id": "log-second",
112 + },
113 + ]
114 + )
115 +
116 + def respond(request):
117 + return httpx.Response(200, json=next(payloads))
118 +
119 + message = Message(
120 + id="message",
121 + model="test",
122 + role="assistant",
123 + type="message",
124 + stop_reason="tool_use",
125 + usage={"input_tokens": 1, "output_tokens": 1},
126 + content=[
127 + {"type": "tool_use", "id": "use-first", "name": "SEARCH", "input": {}},
128 + {"type": "text", "text": "Checking another result."},
129 + {"type": "tool_use", "id": "use-second", "name": "SEARCH", "input": {}},
130 + ],
131 + )
132 + with HttpClient(
133 + provider="anthropic",
134 + auth=ProjectAuth("test-key"),
135 + base_url="https://backend.invalid",
136 + http_client=httpx.Client(transport=httpx.MockTransport(respond)),
137 + ) as client:
138 + session = ToolRouterSession(
139 + client=client,
140 + provider=provider,
141 + dangerously_allow_auto_upload_download_files=False,
142 + session_id="session",
143 + mcp=None,
144 + experimental={},
145 + )
146 + if target == "session":
147 + results = provider.handle_tool_calls(session=session, response=message)
148 + else:
149 + # Keep the real direct-result dictionary to check that adding correlation
150 + # doesn't mutate an executor's result (it may be shared with a modifier).
151 + direct_results = [
152 + {"data": {"value": "found"}, "error": None, "successful": True},
153 + {"data": {}, "error": "", "successful": False},
154 + ]
155 + pending = iter(direct_results)
156 + provider.set_execute_tool_fn(lambda *args, **kwargs: next(pending))
157 + results = provider.handle_tool_calls(user_id="user", response=message)
158 + assert all("tool_use_id" not in result for result in direct_results)
159 +
160 + assert [result["tool_use_id"] for result in results] == ["use-first", "use-second"]
161 + assert [result["successful"] for result in results] == [True, False]
162 + assert results[1]["error"] == ""
163 + if target == "session":
164 + assert [result["result_type"] for result in results] == ["completed", "failed"]
165 + assert [result["log_id"] for result in results] == ["log-first", "log-second"]
166 + assert json.loads(json.dumps(results[0]))["instant_charge"]["amount"] == "0.01"
167 + assert "instant_charge" not in results[1]
168 +
169 +
170 +def test_tool_call_does_not_turn_auth_failure_into_tool_failure():
171 + provider = AnthropicProvider()
172 +
173 + def respond(request):
174 + return httpx.Response(401, json={"message": "Invalid test credentials"})
175 +
176 + with HttpClient(
177 + provider="anthropic",
178 + auth=ProjectAuth("test-key"),
179 + base_url="https://backend.invalid",
180 + http_client=httpx.Client(transport=httpx.MockTransport(respond)),
181 + ) as client:
182 + session = ToolRouterSession(
183 + client=client,
184 + provider=provider,
185 + dangerously_allow_auto_upload_download_files=False,
186 + session_id="session",
187 + mcp=None,
188 + experimental={},
189 + )
190 + with pytest.raises(AuthenticationError):
191 + provider.execute_tool_call(
192 + session=session,
193 + tool_call=ToolUseBlock(
194 + type="tool_use", id="use-auth", name="SEARCH", input={}
195 + ),
196 + )
python/tests/test_google_provider.py
+16 -2
@@ -88,7 +88,15 @@ def test_handle_response_routes_function_calls_through_session() -> None:
88 tool_slug="COMPOSIO_SEARCH_TOOLS", arguments={"query": "send an email"}
89 )
90 provider.execute_tool.assert_not_called()
91 - assert results == [{"data": {"results": []}, "error": None, "successful": True}]
91 + assert results == [
92 + {
93 + "data": {"results": []},
94 + "error": None,
95 + "successful": True,
96 + "log_id": "log-session",
97 + "result_type": "completed",
98 + }
99 + ]
100
101
102 def test_handle_response_keeps_direct_user_id_execution() -> None:
@@ -122,7 +130,13 @@ def test_execute_tool_call_routes_through_session() -> None:
130 tool_slug="COMPOSIO_SEARCH_TOOLS", arguments={"query": "x"}
131 )
132 provider.execute_tool.assert_not_called()
125 - assert result == {"data": {"results": []}, "error": None, "successful": True}
133 + assert result == {
134 + "data": {"results": []},
135 + "error": None,
136 + "successful": True,
137 + "log_id": "log-session",
138 + "result_type": "completed",
139 + }
140
141
142 def test_handle_response_rejects_modifiers_with_session() -> None:
python/tests/test_provider.py
+17 -4
@@ -12,13 +12,12 @@ from types import SimpleNamespace
12 from unittest.mock import Mock, call
13
14 import pytest
15 +from pydantic import ValidationError
16
17 from composio.client.types import Tool, tool_list_response
18 from composio.core.models.base import allow_tracking
19 from composio.core.models.tools import Tools
20 from composio.core.provider import AgenticProvider, NonAgenticProvider
20 -from pydantic import ValidationError
21 -
21 from tests.conftest import mock_http_client
22 from tests.fixtures.json_schema_conversion_corpus import find_case
23
@@ -479,6 +478,8 @@ class TestNonAgenticProviderHelperMethods:
478 "data": {"tools": ["GMAIL_SEND_EMAIL"]},
479 "error": None,
480 "successful": True,
481 + "log_id": "log-session",
482 + "result_type": "completed",
483 }
484 ]
485
@@ -534,8 +535,20 @@ class TestNonAgenticProviderHelperMethods:
535 ]
536 mock_client.tools.execute.assert_not_called()
537 assert results == [
537 - {"data": {"index": 1}, "error": None, "successful": True},
538 - {"data": {"index": 2}, "error": "failed", "successful": False},
538 + {
539 + "data": {"index": 1},
540 + "error": None,
541 + "successful": True,
542 + "log_id": "log-1",
543 + "result_type": "completed",
544 + },
545 + {
546 + "data": {"index": 2},
547 + "error": "failed",
548 + "successful": False,
549 + "log_id": "log-2",
550 + "result_type": "failed",
551 + },
552 ]
553
554 def test_openai_responses_provider_propagates_session_exceptions(self):
python/tests/test_tool_router.py
+27 -13
@@ -32,7 +32,6 @@ from pydantic import BaseModel, Field
32 from composio.client import HttpClient
33 from composio.core.models.experimental import ExperimentalAPI
34 from composio.core.models.session_context import SessionContextImpl
35 -from composio.core.provider import get_execution_target
35 from composio.core.models.tool_router import (
36 SESSION_PRESET_DIRECT_TOOLS,
37 ToolkitConnectionsDetails,
@@ -53,6 +52,7 @@ from composio.core.models.tool_router_session import (
52 ToolRouterSessionMetaToolSlug,
53 ToolRouterSessionWithMcp,
54 )
55 +from composio.core.provider import get_execution_target
56 from composio.exceptions import (
57 ComposioDeprecationWarning,
58 InvalidParams,
@@ -2316,11 +2316,12 @@ class TestToolRouterExecution:
2316 self, tool_router, mock_client, mock_provider
2317 ):
2318 """Provider-wrapped session tools pass inline custom definitions."""
2319 - mock_execute_response = MagicMock()
2320 - mock_execute_response.data = {"result": "success"}
2321 - mock_execute_response.error = None
2322 - mock_execute_response.result_type = "completed"
2323 - mock_client.tool_router.session.execute.return_value = mock_execute_response
2319 + mock_client.tool_router.session.execute.return_value = SessionExecuteResponse(
2320 + data={"result": "success"},
2321 + error=None,
2322 + result_type="completed",
2323 + log_id="log-inline",
2324 + )
2325
2326 from composio.core.models.tools import Tools as RealTools
2327
@@ -2358,11 +2359,12 @@ class TestToolRouterExecution:
2359 self, tool_router, mock_client, mock_provider
2360 ):
2361 """Test that modifiers are applied before and after tool execution."""
2361 - mock_execute_response = MagicMock()
2362 - mock_execute_response.data = {"result": "success"}
2363 - mock_execute_response.error = None
2364 - mock_execute_response.result_type = "completed"
2365 - mock_client.tool_router.session.execute.return_value = mock_execute_response
2362 + mock_client.tool_router.session.execute.return_value = SessionExecuteResponse(
2363 + data={"result": "success"},
2364 + error=None,
2365 + result_type="completed",
2366 + log_id="log-modified",
2367 + )
2368
2369 # Create modifier functions
2370 def before_modifier(tool, toolkit, params):
@@ -3445,7 +3447,13 @@ class TestSessionExecutionSuccess:
3447 result = _session_tool_execute_fn(client)("GMAIL_SEND_EMAIL", {})
3448
3449 # The error is passed through as the API sent it.
3448 - assert result == {"data": {}, "error": error, "successful": successful}
3450 + assert result == {
3451 + "data": {},
3452 + "error": error,
3453 + "successful": successful,
3454 + "log_id": "log",
3455 + "result_type": result_type,
3456 + }
3457
3458 @pytest.mark.parametrize(("result_type", "error", "successful"), _EXECUTED_ANSWERS)
3459 def test_provider_tool_call_bound_to_a_session(
@@ -3459,7 +3467,13 @@ class TestSessionExecutionSuccess:
3467 target=_created_session(client), slug="GMAIL_SEND_EMAIL", arguments={}
3468 )
3469
3462 - assert result == {"data": {}, "error": error, "successful": successful}
3470 + assert result == {
3471 + "data": {},
3472 + "error": error,
3473 + "successful": successful,
3474 + "log_id": "log",
3475 + "result_type": result_type,
3476 + }
3477
3478 @pytest.mark.parametrize(("result_type", "error", "successful"), _EXECUTED_ANSWERS)
3479 def test_session_execute_exposes_result_type(self, result_type, error, successful):
python/tests/test_tool_schema_aliasing.py
+9 -2
@@ -20,7 +20,6 @@ from composio.utils.shared import (
20 substitute_reserved_python_keywords,
21 )
22
23 -
23 PYTHON_ROOT = Path(__file__).resolve().parents[1]
24 ANTHROPIC_PROPERTY_RE = re.compile(r"^[a-zA-Z0-9_.-]{1,64}$")
25
@@ -340,6 +339,7 @@ def test_anthropic_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
339 assert all(ANTHROPIC_PROPERTY_RE.fullmatch(name) for name in aliased_names)
340
341 tool_call = SimpleNamespace(
342 + id="use-odata",
343 name="TOOL_WITH_ODATA",
344 input={
345 "param_top": 10,
@@ -376,7 +376,14 @@ def test_anthropic_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
376 },
377 )
378 provider.execute_tool.assert_not_called()
379 - assert result == {"data": {"ok": True}, "error": None, "successful": True}
379 + assert result == {
380 + "data": {"ok": True},
381 + "error": None,
382 + "successful": True,
383 + "tool_use_id": "use-odata",
384 + "log_id": "log-session",
385 + "result_type": "completed",
386 + }
387
388
389 def test_claude_agent_sdk_wrap_tool_aliases_schema_and_restores_arguments(monkeypatch):
python/tests/test_type_inference_anthropic.py
+31 -3
@@ -20,11 +20,12 @@ from typing import TYPE_CHECKING
20 from composio import Composio
21
22 if TYPE_CHECKING:
23 - from typing_extensions import assert_type
24 -
23 + from anthropic.types import Message, ToolUseBlock
24 from anthropic.types.tool_param import ToolParam
25 + from composio_anthropic import AnthropicProvider, AnthropicToolExecutionResponse
26 + from typing_extensions import assert_type
27
27 - from composio_anthropic import AnthropicProvider
28 + from composio.core.models.tool_router_session import ToolRouterSession
29
30
31 def test_anthropic_provider_toolkits() -> None:
@@ -83,3 +84,30 @@ def test_anthropic_provider_inferred() -> None:
84
85 # Should infer list[ToolParam] from provider type
86 assert_type(tools, list[ToolParam])
87 +
88 +
89 +if TYPE_CHECKING:
90 +
91 + def check_anthropic_execution_results(
92 + provider: AnthropicProvider,
93 + session: ToolRouterSession,
94 + response: Message,
95 + tool_call: ToolUseBlock,
96 + ) -> None:
97 + """Both execution targets expose the same correlated dictionary contract."""
98 + assert_type(
99 + provider.execute_tool_call(session=session, tool_call=tool_call),
100 + AnthropicToolExecutionResponse,
101 + )
102 + assert_type(
103 + provider.execute_tool_call(user_id="test", tool_call=tool_call),
104 + AnthropicToolExecutionResponse,
105 + )
106 + assert_type(
107 + provider.handle_tool_calls(session=session, response=response),
108 + list[AnthropicToolExecutionResponse],
109 + )
110 + assert_type(
111 + provider.handle_tool_calls(user_id="test", response=response),
112 + list[AnthropicToolExecutionResponse],
113 + )
python/tests/test_typesafe_provider.py
+8 -2
@@ -1351,7 +1351,7 @@ class TestExecute:
1351 def test_executes_through_a_session_which_takes_no_modifiers(self) -> None:
1352 session = Mock()
1353 session.execute.return_value = Mock(
1354 - data={"ok": True}, error=None, result_type="completed"
1354 + data={"ok": True}, error=None, result_type="completed", log_id="log_123"
1355 )
1356 result = self.provider.execute(
1357 session=session, decision=PARTIAL, arguments={"body": "text"}
@@ -1359,7 +1359,13 @@ class TestExecute:
1359 session.execute.assert_called_once_with(
1360 tool_slug="ISSUES_CREATE", arguments={"priority": "low", "body": "text"}
1361 )
1362 - assert result == {"data": {"ok": True}, "error": None, "successful": True}
1362 + assert result == {
1363 + "data": {"ok": True},
1364 + "error": None,
1365 + "successful": True,
1366 + "log_id": "log_123",
1367 + "result_type": "completed",
1368 + }
1369 self.execute_tool.assert_not_called()
1370 with pytest.raises(ValueError, match="modifiers"):
1371 self.provider.execute( # type: ignore[call-overload]
ts/packages/core/README.md
+23
@@ -36,6 +36,29 @@ const session = await composio.use(sessionId);
36
37 See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.
38
39 +## Execution results
40 +
41 +`session.execute(toolSlug, arguments)` returns a plain `ToolRouterSessionExecuteResponse` object:
42 +
43 +```typescript
44 +const result = await session.execute('COMPOSIO_SEARCH_TOOLS', {
45 + queries: [{ use_case: 'find recent emails' }],
46 +});
47 +if (result.resultType === 'completed') {
48 + console.log(result.data);
49 +} else { // 'failed' or 'blocked', even if error is empty
50 + console.error(result.resultType, result.error);
51 +}
52 +```
53 +
54 +Read `resultType`, not `successful`, on a session result. It also includes `data`, `error`, and `logId`; serialize with `JSON.stringify(result)`. A direct session call has no model tool-call ID, so keep that ID separately when constructing provider messages.
55 +
56 +`composio.tools.execute(toolSlug, { arguments, userId })` and `afterExecute` modifiers instead use `ToolExecuteResponse` objects with a `successful` boolean. Check `result.successful` there. Session provider adapters derive it from `resultType === 'completed'`. An `afterExecute` modifier receives `{ toolSlug, toolkitSlug, result }` and returns the result. Calling `session.execute` directly doesn't run callbacks supplied to `session.tools()`.
57 +
58 +Transport/authentication errors and requests for user input can throw instead of returning a tool result. Handle authentication recovery separately from returned failures. A non-throwing call, empty error, or log ID isn't proof of a provider-side action. Check the explicit outcome and tool-specific `data`; retry and idempotency policy stays in your application.
59 +
60 +Provider helpers serialize differently. The Anthropic `executeToolCall` returns a JSON string; `handleToolCalls` returns correlated `user` messages containing `tool_result` blocks. These payload projections aren't the session/modifier outcome contract. See the provider package's execution contract before using a helper result to make application decisions.
61 +
62 ## Providers
63
64 A provider formats session tools for your agent framework and wires up execution:
ts/packages/providers/anthropic/README.md
+14
@@ -74,6 +74,20 @@ Building on the Claude Agent SDK instead? Use [`@composio/claude-agent-sdk`](../
74 - `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.
75 - Claude occasionally emits a tool's `input` as a JSON string instead of an object; the provider normalizes this before execution.
76
77 +## Execution contracts
78 +
79 +| Entry point | Arguments | Return value |
80 +| --- | --- | --- |
81 +| `session.execute` | `toolSlug`, `arguments` | Plain object with `resultType`, `data`, `error`, and `logId`. Check `result.resultType === 'completed'`; serialize with `JSON.stringify(result)`. |
82 +| `composio.tools.execute` | `toolSlug`, `{ arguments, userId }` | `ToolExecuteResponse`; check `result.successful`. |
83 +| `afterExecute` modifier | `{ toolSlug, toolkitSlug, result }` | Receives and returns `ToolExecuteResponse`; check `result.successful`. |
84 +| `executeToolCall` | `session, toolUse` or `userId, toolUse, options?, modifiers?` | JSON string: `data` when `error === null`, otherwise `{ error }`. |
85 +| `handleToolCalls` | `session, message` or `userId, message, options?, modifiers?` | `Anthropic.Messages.MessageParam[]`: a `user` message containing ordered `tool_result` blocks, or `[]` when there are no tool uses. |
86 +
87 +`handleToolCalls` sets each block's `tool_use_id` from the original `tool_use.id`. It doesn't include the full execution metadata or an `is_error` flag; its serialized content is **not** an explicit success discriminator. If your application needs to inspect execution outcomes, use `session.execute` or direct execution and retain the model call ID when building your own message blocks. Python's `handle_tool_calls` returns execution dictionaries instead of TypeScript-native messages.
88 +
89 +Session adapters derive `successful` from `resultType === 'completed'`. A failed execution can have an empty or `null` error. A log ID is for correlation, not proof of a provider-side side effect. Check the explicit status and tool-specific `data`. Transport/authentication errors can throw; handle authentication recovery separately from returned execution failures. A batch can stop after earlier calls have run, so don't blindly replay it. Retry and idempotency decisions remain yours.
90 +
91 ## Links
92
93 - [Anthropic provider docs](https://docs.composio.dev/docs/providers/anthropic)
ts/packages/providers/anthropic/src/index.ts
+6 -2
@@ -266,7 +266,9 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
266 * @param toolUse - The tool use object from Anthropic
267 * @param options - Additional options for tool execution
268 * @param modifiers - Modifiers for tool execution
269 - * @returns The result of the tool execution as a JSON string
269 + * @returns A JSON string: data when error is null, otherwise { error }. This
270 + * projection omits the execution status; use session.execute or direct
271 + * execution when application logic needs resultType or successful.
272 *
273 * @example
274 * ```typescript
@@ -337,7 +339,9 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
339 * @param message - The message response from Anthropic
340 * @param options - Additional options for tool execution
341 * @param modifiers - Modifiers for tool execution
340 - * @returns Array of tool execution results as JSON strings
342 + * @returns Ready-to-append user messages containing ordered tool_result blocks,
343 + * each correlated by tool_use_id. Content is the JSON projection returned by
344 + * executeToolCall, not a full execution response or a success discriminator.
345 *
346 * @example
347 * ```typescript