@devries-cameron20 / composio Mirror · read-only / commits / 887d3527a
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, 08:30 UTC

docs: clarify session.execute result shape and success checks (#4978)

## Summary Clarify the current `session.execute()` result contract in the canonical session guide so integrations do not confuse session results with direct execution results or tool-specific payloads. Source: Gauge action `cmtw6ww2z00460itkggry6bsy`, [underlying run](https://agents.withgauge.com/composio-aclx/runs/cmtvyjvhx000201j6zask5h9f). The run used `@composio/core@0.18.1` and hit a type error after assuming a top-level `successful` field. Its workaround is not the current contract: current sessions expose `resultType` (`result_type` in Python), which is authoritative even when `error` is null or empty. A nested `data.successful` field is tool-specific, not guaranteed. ## Changes - Add explicit Python and TypeScript failure handling to the existing session execution examples, with log IDs in fallback errors. - Document `data`, `error`, `logId`/`log_id`, and `resultType`/`result_type`, plus optional Instant charge reporting. - Distinguish the session envelope from direct execution results and tool payloads; explicitly warn against a general `result.data.successful` check. - Keep existing input-required exception guidance and provider requirements intact. Only `docs/content/docs/how-composio-works.mdx` changes. SDK reference pages are generated and are intentionally not hand-edited. No runtime changes or Changeset. ## Type of change - [x] Documentation ## How Has This Been Tested? From `docs/`, after synchronizing the local dependency tree with `bun install --frozen-lockfile`: - `bun run build` passed, including Twoslash checking of the TypeScript example. - `bun run test`: 732 passed, 0 failed. - `bun run lint` passed with existing warnings in unrelated files. - `bun run types:check` passed. - `bun run lint:links` passed: 0 errors, including SDK links. - `bun run check:kb-semantic --allow-stale` passed with the expected stale-content-hash warning; search falls back to keyword results until the existing rebuild workflow refreshes the artifact. - Opened `/docs/how-composio-works` in Chromium and visually checked the result table and both Python/TypeScript examples. Inspected `/docs/how-composio-works.md` for the same guidance. - Executed the exact edited Python and TypeScript example bodies against three deterministic response fixtures: completed without a nested success flag, failed with a null error, and failed with an empty error plus misleading `data.successful: true`. All six cases passed. The TypeScript fixtures went through the real SDK response transformer and schema. No permanent tests added: this is a docs-only clarification of an existing contract. The example smoke checks were throwaway scripts and made no external tool calls. The first build attempt exposed stale/missing local dependencies, including a pre-resultType SDK and missing icon package. Installing the existing lockfile resolved those failures without dependency or lockfile changes. ## Checklist - [x] Reviewed the change and verified the documented contract against SDK source. - [x] No new third-party documentation links. - [x] Updated documentation and exercised the changed examples. - [x] No Changeset needed for a docs-only change. ## Additional context The original Gauge recommendation to universally check `data.successful` should not be applied to the current SDK. This PR documents `resultType` instead. Please review the full diff before merging.

Brendan O'Leary committed Oct 20, 2026 at 08:23 UTC 887d3527a6081181a82ed049d04159296499043d
1 file changed +29 -1
docs/content/docs/how-composio-works.mdx
+29 -1
@@ -113,6 +113,11 @@ When your model asks to call a session tool, execute it with `session.execute()`
113 <Tab value="Python">
114 ```python
115 result = session.execute("COMPOSIO_SEARCH_TOOLS", arguments={"queries": [{"use_case": "send an email"}]})
116 +
117 +if result.result_type == "failed":
118 + raise RuntimeError(result.error or f"Tool execution failed (log ID: {result.log_id})")
119 +
120 +print(result.data)
121 ```
122 </Tab>
123 <Tab value="TypeScript">
@@ -122,13 +127,36 @@ const composio = new Composio({ apiKey: 'your_api_key' });
127 const session = await composio.create("user_123");
128 // ---cut---
129 const result = await session.execute("COMPOSIO_SEARCH_TOOLS", { queries: [{ use_case: "send an email" }] });
130 +
131 +if (result.resultType === 'failed') {
132 + throw new Error(result.error || `Tool execution failed (log ID: ${result.logId})`);
133 +}
134 +
135 +console.log(result.data);
136 ```
137 </Tab>
138 </Tabs>
139
140 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.
141
131 -Read `result.result_type` in Python or `result.resultType` in TypeScript to distinguish `completed` from `failed`. A failed execution can have an empty `error`, so checking `error` alone doesn't tell you whether the tool succeeded. If you pass a custom TypeScript `ToolCallSession` to a provider, its `execute()` method must return `resultType`; providers use it to determine `successful`.
142 +#### Reading execution results
143 +
144 +`session.execute()` returns a result envelope, not the tool payload directly:
145 +
146 +| TypeScript | Python | Meaning |
147 +| --- | --- | --- |
148 +| `data` | `data` | The tool-specific output. |
149 +| `error` | `error` | Error text, or `null` (`None` in Python). A failed execution can have no error text. |
150 +| `logId` | `log_id` | The execution log ID. Local custom tools return an empty string. |
151 +| `resultType` | `result_type` | `completed` if execution succeeded, or `failed` if it failed. |
152 +
153 +The result can also include `instantCharge` (`instant_charge` in Python) when you enable [Instant usage charge reporting](/docs/instant-tools#report-charges-and-use-instant-tools).
154 +
155 +Use `resultType` (`result_type` in Python) to check success, as shown above. Checking `error` alone can mistake a failed execution with an empty error for a success.
156 +
157 +Unlike direct `composio.tools.execute()` results, session results have no top-level `successful` field. A `successful` field inside `data` belongs to the tool-specific payload and is not guaranteed. Don't use `result.data.successful` as a general session success check.
158 +
159 +If you pass a custom TypeScript `ToolCallSession` to a provider, its `execute()` method must return `resultType`; providers use it to determine `successful`.
160
161 #### Handling requests for user input
162