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.

Harden `composio run` subagent output and parallel discovery (#3051)

Rahul Tarak2a0d9552299c
diff --git a/ts/packages/cli/skills/composio-cli/SKILL.md b/ts/packages/cli/skills/composio-cli/SKILL.md
index 76ea8f013..2265dc423 100644
--- a/ts/packages/cli/skills/composio-cli/SKILL.md
+++ b/ts/packages/cli/skills/composio-cli/SKILL.md
@@ -8,9 +8,10 @@ description: Help users operate the published Composio CLI to find the right too
## Default Workflow
1. Start with `composio execute <slug>` whenever the slug is known.
-2. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.
-3. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.
-4. Reach for `composio search "<task>"` only when the slug is unknown.
+2. If several independent tool calls must happen at once, use `composio execute -p/--parallel` with repeated `<slug> -d <json>` groups.
+3. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.
+4. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.
+5. Reach for `composio search "<task>"` only when the slug is unknown. `search` accepts one or more queries, so batch related discovery work into a single command when useful.
## `execute` — Run A Tool
@@ -37,14 +38,24 @@ composio execute GITHUB_CREATE_AN_ISSUE -d @issue.json
cat issue.json | composio execute GITHUB_CREATE_AN_ISSUE -d -
```
+Run independent tool calls in parallel:
+
+```bash
+composio execute --parallel \
+ GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \
+ GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
+```
+
## `search` — Find The Slug
```bash
composio search "create a github issue"
composio search "send an email" --toolkits gmail
+composio search "send an email" "create a github issue"
+composio search "my emails" "my github issues" --toolkits gmail,github
```
-Read the returned slugs, choose the best match, and move back to `execute`.
+Use multiple quoted queries when the user is exploring more than one task or a small cross-app workflow. Read the returned slugs, choose the best match, and move back to `execute`.
## `link` — Connect An Account
@@ -81,6 +92,8 @@ composio run '
'
```
+Use top-level `execute --parallel` when the user just needs a few independent tool calls and does not need script logic, loops, or output plumbing.
+
Fan out with `Promise.all`:
```bash
@@ -106,7 +119,7 @@ composio run --logs-off '
'
```
-For more patterns — `proxy()` inside scripts, `search()` inside scripts, mixed `execute()` + `proxy()`, and `--dry-run`/`--debug` flags — load [references/power-user-examples.md](references/power-user-examples.md).
+For more patterns — multi-query top-level `search`, `proxy()` inside scripts, mixed `execute()` + `proxy()`, and `--dry-run`/`--debug` flags — load [references/power-user-examples.md](references/power-user-examples.md).
## Auth
diff --git a/ts/packages/cli/skills/composio-cli/references/power-user-examples.md b/ts/packages/cli/skills/composio-cli/references/power-user-examples.md
index 649fc03d5..690a30fce 100644
--- a/ts/packages/cli/skills/composio-cli/references/power-user-examples.md
+++ b/ts/packages/cli/skills/composio-cli/references/power-user-examples.md
@@ -20,6 +20,14 @@ composio run '
'
```
+If the user does not need script logic and just wants a few independent calls, prefer top-level parallel execute instead:
+
+```bash
+composio execute --parallel \
+ GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \
+ GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'
+```
+
## Use `Promise.all` To Fan Out
Fetch from multiple services at once:
@@ -58,6 +66,12 @@ composio run '
'
```
+Batch related discovery work with multiple queries when it keeps the workflow simpler:
+
+```bash
+composio search "send an email" "create a github issue" --toolkits gmail,github
+```
+
## Use `subAgent()` With `z` And `result.prompt()`
Turn a tool result into structured output:
diff --git a/ts/packages/cli/skills/composio-cli/references/troubleshooting.md b/ts/packages/cli/skills/composio-cli/references/troubleshooting.md
index 23bcba425..7d97fed87 100644
--- a/ts/packages/cli/skills/composio-cli/references/troubleshooting.md
+++ b/ts/packages/cli/skills/composio-cli/references/troubleshooting.md
@@ -66,9 +66,10 @@ Fix:
```bash
composio search "create a github issue"
composio search "send an email" --toolkits gmail
+composio search "send an email" "create a github issue"
```
-Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.
+Use multiple queries in one `search` call when the user is exploring several related tasks at once. Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.
## Confusion About Required Inputs
@@ -86,6 +87,23 @@ composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{
Use `composio tools info <slug>` only when the user wants a compact summary of a known slug and the `execute --get-schema` output is still not enough.
+## Several Independent Tool Calls
+
+Symptoms:
+
+- the user wants to run multiple unrelated tools in one step
+- the user is about to write a script only to execute a few independent calls
+
+Fix:
+
+```bash
+composio execute --parallel \
+ GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi" }' \
+ GITHUB_CREATE_AN_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
+```
+
+Escalate to `composio run` only when the user needs control flow, loops, `Promise.all`, `search()` inside a script, `proxy()`, or `subAgent()`.
+
## `tools info` And `tools list` Are Fallbacks
Treat these commands as secondary inspection tools: