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: Revamp provider pages — session pattern, tested code, no direct execution

Sushmithamalleshc8146a9dc202
diff --git a/docs/components/quickstart/integration-tabs.tsx b/docs/components/quickstart/integration-tabs.tsx
index 26ef93729..b9296901a 100644
--- a/docs/components/quickstart/integration-tabs.tsx
+++ b/docs/components/quickstart/integration-tabs.tsx
@@ -4,54 +4,52 @@ import Image from 'next/image';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
import { ReactNode } from 'react';
+interface TabConfig {
+ value: string;
+ label: string;
+ icon?: string;
+ iconDark?: string;
+}
+
+const defaultTabs: TabConfig[] = [
+ { value: 'native', label: 'Native Tools', icon: '/images/providers/native-tools-logo.svg', iconDark: '/images/providers/native-tools-logo-dark.svg' },
+ { value: 'mcp', label: 'MCP', icon: '/images/mcp-logo.svg', iconDark: '/images/mcp-logo-dark.svg' },
+];
+
interface IntegrationTabsProps {
children: ReactNode;
- defaultValue?: 'native' | 'mcp';
+ defaultValue?: string;
+ tabs?: TabConfig[];
}
-export function IntegrationTabs({ children, defaultValue = 'native' }: IntegrationTabsProps) {
+export function IntegrationTabs({ children, defaultValue, tabs = defaultTabs }: IntegrationTabsProps) {
return (
- <Tabs defaultValue={defaultValue} className="not-prose -mt-2">
+ <Tabs defaultValue={defaultValue ?? tabs[0]?.value ?? 'native'} className="not-prose -mt-2">
<div className="mb-5 flex justify-start">
<TabsList>
- <TabsTrigger value="native" className="gap-2">
- <div className="flex h-4 w-4 shrink-0 items-center justify-center">
- <Image
- src="/images/providers/native-tools-logo.svg"
- alt="Native Tools"
- width={16}
- height={16}
- className="h-4 w-4 dark:hidden"
- />
- <Image
- src="/images/providers/native-tools-logo-dark.svg"
- alt="Native Tools"
- width={16}
- height={16}
- className="hidden h-4 w-4 dark:block"
- />
- </div>
- Native Tools
- </TabsTrigger>
- <TabsTrigger value="mcp" className="gap-2">
- <div className="flex h-4 w-4 shrink-0 items-center justify-center">
- <Image
- src="/images/mcp-logo.svg"
- alt="MCP"
- width={16}
- height={16}
- className="h-4 w-4 dark:hidden"
- />
- <Image
- src="/images/mcp-logo-dark.svg"
- alt="MCP"
- width={16}
- height={16}
- className="hidden h-4 w-4 dark:block"
- />
- </div>
- MCP
- </TabsTrigger>
+ {tabs.map((tab) => (
+ <TabsTrigger key={tab.value} value={tab.value} className="gap-2">
+ {tab.icon && tab.iconDark && (
+ <div className="flex h-4 w-4 shrink-0 items-center justify-center">
+ <Image
+ src={tab.icon}
+ alt={tab.label}
+ width={16}
+ height={16}
+ className="h-4 w-4 dark:hidden"
+ />
+ <Image
+ src={tab.iconDark}
+ alt={tab.label}
+ width={16}
+ height={16}
+ className="hidden h-4 w-4 dark:block"
+ />
+ </div>
+ )}
+ {tab.label}
+ </TabsTrigger>
+ ))}
</TabsList>
</div>
{children}
@@ -63,7 +61,7 @@ export function IntegrationContent({
value,
children
}: {
- value: 'native' | 'mcp';
+ value: string;
children: ReactNode;
}) {
return <TabsContent value={value}>{children}</TabsContent>;
diff --git a/docs/content/docs/providers/anthropic.mdx b/docs/content/docs/providers/anthropic.mdx
index d970ba45a..0f9d364aa 100644
--- a/docs/content/docs/providers/anthropic.mdx
+++ b/docs/content/docs/providers/anthropic.mdx
@@ -371,93 +371,3 @@ console.log(result);
</Step>
</Steps>
-<Accordions>
-<Accordion title="Direct tool usage">
-<Callout type="info">
-Only use this if you want to use a single, direct tool with your AI Agent.
-</Callout>
-
-**Install**
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-```bash
-pip install composio composio-anthropic anthropic
-```
-</Tab>
-<Tab value="TypeScript">
-```bash
-npm install @composio/core @composio/anthropic @anthropic-ai/sdk
-```
-</Tab>
-</Tabs>
-
-**Usage**
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-```python
-import anthropic
-from composio import Composio
-from composio_anthropic import AnthropicProvider
-
-anthropic_client = anthropic.Anthropic()
-composio = Composio(provider=AnthropicProvider())
-
-external_user_id = "user_2nFh83Hde"
-recipient_email = "[email protected]"
-
-# Get a specific tool
-tools = composio.tools.get(user_id=external_user_id, tools=["GMAIL_SEND_EMAIL"])
-
-response = anthropic_client.messages.create(
- model="claude-sonnet-4-5",
- max_tokens=1024,
- tools=tools,
- messages=[
- {"role": "user", "content": f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'"},
- ],
-)
-
-result = composio.provider.handle_tool_calls(user_id=external_user_id, response=response)
-print(result)
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from "@composio/core";
-import { AnthropicProvider } from "@composio/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-const composio = new Composio({
- provider: new AnthropicProvider(),
-});
-const anthropic = new Anthropic();
-
-const externalUserId = "user_2nFh83Hde";
-const recipientEmail = "[email protected]";
-
-// Get a specific tool
-const tools = await composio.tools.get(externalUserId, {
- tools: ["GMAIL_SEND_EMAIL"],
-});
-
-const msg = await anthropic.messages.create({
- model: "claude-sonnet-4-5",
- messages: [
- {
- role: "user",
- content: `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`,
- },
- ],
- tools: tools,
- max_tokens: 1000,
-});
-
-const result = await composio.provider.handleToolCalls(externalUserId, msg);
-console.log(result);
-```
-</Tab>
-</Tabs>
-</Accordion>
-</Accordions>
diff --git a/docs/content/docs/providers/crewai.mdx b/docs/content/docs/providers/crewai.mdx
index ab180cd87..b3e35715d 100644
--- a/docs/content/docs/providers/crewai.mdx
+++ b/docs/content/docs/providers/crewai.mdx
@@ -4,14 +4,14 @@ description: Build an agent with CrewAI and enable it to use 800+ tools with Com
keywords: [crew]
---
-The CrewAI Provider formats the Composio tools into an object compatible with CrewAI's tool calling capabilities. Agents and LLM workflows built with this can call and execute the Composio tools.
+The CrewAI Provider formats Composio tools into an object compatible with CrewAI's tool calling capabilities.
## Setup
The CrewAI provider is available for only the Python SDK.
```bash
-pip install composio_crewai==0.8.0
+pip install composio composio_crewai crewai langchain_openai
```
## Usage
@@ -23,34 +23,26 @@ from langchain_openai import ChatOpenAI
from composio import Composio
from composio_crewai import CrewAIProvider
-# Initialize tools.
openai_client = ChatOpenAI()
composio = Composio(provider=CrewAIProvider())
-# Get All the tools
-tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
-# Define agent
crewai_agent = Agent(
role="Github Agent",
- goal="""You take action on Github using Github APIs""",
- backstory=(
- "You are AI agent that is responsible for taking actions on Github "
- "on users' behalf. You need to take action on Github using Github APIs"
- ),
+ goal="You take action on Github using Github APIs",
+ backstory="You are an AI agent that takes actions on Github on users' behalf.",
verbose=True,
tools=tools,
llm=openai_client,
)
-# Define task
task = Task(
- description=(
- "Star a repo composiohq/composio on GitHub, if the action is successful "
- "include Action executed successfully"
- ),
+ description="Star the composiohq/composio repository on GitHub",
agent=crewai_agent,
- expected_output="if the star happened",
+ expected_output="Whether the star action succeeded",
)
my_crew = Crew(agents=[crewai_agent], tasks=[task])
diff --git a/docs/content/docs/providers/google.mdx b/docs/content/docs/providers/google.mdx
index 17643c5d1..a085a51a9 100644
--- a/docs/content/docs/providers/google.mdx
+++ b/docs/content/docs/providers/google.mdx
@@ -4,105 +4,78 @@ description: Build an agent with Gemini and enable it to use 800+ tools with Com
keywords: [gemini]
---
-The Google provider transforms Composio tools into a format compatible with Gemini's function calling capabilities through it's API
+The Google provider transforms Composio tools into a format compatible with Gemini's function calling capabilities through its API.
## Setup
<Tabs items={["Python", "TypeScript"]}>
<Tab value="Python">
```bash
-pip install google-genai composio_google
+pip install composio composio_google google-genai
```
</Tab>
<Tab value="TypeScript">
```bash
-npm install @google/genai
-npm i @composio/core @composio/gemini
+npm install @composio/core @composio/google @google/genai
```
</Tab>
</Tabs>
+## Usage
+
<Tabs items={["Python", "TypeScript"]}>
<Tab value="Python">
```python
from composio import Composio
-from composio_gemini import GeminiProvider
+from composio_google import GoogleProvider
from google import genai
from google.genai import types
-# Create composio client
-composio = Composio(provider=GeminiProvider())
-# Create google client
+composio = Composio(provider=GoogleProvider())
client = genai.Client()
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import {Composio} from '@composio/core';
-import {GoogleProvider} from '@composio/google'
-import {GoogleGenAI} from '@google/genai'
-
-const composio = new Composio({
- apiKey: "your-composio-api-key",
- provider: new GoogleProvider()
-})
-
-const ai = new GoogleGenAI({
- apiKey: "your-gemini-api-key"
-})
-```
-</Tab>
-</Tabs>
-## Usage
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-```python
-user_id = "0000-1111-2222"
-tools = composio.tools.get(user_id, tools=["COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH"])
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
-# Create genai client config
config = types.GenerateContentConfig(tools=tools)
-# # Use the chat interface.
chat = client.chats.create(model="gemini-2.0-flash", config=config)
-response = chat.send_message("search about the latest info on windsurf acquisition.")
+response = chat.send_message("Star the composiohq/composio repository on github")
print(response.text)
```
</Tab>
<Tab value="TypeScript">
```typescript
-import {Composio} from '@composio/core';
-import {GoogleProvider} from '@composio/google'
-import {GoogleGenAI} from '@google/genai'
-const composio = new Composio({ apiKey: "key", provider: new GoogleProvider() });
-const ai = new GoogleGenAI({ apiKey: "key" });
-// ---cut---
-// Use a unique identifier for each user in your application
-const user_id = "your-external-user-id"
+import { Composio } from '@composio/core';
+import { GoogleProvider } from '@composio/google';
+import { GoogleGenAI } from '@google/genai';
+
+const composio = new Composio({
+ provider: new GoogleProvider(),
+});
+const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });
-// Get tools - this returns already wrapped tools when using GoogleProvider
-const tools = await composio.tools.get(user_id, 'HACKERNEWS_GET_USER')
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
const response = await ai.models.generateContent({
model: 'gemini-2.0-flash-001',
- contents: "Search for the user 'pg's",
+ contents: "Star the composiohq/composio repository on github",
config: {
tools: [{ functionDeclarations: tools }],
},
});
if (response.functionCalls && response.functionCalls.length > 0) {
- console.log(`Calling tool ${response.functionCalls[0].name}`);
const functionCall = {
name: response.functionCalls[0].name || '',
args: response.functionCalls[0].args || {},
};
- const result = await composio.provider.executeToolCall(user_id, functionCall);
- console.log(`Result: ${result}`);
+ const result = await composio.provider.executeToolCall("user_123", functionCall);
+ console.log(result);
} else {
- console.log('No function calls in the response');
console.log(response.text);
}
```
diff --git a/docs/content/docs/providers/langchain.mdx b/docs/content/docs/providers/langchain.mdx
index 209f5db7f..9751665f5 100644
--- a/docs/content/docs/providers/langchain.mdx
+++ b/docs/content/docs/providers/langchain.mdx
@@ -11,12 +11,12 @@ The LangChain Provider transforms Composio tools into a format compatible with L
<Tabs items={["Python", "TypeScript"]}>
<Tab value="Python">
```bash
-pip install composio_langchain==0.8.0 langchain
+pip install composio composio_langchain langchain langchain_openai
```
</Tab>
<Tab value="TypeScript">
```bash
-npm install @composio/langchain
+npm install @composio/core @composio/langchain @langchain/openai @langchain/langgraph @langchain/core
```
</Tab>
</Tabs>
@@ -32,26 +32,19 @@ from langchain import hub # type: ignore
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI
-# Pull relevant agent model.
prompt = hub.pull("hwchase17/openai-functions-agent")
-
-# Initialize tools.
openai_client = ChatOpenAI(model="gpt-5")
composio = Composio(provider=LangchainProvider())
-# Get All the tools
-tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])
-
-# Define task
-task = "Star a repo composiohq/composio on GitHub"
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
-# Define agent
agent = create_openai_functions_agent(openai_client, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
-# Execute using agent_executor
-agent_executor.invoke({"input": task})
+agent_executor.invoke({"input": "Star the composiohq/composio repository on GitHub"})
```
</Tab>
<Tab value="TypeScript">
@@ -63,71 +56,47 @@ import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';
import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';
-// initiate composio
const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
provider: new LangchainProvider(),
});
-// fetch the tool
-console.log(`🔄 Fetching the tool...`);
-const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER');
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
-// Define the tools for the agent to use
const toolNode = new ToolNode(tools);
-// Create a model and give it access to the tools
const model = new ChatOpenAI({
model: 'gpt-4o-mini',
temperature: 0,
}).bindTools(tools);
-// Define the function that determines whether to continue or not
function shouldContinue({ messages }: typeof MessagesAnnotation.State) {
const lastMessage = messages[messages.length - 1] as AIMessage;
-
- // If the LLM makes a tool call, then we route to the "tools" node
if (lastMessage.tool_calls?.length) {
return 'tools';
}
- // Otherwise, we stop (reply to the user) using the special "__end__" node
return '__end__';
}
-// Define the function that calls the model
async function callModel(state: typeof MessagesAnnotation.State) {
- console.log(`🔄 Calling the model...`);
const response = await model.invoke(state.messages);
-
- // We return a list, because this will get added to the existing list
return { messages: [response] };
}
-// Define a new graph
const workflow = new StateGraph(MessagesAnnotation)
.addNode('agent', callModel)
- .addEdge('__start__', 'agent') // __start__ is a special name for the entrypoint
+ .addEdge('__start__', 'agent')
.addNode('tools', toolNode)
.addEdge('tools', 'agent')
.addConditionalEdges('agent', shouldContinue);
-// Finally, we compile it into a LangChain Runnable.
const app = workflow.compile();
-// Use the agent
const finalState = await app.invoke({
- messages: [new HumanMessage('Find the details of the user `pg` on HackerNews')],
+ messages: [new HumanMessage('Star the composiohq/composio repository on GitHub')],
});
-console.log(`✅ Message recieved from the model`);
console.log(finalState.messages[finalState.messages.length - 1].content);
-
-const nextState = await app.invoke({
- // Including the messages from the previous run gives the LLM context.
- // This way it knows we're asking about the weather in NY
- messages: [...finalState.messages, new HumanMessage('what about haxzie')],
-});
-console.log(`✅ Message recieved from the model`);
-console.log(nextState.messages[nextState.messages.length - 1].content);
```
</Tab>
</Tabs>
diff --git a/docs/content/docs/providers/llamaindex.mdx b/docs/content/docs/providers/llamaindex.mdx
index bb1fa45b3..a0fe5c57a 100644
--- a/docs/content/docs/providers/llamaindex.mdx
+++ b/docs/content/docs/providers/llamaindex.mdx
@@ -11,12 +11,12 @@ The LlamaIndex Provider transforms Composio tools into a format compatible with
<Tabs items={["Python", "TypeScript"]}>
<Tab value="Python">
```bash
-pip install composio_llamaindex==0.8.0 llama-index
+pip install composio composio_llamaindex llama-index
```
</Tab>
<Tab value="TypeScript">
```bash
-npm install @composio/llamaindex @llamaindex/openai @llamaindex/workflow
+npm install @composio/core @composio/llamaindex @llamaindex/openai @llamaindex/workflow
```
</Tab>
</Tabs>
@@ -27,24 +27,20 @@ npm install @composio/llamaindex @llamaindex/openai @llamaindex/workflow
<Tab value="Python">
```python
import asyncio
-import dotenv
+from dotenv import load_dotenv
+from composio import Composio
from composio_llamaindex import LlamaIndexProvider
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
-from composio import Composio
-
-# Load environment variables from .env
-dotenv.load_dotenv()
+load_dotenv()
-# Setup client
llm = OpenAI(model="gpt-5")
composio = Composio(provider=LlamaIndexProvider())
-tools = composio.tools.get(
- user_id="[email protected]",
- tools=["GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"],
-)
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
workflow = FunctionAgent(
tools=tools,
@@ -55,7 +51,7 @@ workflow = FunctionAgent(
async def main():
result = await workflow.run(
- user_msg="Hello! I would like to star a repo composiohq/composio on GitHub"
+ user_msg="Star the composiohq/composio repository on GitHub"
)
print(result)
@@ -66,102 +62,33 @@ if __name__ == "__main__":
</Tab>
<Tab value="TypeScript">
```typescript
+import 'dotenv/config';
import { Composio } from '@composio/core';
import { LlamaindexProvider } from '@composio/llamaindex';
import { openai } from '@llamaindex/openai';
import { agent } from '@llamaindex/workflow';
-import 'dotenv/config';
-// Initialize Composio with LlamaIndex provider
const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
provider: new LlamaindexProvider(),
});
-async function main() {
- // Get tools
- const tools = await composio.tools.get('[email protected]', {
- tools: ['GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER'],
- });
-
- // Create LlamaIndex agent with Composio tools
- const githubAgent = agent({
- name: 'GitHub Agent',
- description: 'An agent that performs GitHub actions',
- llm: openai({ model: 'gpt-4o-mini' }),
- systemPrompt: 'You are an agent that performs github actions.',
- tools,
- });
-
- // Run the agent
- const result = await githubAgent.run(
- 'Hello! I would like to star a repo composiohq/composio on GitHub'
- );
-
- console.log(result);
-}
-
-main().catch(console.error);
-```
-</Tab>
-</Tabs>
-
-## Advanced Usage
-
-### Streaming Agent with Multiple Toolkits
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
-```typescript
-import { Composio } from '@composio/core';
-import { LlamaindexProvider } from '@composio/llamaindex';
-import { openai } from '@llamaindex/openai';
-import { agent, agentStreamEvent } from '@llamaindex/workflow';
-import 'dotenv/config';
-
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
- provider: new LlamaindexProvider(),
+const githubAgent = agent({
+ name: 'GitHub Agent',
+ description: 'An agent that performs GitHub actions',
+ llm: openai({ model: 'gpt-4o-mini' }),
+ systemPrompt: 'You are an agent that performs github actions.',
+ tools,
});
-async function streamingExample() {
- // Get tools from multiple toolkits with execution modifiers
- const tools = await composio.tools.get(
- 'default',
- {
- toolkits: ['gmail', 'googlecalendar', 'slack'],
- limit: 20,
- },
- {
- beforeExecute: ({ toolSlug, params }) => {
- console.log(`🔄 Executing ${toolSlug} with:`, params);
- return params;
- },
- afterExecute: ({ toolSlug, result }) => {
- console.log(`✅ ${toolSlug} completed:`, result);
- return result;
- },
- }
- );
-
- // Create streaming agent
- const assistantAgent = agent({
- name: 'Personal Assistant',
- description: 'A helpful personal assistant',
- llm: openai({ model: 'gpt-4o-mini' }),
- systemPrompt: 'You are a helpful personal assistant that can manage emails, calendar events, and slack messages.',
- tools,
- });
-
- // Stream the response
- const stream = await assistantAgent.runStream(
- 'Schedule a meeting for tomorrow at 2 PM and send a slack message about it'
- );
-
- for await (const event of stream) {
- if (agentStreamEvent.include(event)) {
- process.stdout.write(event.data.delta);
- }
- }
-}
-
-streamingExample().catch(console.error);
+const result = await githubAgent.run(
+ 'Star the composiohq/composio repository on GitHub'
+);
+
+console.log(result);
```
+</Tab>
+</Tabs>
diff --git a/docs/content/docs/providers/mastra.mdx b/docs/content/docs/providers/mastra.mdx
index 1af676cf7..d46c8d339 100644
--- a/docs/content/docs/providers/mastra.mdx
+++ b/docs/content/docs/providers/mastra.mdx
@@ -4,23 +4,15 @@ description: Build an agent with Mastra and enable it to use 800+ tools with Com
keywords: [mastra]
---
-Mastra is a TypeScript native framework for building agents with tools and MCPs. It expects tools to be in the following format:
-- Inputs: What information the tool needs to run (defined with an `inputSchema`, often using Zod).
-- Outputs: The structure of the data the tool returns (defined with an `outputSchema`).
-- Execution Logic: The code that performs the tool's action.
-- Description: Text that helps the agent understand what the tool does and when to use it.
-
-More documentation [here](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools)
-
-The Mastra provider formats the Composio tools into this format along with the execution logic so that agents can call and execute the Composio tools.
+The Mastra provider formats Composio tools into a format compatible with [Mastra](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools)'s tool calling capabilities, including input schemas, execution logic, and descriptions.
## Setup
```bash
-npm install @composio/mastra
+npm install @composio/core @composio/mastra @mastra/core @ai-sdk/openai
```
-You can specify the provider in the constructor.
+## Usage
```typescript
import { Composio } from "@composio/core";
@@ -31,45 +23,27 @@ import { openai } from "@ai-sdk/openai";
const composio = new Composio({
provider: new MastraProvider(),
});
-```
-
-## Usage
-The tools are passed to the agent as a parameter.
-
-```typescript
-import { Composio } from "@composio/core";
-import { MastraProvider } from "@composio/mastra";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-const composio = new Composio({ provider: new MastraProvider() });
-// ---cut---
-const userId = "john doe";
-
-const tools = await composio.tools.get(
- userId,
- {
- toolkits: ["SUPABASE"],
- }
-);
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
const agent = new Agent({
- id: "supabase-agent",
- name: "Supabase Agent",
- instructions: "You think therefore you are.",
+ id: "github-agent",
+ name: "GitHub Agent",
+ instructions: "You are a helpful assistant that can perform GitHub actions.",
model: openai("gpt-4.1"),
tools: tools,
});
const { text } = await agent.generate([
- { role: "user", content: "Tell me about my Supabase project" },
+ { role: "user", content: "Star the composiohq/composio repository on GitHub" },
]);
-console.log("\n🤖 Agent Response:\n");
console.log(text);
```
-## Usage: Direct MCP Servers
+## Usage with MCP
You can also use Composio MCP servers directly with Mastra's MCPClient.
@@ -84,52 +58,29 @@ import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { Composio } from "@composio/core";
-// Initialize Composio
const composio = new Composio();
-// Create MCP server with GitHub, Linear, and Notion tools
-const server = await composio.mcp.create(
- "dev-automation-server",
- {
- toolkits: [
- { toolkit: "github", authConfigId: "ac_github_id" },
- { toolkit: "linear", authConfigId: "ac_linear_id" },
- { toolkit: "notion", authConfigId: "ac_notion_id" }
- ],
- allowedTools: [
- "GITHUB_LIST_ISSUES", "GITHUB_CREATE_ISSUE",
- "LINEAR_CREATE_ISSUE", "LINEAR_UPDATE_ISSUE",
- "NOTION_CREATE_PAGE", "NOTION_UPDATE_PAGE"
- ]
- }
-);
-
-// Generate MCP instance for user
-const instance = await server.generate("[email protected]");
+// Create a session for your user
+const session = await composio.create("user_123");
-// Create MCP client with Composio server
-export const mcpClient = new MCPClient({
+// Create MCP client with the session's MCP server
+const mcpClient = new MCPClient({
id: "composio-mcp-client",
servers: {
- composio: { url: new URL(instance.url) },
+ composio: { url: new URL(session.mcp.url) },
}
});
-// Create a development workflow agent
-export const devAgent = new Agent({
+const agent = new Agent({
id: "dev-assistant",
name: "Dev Assistant",
- description: "AI assistant for development workflow automation",
instructions: "Help manage GitHub repos, Linear issues, and Notion documentation.",
model: openai("gpt-4-turbo"),
tools: await mcpClient.getTools()
});
-// Example: Automate development workflow
-(async () => {
- const response = await devAgent.generate(
- "Review open GitHub issues, create Linear tasks for bugs labeled 'priority', and update the Notion roadmap page"
- );
- console.log(response.text);
-})();
+const response = await agent.generate(
+ "Star the composiohq/composio repository on GitHub"
+);
+console.log(response.text);
```
diff --git a/docs/content/docs/providers/openai-agents.mdx b/docs/content/docs/providers/openai-agents.mdx
index a9be32ec3..c12dde676 100644
--- a/docs/content/docs/providers/openai-agents.mdx
+++ b/docs/content/docs/providers/openai-agents.mdx
@@ -259,98 +259,3 @@ if (result.finalOutput) {
</ToolTypeFlow>
-<Accordions>
-<Accordion title="Direct tool usage">
-<Callout type="info">
-Only use this if you want to use a single, direct tool with your AI Agent.
-</Callout>
-
-**Install**
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-```bash
-pip install composio openai-agents composio-openai-agents
-```
-</Tab>
-<Tab value="TypeScript">
-```bash
-npm install @composio/core @openai/agents @composio/openai-agents
-```
-</Tab>
-</Tabs>
-
-**Usage**
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-```python
-import asyncio
-from composio import Composio
-from agents import Agent, Runner
-from composio_openai_agents import OpenAIAgentsProvider
-
-composio = Composio(provider=OpenAIAgentsProvider())
-
-external_user_id = "user_2nFh83Hde"
-recipient_email = "[email protected]"
-
-# Get a specific tool
-tools = composio.tools.get(user_id=external_user_id, tools=["GMAIL_SEND_EMAIL"])
-
-agent = Agent(
- name="Email Manager",
- instructions="You are a helpful assistant.",
- tools=tools,
-)
-
-async def main():
- result = await Runner.run(
- starting_agent=agent,
- input=f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'",
- )
- print(result.final_output)
-
-asyncio.run(main())
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from "@composio/core";
-import { Agent, run } from "@openai/agents";
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
-
-const composio = new Composio({
- provider: new OpenAIAgentsProvider(),
-});
-
-const externalUserId = "user_2nFh83Hde";
-const recipientEmail = "[email protected]";
-
-// Get a specific tool
-const tools = await composio.tools.get(externalUserId, {
- tools: ["GMAIL_SEND_EMAIL"],
-});
-
-const agent = new Agent({
- name: "Email Manager",
- instructions: "You are a helpful assistant.",
- tools: tools,
-});
-
-console.log("Running agent...");
-const result = await run(
- agent,
- `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`
-);
-
-console.log("Received response from agent");
-if (result.finalOutput) {
- console.log(result.finalOutput);
-}
-```
-</Tab>
-</Tabs>
-</Accordion>
-
-</Accordions>
diff --git a/docs/content/docs/providers/openai.mdx b/docs/content/docs/providers/openai.mdx
index 04d354503..fdd17220e 100644
--- a/docs/content/docs/providers/openai.mdx
+++ b/docs/content/docs/providers/openai.mdx
@@ -6,65 +6,94 @@ keywords: [gpt, responses api, chat completions]
The OpenAI Provider is the default provider for the Composio SDK. It transforms Composio tools into a format compatible with OpenAI's function calling capabilities through both the Responses and Chat Completion APIs.
-## Setup
+<IntegrationTabs tabs={[
+ { value: "responses", label: "Responses API" },
+ { value: "chat", label: "Chat Completions" },
+]}>
-By default, the OpenAI Provider is installed when you install the Composio SDK. You can also install it manually:
+<IntegrationContent value="responses">
+<Steps>
+<Step>
+**Install**
-<Tabs items={["Python", "TypeScript"]}>
+<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```bash
-pip install composio_openai
+pip install composio composio_openai openai
```
</Tab>
<Tab value="TypeScript">
```bash
-npm install @composio/openai
+npm install @composio/core @composio/openai openai
```
</Tab>
</Tabs>
+</Step>
-## Responses API
+<Step>
+**Configure API Keys**
-The Responses API is the recommended way to build more agentic flows with the OpenAI API.
-Read more about it in the [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses)
-
-<Callout>
-Before executing any tools that require authentication (like Gmail), you'll need to:
-1. [Create an Auth Configuration](/docs/tools-direct/authenticating-tools#creating-an-auth-config) for your app
-2. [Set up a Connected Account](/docs/tools-direct/authenticating-tools#connecting-an-account) for the user.
+<Callout type="info">
+Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `OPENAI_API_KEY` with your [OpenAI API key](https://platform.openai.com/api-keys).
</Callout>
-<Tabs items={["Python", "TypeScript"]}>
+```txt title=".env"
+COMPOSIO_API_KEY=xxxxxxxxx
+OPENAI_API_KEY=xxxxxxxxx
+```
+</Step>
+
+<Step>
+**Create session and run**
+
+The [Responses API](https://platform.openai.com/docs/api-reference/responses) is the recommended way to build agentic flows with OpenAI.
+
+<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```python
+import json
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIResponsesProvider
-# Initialize Composio client with OpenAI Provider
composio = Composio(provider=OpenAIResponsesProvider())
-openai = OpenAI()
+client = OpenAI()
-# Make sure to create an auth config and a connected account for the user with gmail toolkit
-# Make sure to replace "your-user-id" with the actual user ID
-user_id = "your-user-id"
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
-tools = composio.tools.get(user_id=user_id, tools=["GMAIL_SEND_EMAIL"])
-
-response = openai.responses.create(
- model="gpt-5",
+response = client.responses.create(
+ model="gpt-5.2",
tools=tools,
input=[
{
"role": "user",
- "content": "Send an email to [email protected] with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"
+ "content": "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"
}
]
)
-# Execute the function calls
-result = composio.provider.handle_tool_calls(response=response, user_id=user_id)
-print(result)
+# Agentic loop — keep executing tool calls until the model responds with text
+while True:
+ tool_calls = [o for o in response.output if o.type == "function_call"]
+ if not tool_calls:
+ break
+ results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
+ response = client.responses.create(
+ model="gpt-5.2",
+ tools=tools,
+ previous_response_id=response.id,
+ input=[
+ {"type": "function_call_output", "call_id": tool_calls[i].call_id, "output": json.dumps(result)}
+ for i, result in enumerate(results)
+ ]
+ )
+
+# Print final response
+for item in response.output:
+ if item.type == "message":
+ print(item.content[0].text)
```
</Tab>
<Tab value="TypeScript">
@@ -73,83 +102,140 @@ import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIResponsesProvider } from '@composio/openai';
-// Initialize Composio client with OpenAI Provider
const composio = new Composio({
provider: new OpenAIResponsesProvider(),
});
-const openai = new OpenAI({});
-
-// Make sure to create an auth config and a connected account for the user with gmail toolkit
-// Make sure to replace "your-user-id" with the actual user ID
-const userId = "your-user-id";
-
-async function main() {
- try {
- const tools = await composio.tools.get(userId, {tools: ["GMAIL_SEND_EMAIL"]});
-
- const response = await openai.responses.create({
- model: "gpt-5",
- tools: tools,
- input: [
- {
- role: "user",
- content: "Send an email to [email protected] with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"
- },
- ],
- });
+const client = new OpenAI();
- // Execute the function calls
- const result = await composio.provider.handleToolCalls(userId, response.output);
- console.log(result);
- } catch (error) {
- console.error('Error:', error);
- }
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
+
+let response = await client.responses.create({
+ model: "gpt-5.2",
+ tools: tools,
+ input: [
+ {
+ role: "user",
+ content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"
+ },
+ ],
+});
+
+// Agentic loop — keep executing tool calls until the model responds with text
+while (true) {
+ const toolCalls = response.output.filter((o) => o.type === "function_call");
+ if (toolCalls.length === 0) break;
+
+ const results = await composio.provider.handleToolCalls("user_123", response.output);
+ response = await client.responses.create({
+ model: "gpt-5.2",
+ tools: tools,
+ previous_response_id: response.id,
+ input: results.map((result, i) => ({
+ type: "function_call_output" as const,
+ call_id: toolCalls[i].call_id,
+ output: JSON.stringify(result),
+ })),
+ });
}
-main();
+// Print final response
+for (const item of response.output) {
+ if (item.type === "message") {
+ const block = item.content[0];
+ if (block.type === "output_text") {
+ console.log(block.text);
+ }
+ }
+}
```
</Tab>
</Tabs>
+</Step>
+</Steps>
+</IntegrationContent>
+
+<IntegrationContent value="chat">
+<Steps>
+<Step>
+**Install**
-## Chat Completion API
+<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
+<Tab value="Python">
+```bash
+pip install composio composio_openai openai
+```
+</Tab>
+<Tab value="TypeScript">
+```bash
+npm install @composio/core @composio/openai openai
+```
+</Tab>
+</Tabs>
+</Step>
-The Chat Completion API generates a model response from a list of messages. Read more about it in the [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat).
-The OpenAI Chat Provider is the default provider used by Composio SDK, but you can also explicitly initialise it.
+<Step>
+**Configure API Keys**
-<Callout>
-Before executing any tools that require authentication (like Gmail), you'll need to:
-1. [Create an Auth Configuration](/docs/tools-direct/authenticating-tools#creating-an-auth-config) for your app
-2. [Set up a Connected Account](/docs/tools-direct/authenticating-tools#connecting-an-account) for the user.
+<Callout type="info">
+Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `OPENAI_API_KEY` with your [OpenAI API key](https://platform.openai.com/api-keys).
</Callout>
-<Tabs items={["Python", "TypeScript"]}>
+```txt title=".env"
+COMPOSIO_API_KEY=xxxxxxxxx
+OPENAI_API_KEY=xxxxxxxxx
+```
+</Step>
+
+<Step>
+**Create session and run**
+
+The [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) generates a model response from a list of messages.
+The `OpenAIProvider` (Chat Completions) is the default provider used by Composio SDK.
+
+<Tabs groupId="language" items={["Python", "TypeScript"]} persist>
<Tab value="Python">
```python
+import json
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIProvider
-# Initialize Composio client with OpenAI Provider
composio = Composio(provider=OpenAIProvider())
-openai = OpenAI()
+client = OpenAI()
-# Make sure to create an auth config and a connected account for the user with gmail toolkit
-# Make sure to replace "your-user-id" with the actual user ID
-user_id = "your-user-id"
+# Create a session for your user
+session = composio.create(user_id="user_123")
+tools = session.tools()
-tools = composio.tools.get(user_id=user_id, tools=["GMAIL_SEND_EMAIL"])
+messages = [
+ {"role": "user", "content": "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"}
+]
-response = openai.chat.completions.create(
- model="gpt-5",
+response = client.chat.completions.create(
+ model="gpt-5.2",
tools=tools,
- messages=[
- {"role": "user", "content": "Send an email to [email protected] with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"},
- ],
+ messages=messages,
)
-# Execute the function calls
-result = composio.provider.handle_tool_calls(response=response, user_id=user_id)
-print(result)
+# Agentic loop — keep executing tool calls until the model responds with text
+while response.choices[0].message.tool_calls:
+ results = composio.provider.handle_tool_calls(response=response, user_id="user_123")
+ messages.append(response.choices[0].message)
+ for i, tc in enumerate(response.choices[0].message.tool_calls):
+ messages.append({
+ "role": "tool",
+ "tool_call_id": tc.id,
+ "content": json.dumps(results[i]),
+ })
+ response = client.chat.completions.create(
+ model="gpt-5.2",
+ tools=tools,
+ messages=messages,
+ )
+
+print(response.choices[0].message.content)
```
</Tab>
<Tab value="TypeScript">
@@ -158,41 +244,52 @@ import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
-// Initialize Composio client with OpenAI Provider
const composio = new Composio({
provider: new OpenAIProvider(),
});
+const client = new OpenAI();
+
+// Create a session for your user
+const session = await composio.create("user_123");
+const tools = await session.tools();
+
+const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+ {
+ role: "user",
+ content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"
+ },
+];
+
+let response = await client.chat.completions.create({
+ model: "gpt-5.2",
+ tools: tools,
+ messages: messages,
+});
-const openai = new OpenAI();
-
-// Make sure to create an auth config and a connected account for the user with gmail toolkit
-// Make sure to replace "your-user-id" with the actual user ID
-const userId = "your-user-id";
-
-async function main() {
- try {
- const tools = await composio.tools.get(userId, {tools: ["GMAIL_SEND_EMAIL"]});
-
- const response = await openai.chat.completions.create({
- model: "gpt-5",
- tools: tools,
- messages: [
- {
- role: "user",
- content: "Send an email to [email protected] with the subject 'Running OpenAI Provider snippet' and body 'Hello from the code snippet in openai docs'"
- },
- ],
+// Agentic loop — keep executing tool calls until the model responds with text
+while (response.choices[0].message.tool_calls) {
+ const results = await composio.provider.handleToolCalls("user_123", response);
+ messages.push(response.choices[0].message);
+ for (const [i, tc] of response.choices[0].message.tool_calls.entries()) {
+ messages.push({
+ role: "tool",
+ tool_call_id: tc.id,
+ content: JSON.stringify(results[i]),
});
-
- // Execute the function calls
- const result = await composio.provider.handleToolCalls(userId, response);
- console.log(result);
- } catch (error) {
- console.error('Error:', error);
}
+ response = await client.chat.completions.create({
+ model: "gpt-5.2",
+ tools: tools,
+ messages: messages,
+ });
}
-main();
+console.log(response.choices[0].message.content);
```
</Tab>
</Tabs>
+</Step>
+</Steps>
+</IntegrationContent>
+
+</IntegrationTabs>
diff --git a/docs/content/docs/providers/vercel.mdx b/docs/content/docs/providers/vercel.mdx
index 243f624ed..ba0796142 100644
--- a/docs/content/docs/providers/vercel.mdx
+++ b/docs/content/docs/providers/vercel.mdx
@@ -138,54 +138,3 @@ console.log("\n\n---");
console.log("Tip: If prompted to authenticate, complete the auth flow and run again.")
```
-## Usage with direct tools
-
-### Setup
-
-Vercel AI SDK and the provider are only available for the TypeScript SDK.
-
-```bash
-npm install @composio/vercel
-```
-
-You can specify and import the provider in the constructor.
-
-```typescript
-import { Composio } from '@composio/core';
-import { VercelProvider } from '@composio/vercel';
-import { generateText } from 'ai';
-import { openai } from "@ai-sdk/openai";
-
-const composio = new Composio({
- provider: new VercelProvider(),
-});
-```
-
-### Usage
-
-```typescript
-import { Composio } from '@composio/core';
-import { VercelProvider } from '@composio/vercel';
-import { generateText } from 'ai';
-import { openai } from "@ai-sdk/openai";
-const composio = new Composio({ provider: new VercelProvider() });
-// ---cut---
-// create an auth config for gmail
-// then create a connected account with an external user id that identifies the user
-const externalUserId = "your-external-user-id";
-const tools = await composio.tools.get(externalUserId, "GMAIL_SEND_EMAIL");
-
-// env: OPENAI_API_KEY
-const { text } = await generateText({
- model: openai("gpt-5"),
- messages: [
- {
- role: "user",
- content: `Send an email to [email protected] with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'`,
- },
- ],
- tools,
-});
-
-console.log("Email sent successfully!", { text });
-```
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 3d037c1f7..71df6c05f 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -171,10 +171,24 @@ export function mdxToCleanMarkdown(content: string): string {
);
result = result.replace(/<\/FrameworkOption>/g, '');
- // Convert IntegrationContent to labeled section (Native Tools / MCP)
+ // Convert IntegrationTabs — extract label from tabs prop if present
+ const tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };
+ result = result.replace(
+ /<IntegrationTabs[\s\S]*?tabs=\{\[([\s\S]*?)\]\}[\s\S]*?>/g,
+ (_, tabsContent: string) => {
+ const labelRegex = /value:\s*"([^"]+)"[\s\S]*?label:\s*"([^"]+)"/g;
+ let match;
+ while ((match = labelRegex.exec(tabsContent)) !== null) {
+ tabLabelMap[match[1]] = match[2];
+ }
+ return '';
+ }
+ );
+
+ // Convert IntegrationContent to labeled section
result = result.replace(
/<IntegrationContent[\s\S]*?value="([^"]*)"[\s\S]*?>/g,
- (_, value) => `\n### ${value === 'native' ? 'Native Tools' : 'MCP'}\n`
+ (_, value: string) => `\n### ${tabLabelMap[value] || value}\n`
);
result = result.replace(/<\/IntegrationContent>/g, '');