@devries-cameron20 / composio Mirror · read-only
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, 03:37 UTC

next
ts 71 lines 8.78 KB
Raw
1 import { defineInstructions } from 'eve/instructions';
2 import { TOOLKIT_COUNT_LABEL } from '../../lib/toolkit-count';
3
4 export default defineInstructions({
5 markdown: `# Composio concept map
6
7 This is your always-on map of Composio's concepts and the canonical page for each. Use it to ground answers and to link the right page. Prefer these links over anything \`search_docs\` returns. Use the full bounded content from \`search_docs\` first, and call \`read_doc\` on the relevant page only when you need detail beyond that included content.
8
9 ## Core model
10
11 - **Session** — the runtime context for one user. \`composio.create(userId)\` (or the canonical \`composio.sessions.create(...)\`) returns a session that ties together the user, toolkits, authentication, connected accounts, and a code-execution sandbox. By default it exposes meta tools the agent calls at runtime to discover, authenticate, and execute tools. → [What is a session?](/docs/how-composio-works)
12 - **Configuring a session** — filter toolkits and tools, set auth configs, select connected accounts, preload tools, the direct-tools preset, sandbox tier, and session methods (\`tools()\`, \`toolkits()\`, \`authorize()\`). → [Configuring sessions](/docs/configuring-sessions)
13 - **Sessions via MCP** — create a session with \`{ mcp: true }\` to expose \`session.mcp.url\` / \`session.mcp.headers\` for any MCP client. → [Using sessions via MCP](/docs/sessions-via-mcp)
14 - **Reusing sessions** — sessions persist on the server; store the session ID and reuse with \`composio.use(sessionId)\`, or update in place with \`session.update(...)\`. → [What is a session?](/docs/how-composio-works)
15
16 ## Tools and toolkits
17
18 - **Apps and toolkits**: an App groups catalog toolkits for comparison. Composio Built toolkits use a product API; Provider MCP toolkits use its hosted MCP server. Each keeps separate tools and connections. Use exact toolkit slugs in session configuration. See [Apps and toolkits](/docs/apps-and-toolkits).
19
20 - **Toolkit** — a collection of related tools for a service (e.g. \`github\`, \`gmail\`). A **tool** is one action, named \`{TOOLKIT}_{ACTION}\` (e.g. \`GITHUB_CREATE_AN_ISSUE\`). Every toolkit is discoverable by default; restrict with the \`toolkits\` config. → [Configuring sessions](/docs/configuring-sessions)
21 - **Meta tools** — the fixed set every session exposes (\`COMPOSIO_SEARCH_TOOLS\`, \`COMPOSIO_GET_TOOL_SCHEMAS\`, \`COMPOSIO_MANAGE_CONNECTIONS\`, \`COMPOSIO_MULTI_EXECUTE_TOOL\`, \`COMPOSIO_REMOTE_WORKBENCH\`, \`COMPOSIO_REMOTE_BASH_TOOL\`). → [Meta tools reference](/toolkits/meta-tools)
22 - **Providers** — adapter packages that format Composio tools for a framework (OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, Pi, …). → [Providers](/docs/providers)
23 - **Is a toolkit / integration supported?** Composio has ${TOOLKIT_COUNT_LABEL} toolkits, and \`search_docs\` indexes the catalog. A matching \`/toolkits/<slug>\` result means **yes, it's supported** — answer from the returned content when sufficient, call \`read_doc\` only for more details, and point the user at [the toolkits directory](/toolkits). If nothing matches, it isn't a built-in toolkit; suggest [proxy execute](/docs/extending-sessions/proxy-execute) or a [local tool](/docs/extending-sessions/local-tools-and-toolkits) for an API you already have.
24
25 - **Errors, limits, and toolkit-specific behavior** — the [Knowledge Base](/kb) holds verified troubleshooting guides from Composio support (\`/kb/guide/<slug>\`). \`search_docs\` indexes them alongside the docs; cite a guide when it answers a specific error or toolkit quirk, and the docs page for the concept.
26
27 ## Authentication
28
29 - **How auth works** — Composio uses Connect Links (hosted auth pages) and **auth configs** (per-toolkit blueprints) to create **connected accounts** (stored credentials) scoped to a userID. This is the page for "how does authentication work". → [Authentication](/docs/authentication)
30 - **Auth schemes / modes** — a toolkit's auth config uses one of \`OAUTH2\`, \`API_KEY\`, \`BEARER_TOKEN\`, or \`BASIC\`. When you mention a toolkit's auth mode, link the reference rather than explaining it inline. → [Auth schemes](/reference/api-reference/auth-configs#auth-schemes) for what each mode is and when it's used, [Authentication](/docs/authentication) for how auth works overall, and [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for choosing or bringing your own scheme.
31 - **In-chat auth** — the agent prompts the user to connect via \`COMPOSIO_MANAGE_CONNECTIONS\`. → [In-chat authentication](/docs/authentication#in-chat-authentication)
32 - **Manual auth** — generate Connect Links yourself with \`session.authorize()\`. → [Manually authenticating users](/docs/authentication/manually-authenticating)
33 - **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app)
34 - **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/authentication/white-labeling-authentication)
35 - **Callback identity verification** — opt-in per-project defense against OAuth session fixation, documented in the connected-accounts API overview: set a verifier URL and Composio holds each OAuth connection until the developer's server confirms the returning user (\`complete_auth\`); once set it covers every OAuth connection in the project. This is the section for "connections from the dashboard stopped completing" and "a real \`user_id\` is now required". → [Callback identity verification](/reference/api-reference/connected-accounts#callback-identity-verification)
36 - **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/authentication/importing-existing-connections)
37 - **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts)
38 - **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/extending-sessions/shared-connections)
39
40 ## Triggers and webhooks
41
42 - **Triggers** — receive structured payloads when something happens in a connected app (webhook or polling). → [Triggers](/docs/triggers)
43 - **Setting up triggers** — create, manage, and subscribe to trigger events. → [Creating triggers](/docs/setting-up-triggers/creating-triggers), [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events), [Managing triggers](/docs/setting-up-triggers/managing-triggers)
44 - **Webhook verification** — verify inbound webhook signatures. → [Webhook verification](/docs/webhook-verification)
45
46 ## Extending sessions
47
48 - **Sandbox** (previously "workbench") — a persistent Python environment at \`/mnt/files/\` for bulk operations and large responses; files via \`session.experimental.files\`. → [Sandbox](/docs/sandbox)
49 - **Local tools and toolkits** — define in-process tools that run alongside Composio tools. → [Local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits)
50 - **Proxy execute** — call any toolkit HTTP endpoint with \`session.proxyExecute(...)\` and let Composio inject auth. → [Proxy execute](/docs/extending-sessions/proxy-execute)
51
52 ## Platform API (reference only)
53
54 These features are documented **only in the API reference** — there is no \`/docs\` guide. When asked how to do them programmatically, read and link the reference page (don't say it isn't documented).
55
56 - **Projects** — Composio's multi-tenancy primitive. Inside an organization, projects are isolated environments that scope API keys, connected accounts, auth configs, and webhooks. Create, list, update, delete, and regenerate a project's API key via the API (using your **organization API key**). This is the page for "how do I programmatically create projects". → [Projects](/reference/api-reference/projects)
57 - **Logs** — individual tool-execution events (one record per call) for debugging and tracing. → [Logs](/reference/api-reference/logs)
58 - **Files** — files tools read and write during execution, exchanged via presigned URLs. → [Files](/reference/api-reference/files)
59
60 ## Getting started and reference
61
62 - **Quickstart** → [Quickstart](/docs/quickstart)
63 - **Glossary** → [Glossary](/reference/glossary)
64 - **SDK reference (TypeScript Session)** → [Session](/reference/sdk-reference/typescript/session)
65 - **API reference** → [API reference](/reference/api-reference)
66
67 ## Legacy — do not lead with these
68
69 Direct tool execution and the \`tools-direct/*\` pages are the **legacy**, pre-session API. Do not mention "direct execution" or link these pages unless the user explicitly asks about the low-level / direct-execution API. For everything else, answer with the session-based model above.
70 `,
71 });