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.

docs: add chat app tutorial and revamp welcome page

Sushmitha Mallesh6a668e1f098f
diff --git a/docs/components/ai-tools-banner.tsx b/docs/components/ai-tools-banner.tsx
new file mode 100644
index 000000000..1e0a5bd01
--- /dev/null
+++ b/docs/components/ai-tools-banner.tsx
@@ -0,0 +1,105 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { Bot, FileText, Copy, Check, ExternalLink } from 'lucide-react';
+
+function CopyButton({ text }: { text: string }) {
+ const [copied, setCopied] = useState(false);
+
+ return (
+ <button
+ onClick={() => {
+ navigator.clipboard.writeText(text);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ }}
+ className="shrink-0 rounded-md p-1 text-fd-muted-foreground/60 hover:text-fd-foreground transition-colors"
+ aria-label="Copy to clipboard"
+ >
+ {copied ? (
+ <Check className="h-3.5 w-3.5 text-green-500" />
+ ) : (
+ <Copy className="h-3.5 w-3.5" />
+ )}
+ </button>
+ );
+}
+
+export function AIToolsBanner() {
+ const skillsCommand = 'npx skills add composiohq/skills';
+
+ return (
+ <div className="not-prose relative mt-6 overflow-hidden rounded-xl border border-fd-border bg-gradient-to-br from-fd-card via-fd-card to-fd-muted/50 dark:from-fd-muted/20 dark:via-fd-card dark:to-fd-muted/40">
+ {/* Subtle grid pattern */}
+ <div
+ className="pointer-events-none absolute inset-0 opacity-[0.03] dark:opacity-[0.04]"
+ style={{
+ backgroundImage:
+ 'linear-gradient(var(--color-fd-foreground) 1px, transparent 1px), linear-gradient(90deg, var(--color-fd-foreground) 1px, transparent 1px)',
+ backgroundSize: '24px 24px',
+ }}
+ />
+ <div className="relative p-5">
+ {/* Header */}
+ <div className="mb-4 flex items-center gap-2.5">
+ <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-fd-muted dark:bg-fd-muted/60">
+ <Bot className="h-4 w-4 text-fd-muted-foreground" />
+ </div>
+ <span className="text-sm font-semibold text-fd-foreground tracking-tight">
+ For AI tools
+ </span>
+ </div>
+
+ {/* Skills command */}
+ <div className="mb-3 flex items-center gap-2 rounded-lg border border-fd-border bg-fd-background dark:bg-fd-background/50 px-3.5 py-2.5 font-mono text-[13px] text-fd-foreground">
+ <span className="select-none text-fd-muted-foreground">$</span>
+ <span className="flex-1 select-all">{skillsCommand}</span>
+ <CopyButton text={skillsCommand} />
+ </div>
+
+ {/* Skills links */}
+ <div className="mb-4 flex items-center gap-3 text-xs">
+ <Link
+ href="https://skills.sh/composiohq/skills/composio"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1 text-fd-muted-foreground hover:text-[var(--composio-orange)] transition-colors"
+ >
+ Skills.sh
+ <ExternalLink className="h-3 w-3" />
+ </Link>
+ <Link
+ href="https://github.com/composiohq/skills"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1 text-fd-muted-foreground hover:text-[var(--composio-orange)] transition-colors"
+ >
+ GitHub
+ <ExternalLink className="h-3 w-3" />
+ </Link>
+ </div>
+
+ {/* Context files */}
+ <div className="flex gap-2">
+ <Link
+ href="/llms.txt"
+ className="group flex flex-1 items-center gap-2.5 rounded-lg border border-fd-border/80 bg-fd-card dark:bg-fd-background/30 px-3 py-2 transition-all hover:border-[var(--composio-orange)]/40"
+ >
+ <FileText className="h-3.5 w-3.5 shrink-0 text-fd-muted-foreground group-hover:text-[var(--composio-orange)] transition-colors" />
+ <span className="text-sm font-medium text-fd-foreground">llms.txt</span>
+ <span className="text-[11px] text-fd-muted-foreground">Index</span>
+ </Link>
+ <Link
+ href="/llms-full.txt"
+ className="group flex flex-1 items-center gap-2.5 rounded-lg border border-fd-border/80 bg-fd-card dark:bg-fd-background/30 px-3 py-2 transition-all hover:border-[var(--composio-orange)]/40"
+ >
+ <FileText className="h-3.5 w-3.5 shrink-0 text-fd-muted-foreground group-hover:text-[var(--composio-orange)] transition-colors" />
+ <span className="text-sm font-medium text-fd-foreground">llms-full.txt</span>
+ <span className="text-[11px] text-fd-muted-foreground">Complete</span>
+ </Link>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/docs/content/cookbooks/chat-app.mdx b/docs/content/cookbooks/chat-app.mdx
new file mode 100644
index 000000000..9e0f9ab19
--- /dev/null
+++ b/docs/content/cookbooks/chat-app.mdx
@@ -0,0 +1,125 @@
+---
+title: Build a Chat App
+description: Build an AI chat app with tool access to 1000+ apps in about 30 lines of code
+---
+
+Give your AI agent access to Gmail, GitHub, Slack, Notion, and 1000+ other apps. This tutorial builds a Next.js chat app that handles tool discovery, user authentication, and action execution in about **30 lines of code**.
+
+## What you'll build
+
+- A chat app where your agent can find and use tools across 1000+ apps
+- In-chat OAuth authentication so users can connect apps directly in the conversation
+- A tool call display that shows what the agent is doing in real time
+
+## Prerequisites
+
+- Node.js 18+
+- [Composio API key](https://platform.composio.dev/settings)
+- [OpenAI API key](https://platform.openai.com/api-keys)
+
+**Stack:** Next.js, Vercel AI SDK, OpenAI, Composio
+
+## Create the project
+
+Create a new Next.js app and install the dependencies:
+
+```bash
+pnpm create next-app composio-chat --yes
+cd composio-chat
+pnpm install @composio/core @composio/vercel @ai-sdk/openai ai @ai-sdk/react
+```
+
+<Callout type="info">
+Get your `COMPOSIO_API_KEY` from [Settings](https://platform.composio.dev/settings) and `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
+</Callout>
+
+Add your API keys to a `.env.local` file in the project root:
+
+```bash title=".env.local"
+COMPOSIO_API_KEY=your_composio_api_key
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Start the dev server:
+
+```bash
+pnpm dev
+```
+
+## Build the backend
+
+A **session** scopes tools and credentials to a specific user. Create `app/api/chat/route.ts`:
+
+<include meta='title="app/api/chat/route.ts"'>../../examples/chat-app/route.ts</include>
+
+That's the entire backend. `composio.create("user_123")` creates a session that lets the agent search for tools, authenticate users, and execute actions. This ID scopes all connections and credentials to this user. In production, use the user ID from your auth system.
+
+## Build the chat UI
+
+Replace `app/page.tsx`:
+
+<include meta='title="app/page.tsx"'>../../examples/chat-app/page.tsx</include>
+
+Go to [localhost:3000](http://localhost:3000). You should see the chat interface.
+
+## Try a tool call
+
+Send this message:
+
+```
+Star the composio repo on GitHub
+```
+
+Here's what happens:
+
+1. The agent searches for relevant tools, finds `GITHUB_STAR_REPO`, and checks your connection status.
+2. You haven't connected GitHub yet, so the agent generates an auth link and shows it to you.
+3. Click the link, authorize with GitHub, and tell the agent you're done.
+4. The agent executes `GITHUB_STAR_REPO` with your credentials.
+
+Discovery, authentication, and execution all happened automatically. You didn't write any tool-specific code.
+
+<Callout>
+This in-chat authentication flow works out of the box. For production apps, you can [authenticate users ahead of time](/docs/authenticating-users/manually-authenticating) during onboarding.
+</Callout>
+
+## Show tool calls in the UI
+
+Tool calls happen invisibly by default. Add a component that shows the tool name and status so you can see what the agent is doing.
+
+Create `components/ToolCallDisplay.tsx`:
+
+<include meta='title="components/ToolCallDisplay.tsx"'>../../examples/chat-app/ToolCallDisplay.tsx</include>
+
+Update `app/page.tsx` to render tool calls:
+
+<include meta='title="app/page.tsx"'>../../examples/chat-app/page-with-tools.tsx</include>
+
+Tool calls now show inline with a spinner while running and a checkmark when complete. Click to expand and see the raw output.
+
+## How it works
+
+The session handles tool discovery and execution at runtime. Instead of loading thousands of tool definitions into your agent's context, the agent searches for what it needs, authenticates the user if necessary, and executes the action. Token refresh and credential management are handled automatically.
+
+Try a few more requests:
+
+- "Summarize my emails from today"
+- "What's on my calendar this week?"
+- "Create a GitHub issue in my repo"
+
+## Take it further
+
+<Cards>
+ <Card title="Configuring sessions" href="/docs/configuring-sessions">
+ Lock down which toolkits your agent can access
+ </Card>
+ <Card title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
+ Move authentication to your onboarding flow instead of in-chat
+ </Card>
+ <Card title="Users and sessions" href="/docs/users-and-sessions">
+ Scope sessions to real users for multi-tenant apps
+ </Card>
+ <Card title="How Composio works" href="/docs/how-composio-works">
+ Understand sessions, tool discovery, and execution under the hood
+ </Card>
+</Cards>
diff --git a/docs/content/cookbooks/meta.json b/docs/content/cookbooks/meta.json
index a90576904..dbd9a8cfa 100644
--- a/docs/content/cookbooks/meta.json
+++ b/docs/content/cookbooks/meta.json
@@ -4,6 +4,7 @@
"pages": [
"---Getting Started---",
"templates",
+ "chat-app",
"fast-api",
"hono",
"---Productivity & Automation---",
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index a77127cbd..2fba4620b 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -8,44 +8,47 @@ Composio powers 1000+ toolkits, tool search, context management, authentication,
<Cards>
<Card
- icon={<Rocket />}
- title="Quickstart"
- href="/docs/quickstart"
- description="Build your first agent in 5 minutes"
+ title="Tutorial: Build a chat app"
+ href="/cookbooks/chat-app"
+ description="Build a Next.js chat app where your agent can discover and use tools across 1000+ apps."
/>
<Card
- icon={<Play />}
- title="Playground"
- href="https://platform.composio.dev/auth?next_page=%2Ftool-router"
- description="Try Composio in your browser"
+ title="How Composio works"
+ href="/docs/how-composio-works"
+ description="Learn about sessions, meta tools, authentication, and the architecture behind Composio."
/>
+</Cards>
+
+## Get Started
+
+<Cards className="grid-cols-1">
<Card
icon={<Rocket />}
- title="How it works"
- href="/docs/how-composio-works"
- description="Sessions, meta tools, authentication, and execution"
+ title="Quickstart"
+ href="/docs/quickstart"
+ description="Install the SDK, connect an app, and run your first tool call in 5 minutes."
/>
+</Cards>
+
+<AIToolsBanner />
+
+## Explore
+
+<Cards>
<Card
icon={<Wrench />}
title="Toolkits"
href="/toolkits"
- description="Browse 1000+ toolkits"
+ description="Browse 1000+ toolkits across GitHub, Gmail, Slack, Notion, and more."
+ />
+ <Card
+ icon={<Play />}
+ title="Playground"
+ href="https://platform.composio.dev/auth?next_page=%2Ftool-router"
+ description="Try Composio in your browser without writing any code."
/>
</Cards>
-## For AI tools
-
-- [composio.dev/llms.txt](/llms.txt) - Documentation index with links
-- [composio.dev/llms-full.txt](/llms-full.txt) - Complete documentation in one file
-
-### Skills
-
-```bash
-npx skills add composiohq/skills
-```
-
-[View on Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)
-
## Providers
Composio works with any AI framework. Pick your preferred SDK:
diff --git a/docs/examples/chat-app/ToolCallDisplay.tsx b/docs/examples/chat-app/ToolCallDisplay.tsx
new file mode 100644
index 000000000..5c82a2058
--- /dev/null
+++ b/docs/examples/chat-app/ToolCallDisplay.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { useState } from "react";
+
+export function ToolCallDisplay({
+ toolName,
+ input,
+ output,
+ isLoading,
+}: {
+ toolName: string;
+ input: unknown;
+ output?: unknown;
+ isLoading: boolean;
+}) {
+ const [expanded, setExpanded] = useState(false);
+
+ return (
+ <div className="my-1">
+ <button
+ onClick={() => setExpanded(!expanded)}
+ className={`inline-flex items-center gap-2 rounded-md border px-3 py-1.5 text-xs transition-colors ${
+ isLoading
+ ? "border-gray-200 bg-gray-50 text-gray-500 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-400"
+ : "border-gray-200 bg-gray-50 text-gray-700 hover:bg-gray-100 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300 dark:hover:bg-gray-800"
+ }`}
+ >
+ {isLoading ? (
+ <span className="inline-block h-3 w-3 animate-spin rounded-full border border-gray-300 border-t-gray-600 dark:border-gray-600 dark:border-t-gray-300" />
+ ) : (
+ <span className="text-green-600 dark:text-green-400">✓</span>
+ )}
+ <code className="font-mono">{toolName}</code>
+ {!isLoading && <span className="text-gray-400">{expanded ? "▴" : "▾"}</span>}
+ </button>
+
+ {expanded && !isLoading && (
+ <pre className="mt-1 ml-1 max-h-40 max-w-full overflow-auto whitespace-pre-wrap break-words rounded-md border border-gray-200 bg-gray-50 p-2 text-xs text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-400">
+ {output != null
+ ? String(JSON.stringify(output, null, 2))
+ : String(JSON.stringify(input, null, 2))}
+ </pre>
+ )}
+ </div>
+ );
+}
diff --git a/docs/examples/chat-app/page-with-tools.tsx b/docs/examples/chat-app/page-with-tools.tsx
new file mode 100644
index 000000000..42115598b
--- /dev/null
+++ b/docs/examples/chat-app/page-with-tools.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import { useState } from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport, getToolName, isToolUIPart } from "ai";
+import { ToolCallDisplay } from "../components/ToolCallDisplay";
+
+export default function Chat() {
+ const [input, setInput] = useState("");
+ const { messages, sendMessage, status } = useChat({
+ transport: new DefaultChatTransport({ api: "/api/chat" }),
+ });
+
+ const isLoading = status === "streaming" || status === "submitted";
+
+ return (
+ <main className="max-w-2xl mx-auto p-6">
+ <h1 className="text-2xl font-bold mb-6">Composio Chat</h1>
+
+ <div className="space-y-4 mb-6 min-h-[200px]">
+ {messages.length === 0 && (
+ <p className="text-gray-400 text-center py-12">
+ Try: &quot;Star the composio repo on GitHub&quot;
+ </p>
+ )}
+ {messages.map((m) => (
+ <div key={m.id} className="flex gap-2">
+ <span className="font-semibold shrink-0">
+ {m.role === "user" ? "You:" : "Agent:"}
+ </span>
+ <div className="flex-1 whitespace-pre-wrap">
+ {m.parts.map((part, i) => {
+ if (part.type === "text") {
+ return (
+ <span key={i}>
+ {String(part.text)
+ .split(/(https?:\/\/[^\s)]+)/g)
+ .map((segment, j) =>
+ segment.match(/^https?:\/\//) ? (
+ <a key={j} href={segment} target="_blank" rel="noopener noreferrer" className="text-blue-600 underline">{segment}</a>
+ ) : (
+ segment
+ )
+ )}
+ </span>
+ );
+ }
+ if (isToolUIPart(part)) {
+ return (
+ <ToolCallDisplay
+ key={part.toolCallId}
+ toolName={getToolName(part)}
+ input={part.input}
+ output={
+ part.state === "output-available"
+ ? part.output
+ : undefined
+ }
+ isLoading={part.state !== "output-available"}
+ />
+ );
+ }
+ return null;
+ })}
+ </div>
+ </div>
+ ))}
+ {isLoading && (
+ <p className="text-gray-400 text-sm">Thinking...</p>
+ )}
+ </div>
+
+ <form
+ onSubmit={(e) => {
+ e.preventDefault();
+ if (!input.trim()) return;
+ sendMessage({ text: input });
+ setInput("");
+ }}
+ >
+ <input
+ value={input}
+ onChange={(e) => setInput(e.target.value)}
+ placeholder="Ask me anything..."
+ disabled={isLoading}
+ className="w-full p-3 border border-gray-300 rounded-lg"
+ />
+ </form>
+ </main>
+ );
+}
diff --git a/docs/examples/chat-app/page.tsx b/docs/examples/chat-app/page.tsx
new file mode 100644
index 000000000..32bc34ee2
--- /dev/null
+++ b/docs/examples/chat-app/page.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import { useState } from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+
+export default function Chat() {
+ const [input, setInput] = useState("");
+ const { messages, sendMessage, status } = useChat({
+ transport: new DefaultChatTransport({ api: "/api/chat" }),
+ });
+
+ const isLoading = status === "streaming" || status === "submitted";
+
+ return (
+ <main className="max-w-2xl mx-auto p-6">
+ <h1 className="text-2xl font-bold mb-6">Composio Chat</h1>
+
+ <div className="space-y-4 mb-6 min-h-[200px]">
+ {messages.length === 0 && (
+ <p className="text-gray-400 text-center py-12">
+ Try: &quot;Star the composio repo on GitHub&quot;
+ </p>
+ )}
+ {messages.map((m) => (
+ <div key={m.id} className="flex gap-2">
+ <span className="font-semibold shrink-0">
+ {m.role === "user" ? "You:" : "Agent:"}
+ </span>
+ <div className="whitespace-pre-wrap">
+ {m.parts.map((part, i) =>
+ part.type === "text" ? (
+ <span key={i}>
+ {String(part.text)
+ .split(/(https?:\/\/[^\s)]+)/g)
+ .map((segment, j) =>
+ segment.match(/^https?:\/\//) ? (
+ <a key={j} href={segment} target="_blank" rel="noopener noreferrer" className="text-blue-600 underline">{segment}</a>
+ ) : (
+ segment
+ )
+ )}
+ </span>
+ ) : null
+ )}
+ </div>
+ </div>
+ ))}
+ {isLoading && (
+ <p className="text-gray-400 text-sm">Thinking...</p>
+ )}
+ </div>
+
+ <form
+ onSubmit={(e) => {
+ e.preventDefault();
+ if (!input.trim()) return;
+ sendMessage({ text: input });
+ setInput("");
+ }}
+ >
+ <input
+ value={input}
+ onChange={(e) => setInput(e.target.value)}
+ placeholder="Ask me anything..."
+ disabled={isLoading}
+ className="w-full p-3 border border-gray-300 rounded-lg"
+ />
+ </form>
+ </main>
+ );
+}
diff --git a/docs/examples/chat-app/route.ts b/docs/examples/chat-app/route.ts
new file mode 100644
index 000000000..b0900f298
--- /dev/null
+++ b/docs/examples/chat-app/route.ts
@@ -0,0 +1,32 @@
+import { openai } from "@ai-sdk/openai";
+import { Composio } from "@composio/core";
+import { VercelProvider } from "@composio/vercel";
+import {
+ streamText,
+ convertToModelMessages,
+ generateId,
+ stepCountIs,
+ type UIMessage,
+} from "ai";
+
+const composio = new Composio({ provider: new VercelProvider() });
+
+export async function POST(req: Request) {
+ const { messages }: { messages: UIMessage[] } = await req.json();
+
+ const session = await composio.create("user_123");
+ const tools = await session.tools();
+
+ const result = streamText({
+ model: openai("gpt-5"),
+ system: "You are a helpful assistant. Use Composio tools to help the user.",
+ messages: await convertToModelMessages(messages),
+ tools,
+ stopWhen: stepCountIs(10),
+ });
+
+ return result.toUIMessageStreamResponse({
+ originalMessages: messages,
+ generateMessageId: () => generateId(),
+ });
+}
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 71df6c05f..b1cd7c0f3 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -227,6 +227,18 @@ export function mdxToCleanMarkdown(content: string): string {
'- [$2]($1): $3'
);
+ // Convert AIToolsBanner to plain text
+ result = result.replace(
+ /<AIToolsBanner\s*\/>/g,
+ '### For AI tools\n\n' +
+ '**Skills:**\n' +
+ '```bash\nnpx skills add composiohq/skills\n```\n' +
+ '[Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)\n\n' +
+ '**Context files:**\n' +
+ '- [llms.txt](/llms.txt) — Documentation index with links\n' +
+ '- [llms-full.txt](/llms-full.txt) — Complete documentation in one file'
+ );
+
// Remove wrapper components (Cards, ProviderGrid, Tabs, Frame, div, QuickstartFlow, IntegrationTabs, Accordions, ToolTypeFlow, ToolkitsLanding, TemplateGrid, etc.)
result = result.replace(/<\/?(Cards|ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid)[^>]*>/g, '');
diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsx
index 6b67b93a4..90e216b7b 100644
--- a/docs/mdx-components.tsx
+++ b/docs/mdx-components.tsx
@@ -20,6 +20,7 @@ import { CapabilityCard, CapabilityList } from '@/components/capability-card';
import { TemplateCard, TemplateGrid } from '@/components/template-card';
import { ToolkitsLanding } from '@/components/toolkits/toolkits-landing';
import { Mermaid } from '@/components/mermaid';
+import { AIToolsBanner } from '@/components/ai-tools-banner';
import {
ShieldCheck,
Route as RouteIcon,
@@ -86,6 +87,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
TemplateGrid,
ToolkitsLanding,
Mermaid,
+ AIToolsBanner,
StepTitle,
// Lucide icons
ShieldCheck,