@devries-cameron20 / composio Mirror · read-only / commits / c57cb42f7
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, 16:00 UTC

refactor(skills): make Composio guidance a generic router

Kshitij Jhunjhunwala committed Aug 7, 2026 at 17:22 UTC c57cb42f771992ff31f0f6e085f927b61eea784f
4 files changed +207 -155
skills/composio/SKILL.md
+43 -34
@@ -1,66 +1,75 @@
1 ---
2 name: composio
3 -description: Use when the user mentions Composio, wants to add Composio to an agent or codebase, wants an AI agent to act in real apps such as Gmail, Slack, GitHub, Notion, Calendar, or Linear, or needs help fixing a Composio setup, connection, or tool call.
3 +description: Route and complete Composio work across Composio For You and Composio Platform. Use when the user mentions Composio; wants an agent to use apps such as Gmail, Slack, GitHub, Notion, Calendar, or Linear; needs first-time setup, an SDK or MCP integration, CLI operation, migration guidance, current documentation, or help diagnosing a connection or tool call.
4 ---
5
6 # Composio
7
8 -Composio gives AI agents tools and authenticated access to external apps.
8 +Use this skill as a router. Identify the product and the job, load only the relevant guidance, consult canonical documentation for volatile details, and then answer or do the work the user requested.
9
10 -There are two products. They have different URLs, keys, and setup paths. Decide which one applies before doing anything else, and do not blend them.
10 +## 1. Choose the product
11 +
12 +Do not blend the products. They use different credentials and setup paths.
13
14 | | Composio For You | Composio Platform |
15 |---|---|---|
14 -| For | You want your agent to use your apps | You are building a product where your users connect their accounts |
15 -| Surface | An MCP server attached to an AI client | An SDK integrated into a codebase |
16 -| Key | `ck_...` consumer key | `COMPOSIO_API_KEY` project key |
16 +| Use when | Someone wants their own agent to use their own apps | A developer is building a product whose users connect accounts |
17 +| Primary surface | MCP or the Composio CLI | SDK sessions inside an application |
18 +| Credential | `ck_...` consumer key when the client requires a header | `COMPOSIO_API_KEY` project key |
19 | Dashboard | `dashboard.composio.dev` → For You | `dashboard.composio.dev` → Platform |
20
19 -## First decide the product
20 -
21 -Ask one question when the answer is not already clear:
22 -
23 -> Are you setting Composio up for yourself so your coding agent can use your apps, or are you building a product where your own users connect their accounts?
24 -
25 -Skip the question when context is sufficient:
21 +Ask one short question only when context does not establish the product:
22
27 -- The user names an AI client and is not building code → For You.
28 -- The user is inside a codebase or mentions users, tenants, `user_id`, an SDK, or an agent they are building → Platform.
23 +> Is this for your own agent and accounts, or for a product where your users connect their accounts?
24
30 -Read exactly one product guide. Do not read both.
25 +Treat a named personal AI client with no product code as For You. Treat an application codebase, SDK, user or tenant identity, backend, or product agent as Platform.
26
32 -### 1. Composio For You
27 +## 2. Choose the job
28
34 -Read [Composio For You](references/for-you.md).
29 +Identify the requested outcome before taking action:
30
36 -### 2. Composio Platform
31 +- **Explain or discover:** answer a question, compare approaches, or find the current API.
32 +- **Set up:** establish credentials, an MCP client, the CLI, or an SDK for the first time.
33 +- **Build or change:** integrate Composio into an existing agent or application.
34 +- **Operate:** find, connect, and run tools for a real task.
35 +- **Debug or migrate:** diagnose a failure, update an older integration, or move from legacy direct execution or Tool Router.
36
38 -Read [Composio Platform](references/platform.md).
37 +Do not turn an explanation, documentation lookup, or narrow bug fix into onboarding.
38
40 -### 3. Errors and provider failures
39 +## 3. Load only the relevant guidance
40
42 -For provider- and toolkit-level failures shared by both products, read [Errors and provider gotchas](references/errors.md).
41 +- For You: read [Composio For You](references/for-you.md).
42 +- Platform: read [Composio Platform](references/platform.md).
43 +- Provider, connection, or execution failure: also read [Errors and provider gotchas](references/errors.md).
44
44 -## Finish the work
45 +## Complete the selected job
46
46 -Install the dependency, write the configuration, and run the existing agent path. Setup is not complete until one safe, read-only real tool call returns an actual result and log ID.
47 +- For a question, fetch current documentation when needed and give the concrete answer. Do not mutate a project or force a tool call.
48 +- For setup or integration, inspect the existing environment, preserve its architecture and identity model, make the smallest useful change, and verify it with one safe real tool call when credentials and user authorization are available.
49 +- For an operational request, connect only the apps the task needs and execute the requested workflow.
50 +- For debugging, get the Composio log or request ID, identify the failing boundary, fix that boundary, and retry when the user authorized execution.
51
52 ## Stable rules
53
50 -1. Establish which product applies before setup.
51 -2. For Platform, use the existing project `COMPOSIO_API_KEY` from the repository's environment or secret mechanism. Platform onboarding never creates, rotates, or replaces a key and never asks the user to paste one into chat.
52 -3. Never invent a toolkit or tool slug. For Platform sessions, discover tools at runtime. For direct CLI work in the For You path, use `composio search` and inspect with `composio execute --get-schema`.
53 -4. Do not build an OAuth flow. Composio supplies a Connect Link when authentication is required.
54 -5. Use sessions for new Platform integrations. Preserve the application's existing user identity mapping and agent architecture.
55 -6. Keep credentials out of source control, URLs, logs, chat, and command output.
56 -7. Get the log ID before diagnosing a failed tool call.
54 +1. Establish the product before choosing credentials, URLs, SDKs, or commands.
55 +2. Treat dashboard onboarding as a context, not the skill's identity. When the developer arrives with an existing `COMPOSIO_API_KEY` from Getting Started, use it and never create, rotate, replace, print, or request it in chat. Do not run `composio dev init` in that path.
56 +3. For a general first-time Platform setup with no dashboard credential handoff, follow the current setup path in the Platform guide.
57 +4. Never invent toolkit or tool slugs. Discover them at runtime or with the CLI.
58 +5. Do not build a provider OAuth flow. Composio returns a Connect Link when authentication is needed.
59 +6. Use sessions for new Platform integrations. Preserve the application's existing user identity and agent architecture.
60 +7. Keep credentials out of source control, URLs, logs, chat, and command output.
61 +8. Get the log or request ID before diagnosing a failed tool call.
62 +9. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them.
63 +10. Do not invent repository facts. Never claim that a file, framework, environment loader, identity field, agent path, or dependency exists until it was provided or inspected. If codebase context is unavailable, state the unknown and ask for access or one necessary detail.
64
58 -## Fresh information
65 +## Canonical information
66
60 -When a detail is not covered by the selected guide, fetch the current markdown documentation and complete the work from it:
67 +Use bundled references for stable decisions. For versions, provider adapters, client-specific setup, toolkit behavior, or APIs that may have changed, fetch the current Markdown source before answering or editing code:
68
69 ```text
63 -https://docs.composio.dev/docs/<page>.md
70 https://docs.composio.dev/llms.txt
71 +https://docs.composio.dev/docs/<page>.md
72 https://docs.composio.dev/toolkits/<toolkit>.md
73 ```
74 +
75 +Use the documentation to complete the task. Do not merely hand the user a link unless they asked for one.
skills/composio/references/errors.md
+36 -25
@@ -1,12 +1,12 @@
1 # Errors and provider gotchas
2
3 -These rules apply to both Composio products.
3 +Use this guide for failures shared by Composio For You and Composio Platform. Keep product-specific credential and client setup in the selected product guide.
4
5 -## Start in Dashboard Logs
5 +## Start with evidence
6
7 -Open the applicable product's Dashboard Logs first and use the Composio log ID or request ID to inspect the exact execution. Framework wrappers often hide the underlying error.
7 +Get the Composio log or request ID and inspect Dashboard Logs before changing credentials or code. Agent frameworks often wrap the underlying provider error.
8
9 -CLI diagnostics are optional. Use them only when the CLI is already installed and configured for the applicable product:
9 +When the CLI is already installed and authenticated for the applicable product, these commands can provide additional evidence:
10
11 ```bash
12 composio dev logs tools
@@ -14,46 +14,57 @@ composio dev logs triggers
14 composio connections list
15 ```
16
17 -The dashboard Logs page provides the same execution trail.
17 +Do not install or reinitialize the CLI solely to diagnose a dashboard log that already contains the failure.
18
19 ## Tool does not exist
20
21 -Never guess the slug. In a Platform session, discover it through `COMPOSIO_SEARCH_TOOLS`. In a direct CLI workflow, use `composio search`, then inspect the result with `composio execute <slug> --get-schema`.
21 +Never guess a slug. In a Platform session, discover tools through the session meta tools. In a CLI workflow, use `composio search`, then inspect the returned tool.
22
23 -For manual legacy v3 execution, a missing tool is often a toolkit-version problem. Use a verified version or the v3.1 path that defaults to the current version. New session integrations should use runtime discovery instead of manually executing a guessed slug.
23 +For legacy manual execution, a missing tool may be a toolkit-version problem. Fetch current migration and execution docs rather than assuming the provider lacks the operation. New session integrations should use runtime discovery.
24
25 -## Authentication failures
25 +## Identify the authentication boundary
26
27 -Identify which boundary returned the 401 before changing anything.
27 +### Composio project or session 401
28
29 -### Composio API or session 401
29 +This happens before a provider tool call succeeds. The Platform project credential may be missing, masked, invalid, or associated with a different project.
30
31 -This failure happens while creating or using a session, before a provider tool call succeeds. The project credential may be invalid, masked, a placeholder, or for the wrong dashboard project.
31 +Re-run the no-output credential checks from the Platform guide. Do not print, rotate, replace, or request the key in chat. If the developer arrived from Dashboard Getting Started, direct them back to that project's Step 1 rather than running `composio dev init`.
32
33 -Stop and re-run the no-output `COMPOSIO_API_KEY` preflight from the Platform guide. Do not print, rotate, replace, or request the key in chat. Direct the developer to Platform → project → Getting Started → Step 1 when the repository does not have the correct unmasked project credential. The next SDK request, not key length, validates it over the network.
33 +### Provider connected-account 401
34
35 -### Provider tool-call 401
35 +This appears on a real tool execution after the project and session reached the provider. The selected user's provider token may be revoked, expired, or invalidated by a password, 2FA, consent, or administrator-policy change.
36
37 -This failure appears on a real tool execution in Dashboard Logs, usually with a Composio log ID. The Composio project credential and session reached the provider, but the selected user's connected-account credential was revoked, expired, or invalidated by a password, 2FA, consent, or administrator-policy change.
37 +Keep the same project key and application user ID. Generate a fresh Connect Link for that integration, reconnect the provider account, and retry the safe call. If a link expired, request a new one.
38
39 -Keep the same project key and user ID. Generate a fresh Connect Link for that integration, reconnect the account, and retry the safe read-only call. Do not replace the Composio project credential.
39 +### For You client authentication
40
41 -If an authorization link expired, request a new one. Do not reuse it.
41 +If the MCP client itself cannot authenticate, verify the consumer endpoint, OAuth session, or `ck_...` header path from the For You guide. Do not substitute a Platform project key.
42
43 -## Provider constraints
43 +## Common provider constraints
44
45 -- Google "App is blocked": remove unnecessary scopes or use a verified custom OAuth app.
46 -- Slack 429s: managed apps share a provider quota; use a custom Slack app for a dedicated rate-limit bucket.
47 -- Microsoft 403s: the tenant may require administrator consent.
48 -- GitHub Apps: OAuth credentials and repository installation are separate steps.
49 -- Session Restriction errors for payment tools are policy restrictions, not plan or connection failures.
45 +- **Google "App is blocked":** remove unnecessary scopes or use a verified custom OAuth app.
46 +- **Google API disabled:** enable the required provider API in the Google Cloud project that owns the custom credentials.
47 +- **Slack 429:** managed apps share provider quota; use a custom Slack app for a dedicated bucket when needed.
48 +- **Microsoft 403:** the tenant may require administrator consent.
49 +- **GitHub App access:** OAuth credentials and repository installation are separate steps.
50 +- **Payment toolkit session restriction:** treat it as a surface policy restriction, not a plan or connection failure.
51
51 -## Production
52 +## Branding and production auth
53
53 -Managed auth is intended to make initial development easy. Before launch, use custom OAuth apps for integrations that need the developer's branding, scopes, or dedicated quotas.
54 +Managed auth is intended to make initial development easy. Before launch, move integrations that require the application's branding, scopes, or dedicated quotas onto its own OAuth apps.
55
55 -For toolkit-specific details, fetch:
56 +When someone asks to remove Composio branding, identify the surface first: Connect Link page, provider consent screen, secured badge, callback domain, or success page. They have different fixes. Fetch `white-labeling-authentication.md` before proposing an implementation.
57 +
58 +## Triggers and webhooks
59 +
60 +Check the Composio status page and trigger logs before changing a trigger. Use current trigger documentation for event names, polling limits, and connection-state verification. Do not promise static outbound IPs; use documented webhook signature verification.
61 +
62 +## Canonical follow-up
63 +
64 +For provider- or toolkit-specific behavior, fetch:
65
66 ```text
67 https://docs.composio.dev/toolkits/<toolkit>.md
68 ```
69 +
70 +For APIs, migrations, triggers, or compliance questions, find the current page through `https://docs.composio.dev/llms.txt`. If the problem remains unresolved, include the log ID when escalating to Composio support.
skills/composio/references/for-you.md
+39 -18
@@ -1,45 +1,66 @@
1 # Composio For You
2
3 -Use this path when someone wants their own coding agent or AI client to use their own connected apps. This is an MCP setup, not an SDK integration.
3 +Use this product when someone wants their own AI client or terminal agent to use their own connected apps. Route by task: answer a question, configure an MCP client, operate through the CLI, connect an app, or debug an existing setup.
4
5 -## MCP endpoint
5 +## Stable product contract
6
7 -```text
8 -https://connect.composio.dev/mcp
9 -```
7 +- MCP endpoint: `https://connect.composio.dev/mcp`
8 +- Consumer key when a client needs a header: `ck_...`
9 +- Header name: `x-consumer-api-key`
10 +- Key location: Dashboard → For You → AI Clients → select the client
11 +
12 +The removed `mcp.composio.dev` endpoint and Platform MCP URLs are not substitutes. The `ck_...` key and Platform's `COMPOSIO_API_KEY` are not interchangeable.
13
11 -Do not use the removed `mcp.composio.dev` endpoint or a Platform MCP URL.
14 +## Choose MCP or CLI
15
13 -## Authentication
16 +Default to MCP for desktop and hosted AI clients. Use the CLI for terminal agents that can execute commands and operate tools directly.
17
15 -Claude Desktop and ChatGPT use browser OAuth. Header-based clients use the consumer key from Dashboard → For You → Settings → Sessions & API Key:
18 +### MCP clients
19 +
20 +Claude Desktop and ChatGPT use browser OAuth and do not need a consumer key. Header-based clients use the endpoint and header above.
21 +
22 +Client configuration changes over time. Before giving client-specific steps, fetch the current source of truth:
23
24 ```text
18 -x-consumer-api-key: ck_...
25 +https://docs.composio.dev/docs/composio-connect.md
26 ```
27
21 -The `ck_...` consumer key and Platform's `COMPOSIO_API_KEY` are not interchangeable.
28 +For any other MCP-capable client, configure HTTP transport with the endpoint and, when required, the `x-consumer-api-key` header. Keep credentials out of committed configuration.
29
23 -## Terminal coding agents
30 +### Terminal agents
31
25 -Terminal agents can use the Composio CLI directly:
32 +Install and authenticate the CLI only when the task needs it:
33
34 ```bash
35 curl -fsSL https://composio.dev/install | bash
36 composio login
37 +```
38 +
39 +For a real task:
40 +
41 +```bash
42 composio search "<what the user wants>"
43 composio link <toolkit>
44 composio execute <TOOL_SLUG> -d '{...}'
45 ```
46
35 -Use `composio login --no-wait | jq` when the agent cannot open a browser. Share the returned login URL, then complete login with the returned key.
47 +Use `composio login --no-wait | jq` when the agent cannot open a browser. Give the returned login URL to the user and complete authentication with the returned key. Once installed, prefer the bundled `composio-cli` skill for current command and flag details.
48 +
49 +## Connect apps when the task needs them
50 +
51 +Do not pre-connect every app. Start the requested task. When an integration is required, Composio returns an authorization link and the connection persists for future runs.
52 +
53 +For setup or an operational request, verify the selected path with one safe real call when authorization is available. For a question or configuration explanation, answer it without forcing execution.
54
37 -## Client configuration
55 +## Debugging
56
39 -For any MCP-capable client, configure HTTP transport with the endpoint above and, when required, the `x-consumer-api-key` header. Fetch `https://docs.composio.dev/docs/composio-connect.md` for current client-specific steps.
57 +First confirm that the client is connected to the correct MCP endpoint or that the CLI is authenticated. Then get the Composio log or request ID and read [Errors and provider gotchas](errors.md).
58
41 -## Connect apps naturally
59 +Common product-specific checks:
60
43 -Do not pre-connect every app. Start the real task. When an app is required, Composio returns an authorization link and the connection persists for future runs.
61 +- If MCP tools do not appear, confirm the connector is enabled, clear its cache when the client supports that, and reconnect it.
62 +- If browser OAuth repeatedly selects the wrong account, retry in a clean browser profile with one Composio account signed in.
63 +- If an authorization link expired, request a new link rather than reusing it.
64 +- If a connected app action returns an auth error, reconnect that app and retry without regenerating the consumer key.
65
45 -Setup is complete only after one real tool call succeeds.
66 +Manage connections in Dashboard → For You → Connect Apps. Manage consumer keys and MCP or CLI sessions in Settings → Sessions & API Key.
skills/composio/references/platform.md
+89 -78
@@ -1,62 +1,81 @@
1 # Composio Platform
2
3 -Use this path when the developer is adding Composio to an agent, application, or backend where their users connect accounts.
3 +Use this product when a developer is building an agent, application, or backend whose users connect their own accounts. Route by task instead of assuming every request is onboarding.
4
5 -The goal is not to complete a canned task. The goal is to make Composio the tool and authentication layer inside the developer's existing system, then prove the integration with one real tool call.
5 +## Contents
6
7 -## 1. Inspect the codebase first
7 +1. [Choose the task](#choose-the-task)
8 +2. [Establish project access](#establish-project-access)
9 +3. [Integrate sessions](#integrate-sessions)
10 +4. [Choose tools and authentication behavior](#choose-tools-and-authentication-behavior)
11 +5. [Handle advanced product work](#handle-advanced-product-work)
12 +6. [Verify setup when relevant](#verify-setup-when-relevant)
13 +7. [Use canonical documentation](#use-canonical-documentation)
14
9 -Before choosing packages or generating files, identify:
15 +## Choose the task
16
11 -- The package manager and language.
12 -- The existing agent or LLM framework.
13 -- The current user or tenant identifier.
14 -- Where environment variables are loaded.
15 -- The smallest existing execution path where Composio tools belong.
17 +- **Explain or discover:** answer from this guide and current documentation without changing code.
18 +- **First-time setup:** establish project access and the smallest working SDK path.
19 +- **Integrate or extend:** inspect the codebase and add Composio to the existing agent architecture.
20 +- **Operate:** discover, authorize, and execute tools for the application's current user.
21 +- **Debug or migrate:** inspect the log ID and current implementation before changing credentials or architecture.
22
17 -Extend the existing architecture. Do not create a separate demo agent when the repository already has one.
23 +When modifying code, first inspect and identify the language, package manager, agent or LLM framework, stable user or tenant ID, secret-loading mechanism, and smallest existing execution path where Composio tools belong. Extend that path; do not create a parallel demo agent when one already exists. Never infer filenames, framework choices, environment behavior, or identity fields that were not provided or observed.
24
19 -## 2. Require the existing project credential
25 +Use progressive disclosure. The basic path is project access, the core SDK, one user-scoped session, and the existing agent's tool interface. Do not add toolkit filters, tag policies, sandbox changes, custom auth, provider adapters, or production hardening unless the request or inspected code requires them. If essential repository context is missing, give the minimum stable outline and ask only for the missing detail instead of filling a large example with placeholders.
26
21 -The dashboard Getting Started Step 1 supplies the one project credential as `COMPOSIO_API_KEY=ak_*`. Use that credential from `.env.local`, the current process environment, or the repository's existing secret mechanism.
27 +## Establish project access
28
23 -Platform onboarding never creates, rotates, or replaces an API key. Never print the value, place it in a command or URL, copy it to another file unnecessarily, or ask the developer to paste it into chat. The key already identifies the dashboard project; do not select or bind a project separately.
29 +Choose exactly one credential path from context.
30
25 -Complete this preflight before installing packages or changing application code:
31 +### Existing dashboard or repository credential
32
27 -1. Find how the repository already loads environment variables or secrets.
28 -2. Check for `COMPOSIO_API_KEY` without opening, echoing, or logging the value.
29 -3. Require the value to begin with `ak_`.
30 -4. Reject values containing `*`, mask glyphs, ellipses, angle-bracket templates, or placeholder words such as `example`, `placeholder`, `replace`, or `your_key`.
31 -5. When the credential is in a file, verify that the containing file is ignored by source control. Check the path only; never print the matching line.
33 +If `COMPOSIO_API_KEY` already exists, or the developer arrived from Dashboard Getting Started after copying an `ak_*` project key, use that credential from the repository's existing environment or secret mechanism.
34
33 -These checks catch missing, masked, or placeholder values. They do not prove that a key is authentic, and key length is not validation. The first SDK request is the network validation.
35 +In this path:
36
35 -If the credential is missing, masked, placeholder-like, or stored in a tracked file, hard stop before package installation or app-code changes. Direct the developer to Platform → project → Getting Started → Step 1, then resume only after the repository's normal secret-loading path supplies an unmasked value. Do not accept the key through chat.
37 +- Never run `composio dev init` or select another project.
38 +- Never create, rotate, replace, print, echo, log, or request the key in chat.
39 +- Check only whether the environment variable exists and is not visibly masked or placeholder-like.
40 +- When it lives in a file, check that the file is ignored by source control without printing the matching line.
41 +- Let the first SDK request validate the credential; length is not validation.
42
37 -## 3. Install only what the codebase needs
43 +If the dashboard handoff is missing or masked, direct the developer back to Platform → project → Getting Started → Step 1. Do not silently switch to a provisioning flow.
44
39 -TypeScript:
45 +### General first-time setup
46 +
47 +If there is no existing project credential and no dashboard handoff, use the current first-time setup path:
48
49 ```bash
42 -npm install @composio/core
50 +curl -fsSL https://composio.dev/install | bash
51 +composio login
52 +composio dev init
53 ```
54
45 -Python:
55 +`composio dev init` writes `COMPOSIO_API_KEY` and `COMPOSIO_TEST_USER_ID` to `.env.local`. Python dotenv does not load `.env.local` by default, so pass the path explicitly or move the variables through the project's normal secret mechanism. There is no bare `composio init` command.
56 +
57 +Verification stamp: these commands were exercised against CLI 0.2.32 and 0.3.1 on 2026-08-06. If the installed version differs or behavior conflicts, check `composio dev --help` and current docs rather than forcing the stamped behavior.
58 +
59 +### Install the SDK the codebase needs
60
61 ```bash
62 +npm install @composio/core
63 pip install composio
64 ```
65
51 -Add a provider package only when the repository's framework requires one, for example `@composio/vercel`, `@composio/openai-agents`, `@composio/mastra`, `@composio/anthropic`, `composio-openai-agents`, or `composio-langchain`.
66 +Add a provider adapter only when the existing framework needs one. Fetch the current provider index before naming a package:
67
53 -Do not introduce a second LLM framework solely for onboarding.
68 +```text
69 +https://docs.composio.dev/docs/providers.md
70 +```
71
55 -## 4. Preserve the current user identity
72 +Do not introduce another LLM framework solely to demonstrate Composio.
73
57 -A session is the runtime context for one user. It carries identity, connections, tool scope, and the remote sandbox.
74 +## Integrate sessions
75
59 -Trace the application's current authenticated user or tenant ID before creating a session. Pass that same stable ID to Composio. Do not add a parallel user system, replace an existing session model, or use one shared placeholder identity for multiple users.
76 +A session is the runtime context for one application user. It carries identity, connections, tool scope, and sandbox configuration.
77 +
78 +Trace the application's existing authenticated user or tenant ID and use that stable identifier. Do not add a parallel user system or share one placeholder identity across users.
79
80 TypeScript:
81
@@ -64,7 +83,7 @@ TypeScript:
83 import { Composio } from "@composio/core";
84
85 const composio = new Composio();
67 -const session = await composio.sessions.create(existingUserId);
86 +const session = await composio.create(existingUserId);
87 const tools = await session.tools();
88 ```
89
@@ -74,29 +93,19 @@ Python:
93 from composio import Composio
94
95 composio = Composio()
77 -session = composio.sessions.create(user_id=existing_user_id)
96 +session = composio.create(user_id=existing_user_id)
97 tools = session.tools()
98 ```
99
81 -Do not pass the API key inline. The SDK reads the existing `COMPOSIO_API_KEY`. If this first SDK request returns a Composio API/session 401, stop and follow [Errors and provider gotchas](errors.md); do not modify packages or application code to work around it.
100 +Both SDKs also expose `composio.sessions.create(...)`; do not teach an artificial TypeScript/Python asymmetry. The SDK reads `COMPOSIO_API_KEY` from the environment, so do not pass it inline.
101
83 -Create a session for an agentic run. For a multi-turn conversation, persist the returned session ID and resume it instead of creating a fresh session on every message:
102 +For a multi-turn conversation, persist the returned session ID and resume it instead of creating a fresh session on every message. Confirm current method names against `configuring-sessions.md` before writing production code.
103
85 -```typescript
86 -const sessionId = session.sessionId;
87 -const resumedSession = await composio.use(sessionId);
88 -```
89 -
90 -```python
91 -session_id = session.session_id
92 -resumed_session = composio.use(session_id)
93 -```
94 -
95 -## 5. Put Composio into the existing agent
104 +Pass the session tools to the repository's existing model or agent using its native tool integration. Preserve the current prompt, model, streaming, and request lifecycle unless tools require a targeted change.
105
97 -Pass the session tools to the repository's existing agent or model provider using its native tool integration. Preserve the current prompt, model, streaming, and request lifecycle unless a change is required for tools to execute.
106 +## Choose tools and authentication behavior
107
99 -Sessions expose a small set of meta tools by default. The agent discovers the right integration and tool at runtime rather than loading thousands of schemas into context:
108 +Sessions expose a small set of meta tools by default so the agent can discover integrations and authenticate at runtime:
109
110 - `COMPOSIO_SEARCH_TOOLS`
111 - `COMPOSIO_GET_TOOL_SCHEMAS`
@@ -106,50 +115,52 @@ Sessions expose a small set of meta tools by default. The agent discovers the ri
115 - `COMPOSIO_REMOTE_WORKBENCH`
116 - `COMPOSIO_REMOTE_BASH_TOOL`
117
109 -Keep connection management enabled for interactive agents. It is what returns a Connect Link when a user needs to authenticate an app.
118 +Keep connection management enabled for interactive agents. It returns a Connect Link when a user needs to authorize an app; do not build a provider OAuth flow.
119
111 -## 6. Prove it with a real call
120 +Use the direct-tools preset only for a narrow, deterministic agent with a fixed allowlist. It removes meta tools by default. Re-enable connection management when users must authenticate in the agent, and keep or disable the sandbox deliberately. Fetch `configuring-sessions.md` for the current preset and option syntax before implementing it.
121
113 -Setup is incomplete until a programmatic tool call succeeds from the developer's repository.
122 +If the application has its own connect UI, use session authorization and connection-state methods and suppress in-chat connection prompts. Use managed auth initially. Create a custom auth config only for the application's OAuth branding, additional scopes, dedicated provider quotas, or self-hosted or regional requirements.
123
115 -For onboarding:
124 +## Handle advanced product work
125
117 -1. Use the installed Composio skill and the existing agent path.
118 -2. Ask the developer which integration they want to try unless the repository already makes the choice clear.
119 -3. Let the session discover the actual toolkit and tool slug for that integration; never hard-code or guess one.
120 -4. If the integration is not connected for the existing user ID, return the Connect Link, wait for authorization, and retry.
121 -5. Execute one safe, read-only tool through the existing agent.
122 -6. Require a real result payload and a non-empty `logId` (`log_id` in Python).
126 +Do not force advanced requests through first-time setup. Route them to current documentation:
127
124 -The proof must hit Composio and the selected provider. A mock, Playground call, tool search, schema fetch, session creation, or Connect Link alone does not count as success.
128 +- Session scoping, account selection, callbacks, direct tools, and sandbox controls: `configuring-sessions.md`
129 +- Custom connection UI: `manually-authenticating.md`
130 +- Triggers and webhooks: `triggers.md` and the setting-up-triggers guides
131 +- Custom MCP servers, tools, toolkits, or proxy execution: the `extending-sessions` guides
132 +- Legacy direct execution, MCP servers, or Tool Router migrations: the migration and sessions guides
133 +- White labeling and custom OAuth apps: `white-labeling-authentication.md`
134
126 -If the repository has no runnable agent loop, add the smallest test entrypoint compatible with its existing LLM provider. Do not require a new hosted model solely for onboarding.
135 +"Tool Router" is the former name for sessions. Treat direct execution as a migration path, not the default for new agent integrations.
136
128 -## 7. Authentication happens when needed
137 +## Verify setup when relevant
138
130 -Do not build OAuth. If a selected app is not connected, `COMPOSIO_MANAGE_CONNECTIONS` returns a Connect Link, the user authorizes in the browser, and the agent retries.
139 +For a first-time setup or integration request, success means a programmatic, safe, read-only tool call from the developer's real execution path returns an actual provider result and a non-empty Composio log ID.
140
132 -Start with managed auth. A custom auth config is needed only for custom branding, additional scopes, dedicated provider quotas, or self-hosted/regional requirements.
141 +Ask which integration the developer wants to try unless the application already makes the choice clear. Discover the real toolkit and tool at runtime. If the current user is not connected, return the Connect Link, wait for authorization, and retry.
142
134 -## 8. Hand off the useful next steps
143 +A mock, Playground run, tool search, schema fetch, session creation, or Connect Link alone does not prove the integration. If the repository has no runnable agent loop, add only the smallest entrypoint compatible with its existing provider; do not require another hosted model.
144
136 -After the first call succeeds, report:
145 +After success, report the code location, identity and session mapping, integration and tool, safe result summary, log ID, and useful dashboard destinations. For an explanation, migration plan, or narrow bug fix, use that task's own completion condition instead of forcing a new tool call.
146
138 -- Where Composio was added in the existing codebase.
139 -- Which existing application identity supplies Composio's `userId`, and how the resulting session ID is persisted or resumed.
140 -- The integration and exact read-only tool used.
141 -- A safe summary of the actual result and the Composio log ID.
142 -- Where to continue: Platform dashboard → Logs for the request/response, Users for identity and connections, and Toolkits for integrations.
147 +## Use canonical documentation
148
144 -Link the developer to the relevant framework guide from `https://docs.composio.dev/docs/providers` and the selected integration guide at `https://docs.composio.dev/toolkits/<toolkit>`.
149 +Fetch current Markdown before giving version-sensitive commands or editing SDK integration code:
150
146 -## Do not
151 +```text
152 +https://docs.composio.dev/llms.txt
153 +https://docs.composio.dev/docs/<page>.md
154 +https://docs.composio.dev/toolkits/<toolkit>.md
155 +```
156
148 -- Do not stop after linking documentation.
149 -- Do not substitute a canned integration task for the developer's choice or repository context.
150 -- Do not create an auth config as a prerequisite.
151 -- Do not guess tool or toolkit slugs.
152 -- Do not use direct execution for a new agent integration.
153 -- Do not claim success before a real programmatic tool call returns a result and log ID.
157 +Read [Errors and provider gotchas](errors.md) for failures shared across products.
158 +
159 +## Do not
160
155 -Current documentation index: `https://docs.composio.dev/llms.txt`.
161 +- Do not replace a dashboard-provided credential with a general setup flow.
162 +- Do not stop at documentation when the user asked for implementation.
163 +- Do not guess toolkit or tool slugs.
164 +- Do not create auth configs as a universal prerequisite.
165 +- Do not replace the application's identity model or agent architecture.
166 +- Do not claim an integration works before the requested proof succeeds.