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

docs: add product architecture guides

Soham Basu committed Aug 28, 2026 at 14:24 UTC e2976a65ff3a9c390a871717a078a30e50f7b3e5
9 files changed +435 -6
docs/content/docs/authentication/programmatic-auth-configs.mdx
+3 -3
@@ -48,7 +48,7 @@ console.log(authConfig.id); // ac_xxxxxxxx
48 Bring your own OAuth app to show your branding on consent screens, request custom scopes, or get a dedicated rate-limit quota. Register the app in the provider's developer portal, set its authorized redirect URI to Composio's callback, then pass the client ID and secret.
49
50 ```
51 -https://backend.composio.dev/api/v1/auth-apps/add
51 +https://backend.composio.dev/api/v3/toolkits/auth/callback
52 ```
53
54 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
@@ -68,7 +68,7 @@ auth_config = composio.auth_configs.create(
68 "credentials": {
69 "client_id": os.environ["NOTION_CLIENT_ID"],
70 "client_secret": os.environ["NOTION_CLIENT_SECRET"],
71 - "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add",
71 + "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",
72 },
73 },
74 )
@@ -87,7 +87,7 @@ const authConfig = await composio.authConfigs.create('notion', {
87 credentials: {
88 client_id: process.env.NOTION_CLIENT_ID!,
89 client_secret: process.env.NOTION_CLIENT_SECRET!,
90 - oauth_redirect_uri: 'https://backend.composio.dev/api/v1/auth-apps/add',
90 + oauth_redirect_uri: 'https://backend.composio.dev/api/v3/toolkits/auth/callback',
91 },
92 });
93 ```
docs/content/docs/authentication/white-labeling-authentication.mdx
+44 -3
@@ -13,6 +13,17 @@ There are four places where Composio branding shows up during authentication:
13 | [**Browser address bar**](#routing-the-callback-through-your-domain) | `backend.composio.dev` flashes during OAuth redirect-back | Proxy the redirect through your domain |
14 | [**Post-auth success page**](#redirecting-users-after-authentication) | Composio-branded success page after OAuth completes | Pass a `callbackUrl` when initiating the connection |
15
16 +## Start with the smallest setup
17 +
18 +You do not need every option to launch a branded connection flow. Apply only the layers your users will see:
19 +
20 +1. Set your app title, logo, and theme for the hosted Connect Link.
21 +2. Add your own OAuth app only for toolkits where the provider consent screen must show your brand.
22 +3. Add a redirect proxy only when the browser must stay on your domain during the OAuth callback.
23 +4. Pass a `callbackUrl` when users should return directly to your product after connecting.
24 +
25 +Start with Connect Link branding, then test the complete flow for one representative OAuth toolkit. Add the other layers only if that test exposes Composio branding you need to remove.
26 +
27 ## Customizing the Connect Link
28
29 The Connect Link is the hosted page your users see when connecting their accounts. By default it shows Composio branding on a neutral light theme. You can swap in your logo and name, then restyle the whole page to match your product.
@@ -107,7 +118,7 @@ app = FastAPI()
118
119 @app.get("/api/composio-redirect")
120 def composio_redirect(request: Request):
110 - composio_url = "https://backend.composio.dev/api/v1/auth-apps/add"
121 + composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
122 return RedirectResponse(url=f"{composio_url}?{request.url.query}")
123 ```
124 </Tab>
@@ -117,7 +128,7 @@ def composio_redirect(request: Request):
128 import type { NextApiRequest, NextApiResponse } from "next";
129
130 export default function handler(req: NextApiRequest, res: NextApiResponse) {
120 - const composioUrl = "https://backend.composio.dev/api/v1/auth-apps/add";
131 + const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
132 const params = new URLSearchParams(req.query as Record<string, string>);
133 res.redirect(302, `${composioUrl}?${params.toString()}`);
134 }
@@ -175,6 +186,36 @@ const connectionRequest = await session.authorize("gmail", {
186
187 After authentication, Composio redirects the user to your callback URL instead of the default success page. For full details on the parameters appended to your callback URL, see [Manually authenticating users → Redirecting users after authentication](/docs/authentication/manually-authenticating#redirecting-users-after-authentication).
188
189 +## Frequently asked questions
190 +
191 +### Do I need a custom OAuth app for every toolkit?
192 +
193 +No. Create one only for OAuth toolkits where users see a provider consent screen and your product needs its own branding, scopes, or quotas. API-key toolkits do not have an OAuth consent screen. You can mix managed and custom auth configs in the same project.
194 +
195 +### Does changing the Connect Link logo change the provider consent screen?
196 +
197 +No. Connect Link branding changes the Composio-hosted connection page. Google, GitHub, Slack, and other OAuth providers get their consent-screen identity from the OAuth app. Use [your own OAuth app](#using-your-own-oauth-apps) to change it.
198 +
199 +### Can each customer have different branding?
200 +
201 +Each Composio project has one app title, logo, and theme. If separate products or customers need independent branding, use separate projects and account for the additional provisioning and credential management.
202 +
203 +### What happens to existing connections when I switch auth configs?
204 +
205 +They remain tied to the auth config used when they were created. New connections can use the custom config, while existing users continue with their current connected accounts until they re-authenticate or you migrate their credentials where supported.
206 +
207 +### How do I remove the Composio domain and success page?
208 +
209 +Use a [redirect proxy](#routing-the-callback-through-your-domain) to keep the browser callback on your domain. Pass a [`callbackUrl`](#redirecting-users-after-authentication) to return users directly to your product after authentication. These solve separate parts of the redirect flow.
210 +
211 +### Why does the "Secured by Composio" badge still appear?
212 +
213 +Connect Link styling alone does not remove it. Configure your own OAuth app for that toolkit so the provider consent flow uses your credentials and identity.
214 +
215 ## Next
216
180 -<Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Set up auth configs for OAuth apps, API keys, and toolkits without managed auth" />
217 +<Cards>
218 + <Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Set up auth configs for OAuth apps, API keys, and toolkits without managed auth." />
219 + <Card title="B2B agent architecture" href="/docs/b2b-agents" description="Decide when customer-specific branding or credentials require separate projects." />
220 + <Card title="Production readiness" href="/docs/production-readiness" description="Test authentication, isolation, logs, and failure recovery before launch." />
221 +</Cards>
docs/content/docs/b2b-agents.mdx new
+108
@@ -0,0 +1,108 @@
1 +---
2 +title: Design a B2B agent with Composio
3 +description: Structure tenants, members, projects, sessions, and connections for a B2B agent
4 +keywords: [b2b agent, multi tenant, workspace, organization, users, projects]
5 +---
6 +
7 +A B2B agent serves organizations with multiple members. Before writing integration code, decide who owns each app connection: an individual member or the customer workspace. That decision determines the Composio user ID and access model.
8 +
9 +## Choose the connection owner
10 +
11 +| Model | Use it when | Composio user ID example |
12 +|---|---|---|
13 +| Member-owned | Each member connects and acts through their own account | `org_42:user_7` |
14 +| Workspace-owned | The organization connects one shared service account or integration | `org_42:integration` |
15 +
16 +Use globally unique, immutable IDs. Prefixing your member ID with the workspace ID makes the tenant boundary explicit even when member IDs are only unique inside one workspace.
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 +```python
21 +from composio import Composio
22 +
23 +composio = Composio()
24 +
25 +workspace_id = "org_42"
26 +member_id = "user_7"
27 +composio_user_id = f"{workspace_id}:{member_id}"
28 +
29 +session = composio.sessions.create(
30 + user_id=composio_user_id,
31 + toolkits=["slack", "salesforce"],
32 +)
33 +tools = session.tools()
34 +```
35 +</Tab>
36 +<Tab value="TypeScript">
37 +```typescript
38 +import { Composio } from "@composio/core";
39 +
40 +const composio = new Composio();
41 +
42 +const workspaceId = "org_42";
43 +const memberId = "user_7";
44 +const composioUserId = `${workspaceId}:${memberId}`;
45 +
46 +const session = await composio.create(composioUserId, {
47 + toolkits: ["slack", "salesforce"],
48 +});
49 +const tools = await session.tools();
50 +```
51 +</Tab>
52 +</Tabs>
53 +
54 +<Callout type="warn" title="Do not collapse every member into one tenant ID">
55 +If members should use separate accounts, do not create all sessions with only the workspace ID. That would place their connections in the same user scope. Use a member-scoped ID and enforce your product's workspace authorization before creating or restoring a session.
56 +</Callout>
57 +
58 +## Start with one project per environment
59 +
60 +Use one Composio project for each application environment, such as development, staging, and production. Keep the tenant boundary in your application and `user_id` model.
61 +
62 +Create a separate project for a customer only when you need a hard operational boundary, such as:
63 +
64 +- Independent API keys, auth configs, branding, or webhooks
65 +- Contractual or regulatory isolation
66 +- Customer-specific provider credentials or infrastructure
67 +- Separate usage and administration controlled by that customer
68 +
69 +Project-per-customer isolation adds provisioning, credential management, and operational overhead. It is usually unnecessary for the first version of a multi-tenant product.
70 +
71 +## Model workspace-owned connections explicitly
72 +
73 +For an organization-wide service account, create a dedicated integration identity such as `org_42:integration`. Do not reuse a real member's identity, because the connection should survive membership changes.
74 +
75 +Your application remains responsible for deciding which members may ask the workspace-owned agent to act. Resolve the workspace, verify the member's role, then create or restore the session for the integration identity.
76 +
77 +[Shared connections](/docs/extending-sessions/shared-connections) are available for cases where one connected account must be exposed to a controlled list of Composio users. They are an experimental, explicit access-control feature, not the default tenant model. Pin and test the SDK version before making shared connections part of a production tenant model.
78 +
79 +## Choose the customer's authentication model
80 +
81 +Start with managed auth when Composio's provider app and scopes fit the product. Use [custom auth configs](/docs/authentication/custom-app-vs-managed-app) when your product needs its own OAuth branding, scopes, provider quotas, or self-hosted instances.
82 +
83 +If each customer supplies different OAuth credentials, create and manage auth configs programmatically, then assign the right config when creating that customer's sessions. See [Programmatic auth configs](/docs/authentication/programmatic-auth-configs).
84 +
85 +For a fully branded connection flow, combine custom OAuth credentials with [white-labeling](/docs/authentication/white-labeling-authentication).
86 +
87 +## Route events back to the right tenant
88 +
89 +Store your workspace and member mapping next to the Composio user and connected-account IDs. When a trigger event arrives, resolve that mapping before running customer-specific work. Your webhook handler must also enforce any tenant or role checks required by your product.
90 +
91 +See [Subscribing to trigger events](/docs/setting-up-triggers/subscribing-to-events) for webhook setup and verification.
92 +
93 +## Before you launch
94 +
95 +- Test two members in the same workspace and two members in different workspaces.
96 +- Confirm a removed member can no longer invoke workspace-owned connections.
97 +- Keep development, staging, and production credentials separate.
98 +- Define who can create, replace, or delete a workspace-owned connection.
99 +- Test a real trigger event and verify it maps to the expected workspace.
100 +- Inspect representative tool calls in [Logs](/reference/api-reference/logs).
101 +
102 +## Next
103 +
104 +<Cards>
105 + <Card title="Build a consumer agent" href="/docs/consumer-agents" description="Use a simpler per-person identity and connection model." />
106 + <Card title="White-label authentication" href="/docs/authentication/white-labeling-authentication" description="Brand Connect Links, consent screens, domains, and callbacks." />
107 + <Card title="Move to production" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions." />
108 +</Cards>
docs/content/docs/consumer-agents.mdx new
+91
@@ -0,0 +1,91 @@
1 +---
2 +title: Design a consumer agent with Composio
3 +description: Structure users, projects, sessions, and authentication for a consumer agent
4 +keywords: [consumer agent, b2c, users, projects, sessions, architecture]
5 +---
6 +
7 +A consumer agent serves individual end users. Each person signs in to your product, connects their own apps, and expects their connections and tool calls to stay isolated from everyone else.
8 +
9 +Start with one Composio project per application environment. Map every signed-in user to a stable ID from your database, then create and reuse sessions for that ID.
10 +
11 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
12 +<Tab value="Python">
13 +```python
14 +from composio import Composio
15 +
16 +composio = Composio()
17 +
18 +# Use the immutable primary key from your application database.
19 +app_user_id = "usr_01J9F4M2K8"
20 +session = composio.sessions.create(
21 + user_id=app_user_id,
22 + toolkits=["gmail", "googlecalendar"],
23 +)
24 +tools = session.tools()
25 +```
26 +</Tab>
27 +<Tab value="TypeScript">
28 +```typescript
29 +import { Composio } from "@composio/core";
30 +
31 +const composio = new Composio();
32 +
33 +// Use the immutable primary key from your application database.
34 +const appUserId = "usr_01J9F4M2K8";
35 +const session = await composio.create(appUserId, {
36 + toolkits: ["gmail", "googlecalendar"],
37 +});
38 +const tools = await session.tools();
39 +```
40 +</Tab>
41 +</Tabs>
42 +
43 +## Recommended starting architecture
44 +
45 +| Decision | Start with | Change it when |
46 +|---|---|---|
47 +| Project boundary | One project for each environment, such as development and production | A separate product needs independent credentials, branding, or isolation |
48 +| Composio user ID | Your immutable application user ID | Never change it for an existing user |
49 +| Connected accounts | Private to that user | A deliberate shared-account workflow requires controlled sharing |
50 +| Session lifecycle | Store the session ID and reuse it for the conversation | A new task needs a clean execution context |
51 +| Authentication | Composio managed auth | You need your own branding, scopes, quotas, or provider app |
52 +| Tool access | Only the toolkits your feature needs | The product intentionally supports broader discovery |
53 +
54 +### Keep identity stable
55 +
56 +Use a database UUID or immutable primary key for `user_id`. Do not use an email address because it can change. Never use a shared value such as `default` in production, because different customers could inherit the same connection scope.
57 +
58 +The same application user can connect several accounts for one toolkit, such as personal and work Gmail. Keep the same `user_id` and [select the connected account](/docs/authentication/managing-multiple-connected-accounts) when a session needs a specific one.
59 +
60 +### Reuse sessions for multi-turn work
61 +
62 +Every call to `create()` makes a new session. Store `session.session_id` in Python or `session.sessionId` in TypeScript with your conversation, then restore it with `composio.use(session_id)`. Reusing the session preserves its tool, authentication, and workbench context.
63 +
64 +Create a new session for a different user or a genuinely separate task. Do not create a new session for every message in the same conversation.
65 +
66 +### Choose the connection experience
67 +
68 +Use [in-chat authentication](/docs/authentication#in-chat-authentication) when the agent can show a Connect Link and wait for the user. Use [manual authentication](/docs/authentication/manually-authenticating) when your product has its own integrations page or connection flow.
69 +
70 +Managed auth is the quickest way to start. Create a [custom auth config](/docs/authentication/custom-app-vs-managed-app) only when you need your own consent-screen branding, custom scopes, dedicated provider quotas, or a custom provider instance.
71 +
72 +### Limit the agent to its job
73 +
74 +Restrict the session to the toolkits and tools your feature needs. This makes discovery more relevant and prevents unrelated actions from appearing in the agent's available surface. Ask for user confirmation before destructive or externally visible actions.
75 +
76 +## Before you launch
77 +
78 +- Verify two different users cannot see or use each other's connected accounts.
79 +- Test both the first-time connection flow and a returning user with an existing connection.
80 +- Store the Composio API key only on your server.
81 +- Persist session IDs for multi-turn conversations.
82 +- Test one safe, read-only call against a real connected account.
83 +- Inspect the resulting tool call in [Logs](/reference/api-reference/logs).
84 +
85 +## Next
86 +
87 +<Cards>
88 + <Card title="Build a B2B agent" href="/docs/b2b-agents" description="Choose between member-owned and workspace-owned connections." />
89 + <Card title="Configure sessions" href="/docs/configuring-sessions" description="Restrict toolkits, tools, auth configs, and connected accounts." />
90 + <Card title="Move to production" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions." />
91 +</Cards>
docs/content/docs/meta.json
+4
@@ -5,6 +5,7 @@
5 "quickstart",
6 "providers",
7 "agent-plugins",
8 + "using-composio-skill",
9 "cli",
10 "composio-connect",
11 "---Core concepts---",
@@ -14,6 +15,9 @@
15 "triggers",
16 "skills",
17 "---Guides---",
18 + "consumer-agents",
19 + "b2b-agents",
20 + "production-readiness",
21 "sessions-via-mcp",
22 "sandbox",
23 "extending-sessions",
docs/content/docs/production-readiness.mdx new
+107
@@ -0,0 +1,107 @@
1 +---
2 +title: Move from prototype to production
3 +description: Review the identity, environment, authentication, security, and reliability decisions required for production
4 +keywords: [production, poc, launch checklist, architecture, security, reliability]
5 +---
6 +
7 +A prototype proves that an agent can connect an account and call a tool. A production integration must also preserve user isolation, survive repeat visits, limit what the agent can do, and give your team enough evidence to diagnose failures.
8 +
9 +Use this guide after the [quickstart](/docs/quickstart) works and before customers depend on the integration.
10 +
11 +## Production decisions at a glance
12 +
13 +| Prototype default | Production decision |
14 +|---|---|
15 +| One sample user such as `user_123` | Stable, immutable application user IDs |
16 +| One project for every test | Separate projects for environments that must not share credentials or resources |
17 +| A new session on every run | Persist and reuse session IDs for multi-turn work |
18 +| Every toolkit is discoverable | Restrict toolkits and tools to the product's intended scope |
19 +| Managed auth | Keep it, or use custom auth for branding, scopes, quotas, or custom providers |
20 +| API keys in a local `.env` file | Server-side secret manager and environment-specific keys |
21 +| A successful demo call | Real account, failure-path, webhook, and tenant-isolation tests |
22 +
23 +## 1. Finalize your identity model
24 +
25 +Replace sample values with an immutable ID from your application database. Never use an email address or a shared value such as `default` in production.
26 +
27 +For a consumer product, each person usually owns their connections. See [Design a consumer agent](/docs/consumer-agents).
28 +
29 +For a B2B product, decide whether connections belong to an individual member or to the customer workspace. See [Design a B2B agent](/docs/b2b-agents).
30 +
31 +## 2. Separate environments where it matters
32 +
33 +Use separate Composio projects for development, staging, and production when those environments must not share API keys, auth configs, connected accounts, webhooks, or logs.
34 +
35 +Keep every project API key on the server. Store production keys in your deployment platform's secret manager, rotate them according to your security policy, and never expose them to browser or mobile clients.
36 +
37 +## 3. Decide how customers authenticate
38 +
39 +Keep managed auth when its provider app, scopes, and quotas fit your product. It removes OAuth app setup and token-refresh work.
40 +
41 +Use a [custom auth config](/docs/authentication/custom-app-vs-managed-app) when you need:
42 +
43 +- Your own app name on the provider consent screen
44 +- Different or additional OAuth scopes
45 +- Dedicated provider quotas
46 +- A custom, regional, or self-hosted provider instance
47 +- Customer-specific OAuth credentials
48 +
49 +Test both first-time authentication and a returning user whose connected account already exists. If you need a branded flow, follow the [white-labeling guide](/docs/authentication/white-labeling-authentication).
50 +
51 +## 4. Bound the agent's authority
52 +
53 +Configure sessions with only the toolkits and tools required by the feature. Narrower access improves tool discovery and reduces the number of actions the agent can attempt.
54 +
55 +Require explicit user confirmation before destructive or externally visible actions, such as sending a message, creating a purchase, or deleting data. Enforce product authorization before creating or restoring the session, especially for workspace-owned connections.
56 +
57 +See [Configuring sessions](/docs/configuring-sessions) for toolkit and tool filters.
58 +
59 +## 5. Persist the right state
60 +
61 +Store the Composio session ID with your conversation or task and reuse it with `composio.use()`. This preserves the session's tool, authentication, and workbench context across turns.
62 +
63 +Also store the mapping between your application user, Composio user ID, connected accounts, and tenant when applicable. Your database remains the source of truth for product membership and permissions.
64 +
65 +## 6. Test real execution and failure paths
66 +
67 +Run at least one safe, read-only call against a real connected account. Confirm that:
68 +
69 +- The tool returns expected data for the correct user
70 +- A second user cannot access the first user's connection
71 +- A missing or expired connection returns the expected recovery flow
72 +- Invalid tool arguments produce a useful error
73 +- The tool call appears in [Logs](/reference/api-reference/logs) with a non-empty log ID
74 +
75 +Do not treat a successful Connect Link alone as an end-to-end test. Authentication can succeed while a provider API, scope, or tool input still fails.
76 +
77 +## 7. Verify triggers through your real webhook
78 +
79 +If your product uses triggers, test the deployed HTTPS webhook rather than only a local callback. Parse events with the Composio SDK, verify the payload reaches the correct environment, and map it to the expected user or workspace before doing work.
80 +
81 +See [Subscribing to trigger events](/docs/setting-up-triggers/subscribing-to-events) for the webhook flow.
82 +
83 +## 8. Set security and data-retention expectations
84 +
85 +Review which tool inputs, outputs, logs, and files your integration creates. Align retention with your own product policy and customer commitments. See [Data retention](/docs/security/data-retention) for the controls Composio provides.
86 +
87 +Document who can access production projects, rotate keys, manage auth configs, and inspect logs. Keep those permissions limited to the people and services that need them.
88 +
89 +## Ready to ship
90 +
91 +- Stable user and tenant IDs are used everywhere.
92 +- Development, staging, and production use the intended project boundaries.
93 +- API keys are server-side and stored in a secret manager.
94 +- Authentication, reconnect, and returning-user flows work.
95 +- Session IDs are persisted for multi-turn work.
96 +- Tool access and confirmation rules match the product's intended authority.
97 +- Cross-user or cross-tenant isolation has been tested.
98 +- Real tool calls and trigger events appear in logs and map to the correct user.
99 +- The team knows how to diagnose and recover from provider or authentication failures.
100 +
101 +## Next
102 +
103 +<Cards>
104 + <Card title="Review security" href="/docs/security/overview" description="Understand security controls, data retention, and operational boundaries." />
105 + <Card title="Configure sessions" href="/docs/configuring-sessions" description="Restrict toolkits, tools, auth configs, and connected accounts." />
106 + <Card title="Set up triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create triggers and receive events through your webhook." />
107 +</Cards>
docs/content/docs/quickstart.mdx
+8
@@ -483,3 +483,11 @@ You can inspect the selected tools, inputs, responses, and timing with the [Logs
483 <Card title="Design authentication" href="/docs/authentication" description="Add Connect Links and per-user connections to your application." />
484 <Card title="Expose an MCP endpoint" href="/docs/sessions-via-mcp" description="Use the same Composio session from an MCP-compatible application." />
485 </Cards>
486 +
487 +## Plan your application
488 +
489 +<Cards>
490 + <Card title="Consumer agent architecture" href="/docs/consumer-agents" description="Map individual users to isolated connections and reusable sessions." />
491 + <Card title="B2B agent architecture" href="/docs/b2b-agents" description="Choose member-owned or workspace-owned connections for a multi-tenant product." />
492 + <Card title="Production readiness" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions before launch." />
493 +</Cards>
docs/content/docs/using-composio-skill.mdx new
+69
@@ -0,0 +1,69 @@
1 +---
2 +title: Build with the Composio skill
3 +description: Let your coding agent add, configure, or troubleshoot Composio in an existing project
4 +keywords: [composio skill, coding agent, codex, claude code, setup]
5 +---
6 +
7 +The public `composio` skill gives coding agents current instructions for building with Composio. Use it when you want an agent to inspect your existing project, choose the right Composio path, and implement or troubleshoot the integration in place.
8 +
9 +## Install the skill
10 +
11 +Run this command from your project root:
12 +
13 +```bash
14 +npx skills add ComposioHQ/composio --skill composio -y
15 +```
16 +
17 +Then ask your coding agent for a concrete outcome. Include the apps, agent framework, and user model when you know them.
18 +
19 +```text
20 +Use Composio to add Gmail and Google Calendar tools to this existing agent.
21 +Preserve the current framework and user model. Verify the integration with a safe,
22 +read-only tool call before you finish.
23 +```
24 +
25 +A skill-aware coding agent can load it when your request involves Composio. You can also tell the agent explicitly to use the `composio` skill.
26 +
27 +## What the skill helps with
28 +
29 +The skill routes the agent based on what you are building:
30 +
31 +| Your goal | Recommended path |
32 +|---|---|
33 +| Add app integrations to a product | Composio SDK and sessions |
34 +| Use apps from your own coding agent | Agent plugin, CLI, or MCP |
35 +| Add Composio to an existing MCP client | Composio Connect |
36 +| Diagnose a connection or tool-call error | Current docs and public support knowledge |
37 +
38 +For product integrations, the agent should preserve your framework and application identity model rather than replacing them with a standalone demo. It should use your stable application user ID when creating Composio sessions and keep your Composio API key on the server.
39 +
40 +<Callout type="info" title="The skill is guidance, not a credential">
41 +Installing the skill does not connect accounts or expose credentials. Your product still uses the Composio SDK, API key, sessions, and Connect Links. For personal agent use, the agent may guide you through a CLI, plugin, or MCP connection instead.
42 +</Callout>
43 +
44 +## Give the agent enough context
45 +
46 +Good prompts state the outcome and important constraints. For example:
47 +
48 +```text
49 +Use the Composio skill to add Slack tools to this TypeScript agent.
50 +Each signed-in customer must use their own Slack connection. Keep the API key
51 +server-side, limit the session to Slack, and ask for confirmation before writes.
52 +```
53 +
54 +If you already know the failure, include the exact error and where it occurs:
55 +
56 +```text
57 +Use the Composio skill to diagnose this Google Tasks 401. Check the current
58 +connection state and public support knowledge before changing application code.
59 +```
60 +
61 +The agent can inspect source code and run local checks, but it should ask before actions that need user authorization, such as completing an OAuth flow.
62 +
63 +## Next
64 +
65 +<Cards>
66 + <Card title="Build your first agent" href="/docs/quickstart" description="Create a session and give an agent access to Composio tools." />
67 + <Card title="Use Composio from your coding agent" href="/docs/agent-plugins" description="Choose a plugin, CLI, or MCP setup for personal use." />
68 + <Card title="Add Composio Connect" href="/docs/composio-connect" description="Connect Composio to an MCP-compatible client." />
69 +</Cards>
docs/tests/static/navigation.test.ts
+1
@@ -63,6 +63,7 @@ describe("Navigation - meta.json validity", () => {
63 "quickstart",
64 "providers",
65 "agent-plugins",
66 + "using-composio-skill",
67 "cli",
68 "composio-connect",
69 ]);