Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: refresh README(s) (#3801)
Rahul Tarakcaef908075a3
diff --git a/README.md b/README.mdindex d22c365e2..11f101555 100644--- a/README.md+++ b/README.md@@ -1,257 +1,184 @@+<p align="center">+ <a href="https://composio.dev">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="https://brand.composio.dev/logos/Logomark-White.svg">+ <img alt="Composio logo" src="https://brand.composio.dev/logos/Logomark-Black.svg" width="96">+ </picture>+ </a>+</p>-<div align="center">+<p align="center">+ <a href="https://composio.dev"><b>composio.dev</b></a> •+ <a href="https://docs.composio.dev">Documentation</a> •+ <a href="https://docs.composio.dev/docs/quickstart">Quickstart</a>+</p>-<img src="https://raw.githubusercontent.com/ComposioHQ/composio/next/public/cover.png" alt="Composio Logo" width="auto" height="auto" style="margin-bottom: 20px;"/>+<p align="center">+ <a href="https://github.com/ComposioHQ/composio/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ComposioHQ/composio?style=social" /></a>+ <a href="https://www.npmjs.com/package/@composio/core"><img alt="npm" src="https://img.shields.io/npm/v/@composio/core?label=%40composio%2Fcore" /></a>+ <a href="https://pypi.org/project/composio/"><img alt="PyPI" src="https://img.shields.io/pypi/v/composio?label=composio" /></a>+ <a href="https://discord.gg/composio"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?logo=discord&logoColor=white" /></a>+ <a href="https://hvtracker.net/agents/composio/"><img alt="HVTrust" src="https://hvtracker.net/badge/composio.svg" /></a>+</p>+# Composio-# Composio SDK+Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox, so you can ship agents that turn intent into action.-Skills that evolve for your Agents+This is the Composio SDK monorepo. It contains:-[🌐 Website](https://composio.dev) • [📚 Documentation](https://docs.composio.dev)+- **[`@composio/core`](ts/packages/core)**: TypeScript SDK+- **[`composio`](python)**: Python SDK+- **[`composio` CLI](ts/packages/cli)**: search, execute, and script tools from your shell+- **Provider adapters** for OpenAI Agents, Claude Agent SDK, Vercel AI SDK, LangChain, and [more](#providers)-[](https://github.com/ComposioHQ/composio/stargazers)-[](https://pypi.org/project/composio/)-[](https://www.npmjs.com/package/@composio/core)-[](https://discord.gg/composio)-[](https://hvtracker.net/agents/composio/)-</div>+## Quickstart-This repository contains the official Software Development Kits (SDKs) for Composio, providing seamless integration capabilities for Python and Typescript Agentic Frameworks and Libraries.+Create a session for a user, hand its tools to your agent, and let the agent take action across 1000+ apps. Grab a `COMPOSIO_API_KEY` from the [dashboard](https://dashboard.composio.dev/settings) first.-## Getting Started--### TypeScript SDK Installation+### TypeScript```bash-# Using npm-npm install @composio/core--# Using yarn-yarn add @composio/core--# Using pnpm-pnpm add @composio/core-```--#### Quick start:--```typescript-import { Composio } from '@composio/core';-// Initialize the SDK-const composio = new Composio({- // apiKey: 'your-api-key',-});+npm install @composio/core @composio/openai-agents @openai/agents```-#### Simple Agent with OpenAI Agents--```bash-npm install @composio/openai-agents @openai/agents-```+> `@composio/core` intentionally packages its TypeScript source and SDK docs so the installed package is inspectable to coding agents. If you want a smaller install with the same API, use [`@composio/slim`](ts/packages/slim).```typescript-import { Composio } from '@composio/core';-import { OpenAIAgentsProvider } from '@composio/openai-agents';-import { Agent, run } from '@openai/agents';+import { Composio } from "@composio/core";+import { OpenAIAgentsProvider } from "@composio/openai-agents";+import { Agent, run } from "@openai/agents";-const composio = new Composio({- provider: new OpenAIAgentsProvider(),-});+const composio = new Composio({ provider: new OpenAIAgentsProvider() });-const userId = '[email protected]';--const tools = await composio.tools.get(userId, {- toolkits: ['HACKERNEWS'],-});+// Each session is scoped to one of your users+const session = await composio.create("user_123");+const tools = await session.tools();const agent = new Agent({- name: 'Hackernews assistant',- tools: tools,+ name: "Personal Assistant",+ instructions: "You are a helpful assistant. Use Composio tools to take action.",+ tools,});-const result = await run(agent, 'What is the latest hackernews post about?');--console.log(JSON.stringify(result.finalOutput, null, 2));-// will return the response from the agent with data from HACKERNEWS API.+const result = await run(agent, "Summarize my emails from today");+console.log(result.finalOutput);```-### Python SDK Installation+### Python```bash-# Using pip-pip install composio--# Using poetry-poetry add composio+pip install composio composio-openai-agents openai-agents```-#### Quick start:-```pythonfrom composio import Composio--composio = Composio(- # api_key="your-api-key",-)-```--#### Simple Agent with OpenAI Agents--```bash-pip install composio_openai_agents openai-agents-```--```python-import asyncio-from agents import Agent, Runner-from composio import Composiofrom composio_openai_agents import OpenAIAgentsProvider+from agents import Agent, Runner-# Initialize Composio client with OpenAI Agents Providercomposio = Composio(provider=OpenAIAgentsProvider())-user_id = "[email protected]"-tools = composio.tools.get(user_id=user_id, toolkits=["HACKERNEWS"])+# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()-# Create an agent with the toolsagent = Agent(- name="Hackernews Agent",- instructions="You are a helpful assistant.",+ name="Personal Assistant",+ instructions="You are a helpful assistant. Use Composio tools to take action.",tools=tools,)-# Run the agent-async def main():- result = await Runner.run(- starting_agent=agent,- input="What's the latest Hackernews post about?",- )- print(result.final_output)--asyncio.run(main())-# will return the response from the agent with data from HACKERNEWS API.+result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")+print(result.final_output)```-For more detailed usage instructions and examples, please refer to each SDK's specific documentation.+By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store `session.session_id` and reuse it with `composio.use()` across turns. See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.++**Prefer MCP?** Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to `composio.create()` and point Claude, Cursor, or any MCP client at `session.mcp.url`. See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).-### Open API Specification+## CLI-To update the OpenAPI specifications used for generating SDK documentation:+The `composio` CLI runs Composio from your shell and gives coding agents like Claude Code a local tool surface.```bash-# Pull the latest API specifications from the backend-pnpm api:pull+curl -fsSL https://composio.dev/install | bash+composio login```-This command pulls the OpenAPI specification from `https://backend.composio.dev/api/v3/openapi.json` and updates the local API documentation files.--This is pulled automatically with build step.+Use `composio search` to find tools, `composio execute` to run them, `composio link` to connect accounts, and `composio run` to script workflows in TypeScript. See the [CLI docs](https://docs.composio.dev/docs/cli).-## Available SDKs+## Providers-### TypeScript SDK (/ts)+A provider adapts Composio tools to your agent framework's native tool format:-The TypeScript SDK provides a modern, type-safe way to interact with Composio's services. It's designed for both Node.js and browser environments, offering full TypeScript support with comprehensive type definitions.--For detailed information about the TypeScript SDK, please refer to the [TypeScript SDK Documentation](/ts/README.md).+| Provider | TypeScript | Python |+|----------|:----------:|:------:|+| OpenAI | [`@composio/openai`](ts/packages/providers/openai) | [`composio-openai`](python/providers/openai) |+| OpenAI Agents | [`@composio/openai-agents`](ts/packages/providers/openai-agents) | [`composio-openai-agents`](python/providers/openai_agents) |+| Anthropic | [`@composio/anthropic`](ts/packages/providers/anthropic) | [`composio-anthropic`](python/providers/anthropic) |+| Claude Agent SDK | [`@composio/claude-agent-sdk`](ts/packages/providers/claude-agent-sdk) | [`composio-claude-agent-sdk`](python/providers/claude_agent_sdk) |+| Vercel AI SDK | [`@composio/vercel`](ts/packages/providers/vercel) | — |+| Google GenAI | [`@composio/google`](ts/packages/providers/google) | [`composio-gemini`](python/providers/gemini), [`composio-google`](python/providers/google) |+| Google ADK | — | [`composio-google-adk`](python/providers/google_adk) |+| LangChain | [`@composio/langchain`](ts/packages/providers/langchain) | [`composio-langchain`](python/providers/langchain) |+| LangGraph | via `@composio/langchain` | [`composio-langgraph`](python/providers/langgraph) |+| LlamaIndex | [`@composio/llamaindex`](ts/packages/providers/llamaindex) | [`composio-llamaindex`](python/providers/llamaindex) |+| Mastra | [`@composio/mastra`](ts/packages/providers/mastra) | — |+| Pi | [`@composio/experimental`](ts/packages/experimental)* | — |+| Cloudflare Workers AI | [`@composio/cloudflare`](ts/packages/providers/cloudflare) | — |+| CrewAI | — | [`composio-crewai`](python/providers/crewai) |+| AutoGen | — | [`composio-autogen`](python/providers/autogen) |++\* *The [Pi provider](https://docs.composio.dev/docs/providers/pi) is experimental and ships from `@composio/experimental`.*++Don't see your framework? [Build a custom provider](https://docs.composio.dev/docs/providers/custom-providers), or skip providers entirely and connect over [MCP](https://docs.composio.dev/docs/sessions-via-mcp).++## All packages++Everything published from this repo:++| Package | Description |+|---------|-------------|+| [`@composio/core`](ts/packages/core) | TypeScript SDK |+| [`@composio/slim`](ts/packages/slim) | `@composio/core` without packaged source or docs; same API, smaller install |+| [`composio` CLI](ts/packages/cli) | Standalone CLI binary: `curl -fsSL https://composio.dev/install \| bash` |+| [`@composio/experimental`](ts/packages/experimental) | Experimental integrations, including the Pi provider |+| [`@composio/json-schema-to-zod`](ts/packages/json-schema-to-zod) | JSON Schema to Zod conversion |+| `@composio/*` [provider adapters](#providers) | OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel, Google, LangChain, LlamaIndex, Mastra, Cloudflare |+| [`composio`](python) | Python SDK |+| `composio-*` [provider adapters](#providers) | OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Gemini, Google, Google ADK, LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen |++## Repository layout++```text+ts/ TypeScript SDK workspace+ packages/core/ @composio/core+ packages/providers/ Provider adapters+ packages/cli/ Composio CLI+python/ Python SDK and provider packages+docs/ Documentation site (docs.composio.dev)+```-### Python SDK (/python)+The TypeScript SDK is tested against Node 22+; the Python SDK supports Python 3.10+.-The Python SDK offers a Pythonic interface to Composio's services, making it easy to integrate Composio into your Python applications. It supports Python 3.10+ and follows modern Python development practices.+## Development-For detailed information about the Python SDK, please refer to the [Python SDK Documentation](/python/README.md).+```bash+mise install # pinned toolchain (Node, Python, pnpm)+pnpm install+pnpm build+pnpm test+```-## Provider Support+Python commands run from `python/`; see [`python/README.md`](python/README.md). We welcome contributions to both SDKs; read the [contribution guidelines](CONTRIBUTING.md) before submitting pull requests.-The following table shows which AI frameworks and platforms are supported in each SDK:+## Support-| Provider | TypeScript | Python |-|----------|:----------:|:------:|-| OpenAI | ✅ | ✅ |-| OpenAI Agents | ✅ | ✅ |-| Anthropic | ✅ | ✅ |-| LangChain | ✅ | ✅ |-| LangGraph | ✅* | ✅ |-| LlamaIndex | ✅ | ✅ |-| Vercel AI SDK | ✅ | ❌ |-| Google Gemini | ✅ | ✅ |-| Google ADK | ❌ | ✅ |-| Mastra | ✅ | ❌ |-| Cloudflare Workers AI | ✅ | ❌ |-| CrewAI | ❌ | ✅ |-| AutoGen | ❌ | ✅ |--\* *LangGraph in TypeScript is supported via the `@composio/langchain` package.*--> **Don't see your provider?** Learn how to [build a custom provider](https://docs.composio.dev/sdk/typescript/custom-providers) to integrate with any AI framework.--## Packages--### Core Packages--| Package | Version |-|---------|---------|-| **TypeScript** | |-| [@composio/core](https://www.npmjs.com/package/@composio/core) |  |-| **Python** | |-| [composio](https://pypi.org/project/composio/) |  |--### Provider Packages--| Package | Version |-|---------|---------|-| **TypeScript** | |-| [@composio/openai](https://www.npmjs.com/package/@composio/openai) |  |-| [@composio/openai-agents](https://www.npmjs.com/package/@composio/openai-agents) |  |-| [@composio/anthropic](https://www.npmjs.com/package/@composio/anthropic) |  |-| [@composio/langchain](https://www.npmjs.com/package/@composio/langchain) |  |-| [@composio/llamaindex](https://www.npmjs.com/package/@composio/llamaindex) |  |-| [@composio/vercel](https://www.npmjs.com/package/@composio/vercel) |  |-| [@composio/google](https://www.npmjs.com/package/@composio/google) |  |-| [@composio/mastra](https://www.npmjs.com/package/@composio/mastra) |  |-| [@composio/cloudflare](https://www.npmjs.com/package/@composio/cloudflare) |  |-| **Python** | |-| [composio-openai](https://pypi.org/project/composio-openai/) |  |-| [composio-openai-agents](https://pypi.org/project/composio-openai-agents/) |  |-| [composio-anthropic](https://pypi.org/project/composio-anthropic/) |  |-| [composio-langchain](https://pypi.org/project/composio-langchain/) |  |-| [composio-langgraph](https://pypi.org/project/composio-langgraph/) |  |-| [composio-llamaindex](https://pypi.org/project/composio-llamaindex/) |  |-| [composio-crewai](https://pypi.org/project/composio-crewai/) |  |-| [composio-autogen](https://pypi.org/project/composio-autogen/) |  |-| [composio-gemini](https://pypi.org/project/composio-gemini/) |  |-| [composio-google](https://pypi.org/project/composio-google/) |  |-| [composio-google-adk](https://pypi.org/project/composio-google-adk/) |  |--### Utility Packages--| Package | Version |-|---------|---------|-| [@composio/json-schema-to-zod](https://www.npmjs.com/package/@composio/json-schema-to-zod) |  |-| [@composio/ts-builders](https://www.npmjs.com/package/@composio/ts-builders) |  |--_if you are looking for the older sdk, you can find them [here](https://github.com/ComposioHQ/composio/tree/master)_--## Rube--[Rube](https://rube.app) is a Model Context Protocol (MCP) server built with Composio. It connects your AI tools to 500+ apps like Gmail, Slack, GitHub, and Notion. Simply install it in your AI client, authenticate once with your apps, and start asking your AI to perform real actions like "Send an email" or "Create a task."--It integrates with major AI clients like Cursor, Claude Desktop, VS Code, Claude Code and any custom MCP‑compatible client. You can switch between these clients and your integrations follow you.---## Contributing--We welcome contributions to both SDKs! Please read our [contribution guidelines](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md) before submitting pull requests.+- [Documentation](https://docs.composio.dev)+- [Discord community](https://discord.gg/composio)+- [Open an issue](https://github.com/ComposioHQ/composio/issues)+- [[email protected]](mailto:[email protected])## License-This project is licensed under the MIT License - see the LICENSE file for details.--## Support--If you encounter any issues or have questions about the SDKs:--- Open an issue in this repository-- Contact our [support team](mailto:[email protected])-- Check our [documentation](https://docs.composio.dev/)+MIT. See [LICENSE](LICENSE).diff --git a/python/README.md b/python/README.mdindex 7c83f7082..096d2795c 100644--- a/python/README.md+++ b/python/README.md@@ -1,490 +1,141 @@-+<p align="center">+ <a href="https://composio.dev">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="https://brand.composio.dev/logos/Logomark-White.svg">+ <img alt="Composio logo" src="https://brand.composio.dev/logos/Logomark-Black.svg" width="96">+ </picture>+ </a>+</p>-# Composio+# Composio Python SDK-The Composio Python SDK allows you to interact with the Composio Platform. It provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various AI frameworks and platforms.+Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox. This package is the Python SDK.-[Learn more about the SDK from our docs](https://docs.composio.dev)+- [Documentation](https://docs.composio.dev)+- [Quickstart](https://docs.composio.dev/docs/quickstart)+- [Dashboard](https://dashboard.composio.dev) (grab your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/settings))-## Core Features+## Install-- **Tools**: Manage and execute tools within the Composio ecosystem. Includes functionality to list, retrieve, and execute tools.-- **Toolkits**: Organize and manage collections of tools for specific use cases.-- **Triggers**: Create and manage event triggers that can execute tools based on specific conditions.-- **AuthConfigs**: Configure authentication providers and settings.-- **ConnectedAccounts**: Manage third-party service connections.-- **ActionExecution**: Track and manage the execution of actions within the platform.-- **Provider Integrations**: Built-in support for OpenAI, Anthropic, LangChain, CrewAI, AutoGen, and more.--## Installation+Requires Python 3.10+.```bashpip install composio-# or-pip install composio-core-```--### Provider-Specific Installations--For specific AI framework integrations:--```bash-# OpenAI integration-pip install composio-openai--# LangChain integration-pip install composio-langchain--# CrewAI integration-pip install composio-crewai--# Anthropic integration-pip install composio-anthropic--# AutoGen integration-pip install composio-autogen--# And many more...-```--## Getting Started--### Basic Usage with OpenAI--```python-import os-from composio import Composio-from openai import OpenAI--# Initialize OpenAI client-openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))--# Initialize Composio with your API key-composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))--def main():- try:- # Fetch tools - single tool or multiple tools- tools = composio.tools.get(user_id="default", slug="HACKERNEWS_GET_USER")- # Or fetch multiple tools: composio.tools.get(user_id="default", toolkits=["hackernews"])-- query = "Find information about the HackerNews user 'pg'"-- # Create chat completion with tools- response = openai_client.chat.completions.create(- model="gpt-4o",- messages=[- {- "role": "system",- "content": "You are a helpful assistant that can use tools to answer questions."- },- {"role": "user", "content": query}- ],- tools=tools,- tool_choice="auto"- )-- # Handle tool calls if the assistant decides to use them- if response.choices[0].message.tool_calls:- print("🔧 Assistant is using tool:", response.choices[0].message.tool_calls[0].function.name)-- # Execute the tool call- tool_result = composio.provider.handle_tool_calls(- response=response,- user_id="default"- )-- print("✅ Tool execution result:", tool_result)-- # Get final response from assistant with tool result- final_response = openai_client.chat.completions.create(- model="gpt-4o",- messages=[- {- "role": "system",- "content": "You are a helpful assistant that can use tools to answer questions."- },- {"role": "user", "content": query},- response.choices[0].message,- {- "role": "tool",- "tool_call_id": response.choices[0].message.tool_calls[0].id,- "content": str(tool_result)- }- ]- )-- print("🤖 Final response:", final_response.choices[0].message.content)- else:- print("🤖 Response:", response.choices[0].message.content)-- except Exception as error:- print("❌ Error:", error)--if __name__ == "__main__":- main()```-### Using with Provider Integrations+## Quickstart-#### OpenAI Provider+Create a session for one of your users and hand its tools to your agent:```python-from composio_openai import OpenAIProvider-from openai import OpenAIfrom composio import Composio-# Initialize with OpenAI provider-openai_client = OpenAI()-composio = Composio(provider=OpenAIProvider())--# Define task-task = "Star a repo composiohq/composio on GitHub"+composio = Composio() # reads COMPOSIO_API_KEY, or pass api_key=...-# Get GitHub tools that are pre-configured-tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])--# Get response from the LLM-response = openai_client.chat.completions.create(- model="gpt-4o-mini",- tools=tools,- messages=[- {"role": "system", "content": "You are a helpful assistant."},- {"role": "user", "content": task},- ],-)--# Execute the function calls-result = composio.provider.handle_tool_calls(response=response, user_id="default")-print(result)+session = composio.create(user_id="user_123")+tools = session.tools() # OpenAI-format tool definitions by default```-#### LangChain Integration+By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store `session.session_id` and reuse the session across turns:```python-from composio_langchain import ComposioToolSet-from langchain_openai import ChatOpenAI--# Initialize the toolset-toolset = ComposioToolSet()--# Get tools for a specific toolkit-tools = toolset.get_tools(toolkits=["GITHUB"])--# Initialize LLM-llm = ChatOpenAI(model="gpt-4o")+session = composio.use(session_id)+```-# Create agent with tools-from langchain.agents import create_openai_functions_agent, AgentExecutor-from langchain.prompts import ChatPromptTemplate+See [how Composio works](https://docs.composio.dev/docs/how-composio-works) for sessions and meta tools, and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting `toolkits`, `tools`, `auth_configs`, and `connected_accounts` on `composio.create()`.-prompt = ChatPromptTemplate.from_messages([- ("system", "You are a helpful assistant"),- ("user", "{input}"),- ("assistant", "{agent_scratchpad}")-])+## Use with an agent framework-agent = create_openai_functions_agent(llm, tools, prompt)-agent_executor = AgentExecutor(agent=agent, tools=tools)+Provider packages adapt `session.tools()` to your framework's native tool format. With [OpenAI Agents](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai_agents):-# Execute task-result = agent_executor.invoke({"input": "Star the composiohq/composio repository"})-print(result)+```bash+pip install composio composio-openai-agents openai-agents```-## Configuration--The Composio constructor accepts the following configuration options:-```pythonfrom composio import Composio-from composio.core.provider import OpenAIProvider--composio = Composio(- api_key="your-api-key", # Your Composio API key- base_url="https://api.composio.dev", # Custom API base URL (optional)- timeout=60, # Request timeout in seconds- max_retries=3, # Maximum number of retries- allow_tracking=True, # Enable/disable telemetry (default: True)- file_download_dir="./downloads", # Directory for file downloads- provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)- toolkit_versions={ "github": "12202025_01" } # Toolkit versions to use-)-```--## Modifiers--Composio SDK supports powerful modifiers to transform tool schemas and execution behavior.+from composio_openai_agents import OpenAIAgentsProvider+from agents import Agent, Runner-### Schema Modifiers+composio = Composio(provider=OpenAIAgentsProvider())-Schema modifiers allow you to transform tool schemas before they are used:+session = composio.create(user_id="user_123")+tools = session.tools()-```python-from composio import schema_modifier-from composio.types import Tool--@schema_modifier(tools=["HACKERNEWS_GET_USER"])-def modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:- # Perform modifications on the schema- schema["description"] = "Enhanced HackerNews user lookup with additional features"- schema["parameters"]["properties"]["include_karma"] = {- "type": "boolean",- "description": "Include user karma in response",- "default": True- }- return schema--# Use the modifier when getting tools-tools = composio.tools.get(- user_id="default",- slug="HACKERNEWS_GET_USER",- modifiers=[modify_schema]+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful assistant. Use Composio tools to take action.",+ tools=tools,)-```--### Execution Modifiers-Transform tool execution behavior with before and after execute modifiers:--```python-from composio import before_execute, after_execute-from composio.types import ToolExecuteParams, ToolExecutionResponse--@before_execute(tools=["HACKERNEWS_GET_USER"])-def before_execute_modifier(- tool: str,- toolkit: str,- params: ToolExecuteParams-) -> ToolExecuteParams:- # Transform input before execution- print(f"Executing {tool} with params: {params}")- return params--@after_execute(tools=["HACKERNEWS_GET_USER"])-def after_execute_modifier(- tool: str,- toolkit: str,- response: ToolExecutionResponse-) -> ToolExecutionResponse:- # Transform output after execution- return {- **response,- "data": {- **response["data"],- "processed_at": "2024-01-01T00:00:00Z"- }- }--# Execute tool with modifiers-response = composio.tools.execute(- user_id="default",- slug="HACKERNEWS_GET_USER",- arguments={"username": "pg"},- modifiers=[before_execute_modifier, after_execute_modifier]-)+result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")+print(result.final_output)```-## Connected Accounts+Other Python providers: [`composio-openai`](https://github.com/ComposioHQ/composio/tree/next/python/providers/openai), [`composio-anthropic`](https://github.com/ComposioHQ/composio/tree/next/python/providers/anthropic), [`composio-claude-agent-sdk`](https://github.com/ComposioHQ/composio/tree/next/python/providers/claude_agent_sdk), [`composio-langchain`](https://github.com/ComposioHQ/composio/tree/next/python/providers/langchain), [`composio-langgraph`](https://github.com/ComposioHQ/composio/tree/next/python/providers/langgraph), [`composio-llamaindex`](https://github.com/ComposioHQ/composio/tree/next/python/providers/llamaindex), [`composio-crewai`](https://github.com/ComposioHQ/composio/tree/next/python/providers/crewai), [`composio-autogen`](https://github.com/ComposioHQ/composio/tree/next/python/providers/autogen), [`composio-gemini`](https://github.com/ComposioHQ/composio/tree/next/python/providers/gemini), [`composio-google`](https://github.com/ComposioHQ/composio/tree/next/python/providers/google), [`composio-google-adk`](https://github.com/ComposioHQ/composio/tree/next/python/providers/google_adk). Don't see yours? [Build a custom provider](https://docs.composio.dev/docs/providers/custom-providers).-Composio SDK provides a powerful way to manage third-party service connections through Connected Accounts. This feature allows you to authenticate with various services and maintain those connections.+## MCP-### Creating a Connected Account+Every session also exposes a hosted MCP endpoint. Pass `mcp=True` and point Claude, Cursor, or any MCP client at it:```pythonfrom composio import Composio-from composio.types import auth_scheme--composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))--# Create a connected account with OAuth-connection_request = composio.connected_accounts.initiate(- user_id="user123",- auth_config_id="ac_12343544", # You can create it from the dashboard- callback_url="https://your-app.com/callback",- data={- # Additional data for the connection- "scope": ["read", "write"]- }-)--# Wait for the connection to be established-# Default timeout is 60 seconds-connected_account = connection_request.wait_for_connection()-print(connected_account)-```--### API Key Authentication--```python-# Create a connected account with API Key-connection_request = composio.connected_accounts.initiate(- user_id="user123",- auth_config_id="ac_12343544",- config=auth_scheme.api_key(- options={- "api_key": "your-api-key-here"- }- )-)-```--### Managing Connected Accounts-```python-# List all connected accounts-accounts = composio.connected_accounts.list(user_id="user123")--# Get a specific connected account-account = composio.connected_accounts.get("account_id")--# Enable/Disable a connected account-composio.connected_accounts.enable("account_id")-composio.connected_accounts.disable("account_id")--# Refresh credentials-composio.connected_accounts.refresh("account_id")+composio = Composio()-# Delete a connected account-composio.connected_accounts.delete("account_id")+session = composio.create(user_id="user_123", mcp=True)+print(session.mcp.url) # MCP endpoint for this session+print(session.mcp.headers) # auth headers for the endpoint```-### Connection Statuses--Connected accounts can have the following statuses:--- `ACTIVE`: Connection is established and working-- `INACTIVE`: Connection is temporarily disabled-- `PENDING`: Connection is being processed-- `INITIATED`: Connection request has started-- `EXPIRED`: Connection credentials have expired-- `FAILED`: Connection attempt failed--## Tools and Toolkits--### Working with Tools+See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).-```python-# Get tools by toolkit-tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])--# Get tools by search-tools = composio.tools.get(user_id="default", search="user")--# Get tools by toolkit and search-tools = composio.tools.get(user_id="default", toolkits=["GITHUB"], search="star")--# Execute a tool directly-response = composio.tools.execute(- user_id="default",- slug="HACKERNEWS_GET_USER",- arguments={"username": "pg"}-)-print(response)-```--### Proxy Calls+## Authentication-Make direct API calls through connected accounts:+Sessions manage connections for you by default; the agent walks the user through OAuth with the session's meta tools. To drive the flow yourself, authorize a toolkit from the session:```python-# Execute proxy call (GitHub API)-proxy_response = composio.tools.proxy(- endpoint="/repos/composiohq/composio/issues/1",- method="GET",- connected_account_id="ac_1234", # Use connected account for GitHub- parameters=[- {- "name": "Accept",- "value": "application/vnd.github.v3+json",- "type": "header"- }- ]-)-print(proxy_response)+connection_request = session.authorize("gmail")+print(connection_request.redirect_url) # send the user here to approve access+connection_request.wait_for_connection()```-## Authentication Schemes--Composio supports various authentication schemes:--- OAuth2-- OAuth1-- OAuth1a-- API Key-- Basic Auth-- Bearer Token-- Google Service Account-- And more...+See [authentication](https://docs.composio.dev/docs/authentication) for auth configs, custom OAuth apps, and connection lifecycle.-## Environment Variables+## Triggers-- `COMPOSIO_API_KEY`: Your Composio API key-- `COMPOSIO_BASE_URL`: Custom API base URL-- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)-- `DEVELOPMENT`: Development mode flag-- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific toolkit-- `CI`: CI environment flag--## MCP (Model Context Protocol)--Create MCP servers for seamless integration with Claude, Cursor, and other MCP-compatible tools:+Subscribe to events from connected apps (new email, new commit, and so on) and react to them:```pythonfrom composio import Composiocomposio = Composio()-# Create MCP server-mcp_server = composio.mcp.create(- "my-mcp-server",- toolkits=["github", "gmail"],- manually_manage_connections=False+trigger = composio.triggers.create(+ slug="GITHUB_COMMIT_EVENT",+ user_id="user_123",+ trigger_config={"owner": "composiohq", "repo": "composio"},)-# Generate server instance for a user-server_instance = mcp_server.generate("user123")-print(f"MCP Server URL: {server_instance['url']}")-```--## Supported AI Frameworks--Composio provides dedicated integrations for popular AI frameworks:+subscription = composio.triggers.subscribe()-- **OpenAI** - Direct integration with OpenAI's API-- **LangChain** - Tools and agents for LangChain workflows-- **LangGraph** - State machine workflows with LangGraph-- **CrewAI** - Multi-agent systems with CrewAI-- **AutoGen** - Microsoft's AutoGen framework-- **Anthropic** - Claude integration-- **Google AI** - Gemini and other Google AI services-- **LlamaIndex** - RAG and data framework integration[email protected](trigger_id=trigger.trigger_id)+def handle_event(data):+ print("Event received:", data)-## Error Handling--```python-from composio import Composio-from composio.exceptions import ComposioError, ApiKeyNotProvidedError--try:- composio = Composio() # Will raise ApiKeyNotProvidedError if no API key- tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])-except ApiKeyNotProvidedError:- print("Please provide COMPOSIO_API_KEY environment variable")-except ComposioError as e:- print(f"Composio error: {e}")-except Exception as e:- print(f"Unexpected error: {e}")+subscription.wait_forever()```-## Contributing--We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for more details.+`subscribe()` streams events over a WebSocket for local development. In production, register a webhook URL and parse deliveries with `composio.triggers.parse()`. See [setting up triggers](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers).-## License+## Development-Apache License 2.0+This package lives in the [Composio SDK monorepo](https://github.com/ComposioHQ/composio) under `python/`. See the [contribution guidelines](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md) to get set up.## Support-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Documentation](https://docs.composio.dev)+- [Python SDK reference](https://docs.composio.dev/reference/sdk-reference/python)+- [Discord community](https://discord.gg/composio)+- [Open an issue](https://github.com/ComposioHQ/composio/issues)+- [[email protected]](mailto:[email protected])diff --git a/python/providers/anthropic/README.md b/python/providers/anthropic/README.mdindex ce0987cb0..60c47d833 100644--- a/python/providers/anthropic/README.md+++ b/python/providers/anthropic/README.md@@ -1,71 +1,73 @@-## 🚀🔗 Leveraging Claude with Composio+# composio-anthropic-Facilitate the integration of Claude with Composio to empower Claude models to directly interact with external applications, broadening their capabilities and application scope.+Adapts Composio tools to the Claude Messages API tool format and executes the tool calls Claude returns.-### Objective--- **Automate starring a GitHub repository** using conversational instructions via Claude Function Calls.--### Installation and Setup--Ensure you have the necessary packages installed and connect your GitHub account to allow your agents to utilize GitHub functionalities.+## Installation```bash-# Install Composio LangChain package-pip install composio-claude--# Connect your GitHub account-composio-cli add github--# View available applications you can connect with-composio-cli show-apps+pip install composio composio-anthropic anthropic```-### Usage Steps+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `ANTHROPIC_API_KEY` in your environment.-#### 1. Import Base Packages+## Quickstart-Prepare your environment by initializing necessary imports from Claude and setting up your client.+`AnthropicProvider` is non-agentic: Claude returns `tool_use` blocks, `handle_tool_calls` executes them, and you send the results back as `tool_result` blocks.```python+import jsonimport anthropic+from composio import Composio+from composio_anthropic import AnthropicProvider-# Initialize Claude client+composio = Composio(provider=AnthropicProvider())client = anthropic.Anthropic()-```--### Step 2: Integrating GitHub Tools with Composio--This step involves fetching and integrating GitHub tools provided by Composio, enabling enhanced functionality for LangChain operations.-```python-from composio_claude import App, ComposioToolSet--toolset = ComposioToolSet()-actions = toolset.get_tools(tools=App.GITHUB)-```-### Step 3: Agent Execution+# Create a session for your user+session = composio.create(user_id="user_123")+tools = session.tools()-This step involves configuring and executing the agent to carry out actions, such as starring a GitHub repository.+messages = [+ {"role": "user", "content": "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"}+]-```python-my_task = "Star a repo composiohq/composio on GitHub"--# Create a chat completion request to decide on the action-response = client.beta.tools.messages.create(- model="claude-3-opus-20240229",- max_tokens=1024,- tools= actions,- messages=[{"role": "user", "content": "Star me composiohq/composio repo in github."}],+response = client.messages.create(+ model="claude-opus-4-6",+ max_tokens=4096,+ tools=tools,+ messages=messages,)-pprint(response)++# Agentic loop: keep executing tool calls until the model responds with text+while response.stop_reason == "tool_use":+ tool_use_blocks = [block for block in response.content if block.type == "tool_use"]+ results = composio.provider.handle_tool_calls(user_id="user_123", response=response)+ messages.append({"role": "assistant", "content": response.content})+ messages.append({+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": tool_use_blocks[i].id, "content": json.dumps(result)}+ for i, result in enumerate(results)+ ]+ })+ response = client.messages.create(+ model="claude-opus-4-6",+ max_tokens=4096,+ tools=tools,+ messages=messages,+ )++# Print final response+for block in response.content:+ if block.type == "text":+ print(block.text)```-### Step 4: Validate Execution Response+`handle_tool_calls` extracts every `tool_use` block from the response, executes the matching Composio tools, and returns the raw results in order. Claude occasionally emits tool input as a JSON string instead of an object; the provider normalizes this before execution.-Execute the following code to validate the response, ensuring that the intended task has been successfully completed.+Building on the Claude Agent SDK instead of the Messages API? Use [`composio-claude-agent-sdk`](../claude_agent_sdk).-```python-result = toolset.handle_tool_calls(response)-pprint(result)-```+## Links++- Anthropic provider docs: https://docs.composio.dev/docs/providers/anthropic+- Composio docs: https://docs.composio.devdiff --git a/python/providers/autogen/README.md b/python/providers/autogen/README.mdindex dae1da3b9..50ea562aa 100644--- a/python/providers/autogen/README.md+++ b/python/providers/autogen/README.md@@ -1 +1,61 @@-## 🚀🔗 Integrating Composio with Autogen SDK+# composio-autogen++Adapts Composio tools to AutoGen `FunctionTool` objects and registers them with your caller and executor agents, so your AutoGen agents can take action across 1000+ apps.++## Installation++```bash+pip install composio composio-autogen autogen-agentchat+```++Set `COMPOSIO_API_KEY` (from the [dashboard](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment.++## Quickstart++```python+from autogen import AssistantAgent, UserProxyAgent+from composio import Composio+from composio_autogen import AutogenProvider++composio = Composio(provider=AutogenProvider())++# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()++chatbot = AssistantAgent(+ "chatbot",+ system_message="Reply TERMINATE when the task is done or when user's content is empty",+ llm_config={"config_list": [{"model": "gpt-5.2"}]},+)++user_proxy = UserProxyAgent(+ "user_proxy",+ is_termination_msg=lambda msg: "TERMINATE" in (msg.get("content", "") or ""),+ human_input_mode="NEVER",+ code_execution_config={"use_docker": False},+)++# Register tools with both agents+composio.provider.register_tools(caller=chatbot, executor=user_proxy, tools=tools)++response = user_proxy.initiate_chat(+ chatbot,+ message="Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+)++print(response.chat_history)+```++For multi-turn use, store `session.session_id` and reuse it with `composio.use(session_id)` instead of calling `create()` again.++## Provider specifics++AutoGen needs tools registered with two agents, not passed once. Call `composio.provider.register_tools(caller=..., executor=..., tools=tools)`: the `caller` decides which tool to invoke, and the `executor` runs it. This method is unique to the AutoGen provider.++AutoGen caps function names at 64 characters, so the provider hashes and truncates long tool slugs to stay under the limit. The registered name will not always match the original Composio slug.++## Links++- [AutoGen provider docs](https://docs.composio.dev/docs/providers/autogen)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/claude_agent_sdk/README.md b/python/providers/claude_agent_sdk/README.mdindex 30447d5fd..51b22ec58 100644--- a/python/providers/claude_agent_sdk/README.md+++ b/python/providers/claude_agent_sdk/README.md@@ -1,98 +1,64 @@-# Composio Claude Code Agents Provider+# composio-claude-agent-sdk-Use Composio tools with the Claude Code Agents SDK.+Adapts Composio tools to the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/python), exposing them to Claude through an in-process MCP server.## Installation-### Prerequisites--1. **Claude Code CLI**: The Claude Agent SDK requires Claude Code to be installed:-- ```bash- # macOS/Linux/WSL- curl -fsSL https://claude.ai/install.sh | bash-- # or via Homebrew- brew install --cask claude-code-- # or via npm- npm install -g @anthropic-ai/claude-code- ```--2. **Anthropic API Key**: Set your API key as an environment variable:- ```bash- export ANTHROPIC_API_KEY="your-api-key"- ```--### Install the package-```bash-pip install composio-claude-agent-sdk+pip install composio composio-claude-agent-sdk claude-agent-sdk```-## Usage+The Claude Agent SDK also requires the Claude Code CLI: `npm install -g @anthropic-ai/claude-code`.++Set `COMPOSIO_API_KEY` (from the [dashboard](https://dashboard.composio.dev/settings)) and `ANTHROPIC_API_KEY` in your environment.++## Quickstart```pythonimport asyncio+from composio import Composiofrom composio_claude_agent_sdk import ClaudeAgentSDKProvider-from claude_agent_sdk import query, ClaudeAgentOptions+from claude_agent_sdk import (+ AssistantMessage,+ ClaudeAgentOptions,+ TextBlock,+ create_sdk_mcp_server,+ query,+)-# Initialize Composio with the Claude Code Agents providercomposio = Composio(provider=ClaudeAgentSDKProvider())-async def main():- # Get tools from Composio- tools = composio.tools.get(- user_id="default",- toolkits=["gmail"],- )-- # Create an MCP server configuration with the tools- mcp_server = composio.provider.create_mcp_server(tools)-- # Run a Claude agent with access to Composio tools- async for message in query(- prompt="Fetch my latest email from Gmail",- options=ClaudeAgentOptions(- mcp_servers={"composio": mcp_server},- permission_mode="bypassPermissions",- ),- ):- if message.type == "assistant":- print(message.message)--asyncio.run(main())-```+# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()-## API Reference+server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)-### ClaudeCodeAgentsProvider-The main provider class for integrating Composio tools with Claude Code Agents SDK.+async def main():+ options = ClaudeAgentOptions(+ system_prompt="You are a helpful assistant. Use tools to complete tasks.",+ permission_mode="bypassPermissions",+ mcp_servers={"composio": server},+ )+ async for message in query(prompt="Summarize my emails from today", options=options):+ if isinstance(message, AssistantMessage):+ for block in message.content:+ if isinstance(block, TextBlock):+ print(block.text)-#### Constructor Options-```python-ClaudeCodeAgentsProvider(- server_name: str = "composio", # Name for the MCP server- server_version: str = "1.0.0", # Version for the MCP server-)+asyncio.run(main())```-#### Methods--- `wrap_tool(tool, execute_tool)` - Wraps a single Composio tool as a Claude Agent SDK MCP tool-- `wrap_tools(tools, execute_tool)` - Wraps multiple Composio tools-- `create_mcp_server(wrapped_tools)` - Creates an MCP server configuration from wrapped tools+For multi-turn use, store `session.session_id` and reuse it with `composio.use(session_id)` instead of calling `create()` again.-## Environment Variables+## How tools are exposed-- `COMPOSIO_API_KEY` - Your Composio API key (get one at https://app.composio.dev)-- `ANTHROPIC_API_KEY` - Your Anthropic API key (get one at https://console.anthropic.com)+`session.tools()` returns `SdkMcpTool` objects that plug straight into `create_sdk_mcp_server`. The provider also ships `composio.provider.create_mcp_server(tools)` if you prefer a preconfigured server (name `composio`, customizable via `ClaudeAgentSDKProvider(server_name=..., server_version=...)`).## Links-- [Composio Documentation](https://docs.composio.dev)-- [Claude Agent SDK Documentation](https://platform.claude.com/docs/en/agent-sdk/python)-- [GitHub Repository](https://github.com/ComposioHQ/composio)+- [Quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/crewai/README.md b/python/providers/crewai/README.mdindex 129024596..362ea714f 100644--- a/python/providers/crewai/README.md+++ b/python/providers/crewai/README.md@@ -1 +1,65 @@-# CrewAI plugin\ No newline at end of file+# composio-crewai++Adapts Composio tools to CrewAI's `BaseTool` format so your crew's agents can act across 1000+ apps through a single Composio session.++## Installation++```bash+pip install composio composio-crewai crewai+```++Set `COMPOSIO_API_KEY` (get one from [dashboard.composio.dev/settings](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment:++```bash+export COMPOSIO_API_KEY=xxxxxxxxx+export OPENAI_API_KEY=xxxxxxxxx+```++## Quickstart++Create a session for your user, fetch its tools, and pass them to an `Agent`. CrewAI runs the task end to end; each tool executes itself through Composio.++```python+from crewai import Agent, Crew, Task+from composio import Composio+from composio_crewai import CrewAIProvider++composio = Composio(provider=CrewAIProvider())++# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()++agent = Agent(+ role="Email Agent",+ goal="Send emails on behalf of the user",+ backstory="You are an AI agent that sends emails using Gmail.",+ tools=tools,+ llm="gpt-5.2",+)++task = Task(+ description="Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+ agent=agent,+ expected_output="Confirmation that the email was sent",+)++crew = Crew(agents=[agent], tasks=[task])+result = crew.kickoff()+print(result)+```++## Error handling++Each Composio tool becomes a CrewAI `BaseTool` whose `args_schema` is built from the tool's input schema, so CrewAI validates arguments before running anything. When validation fails, the tool does not raise; it returns a structured result:++```python+{"successful": False, "error": "<validation message>", "data": None}+```++Check `successful` in your task output instead of wrapping calls in `try`/`except`.++## Links++- [CrewAI provider docs](https://docs.composio.dev/docs/providers/crewai)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/gemini/README.md b/python/providers/gemini/README.mdindex 55ee8bc5c..494c15207 100644--- a/python/providers/gemini/README.md+++ b/python/providers/gemini/README.md@@ -1,72 +1,48 @@-## 🚀🔗 Integrating Composio with Google's Gemini SDK+# composio-gemini-Streamline the integration of Composio with Google AI Python to enhance the capabilities of Gemini models, allowing them to interact directly with external applications and expanding their operational scope.+Adapts Composio tools to the [`google-genai`](https://pypi.org/project/google-genai/) SDK as Python callables compatible with Gemini's Automatic Function Calling.-### Objective--- **Automate starring a GitHub repository** using conversational instructions via Google AI Python's Function Calling feature.--### Installation and Setup--Ensure you have the necessary packages installed and connect your GitHub account to allow your agents to utilize GitHub functionalities.+## Installation```bash-# Install Composio Gemini package-pip install composio-gemini--# Connect your GitHub account-composio add github--# View available applications you can connect with-composio apps+pip install composio composio-gemini google-genai```-### Usage Steps+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `GOOGLE_API_KEY` (from https://aistudio.google.com/apikey) in your environment.-#### 1. Import Base Packages+## Quickstart-Prepare your environment by initializing necessary imports from Google AI Python and setting up your client.+`GeminiProvider` wraps each Composio tool as a typed Python callable. Pass the callables to `GenerateContentConfig(tools=...)` and the `google-genai` SDK derives function declarations from their signatures and executes tool calls automatically inside the chat loop; there is no manual tool-call handling.```python+from composio import Composio+from composio_gemini import GeminiProviderfrom google import genai--# Create google client-client = genai.Client()-```--### Step 2: Integrating GitHub Tools with Composio--This step involves fetching and integrating GitHub tools provided by Composio, enabling enhanced functionality for Google AI Python operations.-```pythonfrom google.genai import types-from composio_gemini import Action, ComposioToolSet+composio = Composio(provider=GeminiProvider())+client = genai.Client()-# Create composio client-toolset = ComposioToolSet()+# Create a session for your user+session = composio.create(user_id="user_123")+tools = session.tools()-# Create tools-tools = toolset.get_tools(- actions=[- Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER,- ]-)+config = types.GenerateContentConfig(tools=tools)+chat = client.chats.create(model="gemini-3-pro-preview", config=config)-# Create genai client config-config = types.GenerateContentConfig(- tools=tools, # type: ignore+response = chat.send_message(+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'")+print(response.text)```-### Step 3: Agent Execution+If you disable Automatic Function Calling and handle function calls yourself, `composio.provider.handle_response(response)` executes the function calls in a Gemini response and returns `Part` objects ready to send back.-This step involves configuring and executing the agent to carry out actions, such as starring a GitHub repository.+## composio-gemini vs composio-google-```python-# Use the chat interface.-chat = client.chats.create(model="gemini-2.0-flash", config=config)-response = chat.send_message(- "Can you star composiohq/composio repository on github",-)-print(response.text)-```+This package targets the `google-genai` SDK (`from google import genai`). [`composio-google`](../google) targets the older Vertex AI SDK (`vertexai.generative_models`). For new projects, Google recommends `google-genai`, so use this package.++## Links++- Google provider docs: https://docs.composio.dev/docs/providers/google+- Composio docs: https://docs.composio.devdiff --git a/python/providers/google/README.md b/python/providers/google/README.mdindex 17fd75058..9be4e206d 100644--- a/python/providers/google/README.md+++ b/python/providers/google/README.md@@ -1,66 +1,56 @@-## 🚀🔗 Integrating Composio with Google AI Python+# composio-google-Streamline the integration of Composio with Google AI Python to enhance the capabilities of Gemini models, allowing them to interact directly with external applications and expanding their operational scope.+Adapts Composio tools to the Vertex AI SDK (`vertexai.generative_models`) as `FunctionDeclaration` objects for Gemini function calling.-### Objective--- **Automate starring a GitHub repository** using conversational instructions via Google AI Python's Function Calling feature.--### Installation and Setup--Ensure you have the necessary packages installed and connect your GitHub account to allow your agents to utilize GitHub functionalities.+## Installation```bash-# Install Composio LangChain package-pip install composio-google--# Connect your GitHub account-composio-cli add github--# View available applications you can connect with-composio-cli show-apps+pip install composio composio-google google-cloud-aiplatform```-### Usage Steps+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) in your environment. Vertex AI authenticates with Google Cloud credentials; run `gcloud auth application-default login` or set `GOOGLE_APPLICATION_CREDENTIALS`.-#### 1. Import Base Packages+## Quickstart-Prepare your environment by initializing necessary imports from Google AI Python and setting up your client.+`GoogleProvider` is non-agentic: the model returns function calls, and `composio.provider.handle_response` executes every function call in the response and returns the results.```python-from vertexai.generative_models import GenerativeModel--# Initialize Google AI Python client-model = GenerativeModel("gemini-pro")-```+import vertexai+from vertexai.generative_models import GenerativeModel, Tool-### Step 2: Integrating GitHub Tools with Composio+from composio import Composio+from composio_google import GoogleProvider-This step involves fetching and integrating GitHub tools provided by Composio, enabling enhanced functionality for Google AI Python operations.-```python-from composio_google import App, ComposioToolset+vertexai.init(project="your-gcp-project", location="us-central1")-toolset = ComposioToolset()-actions = toolset.get_tools(apps=[App.GITHUB])-```+composio = Composio(provider=GoogleProvider())-### Step 3: Agent Execution+# Create a session for your user+session = composio.create(user_id="user_123")+tools = session.tools()-This step involves configuring and executing the agent to carry out actions, such as starring a GitHub repository.+model = GenerativeModel(+ "gemini-2.0-flash",+ tools=[Tool(function_declarations=tools)],+)+chat = model.start_chat()-```python-# Define task-task = "Star a repo composiohq/composio on GitHub"+response = chat.send_message(+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"+)-# Send a message to the model-response = chat.send_message(task)+# Execute the function calls the model requested+results = composio.provider.handle_response(user_id="user_123", response=response)+print(results)```-### Step 4: Validate Execution Response+To execute a single call instead of the whole response, use `composio.provider.execute_tool_call(user_id="user_123", function_call=part.function_call)`.-Execute the following code to validate the response, ensuring that the intended task has been successfully completed.+## composio-google vs composio-gemini-```python-result = composio_toolset.handle_response(response)-print("Function call result:", result)-```+This package targets the Vertex AI SDK (`vertexai.generative_models`, installed via `google-cloud-aiplatform`). [`composio-gemini`](../gemini) targets the newer `google-genai` SDK with Automatic Function Calling. For new projects, use `composio-gemini`.++## Links++- Google provider docs: https://docs.composio.dev/docs/providers/google+- Composio docs: https://docs.composio.devdiff --git a/python/providers/google_adk/README.md b/python/providers/google_adk/README.mdindex 24b5f4020..fa799dc81 100644--- a/python/providers/google_adk/README.md+++ b/python/providers/google_adk/README.md@@ -1,2 +1,70 @@-# Composio Provider For Google ADK+# composio-google-adk+Adapts Composio tools to [Google ADK](https://google.github.io/adk-docs/) `FunctionTool` objects, so your ADK agents can take action across 1000+ apps.++## Installation++```bash+pip install composio composio-google-adk google-adk+```++Set `COMPOSIO_API_KEY` (from the [dashboard](https://dashboard.composio.dev/settings)) and `GOOGLE_API_KEY` in your environment.++## Quickstart++```python+from composio import Composio+from composio_google_adk import GoogleAdkProvider+from google.adk.agents import Agent+from google.adk.runners import Runner+from google.adk.sessions import InMemorySessionService+from google.genai import types++composio = Composio(provider=GoogleAdkProvider())++# Each Composio session is scoped to one of your users+composio_session = composio.create(user_id="user_123")+tools = composio_session.tools()++agent = Agent(+ name="personal_assistant",+ model="gemini-2.0-flash",+ instruction="You are a helpful assistant. Use Composio tools to take action.",+ tools=tools,+)++session_service = InMemorySessionService()+session_service.create_session_sync(+ app_name="personal_assistant",+ user_id="user_123",+ session_id="1234",+)+runner = Runner(+ agent=agent,+ app_name="personal_assistant",+ session_service=session_service,+)++events = runner.run(+ user_id="user_123",+ session_id="1234",+ new_message=types.Content(+ role="user",+ parts=[types.Part(text="Star the repository composiohq/composio on GitHub")],+ ),+)+for event in events:+ if event.is_final_response() and event.content and event.content.parts:+ print(event.content.parts[0].text)+```++For multi-turn use, store `composio_session.session_id` and reuse it with `composio.use(session_id)` instead of calling `create()` again.++## How tools are wrapped++`GoogleAdkProvider` turns each Composio tool into a `google.adk.tools.FunctionTool` with a Python signature and docstring generated from the tool's schema, so ADK can pass them to Gemini as regular function declarations.++## Links++- [Quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/langchain/README.md b/python/providers/langchain/README.mdindex 188c6062a..ed6beedaa 100644--- a/python/providers/langchain/README.md+++ b/python/providers/langchain/README.md@@ -1 +1,63 @@-# Langchain provider for composio SDK\ No newline at end of file+# composio-langchain++Adapts Composio tools to LangChain's `StructuredTool` format so a LangChain agent can call 1000+ apps through a single Composio session.++## Installation++```bash+pip install composio composio-langchain langchain langchain-openai+```++Set `COMPOSIO_API_KEY` (get one from [dashboard.composio.dev/settings](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment:++```bash+export COMPOSIO_API_KEY=xxxxxxxxx+export OPENAI_API_KEY=xxxxxxxxx+```++## Quickstart++Create a session for your user, fetch its tools, and hand them to `create_agent`. LangChain runs the tool loop; each tool executes itself through Composio.++```python+from composio import Composio+from composio_langchain import LangchainProvider+from langchain.agents import create_agent+from langchain_openai import ChatOpenAI++composio = Composio(provider=LangchainProvider())+llm = ChatOpenAI(model="gpt-5.2")++# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()++agent = create_agent(tools=tools, model=llm)+result = agent.invoke(+ {+ "messages": [+ (+ "user",+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+ )+ ]+ }+)++print(result["messages"][-1].content)+```++## Error handling++Each wrapped tool builds its `args_schema` from the Composio tool's input schema. When argument validation fails, the tool does not raise; it returns a structured result:++```python+{"successful": False, "error": "<validation message>", "data": None}+```++Check `successful` in tool output instead of wrapping calls in `try`/`except`.++## Links++- [LangChain provider docs](https://docs.composio.dev/docs/providers/langchain)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/langgraph/README.md b/python/providers/langgraph/README.mdindex 8dd22917f..502082aa9 100644--- a/python/providers/langgraph/README.md+++ b/python/providers/langgraph/README.md@@ -1,119 +1,63 @@-## 🦜🕸️ Using Composio With LangGraph+# composio-langgraph-Integrate Composio with LangGraph Agentic workflows & enable them to interact seamlessly with external apps, enhancing their functionality and reach.+Adapts Composio tools to LangChain's `StructuredTool` format for use in LangGraph agents and graph workflows, giving them access to 1000+ apps through a single Composio session.-### Goal--- **Star a repository on GitHub** using natural language commands through a LangGraph Agent.--### Installation and Setup--Ensure you have the necessary packages installed and connect your GitHub account to allow your agents to utilize GitHub functionalities.+## Installation```bash-# Install Composio LangGraph package-pip install composio-langgraph+pip install composio composio-langgraph langgraph langchain langchain-openai+```-# Connect your GitHub account-composio-cli add github+Set `COMPOSIO_API_KEY` (get one from [dashboard.composio.dev/settings](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment:-# View available applications you can connect with-composio-cli show-apps+```bash+export COMPOSIO_API_KEY=xxxxxxxxx+export OPENAI_API_KEY=xxxxxxxxx```-### Usage Steps+## Quickstart-#### 1. Import Base Packages--Prepare your environment by initializing necessary imports from LangGraph & LangChain for setting up your agent.+Create a session for your user, fetch its tools, and hand them to your agent. The wrapped tools also work anywhere LangGraph accepts LangChain tools, such as a `ToolNode` in a custom graph.```python-from typing import Literal-+from composio import Composio+from composio_langgraph import LanggraphProvider+from langchain.agents import create_agentfrom langchain_openai import ChatOpenAI-from langgraph.graph import MessagesState, StateGraph-from langgraph.prebuilt import ToolNode-```--#### 2. Fetch GitHub LangGraph Tools via Composio-Access GitHub tools provided by Composio for LangGraph, initialize a `ToolNode` with necessary tools obtaned from `ComposioToolSet`.+composio = Composio(provider=LanggraphProvider())+llm = ChatOpenAI(model="gpt-5.2")-```python-from composio_langgraph import Action, ComposioToolSet--# Initialize the toolset for GitHub-composio_toolset = ComposioToolSet()-tools = composio_toolset.get_actions(- actions=[- Action.GITHUB_ACTIVITY_STAR_REPO_FOR_AUTHENTICATED_USER,- Action.GITHUB_USERS_GET_AUTHENTICATED,- ])-tool_node = ToolNode(tools)-```--#### 3. Prepare the model+# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()-Initialize the LLM class and bind obtained tools to the model.+agent = create_agent(tools=tools, model=llm)+result = agent.invoke(+ {+ "messages": [+ (+ "user",+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+ )+ ]+ }+)-```python-model = ChatOpenAI(temperature=0, streaming=True)-model_with_tools = model.bind_tools(functions)+print(result["messages"][-1].content)```-#### 4. Define the Graph Nodes-LangGraph expects you to define different nodes of the agentic workflow as separate functions. Here we define a node for calling the LLM model.+## Error handling-```python-def call_model(state: MessagesState):- messages = state["messages"]- response = model_with_tools.invoke(messages)- return {"messages": [response]}-```-#### 5. Define the Graph Nodes and Edges--To establish the agent's workflow, we begin by initializing the workflow with `agent` and `tools` node, followed by specifying the connecting edges between nodes, finally compiling the workflow. These edges can be straightforward or conditional, depending on the workflow requirements.+Each wrapped tool builds its `args_schema` from the Composio tool's input schema. When argument validation fails, the tool does not raise; it returns a structured result:```python-def should_continue(state: MessagesState) -> Literal["tools", "__end__"]:- messages = state["messages"]- last_message = messages[-1]- if last_message.tool_calls:- return "tools"- return "__end__"---workflow = StateGraph(MessagesState)--# Define the two nodes we will cycle between-workflow.add_node("agent", call_model)-workflow.add_node("tools", tool_node)--workflow.add_edge("__start__", "agent")-workflow.add_conditional_edges(- "agent",- should_continue,-)-workflow.add_edge("tools", "agent")--app = workflow.compile()+{"successful": False, "error": "<validation message>", "data": None}```-#### 6. Invoke & Check Response-After the compilation of workflow, we invoke the LLM with a task, and stream the response.+Check `successful` in tool output instead of wrapping calls in `try`/`except`.-```python-for chunk in app.stream(- {- "messages": [- (- "human",- # "Star the Github Repository composiohq/composio",- "Get my information.",- )- ]- },- stream_mode="values",-):- chunk["messages"][-1].pretty_print()-```+## Links++- [LangChain provider docs](https://docs.composio.dev/docs/providers/langchain) (covers LangGraph)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/llamaindex/README.md b/python/providers/llamaindex/README.mdindex 9a9811cb8..63162d8e4 100644--- a/python/providers/llamaindex/README.md+++ b/python/providers/llamaindex/README.md@@ -1,4 +1,53 @@-## Using Composio With LLamaIndex+# composio-llamaindex-Integrate Composio with LLamaIndex Agentic workflows & enable them to interact seamlessly-with external apps, enhancing their functionality and reach.+Adapts Composio tools to LlamaIndex's `FunctionTool` format so a LlamaIndex agent can call 1000+ apps through a single Composio session.++## Installation++```bash+pip install composio composio-llamaindex llama-index llama-index-llms-openai+```++Set `COMPOSIO_API_KEY` (get one from [dashboard.composio.dev/settings](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment:++```bash+export COMPOSIO_API_KEY=xxxxxxxxx+export OPENAI_API_KEY=xxxxxxxxx+```++## Quickstart++Create a session for your user, fetch its tools, and hand them to a `FunctionAgent`. LlamaIndex drives the tool calls; each tool executes itself through Composio.++```python+import asyncio++from composio import Composio+from composio_llamaindex import LlamaIndexProvider+from llama_index.core.agent.workflow import FunctionAgent+from llama_index.llms.openai import OpenAI++composio = Composio(provider=LlamaIndexProvider())+llm = OpenAI(model="gpt-5.2")++# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()++agent = FunctionAgent(tools=tools, llm=llm)+++async def main():+ result = await agent.run(+ user_msg="Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"+ )+ print(result)+++asyncio.run(main())+```++## Links++- [LlamaIndex provider docs](https://docs.composio.dev/docs/providers/llamaindex)+- [Composio documentation](https://docs.composio.dev)diff --git a/python/providers/openai/README.md b/python/providers/openai/README.mdindex 3409c3725..4e017726c 100644--- a/python/providers/openai/README.md+++ b/python/providers/openai/README.md@@ -1,73 +1,70 @@-## 🚀🔗 Leveraging OpenAI with Composio+# composio-openai-Facilitate the integration of OpenAI with Composio to empower OpenAI models to directly interact with external applications, broadening their capabilities and application scope.+Adapts Composio tools to OpenAI function calling, for both the Responses API and the Chat Completions API.-### Objective--- **Automate starring a GitHub repository** using conversational instructions via OpenAI Function Calls.--### Installation and Setup--Ensure you have the necessary packages installed and connect your GitHub account to allow your agents to utilize GitHub functionalities.+## Installation```bash-# Install Composio LangChain package-pip install composio-openai--# Connect your GitHub account-composio-cli add github--# View available applications you can connect with-composio-cli show-apps+pip install composio composio-openai openai```-### Usage Steps+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `OPENAI_API_KEY` in your environment.-#### 1. Import Base Packages+## Quickstart-Prepare your environment by initializing necessary imports from OpenAI and setting up your client.+This package exports two providers: `OpenAIResponsesProvider` for the [Responses API](https://platform.openai.com/docs/api-reference/responses) and `OpenAIProvider` for Chat Completions. Both are non-agentic: the model returns tool calls, you execute them with `handle_tool_calls`, and you feed the results back.```python+import jsonfrom openai import OpenAI--# Initialize OpenAI client-openai_client = OpenAI()-```--### Step 2: Integrating GitHub Tools with Composio--This step involves fetching and integrating GitHub tools provided by Composio, enabling enhanced functionality for LangChain operations.-```python-from composio_openai import App, ComposioToolSet--toolset = ComposioToolSet()-actions = toolset.get_tools(apps=[App.GITHUB])-```--### Step 3: Agent Execution--This step involves configuring and executing the agent to carry out actions, such as starring a GitHub repository.--```python-my_task = "Star a repo composiohq/composio on GitHub"--# Create a chat completion request to decide on the action-response = openai_client.chat.completions.create(model="gpt-5",- tools=actions, # Passing actions we fetched earlier.- messages=[- {"role": "system", "content": "You are a helpful assistant."},- {"role": "user", "content": my_task}+from composio import Composio+from composio_openai import OpenAIResponsesProvider++composio = Composio(provider=OpenAIResponsesProvider())+client = OpenAI()++# Create a session for your user+session = composio.create(user_id="user_123")+tools = session.tools()++response = 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:+ 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)])-pprint(response)+# Print final response+for item in response.output:+ if item.type == "message":+ print(item.content[0].text)```-### Step 4: Validate Execution Response+## Chat Completions-Execute the following code to validate the response, ensuring that the intended task has been successfully completed.+`OpenAIProvider` targets `client.chat.completions.create` and is the Composio SDK default, so `Composio()` with no provider uses it. The loop is the same shape: call `handle_tool_calls` on each response, append the results as `tool` messages, and call the API again. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the full example.-```python-result = toolset.handle_tool_calls(response)-pprint(result)-```+## Links++- OpenAI provider docs: https://docs.composio.dev/docs/providers/openai+- Composio docs: https://docs.composio.devdiff --git a/python/providers/openai_agents/README.md b/python/providers/openai_agents/README.mdindex b772a7ea5..28af5272c 100644--- a/python/providers/openai_agents/README.md+++ b/python/providers/openai_agents/README.md@@ -1,60 +1,41 @@-# Composio Integration for OpenAI Agents+# composio-openai-agents-This package integrates the OpenAI Agents framework with Composio, allowing you to use Composio's rich set of tools with the OpenAI Agents framework.+Adapts Composio tools to the [OpenAI Agents](https://github.com/openai/openai-agents-python) framework's native tool format, so your agents can take action across 1000+ apps.## Installation```bash-pip install composio_openai_agents+pip install composio composio-openai-agents openai-agents```-## Usage+Set `COMPOSIO_API_KEY` (from the [dashboard](https://dashboard.composio.dev/settings)) and `OPENAI_API_KEY` in your environment.++## Quickstart```python-import asyncio-import dotenv+from composio import Composio+from composio_openai_agents import OpenAIAgentsProviderfrom agents import Agent, Runner-from composio_openai_agents import Action, ComposioToolSet--# Load environment variables from .env-dotenv.load_dotenv()+composio = Composio(provider=OpenAIAgentsProvider())-# Initialize Composio toolset-composio_toolset = ComposioToolSet()+# Each session is scoped to one of your users+session = composio.create(user_id="user_123")+tools = session.tools()-# Get all the tools-tools = composio_toolset.get_tools(actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER])--# Create an agent with the toolsagent = Agent(- name="GitHub Agent",- instructions="You are a helpful assistant that helps users with GitHub tasks.",+ name="Personal Assistant",+ instructions="You are a helpful assistant. Use Composio tools to take action.",tools=tools,)-# Run the agent-async def main():- result = await Runner.run(agent, "Star the repository composiohq/composio on GitHub")- print(result.final_output)--asyncio.run(main())+result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")+print(result.final_output)```-## Features--- Seamlessly integrate Composio's tools with OpenAI Agents-- Access hundreds of pre-built API integrations-- Maintain consistent schema formats between frameworks-- Error handling for validation issues-- Proper type annotations that work with mypy and pylance--## Requirements--- Python 3.9+-- OpenAI Agents framework-- Composio (with valid API key)+By default a session gets meta tools that discover, authenticate, and execute app tools at runtime. For multi-turn use, store `session.session_id` and reuse it with `composio.use(session_id)` instead of calling `create()` again.-## License+## Links-Apache 2.0\ No newline at end of file+- [Quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/README.md b/ts/README.mdindex 5dd31f2d7..fd6b2009a 100644--- a/ts/README.md+++ b/ts/README.md@@ -1,305 +1,89 @@-# Composio SDK v3+# Composio TypeScript workspace-The Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. It helps you connect to various services (toolkits), execute tools, and manage user connections seamlessly.+This directory contains the TypeScript half of the Composio SDK monorepo: the core SDK, provider adapters, the CLI, examples, and end-to-end tests. For an overview of Composio itself, start at the [root README](../README.md) and [docs.composio.dev](https://docs.composio.dev).-## Features--- Execute tools from various services (GitHub, Gmail, Slack, etc.)-- Manage user connections to external services-- Create session-scoped custom tools with your own logic-- Integrate with AI providers like OpenAI-- Powerful middleware and modifier support-- Extensive error handling--## Documentation--The SDK is thoroughly documented in the [docs](./docs) directory:--- [Overview](./docs/overview.md) - Introduction and key concepts-- [Getting Started](./docs/getting-started.md) - Quick start guide-- [Core Concepts](./docs/core-concepts.md) - Fundamental SDK concepts-- [Configuration](./docs/internal/configuration.md) - Environment variables and SDK configuration--### API Reference--- [Composio Class](./docs/api/composio.md) - Main SDK class-- [Tools](./docs/api/tools.md) - Listing, fetching, and executing tools-- [Tool Router](./docs/api/tool-router.md) - Sessions, search, and custom tools-- [Toolkits](./docs/api/toolkits.md) - Working with tool collections-- [Connected Accounts](./docs/api/connected-accounts.md) - User authentication-- [Auth Configs](./docs/api/auth-configs.md) - Authentication configuration-- [Providers](./docs/api/providers.md) - AI integration options--### Provider Documentation--- [OpenAI Provider](./docs/providers/openai.md) - Using OpenAI with Composio-- [Google Provider](./docs/providers/google.md) - Using Google GenAI with Composio-- [Custom Providers](./docs/providers/custom.md) - Creating new providers--### Advanced Topics--- [Error Handling](./docs/advanced/error-handling.md) - Managing errors-- [Middleware and Modifiers](./docs/advanced/modifiers.md) - Customizing tools-- [Telemetry](./docs/advanced/telemetry.md) - SDK usage tracking-- [Custom Providers](./docs/advanced/custom-providers.md) - Detailed provider guide--### Internal Documentation--For SDK maintainers and contributors:--- [Configuration and Environment Variables](./docs/internal/configuration.md) - Detailed guide on SDK configuration-- [Triggers Implementation](./docs/internal/triggers.md) - Internal workings of the trigger system--## Installation+If you just want to use the SDK:```bash-# Using npmnpm install @composio/core--# Using yarn-yarn add @composio/core--# Using pnpm-pnpm add @composio/core```-## Quick Start-```typescriptimport { Composio } from '@composio/core';-// Initialize the SDK-const composio = new Composio({- apiKey: 'your-api-key',-});--// Get tools from a specific toolkit-const tools = await composio.tools.get('default', {- toolkits: ['github'],-});--// Get a specific tool-const specificTool = await composio.tools.get('default', 'GITHUB_GET_REPOS');--// Execute a tool-const result = await composio.tools.execute('GITHUB_GET_REPO', {- userId: 'default',- arguments: {- owner: 'composio',- repo: 'sdk',- },-});+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-console.log(result.data);+const session = await composio.create('user_123');+const tools = await session.tools();```-## OpenAI Integration--```typescript-import { Composio } from '@composio/core';-import OpenAI from 'openai';--// Initialize Composio and OpenAI-const composio = new Composio({- apiKey: 'your-composio-api-key',-});--const openai = new OpenAI({- apiKey: 'your-openai-api-key',-});+See the [`@composio/core` README](packages/core/README.md) and the [quickstart](https://docs.composio.dev/docs/quickstart) for the full flow, including provider setup for your agent framework.-// Get GitHub tools-const tools = await composio.tools.get('default', {- toolkits: ['github'],-});+## Packages+Published packages:-// Create a chat completion with the tools-const completion = await openai.chat.completions.create({- model: 'gpt-4',- messages: [- { role: 'system', content: 'You are a helpful assistant with access to GitHub tools.' },- { role: 'user', content: 'Find information about the Composio SDK repository' },- ],- tools, // Pass the tools to OpenAI-});+| Package | Description |+|---------|-------------|+| [`@composio/core`](packages/core) | The Composio SDK. Ships its TypeScript source and SDK docs so installed copies are inspectable by coding agents. |+| [`@composio/slim`](packages/slim) | Same API as `@composio/core` without the packaged source and docs; smaller install. |+| [`composio` CLI](packages/cli) | Standalone CLI binary: search, execute, and script tools from your shell. |+| [`@composio/*` providers](packages/providers) | Adapters that format Composio tools for agent frameworks (OpenAI, Anthropic, Vercel AI SDK, LangChain, and more). See the [provider table](../README.md#providers). |+| [`@composio/experimental`](packages/experimental) | Experimental integrations, currently the Pi provider. |+| [`@composio/json-schema-to-zod`](packages/json-schema-to-zod) | JSON Schema to Zod conversion. |-// If the model wants to use a tool-if (completion.choices[0].message.tool_calls) {- const toolCall = completion.choices[0].message.tool_calls[0];- const args = JSON.parse(toolCall.function.arguments);+Internal (unpublished) packages: `cli-keyring` and `cli-local-tools` support the CLI; `ts-builders` generates TypeScript source.- // Execute the tool- const result = await composio.tools.execute(toolCall.function.name, {- userId: 'default',- arguments: args,- });+## Layout- console.log(result.data);-}+```text+ts/+ packages/ Published and internal packages (see above)+ examples/ Runnable examples per feature and framework+ e2e-tests/ Runtime E2E tests (Node, Deno, Cloudflare Workers, CLI)+ docs/ Workspace SDK docs: API notes and internal guides+ scripts/ Build, validation, and scaffolding scripts+ vendor/ Read-only reference submodules; do not edit```-## Creating Custom Tools+## Development-```typescript-import { Composio, experimental_createTool } from '@composio/core';-import { z } from 'zod';--const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });--const weatherForecast = experimental_createTool('WEATHER_FORECAST', {- name: 'Weather Forecast',- description: 'Get the weather forecast for a location',- inputParams: z.object({- location: z.string().describe('The location to get the forecast for'),- days: z.number().optional().default(3).describe('Number of days for the forecast'),- }),- execute: async (input) => {- const { location, days = 3 } = input;- const forecast = await getWeatherForecast(location, days);- return { forecast };- },-});+Commands run from the repository root. Install the pinned toolchain first:-const session = await composio.create('default', {- experimental: { customTools: [weatherForecast] },-});--const result = await session.execute('WEATHER_FORECAST', {- location: 'San Francisco, CA',-});+```bash+mise install+pnpm install```-## Project Structure+Build and verify:-```-composio/-├── packages/ # Main packages directory-│ ├── core/ # Core SDK package-│ └── providers/ # Provider implementations-├── examples/ # Example implementations-│ ├── connected-accounts/ # Connected accounts examples-│ ├── langchain/ # LangChain integration examples-│ ├── openai/ # OpenAI integration examples-│ ├── modifiers/ # Modifiers examples-│ ├── toolkits/ # Toolkits examples-│ └── vercel/ # Vercel AI examples-├── docs/ # Documentation-├── scripts/ # Development and build scripts-└── .github/ # GitHub configuration+```bash+pnpm build:packages # build all TS packages+pnpm typecheck # typecheck all TS packages+pnpm lint:packages # eslint over ts/packages+pnpm test # package unit tests plus example validation```-## Development Setup+Runtime E2E suites (require credentials):-1. **Prerequisites**-- - Node.js (Latest LTS version recommended)- - [pnpm](https://pnpm.io/) (v10.8.0 or later)- - [bun](https://bun.sh) for productivity (optional)--2. **Clone and Install**-- ```bash- git clone https://github.com/ComposioHQ/sdk-v3-ts.git- cd composio- pnpm install- ```--3. **Build**-- ```bash- pnpm build- ```--4. **Development Commands**-- ```bash- # Lint code- pnpm lint-- # Fix linting issues- pnpm lint:fix-- # Format code- pnpm format-- # Create a new provider- pnpm create:provider <provider-name> [--agentic]-- # Create a new example- pnpm create:example <example-name>-- # Check peer dependencies- pnpm check:peer-deps-- # Update peer dependencies- pnpm update:peer-deps- ```--## Creating a New Example--1. Use the create:example script:-- ```bash- pnpm create:example my-example- ```--2. The script will create a new example in `examples/my-example` with:-- - `package.json` with minimal dependencies (`@composio/core` and `dotenv`)- - `tsconfig.json` for TypeScript configuration- - `.env.example` and `.env` files for environment variables- - `src/index.ts` with basic Composio SDK setup- - `README.md` with setup and usage instructions- - Dependencies automatically installed--3. Next steps after creation:- - Edit `.env` and add your `COMPOSIO_API_KEY`- - Customize `src/index.ts` with your example logic- - Add any additional dependencies as needed- - Run with `pnpm start` or `pnpm dev` (with file watching)--## Creating a New Provider--1. Use the create:provider script:-- ```bash- pnpm create:provider my-provider [--agentic]- ```--2. The script will create a new provider in `packages/providers/my-provider` with:-- - Basic provider implementation- - TypeScript configuration- - Package configuration- - README template--3. Implement the required methods in `src/index.ts`:- - For non-agentic providers: `wrapTool` and `wrapTools`- - For agentic providers: `wrapTool`, `wrapTools`, and execution handlers--## Release Process--For detailed information about both automated and manual release processes, please refer to our [Release Process Documentation](./docs/internal/release.md).--## Environment Variables--- `COMPOSIO_API_KEY`: Your Composio API key-- `COMPOSIO_BASE_URL`: Custom API base URL (optional)-- `COMPOSIO_LOG_LEVEL`: Logging level (silent, error, warn, info, debug)-- `COMPOSIO_DISABLE_TELEMETRY`: Disable telemetry when set to "true"-- `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>`: Specific version for a toolkit (e.g., `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`)-- `DEVELOPMENT`: Development mode flag-- `CI`: CI environment flag--## Contributing+```bash+pnpm test:e2e:node+pnpm test:e2e:deno+pnpm test:e2e:cloudflare+pnpm test:e2e:cli+```-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.+Scaffolding:-## License+```bash+pnpm create:provider <name> [--agentic] # new provider package+pnpm create:example <name> # new example under ts/examples+```-ISC License+Changesets are required for changes to published packages; see the [contribution guidelines](../CONTRIBUTING.md).## Support-For support, please visit our [Documentation](./docs) or join our [Discord Community](https://discord.gg/composio).+- [Documentation](https://docs.composio.dev)+- [Discord community](https://discord.gg/composio)+- [Open an issue](https://github.com/ComposioHQ/composio/issues)diff --git a/ts/packages/core/README.md b/ts/packages/core/README.mdindex 6c07aace7..4f36d7343 100644--- a/ts/packages/core/README.md+++ b/ts/packages/core/README.md@@ -1,304 +1,119 @@--# @composio/core-The core Composio SDK which allows users to interact with the Composio Platform. It provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various platforms and frameworks.--[Learn more about the SDK from our docs](https://docs.composio.dev)+The Composio SDK for TypeScript. Create a session for one of your users, hand its tools to your agent, and let the agent take action across 1000+ apps with authentication handled for you.-## Core Features--- **Tools**: Manage and execute tools within the Composio ecosystem. Includes functionality to list, retrieve, and execute tools.-- **Toolkits**: Organize and manage collections of tools for specific use cases.-- **Triggers**: Create and manage event triggers that can execute tools based on specific conditions.-- **AuthConfigs**: Configure authentication providers and settings.-- **ConnectedAccounts**: Manage third-party service connections.-- **ActionExecution**: Track and manage the execution of actions within the platform.+Full documentation lives at [docs.composio.dev](https://docs.composio.dev). This package intentionally ships its TypeScript source and SDK docs so the installed package is inspectable by coding agents; if you want a smaller install with the same API, use [`@composio/slim`](https://www.npmjs.com/package/@composio/slim).## Installation```bashnpm install @composio/core-# or-yarn add @composio/core-# or-pnpm add @composio/core```-## Getting Started+## Quickstart-### Basic Usage with OpenAI Provider+Grab a `COMPOSIO_API_KEY` from the [dashboard](https://dashboard.composio.dev/settings), then create a session:```typescriptimport { Composio } from '@composio/core';-import { OpenAI } from 'openai';--// Initialize OpenAI client-const openai = new OpenAI({- apiKey: process.env.OPENAI_API_KEY,-});--// Initialize Composio with your API key-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,-});--async function main() {- try {- // Fetch tools - single tool or multiple tools- const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER');- // Or fetch multiple tools: await composio.tools.get('default', { toolkits: ['hackernews'] });-- const query = "Find information about the HackerNews user 'pg'";-- // Create chat completion with tools- const response = await openai.chat.completions.create({- model: 'gpt-4o',- messages: [- {- role: 'system',- content: 'You are a helpful assistant that can use tools to answer questions.',- },- { role: 'user', content: query },- ],- tools: tools,- tool_choice: 'auto',- });-- // Handle tool calls if the assistant decides to use them- if (response.choices[0].message.tool_calls) {- console.log(- '🔧 Assistant is using tool:',- response.choices[0].message.tool_calls[0].function.name- );-- // Execute the tool call- const toolResult = await composio.provider.executeToolCall(- 'default',- response.choices[0].message.tool_calls[0],- {- connectedAccountId: '', // Optional: specify connected account- }- );-- console.log('✅ Tool execution result:', JSON.parse(toolResult));-- // Get final response from assistant with tool result- const finalResponse = await openai.chat.completions.create({- model: 'gpt-4o',- messages: [- {- role: 'system',- content: 'You are a helpful assistant that can use tools to answer questions.',- },- { role: 'user', content: query },- response.choices[0].message,- {- role: 'tool',- tool_call_id: response.choices[0].message.tool_calls[0].id,- content: toolResult,- },- ],- });-- console.log('🤖 Final response:', finalResponse.choices[0].message.content);- } else {- console.log('🤖 Response:', response.choices[0].message.content);- }- } catch (error) {- console.error('❌ Error:', error);- }-}--main();-```--## Configuration-The Composio constructor accepts the following configuration options:+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-```typescript-interface ComposioConfig {- apiKey?: string | null; // Your Composio API key- baseURL?: string | null; // Custom API base URL (optional)- allowTracking?: boolean; // Enable/disable telemetry (default: true)- dangerouslyAllowAutoUploadDownloadFiles?: boolean; // Opt-in for automatic file upload/download during tool execution (default: false)- provider?: TProvider; // Custom provider (default: OpenAIProvider)- host?: string; // Name of the host service which is using the SDK, this is for telemetry- defaultHeaders?: ComposioRequestHeaders; // Request headers to be passed to the Composio API client- disableVersionCheck?: boolean; // Whether to disable version check for the Composio SDK (default: false)-}-```--## Modifiers--Composio SDK supports powerful modifiers to transform tool schemas and execution behavior.--### Schema Modifiers--Schema modifiers allow you to transform tool schemas before they are used:--```typescript-const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {- modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({- ...tool,- description: 'Enhanced HackerNews search with additional features',- inputParameters: {- ...tool.inputParameters,- limit: {- type: 'number',- description: 'Maximum number of posts to return',- default: 10,- },- },- }),-});+// Each session is scoped to one of your users+const session = await composio.create('user_123');+const tools = await session.tools();```-### Execution Modifiers+By default a session gives your agent a small set of meta tools that discover, authenticate, and execute app tools at runtime, so you never load hundreds of tool definitions into context. Without a provider configured, `session.tools()` returns OpenAI function-calling format.-For agentic providers (like Vercel AI and Langchain), you can also modify tool execution behavior:+Sessions persist on the server. For multi-turn conversations, store `session.sessionId` and reuse it instead of calling `create()` again:```typescript-const tools = await composio.tools.get('user123', 'HACKERNEWS_SEARCH_POSTS', {- // Transform input before execution- beforeExecute: ({ toolSlug, toolkitSlug, params }) => ({- ...params,- arguments: {- ...params.arguments,- limit: Math.min((params.arguments?.limit as number) || 10, 100),- },- }),-- // Transform output after execution- afterExecute: ({ toolSlug, toolkitSlug, result }) => ({- ...response,- data: {- ...response.data,- posts: (response.data?.posts as any[]).map(post => ({- ...post,- url: post.url || `https://news.ycombinator.com/item?id=${post.id}`,- })),- },- }),-});+const session = await composio.use(sessionId);```-## Connected Accounts+See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.-Composio SDK provides a powerful way to manage third-party service connections through Connected Accounts. This feature allows you to authenticate with various services and maintain those connections.+## Providers-### Creating a Connected Account+A provider formats session tools for your agent framework and wires up execution:```typescriptimport { Composio } from '@composio/core';+import { OpenAIAgentsProvider } from '@composio/openai-agents';-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,-});+const composio = new Composio({ provider: new OpenAIAgentsProvider() });-// Create a connected account-const connectionRequest = await composio.connectedAccounts.initiate(- 'user123', // userId- 'ac_12343544', // authConfigId: You can create it from the dashboard- {- callbackUrl: 'https://your-app.com/callback',- data: {- // Additional data for the connection- scope: ['read', 'write'],- },- }-);--// Wait for the connection to be established-// Default timeout is 60 seconds-const connectedAccount = await connectionRequest.waitForConnection();-console.log({ connectedAccount });+const session = await composio.create('user_123');+const tools = await session.tools(); // ready to pass to the OpenAI Agents SDK```-### Waiting for Connection Establishment+Adapters exist for OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel AI SDK, Google GenAI, LangChain, LlamaIndex, Mastra, and Cloudflare Workers AI. See the [provider table](https://github.com/ComposioHQ/composio#providers) and the [framework quickstarts](https://docs.composio.dev/docs/quickstart).-The `waitForConnection` method is available on both the `ConnectionRequest` and `ConnectedAccounts` classes. It allows you to poll for a connection to become active:+## MCP++Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to surface it in the type, then point Claude, Cursor, or any MCP client at it:```typescript-// From a ConnectionRequest instance (returned by createConnectedAccount)-const connectedAccount = await connectionRequest.waitForConnection(120000); // 2 minute timeout+const session = await composio.create('user_123', { mcp: true });-// From the ConnectedAccounts class (using a connected account ID)-const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_abc123', 60000); // 1 minute timeout+console.log(session.mcp.url);+console.log(session.mcp.headers);```-The method continuously polls the Composio API until the connection:--- Becomes `ACTIVE` (returns the connected account)-- Enters a terminal state like `FAILED`, `EXPIRED`, or `DELETED` (throws an error)-- Exceeds the specified timeout (throws a timeout error)+See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).-If the connection does not complete within the provided timeout (default: 60 seconds), a `ConnectionRequestTimeoutError` is thrown.+## Modifiers-### Managing Connected Accounts+`session.tools()` accepts modifiers to transform tool schemas and intercept execution:```typescript-// List all connected accounts-const accounts = await composio.connectedAccounts.list({- userId: 'user123',+const tools = await session.tools({+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({+ ...schema,+ description: `${schema.description} (via my-app)`,+ }),+ beforeExecute: ({ toolSlug, toolkitSlug, params }) => params,+ afterExecute: ({ toolSlug, toolkitSlug, result }) => result,});--// Get a specific connected account-const account = await composio.connectedAccounts.get('account_id');--// Enable/Disable a connected account-await composio.connectedAccounts.enable('account_id');-await composio.connectedAccounts.disable('account_id');--// Refresh credentials-await composio.connectedAccounts.refresh('account_id');--// Delete a connected account-await composio.connectedAccounts.delete('account_id');```-### Connection Statuses+See [modify tool behavior](https://docs.composio.dev/docs/tools-direct/modify-tool-behavior/schema-modifiers).-Connected accounts can have the following statuses:+## Configuration-- `ACTIVE`: Connection is established and working-- `INACTIVE`: Connection is temporarily disabled-- `PENDING`: Connection is being processed-- `INITIATED`: Connection request has started-- `EXPIRED`: Connection credentials have expired-- `FAILED`: Connection attempt failed+The `Composio` constructor accepts:-### Authentication Schemes+```typescript+interface ComposioConfig {+ apiKey?: string | null; // Defaults to COMPOSIO_API_KEY+ baseURL?: string | null; // Custom API base URL+ provider?: TProvider; // Provider adapter (default: OpenAIProvider)+ allowTracking?: boolean; // Enable/disable telemetry (default: true)+ defaultHeaders?: ComposioRequestHeaders; // Extra headers for API requests+ disableVersionCheck?: boolean; // Skip the SDK version check (default: false)+ dangerouslyAllowAutoUploadDownloadFiles?: boolean; // Auto file upload/download during execution (default: false)+}+```-Composio supports various authentication schemes:+Environment variables:-- OAuth2-- OAuth1-- OAuth1a-- API Key-- Basic Auth-- Bearer Token-- Google Service Account-- And more...+- `COMPOSIO_API_KEY`: your Composio API key+- `COMPOSIO_BASE_URL`: custom API base URL+- `COMPOSIO_LOG_LEVEL`: `silent`, `error`, `warn`, `info`, or `debug`+- `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>`: pin a toolkit version, e.g. `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`-## Environment Variables+## Beyond sessions-- `COMPOSIO_API_KEY`: Your Composio API key-- `COMPOSIO_BASE_URL`: Custom API base URL-- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)-- `DEVELOPMENT`: Development mode flag-- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific tool-- `CI`: CI environment flag+The `Composio` instance also exposes `composio.toolkits`, `composio.triggers`, `composio.authConfigs`, and `composio.connectedAccounts` for managing resources outside a session. The older [direct tool execution](https://docs.composio.dev/docs/tools-direct/executing-tools) flow (`composio.tools.get` and `composio.tools.execute`) still works but is legacy; prefer sessions for new code.-## Contributing+## Support-We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.+- [Documentation](https://docs.composio.dev)+- [TypeScript SDK reference](https://docs.composio.dev/reference/sdk-reference/typescript)+- [Discord community](https://discord.gg/composio)+- [Open an issue](https://github.com/ComposioHQ/composio/issues)## License-ISC License--## Support--For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+MITdiff --git a/ts/packages/experimental/README.md b/ts/packages/experimental/README.mdindex 308b159df..78f16eab1 100644--- a/ts/packages/experimental/README.md+++ b/ts/packages/experimental/README.md@@ -1,214 +1,20 @@# `@composio/experimental`-Experimental Composio integrations and helpers.+Experimental additions to the Composio TypeScript SDK. Features ship here before they are ready for [`@composio/core`](../core), so APIs can change or be removed between releases.-This package currently includes two framework providers:--- A **Pi provider** for [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). It lets Composio tools be passed to Pi SDK sessions as `customTools` and includes a dynamic Tool Router session toolset modeled after the Slack bot integration in `~/composio/slack-bot`.-- An **eve provider** for the [eve](https://github.com/vercel/eve) agent framework (see [eve provider](#eve-provider) below).--## Install+## Installation```bash-pnpm add @composio/core @composio/experimental @earendil-works/pi-coding-agent-```--## Static tool wrapping--Use this when you already know the exact Composio tools to expose to Pi.--```ts-import { Composio } from '@composio/core';-import { PiProvider } from '@composio/experimental';-import { createAgentSession, SessionManager } from '@earendil-works/pi-coding-agent';--const provider = new PiProvider();-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider,-});--const tools = await composio.tools.get('default', {- tools: ['GITHUB_CREATE_ISSUE'],-});--const { session } = await createAgentSession({- cwd: process.cwd(),- sessionManager: SessionManager.inMemory(process.cwd()),- customTools: tools,- tools: ['read', 'bash', ...tools.map(tool => tool.name)],-});--await session.prompt('Create a GitHub issue for the failing test.');-```--## Dynamic session helpers--Use this when Pi should search and execute tools dynamically inside one Tool Router session. Prefer the capability form so your app owns connection management and uses one Pi-style `hooks` object for interception/result transforms.--```ts-import { Composio } from '@composio/core';-import { PiProvider, createPiComposioSystemPrompt } from '@composio/experimental';-import {- createAgentSession,- DefaultResourceLoader,- getAgentDir,- SessionManager,-} from '@earendil-works/pi-coding-agent';--const provider = new PiProvider();-const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });--const composioSession = await composio.sessions.create('slack:T123:U456', {- toolkits: ['github', 'gmail'],- manageConnections: true,- workbench: { enable: true },-});--const composioTools = provider.createSessionTools({- sessionId: composioSession.sessionId,- search: composioSession.search.bind(composioSession),- execute: composioSession.execute.bind(composioSession),- callbackUrl: 'https://your-app.example.com/auth/callback',- includeWorkbenchTools: true,- connections: {- getToolkitStates: toolkits => composioSession.toolkits({ toolkits }),- authorizeToolkit: (toolkit, options) => composioSession.authorize(toolkit, options),- isConnected: state => state.connection?.isActive === true,- },- hooks: {- search: (ctx, next) => {- ctx.request.toolkits = ctx.request.toolkits?.map(toolkit =>- toolkit === 'slack' ? 'slackbot' : toolkit- );- return next();- },- execute: (ctx, next) => {- if (ctx.request.toolSlug === 'COMPOSIO_MANAGE_CONNECTIONS') {- return ctx.deny('Meta tools are blocked.');- }- return next();- },- remoteWorkbench: async (ctx, next) => {- const result = await next();- await auditWorkbenchRun({ code: ctx.request.code_to_execute, result });- return result;- },- remoteBash: async (ctx, next) => {- if (ctx.request.command.includes('rm -rf')) {- return ctx.deny('Destructive bash commands are blocked.');- }- return next();- },- onAuthLink: async (ctx, next) => {- // DM the user, store the continuation, or redact public output.- await sendConnectionLinkToUser({ url: ctx.url, toolkit: ctx.toolkit });- return { message: 'Connection link sent out-of-band.' };- // To also send the original result/link to the model, use: return next();- },- },- transformResult: async ({ value }) => value,-});--const loader = new DefaultResourceLoader({- cwd: process.cwd(),- agentDir: getAgentDir(),- systemPromptOverride: () =>- createPiComposioSystemPrompt(composioSession.sessionId, { includeWorkbenchTools: true }),-});-await loader.reload();--const { session } = await createAgentSession({- cwd: process.cwd(),- resourceLoader: loader,- sessionManager: SessionManager.inMemory(process.cwd()),- customTools: composioTools,- tools: [- 'read',- 'bash',- 'composio_search_tools',- 'composio_manage_connections',- 'composio_execute_tool',- 'composio_remote_workbench',- 'composio_remote_bash',- ],-});--await session.prompt('Find my recent GitHub issues and summarize the blockers.');-```--`composio_manage_connections` uses your `connections.getToolkitStates()` and `connections.authorizeToolkit()` handlers. It does **not** call `session.execute('COMPOSIO_MANAGE_CONNECTIONS', ...)` internally.--The dynamic helpers are:--- `composio_search_tools` — search Tool Router for exact tool slugs and schemas.-- `composio_manage_connections` — check/initiate user app connections.-- `composio_execute_tool` — execute exact Composio tool slugs in the session.-- `composio_remote_workbench` — execute Python in the Composio remote workbench for large outputs, remote files, and session-authenticated scripting.-- `composio_remote_bash` — run short bash commands in the Composio remote workbench filesystem.--Workbench helpers are opt-in because the Tool Router session must be created with workbench enabled.--## Hooks--`hooks` follows Pi's extension-event style with middleware semantics. Each hook receives a mutable `ctx.request`, `ctx.deny('reason')`, and a typed `next()` function. Calling `await next()` runs the default Composio behavior and returns the result before anything is sent back to the model. Return that result to pass it through, return a replacement value to control what the model sees, or skip `next()` entirely to divert/deny the operation.--Available hooks:--- `search(ctx, next)` — rewrite query/toolkit filters, log search results, or return custom search output.-- `manageConnections(ctx, next)` — rewrite requested toolkits, force reauth, log connection state, or return custom connection output.-- `execute(ctx, next)` — block/rewrite tools, route to another session/execute handler, call `ctx.manageConnections(...)`, log outputs, or return a file/workbench reference instead of inline data.-- `remoteWorkbench(ctx, next)` — rewrite Python code/session metadata, audit workbench runs, or replace large outputs with file/workbench references. Calls through the generic `execute` hook when `next()` is used.-- `remoteBash(ctx, next)` — rewrite/block shell commands, enforce safety policy, audit filesystem access, or replace output. Calls through the generic `execute` hook when `next()` is used.-- `onAuthLink(ctx, next)` — send/redact/resume auth links out-of-band. `return next()` keeps the original model-visible result; returning another value replaces it.--## Auth link handling--Embedded agents often need to keep Composio connection URLs out of the public transcript. Use `hooks.onAuthLink()` to choose whether the model sees the original result or a redacted replacement:--```ts-const tools = provider.createSessionTools({- search: composioSession.search.bind(composioSession),- execute: composioSession.execute.bind(composioSession),- connections: {- getToolkitStates: toolkits => composioSession.toolkits({ toolkits }),- authorizeToolkit: (toolkit, options) => composioSession.authorize(toolkit, options),- },- hooks: {- onAuthLink: async (ctx, next) => {- await sendConnectionLinkToUser({ url: ctx.url, toolkit: ctx.toolkit });-- if (shouldAlsoShowLinkToModel(ctx)) {- return next();- }-- return { message: 'Connection link sent out-of-band.' };- },- },-});-```--## eve provider--`EveProvider` is a Composio provider for the [eve](https://github.com/vercel/eve) agent framework. It makes `session.tools()` return eve-native `defineTool`s, so an eve agent gets the Tool Router meta-tools and any preloaded custom toolkits from one call.--```ts-import { Composio } from '@composio/core';-import { EveProvider, defineComposioTools } from '@composio/experimental/eve';--const composio = new Composio({ provider: new EveProvider() });-const session = composio.sessions.create('user_123', {- /* toolkits, customToolkits */-});--// Expose the tools to eve from agent/tools/<name>.ts:-export default defineComposioTools(session);+npm install @composio/core @composio/experimental```-`defineComposioTools(session)` returns a `step.started` dynamic resolver and memoizes `session.tools()`, because the wrapped tools carry live `execute` closures that eve keeps only for step-scoped tools.+## What's inside-The provider also takes `(ctx, next)` hooks (`new EveProvider({ hooks })`) around the meta-tools, with the same rewrite, `deny`, transform, and `onAuthLink` semantics as the Pi hooks above.+- `PiProvider` (root export): adapts Composio tools for [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), including dynamic session helpers that let Pi search, connect, and execute tools at runtime. See the [Pi provider docs](https://docs.composio.dev/docs/providers/pi) for the full guide.+- `EveProvider` (from `@composio/experimental/eve`): adapts Composio tools for the [eve](https://github.com/vercel/eve) agent framework, with hook-based interception and per-tool approval helpers.+- `experimental_createLocalWorkbenchSession` (from `@composio/experimental/workbench`): run a session's sandbox on your local machine instead of the hosted workbench.-## Status+## Links-Experimental. The dynamic helper names and session helper API may change.+- Pi provider docs: https://docs.composio.dev/docs/providers/pi+- Composio docs: https://docs.composio.devdiff --git a/ts/packages/providers/README.md b/ts/packages/providers/README.mdindex 69ef3ddb9..16ed69efd 100644--- a/ts/packages/providers/README.md+++ b/ts/packages/providers/README.md@@ -1,407 +1,44 @@-# Composio Providers+# Composio TypeScript providers-This directory contains various providers that implement the Composio SDK for different platforms and frameworks. Each provider provides a way to interact with the Composio Platform using the specific platform's conventions and requirements.+Each package in this directory adapts Composio tools to one agent framework's native tool format. You pass a provider to `new Composio({ provider })`, and `session.tools()` returns tools your framework can call directly.-## Types of Providers+## Packages-Composio SDK supports two types of providers, each with different modifier capabilities:+| Package | Framework |+|---------|-----------|+| [`@composio/openai`](openai) | OpenAI Chat Completions and Responses APIs |+| [`@composio/openai-agents`](openai-agents) | OpenAI Agents SDK |+| [`@composio/anthropic`](anthropic) | Anthropic Messages API |+| [`@composio/claude-agent-sdk`](claude-agent-sdk) | Claude Agent SDK |+| [`@composio/vercel`](vercel) | Vercel AI SDK |+| [`@composio/google`](google) | Google GenAI |+| [`@composio/langchain`](langchain) | LangChain and LangGraph |+| [`@composio/llamaindex`](llamaindex) | LlamaIndex |+| [`@composio/mastra`](mastra) | Mastra |+| [`@composio/cloudflare`](cloudflare) | Cloudflare Workers AI |-### 1. Non-Agentic Providers+Each package README has an install command and a runnable quickstart.-These providers only support schema modifiers for transforming tool schemas. They are suitable for simple integrations like OpenAI, Anthropic, etc.+## Provider types-Example implementation:+Providers extend one of two base classes from `@composio/core`:-```typescript-import { BaseNonAgenticProvider } from '@composio/core';-import type { Tool, SchemaModifiersParams } from '@composio/core';+- **Non-agentic** (`BaseNonAgenticProvider`): format tool schemas for a raw model API (OpenAI, Anthropic, Cloudflare). Your code runs the tool loop, calling helpers like `executeToolCall` or `handleToolCalls` on the provider.+- **Agentic** (`BaseAgenticProvider`): wrap tools with an execute function baked in (LangChain, LlamaIndex, Mastra, Vercel, OpenAI Agents). The framework runs the tool loop itself.-export class NonAgenticProvider extends BaseNonAgenticProvider {- async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise<Tool> {- // Apply schema modifiers if provided- if (modifiers?.schema) {- return modifiers.schema(toolSlug, tool);- }- return tool;- }+## Creating a new provider- async getTools(): Promise<Tool[]> {- // Fetch tools from Composio API- const response = await this.client.getTools();- return response.data;- }-- async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise<Tool> {- // Fetch tool from Composio API- const response = await this.client.getToolBySlug(slug);- // Apply schema modifiers if provided- return this.wrapTool(slug, response.data, modifiers);- }-}-```--### 2. Agentic Providers--These providers support full modifier capabilities, making them suitable for complex integrations like Vercel, Langchain, etc. They support:--1. **Schema Modifiers**: Transform tool schemas using `TransformToolSchemaModifier`-2. **Execution Modifiers**: Transform tool execution behavior- - `beforeExecute`: Transform input parameters before execution- - `afterExecute`: Transform output after execution-3. **Execute Modifiers**: Used during tool execution- - `beforeExecute`: Transform input parameters- - `afterExecute`: Transform output--Example implementation:--```typescript-import { BaseAgenticProvider } from '@composio/core';-import type { Tool, ModifiersParams, ToolExecuteParams, ToolExecuteResponse } from '@composio/core';--export class AgenticProvider extends BaseAgenticProvider {- async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise<Tool> {- let wrappedTool = tool;-- // Apply schema modifiers if provided- if (modifiers?.schema) {- wrappedTool = modifiers.schema(toolSlug, wrappedTool);- }-- return wrappedTool;- }-- async getTools(modifiers?: ModifiersParams): Promise<Tool[]> {- // Fetch tools from Composio API- const response = await this.client.getTools();- // Apply modifiers to each tool- return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers)));- }-- async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise<Tool> {- // Fetch tool from Composio API- const response = await this.client.getToolBySlug(slug);- // Apply modifiers- return this.wrapTool(slug, response.data, modifiers);- }-- async executeTool(- tool: Tool,- params: ToolExecuteParams,- modifiers?: ModifiersParams- ): Promise<ToolExecuteResponse> {- let executeParams = params;-- // Apply beforeExecute modifier if provided- if (modifiers?.beforeExecute) {- executeParams = modifiers.beforeExecute(tool.slug, executeParams);- }-- // Execute the tool- const response = await this.client.executeTool(tool.slug, executeParams);-- // Apply afterExecute modifier if provided- if (modifiers?.afterExecute) {- return modifiers.afterExecute(tool.slug, response.data);- }-- return response.data;- }-}-```--## Creating a New Provider--To create a new provider, you can use the provided script:+Scaffold a package from the repository root:```bash-# Create a non-agentic provider (default)-pnpm run create-provider <your-provider-name>--# Create an agentic provider-pnpm run create-provider <your-provider-name> --agentic-```--The script will create a new provider with the following structure:--```-<provider-name>/-├── src/-│ └── index.ts # Provider implementation-├── package.json # Package configuration-├── tsconfig.json # TypeScript configuration-├── tsup.config.ts # Build configuration-└── README.md # Provider documentation+pnpm create:provider <provider-name> [--agentic]```-## Required Methods+This creates `ts/packages/providers/<provider-name>` with `src/index.ts`, `package.json`, and build config. Implement `wrapTool` and `wrapTools` (plus `executeToolCall` for non-agentic providers), then add tests covering wrapping and execution handling.-Each provider must implement the following methods:--### For Non-Agentic Providers--```typescript-class NonAgenticProvider extends BaseNonAgenticProvider {- // Wrap a tool with schema modifiers- async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise<Tool>;-- // Get all available tools- async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;-- // Get a specific tool by slug- async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise<Tool>;-}-```+If you are building an adapter outside this repo, see the [custom providers guide](https://docs.composio.dev/docs/providers/custom-providers).-### For Agentic Providers+## Links-```typescript-class AgenticProvider extends BaseAgenticProvider {- // Wrap a tool with modifiers- async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise<Tool>;-- // Get all available tools- async getTools(modifiers?: ModifiersParams): Promise<Tool[]>;-- // Get a specific tool by slug- async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise<Tool>;-- // Execute a tool with modifiers- async executeTool(- tool: Tool,- params: ToolExecuteParams,- modifiers?: ModifiersParams- ): Promise<ToolExecuteResponse>;-}-```--## Modifier Types--### Schema Modifiers (Both Types)--```typescript-type SchemaModifiersParams = {- schema?: TransformToolSchemaModifier;-};--type TransformToolSchemaModifier = (toolSlug: string, tool: Tool) => Tool;-```--### Execution Modifiers (Agentic Only)--```typescript-type ModifiersParams = {- schema?: TransformToolSchemaModifier;- beforeExecute?: beforeExecuteModifier;- afterExecute?: afterExecuteModifier;-};--type beforeExecuteModifier = (toolSlug: string, params: ToolExecuteParams) => ToolExecuteParams;-type afterExecuteModifier = (- toolSlug: string,- response: ToolExecuteResponse-) => ToolExecuteResponse;-```--## Best Practices--1. **Type Safety**: Always use TypeScript and ensure proper type definitions for all methods and parameters.-2. **Error Handling**: Implement proper error handling for API calls and tool execution.-3. **Documentation**: Document your provider's features, requirements, and usage examples.-4. **Testing**: Write tests for your provider implementation.-5. **Modifier Support**:- - For non-agentic providers, implement schema modifiers to transform tool schemas- - For agentic providers, implement both schema and execution modifiers for full control over tool behavior--## Example Implementation--Here's a complete example of a non-agentic provider implementation:--```typescript-import { BaseNonAgenticProvider } from '@composio/core';-import type { Tool, SchemaModifiersParams } from '@composio/core';--export class OpenAIProvider extends BaseNonAgenticProvider {- async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise<Tool> {- // Apply schema modifiers if provided- if (modifiers?.schema) {- return modifiers.schema(toolSlug, tool);- }- return tool;- }-- async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]> {- // Fetch tools from Composio API- const response = await this.client.getTools();- // Apply modifiers to each tool- return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers)));- }-- async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise<Tool> {- // Fetch tool from Composio API- const response = await this.client.getToolBySlug(slug);- // Apply modifiers- return this.wrapTool(slug, response.data, modifiers);- }-}-```--And here's a complete example of an agentic provider implementation:--```typescript-import { BaseAgenticProvider } from '@composio/core';-import type { Tool, ModifiersParams, ToolExecuteParams, ToolExecuteResponse } from '@composio/core';--export class VercelProvider extends BaseAgenticProvider {- async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise<Tool> {- let wrappedTool = tool;-- // Apply schema modifiers if provided- if (modifiers?.schema) {- wrappedTool = modifiers.schema(toolSlug, wrappedTool);- }-- return wrappedTool;- }-- async getTools(modifiers?: ModifiersParams): Promise<Tool[]> {- // Fetch tools from Composio API- const response = await this.client.getTools();- // Apply modifiers to each tool- return Promise.all(response.data.map(tool => this.wrapTool(tool.slug, tool, modifiers)));- }-- async getToolBySlug(slug: string, modifiers?: ModifiersParams): Promise<Tool> {- // Fetch tool from Composio API- const response = await this.client.getToolBySlug(slug);- // Apply modifiers- return this.wrapTool(slug, response.data, modifiers);- }-- async executeTool(- tool: Tool,- params: ToolExecuteParams,- modifiers?: ModifiersParams- ): Promise<ToolExecuteResponse> {- let executeParams = params;-- // Apply beforeExecute modifier if provided- if (modifiers?.beforeExecute) {- executeParams = modifiers.beforeExecute(tool.slug, executeParams);- }-- // Execute the tool- const response = await this.client.executeTool(tool.slug, executeParams);-- // Apply afterExecute modifier if provided- if (modifiers?.afterExecute) {- return modifiers.afterExecute(tool.slug, response.data);- }-- return response.data;- }-}-```--## Usage Examples--### Using a Non-Agentic Provider--```typescript-import { Composio } from '@composio/core';-import { OpenAIProvider } from '@composio/openai-provider';-import type { Tool } from '@composio/core';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new OpenAIProvider(),-});--// Get a tool with schema modifiers-const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS', {- schema: (toolSlug: string, tool: Tool) => ({- ...tool,- description: 'Search HackerNews posts with improved description',- inputParameters: {- ...tool.inputParameters,- limit: {- type: 'number',- description: 'Maximum number of posts to return',- },- },- }),-});-```--### Using an Agentic Provider--```typescript-import { Composio } from '@composio/core';-import { VercelProvider } from '@composio/vercel-provider';-import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '@composio/core';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new VercelProvider(),-});--// Get a tool with full modifier support-const tool = await composio.getToolBySlug('HACKERNEWS_SEARCH_POSTS', {- // Schema modifier- schema: (toolSlug: string, tool: Tool) => ({- ...tool,- description: 'Search HackerNews posts with improved description',- inputParameters: {- ...tool.inputParameters,- limit: {- type: 'number',- description: 'Maximum number of posts to return',- },- },- }),- // Execution modifiers- beforeExecute: (toolSlug: string, params: ToolExecuteParams) => ({- ...params,- arguments: {- ...params.arguments,- limit: Math.min((params.arguments?.limit as number) || 10, 100),- },- }),- afterExecute: (toolSlug: string, response: ToolExecuteResponse) => ({- ...response,- data: {- ...response.data,- posts: (response.data?.posts as any[]).map(post => ({- ...post,- url: post.url || `https://news.ycombinator.com/item?id=${post.id}`,- })),- },- }),-});--// Execute the tool with execution modifiers-const result = await composio.provider.executeTool(- tool,- {- arguments: { query: 'AI', limit: 20 },- },- {- beforeExecute: (toolSlug: string, params: ToolExecuteParams) => ({- ...params,- arguments: {- ...params.arguments,- limit: Math.min((params.arguments?.limit as number) || 10, 100),- },- }),- afterExecute: (toolSlug: string, response: ToolExecuteResponse) => ({- ...response,- data: {- ...response.data,- posts: (response.data?.posts as any[]).map(post => ({- ...post,- url: post.url || `https://news.ycombinator.com/item?id=${post.id}`,- })),- },- }),- }-);-```+- [Provider docs](https://docs.composio.dev/docs/providers)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/anthropic/README.md b/ts/packages/providers/anthropic/README.mdindex a9f767055..cab3f1695 100644--- a/ts/packages/providers/anthropic/README.md+++ b/ts/packages/providers/anthropic/README.md@@ -1,309 +1,77 @@# @composio/anthropic-Non-Agentic Provider for Anthropic in Composio SDK.--## Features--- **Tool Integration**: Seamless integration with Anthropic's tool calling capabilities-- **Type Safety**: Full TypeScript support with proper type definitions-- **Tool Execution**: Execute tools with proper parameter handling and response formatting-- **Caching Support**: Optional tool caching for improved performance-- **Modifier Support**: Support for execution modifiers to transform tool inputs and outputs-- **Streaming Support**: First-class support for streaming responses+Adapts Composio tools to the Claude Messages API and executes the tool calls Claude returns.## Installation```bash-npm install @composio/anthropic-# or-yarn add @composio/anthropic-# or-pnpm add @composio/anthropic-```--## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key-- `ANTHROPIC_API_KEY`: Your Anthropic API key--Optional environment variables:--- `ANTHROPIC_API_URL`: Custom API base URL (defaults to Anthropic's API)--## Quick Start--```typescript-import { Composio } from '@composio/core';-import { AnthropicProvider } from '@composio/anthropic';--// Initialize Composio with Anthropic provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- // Initialize with optional caching- provider: new AnthropicProvider({ cacheTools: true }),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});+npm install @composio/core @composio/anthropic @anthropic-ai/sdk```-## Examples+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `ANTHROPIC_API_KEY` (from https://console.anthropic.com/settings/keys) in your environment.-Check out our complete example implementations:+## Quickstart-- [Basic Anthropic Integration](../../examples/anthropic/src/index.ts)-- [Streaming Example](../../examples/anthropic/src/streaming.ts)--### Basic Example+Create a session for your user, pass its tools to the Messages API, and run the tool-call loop until Claude replies with text. `handleToolCalls` executes every `tool_use` block and returns a ready-to-append `user` message of `tool_result` blocks.```typescript-import { Composio } from '@composio/core';-import { AnthropicProvider } from '@composio/anthropic';import Anthropic from '@anthropic-ai/sdk';--// Initialize Anthropic-const anthropic = new Anthropic({- apiKey: process.env.ANTHROPIC_API_KEY,-});--// Initialize Composio-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new AnthropicProvider(),-});--// Get tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],-});--// Create a message with tools-const message = await anthropic.messages.create({- model: 'claude-3-sonnet-20240229',- max_tokens: 1024,- tools: tools,- messages: [- {- role: 'user',- content: 'Send an email to [email protected]',- },- ],-});--// Handle tool calls-// Anthropic returns tool calls as `tool_use` content blocks.-for (const block of message.content) {- if (block.type === 'tool_use') {- const result = await composio.provider.executeToolCall('user123', block, {- connectedAccountId: 'account123',- });- console.log('Tool execution result:', result);- }-}-```--### Streaming Example--```typescriptimport { Composio } from '@composio/core';import { AnthropicProvider } from '@composio/anthropic';-import Anthropic from '@anthropic-ai/sdk';--const anthropic = new Anthropic({- apiKey: process.env.ANTHROPIC_API_KEY,-});const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,provider: new AnthropicProvider(),});+const client = new Anthropic();-const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],-});--const stream = await anthropic.messages.stream({- model: 'claude-3-sonnet-20240229',- max_tokens: 1024,- tools: tools,- messages: [- {- role: 'user',- content: 'Send an email to [email protected]',- },- ],-});--for await (const messageChunk of stream) {- // Anthropic streams tool calls as `tool_use` content blocks, emitted via a- // `content_block_start` event whose `content_block` is the `tool_use` block.- if (- messageChunk.type === 'content_block_start' &&- messageChunk.content_block.type === 'tool_use'- ) {- const result = await composio.provider.executeToolCall('user123', messageChunk.content_block, {- connectedAccountId: 'account123',- });- console.log('Tool execution result:', result);- } else {- console.log('Message chunk:', messageChunk);- }-}-```--## Provider Configuration--The Anthropic provider can be configured with various options:--```typescript-const provider = new AnthropicProvider({- // Enable tool caching- cacheTools: true,- // Custom execution modifiers- modifiers: {- beforeExecute: params => {- // Transform parameters before execution- return params;- },- afterExecute: response => {- // Transform response after execution- return response;- },- },-});-```--## API Reference--### AnthropicProvider Class--The `AnthropicProvider` class extends `BaseNonAgenticProvider` and provides Anthropic-specific functionality.--#### Constructor--```typescript-new AnthropicProvider(options?: { cacheTools?: boolean })-```--- `options.cacheTools`: Optional boolean to enable tool caching (default: false)--#### Methods--##### `wrapTool(tool: Tool): AnthropicTool`--Wraps a Composio tool in the Anthropic format.--```typescript-const tool = provider.wrapTool(composioTool);-```--##### `wrapTools(tools: Tool[]): AnthropicToolCollection`--Wraps multiple Composio tools in the Anthropic format.--```typescript-const tools = provider.wrapTools(composioTools);-```--##### `executeToolCall(userId: string, toolUse: AnthropicToolUseBlock, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<string>`+// Create a session for your user+const session = await composio.create('user_123');+const tools = await session.tools();-Executes a tool call from Anthropic and returns the result as a string.--```typescript-const result = await composio.provider.executeToolCall(- 'user123',- {- type: 'tool_use',- id: 'tu_123',- name: 'tool-name',- input: { param: 'value' },- },+const messages: Anthropic.MessageParam[] = [{- connectedAccountId: 'account123',- customAuthParams: {- /* ... */- },+ role: 'user',+ content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",},- {- beforeExecute: params => params,- afterExecute: response => response,- }-);-```--##### `handleToolCalls(userId: string, message: Message, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<Anthropic.Messages.MessageParam[]>`--Processes and executes all tool calls found in an Anthropic message response. This method automatically extracts tool calls from the message content, executes them, and returns their results.+];-**Parameters:**--- `userId` (string): The ID of the user making the tool calls-- `message` (Message): The Anthropic message response containing tool calls-- `options` (optional): Additional options for tool execution- - `connectedAccountId`: ID of the connected account- - `customAuthParams`: Custom authentication parameters-- `modifiers` (optional): Functions to modify tool execution- - `beforeExecute`: Transform parameters before execution- - `afterExecute`: Transform response after execution--**Returns:**-Promise<Anthropic.Messages.MessageParam[]>: Tool execution results for the assistant message--**Example:**+let response = await client.messages.create({+ model: 'claude-opus-4-6',+ max_tokens: 4096,+ tools,+ messages,+});-```typescript-const message = {- id: 'msg_123',- content: [- { type: 'text', text: 'Hello' },- {- type: 'tool_use',- id: 'tu_123',- name: 'test-tool',- input: { param: 'value' },- },- {- type: 'tool_use',- id: 'tu_456',- name: 'another-tool',- input: { param: 'value2' },- },- ],-};+// Agentic loop: keep executing tool calls until the model responds with text+while (response.stop_reason === 'tool_use') {+ const toolResults = await composio.provider.handleToolCalls('user_123', response);+ messages.push({ role: 'assistant', content: response.content });+ messages.push(...toolResults);+ response = await client.messages.create({+ model: 'claude-opus-4-6',+ max_tokens: 4096,+ tools,+ messages,+ });+}-const results = await provider.handleToolCalls(- 'user123',- message,- {- connectedAccountId: 'account123',- customAuthParams: {- parameters: [{ name: 'token', value: 'abc123', in: 'header' }],- },- },- {- beforeExecute: params => params,- afterExecute: response => response,+// Print final response+for (const block of response.content) {+ if (block.type === 'text') {+ console.log(block.text);}-);--// results will be an array of tool execution responses-// from each tool execution in the order they appeared-// this can be passed directly to LLM+}```-## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.+Building on the Claude Agent SDK instead? Use [`@composio/claude-agent-sdk`](../claude-agent-sdk), which exposes Composio tools as an in-process MCP server and lets the SDK run the loop.-## License+## Provider options-ISC License+- `cacheTools`: pass `new AnthropicProvider({ cacheTools: true })` to attach Anthropic's ephemeral `cache_control` to every tool definition and tool-result block. This lets Claude reuse cached tool schemas across requests and can cut prompt cost when you send the same large tool set on every turn. It is the only constructor option.+- `handleToolCalls(userId, message)` returns `Anthropic.Messages.MessageParam[]`, not raw strings, so you append the result directly to your message list. For finer control, `executeToolCall(userId, toolUseBlock)` runs a single `tool_use` block and returns the result as a JSON string.+- Claude occasionally emits a tool's `input` as a JSON string instead of an object; the provider normalizes this before execution.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Anthropic provider docs](https://docs.composio.dev/docs/providers/anthropic)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/claude-agent-sdk/README.md b/ts/packages/providers/claude-agent-sdk/README.mdindex 56d959f9d..f67335837 100644--- a/ts/packages/providers/claude-agent-sdk/README.md+++ b/ts/packages/providers/claude-agent-sdk/README.md@@ -1,138 +1,62 @@-# @composio/claude-code-agents+# @composio/claude-agent-sdk-Composio provider for the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) (`@anthropic-ai/claude-agent-sdk`).--This provider enables seamless integration of Composio tools with Claude Code Agents, allowing you to use any Composio-supported tool (Gmail, Slack, GitHub, etc.) within your Claude agents.+Composio provider for the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) (`@anthropic-ai/claude-agent-sdk`). It wraps Composio tools as in-process MCP tools that Claude agents can call.## Installation```bash-npm install @composio/claude-agent-sdk @composio/core @anthropic-ai/claude-agent-sdk+npm install @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk```-### Prerequisites--1. **Claude Code CLI**: The Claude Agent SDK requires Claude Code to be installed:-- ```bash- # macOS/Linux/WSL- curl -fsSL https://claude.ai/install.sh | bash+Set two environment variables:- # or via Homebrew- brew install --cask claude-code+- `COMPOSIO_API_KEY` from the [Composio dashboard](https://dashboard.composio.dev/settings)+- `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys)- # or via npm- npm install -g @anthropic-ai/claude-code- ```+## Quickstart-2. **API Keys**:- - `ANTHROPIC_API_KEY`: Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com)- - `COMPOSIO_API_KEY`: Your Composio API key from [app.composio.dev](https://app.composio.dev)--## Usage+Create a session for your user, serve its tools through an SDK MCP server, and query Claude:```typescript-import { Composio } from '@composio/core';-import { ClaudeCodeAgentsProvider } from '@composio/claude-code-agents';-import { query, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';--// Initialize Composio-const composio = new Composio({- provider: new ClaudeCodeAgentsProvider(),-});+import { Composio } from "@composio/core";+import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";+import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";-// Create a tool router session-const session = await composio.create('external_user_id');+const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });-// Get tools from the session (native)+// Each session is scoped to one of your users+const session = await composio.create("user_123");const tools = await session.tools();+const customServer = createSdkMcpServer({- name: 'composio',- version: '1.0.0',- tools: tools,+ name: "composio",+ version: "1.0.0",+ tools,});-// Initialize Claude client-for await (const content of query({- prompt: 'Fetch my last email from gmail',+for await (const stream of query({+ prompt: "Summarize my emails from today",options: {mcpServers: { composio: customServer },- permissionMode: 'bypassPermissions',+ permissionMode: "bypassPermissions",},})) {- if (content.type === 'assistant') {- console.log('Claude:', content.message);+ if (stream.type === "assistant") {+ for (const block of stream.message.content) {+ if (block.type === "text") process.stdout.write(block.text);+ }}}--console.log(`✅ Received response from Claude`);```-## API Reference--### `ClaudeCodeAgentsProvider`--The main provider class for integrating Composio tools with Claude Code Agents.--#### Constructor Options--```typescript-interface ClaudeAgentSDKProviderOptions {- serverName?: string; // Name for the MCP server (default: 'composio')- serverVersion?: string; // Version for the MCP server (default: '1.0.0')-}-```--#### Methods--##### `wrapTool(tool, executeTool)`--Wraps a single Composio tool as a Claude Agent SDK MCP tool.--##### `wrapTools(tools, executeTool)`+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.-Wraps multiple Composio tools as Claude Agent SDK MCP tools.+## How it works-## How It Works--The Claude Agent SDK uses MCP (Model Context Protocol) servers to provide tools to Claude agents. This provider:--1. Converts Composio tool definitions to MCP tool format-2. Creates an in-process MCP server using `createSdkMcpServer()`-3. Handles tool execution by routing calls through Composio's execution layer--## Examples--### Using Multiple Tools--```typescript-const tools = await composio.tools.get('default', [- 'GMAIL_SEND_EMAIL',- 'GMAIL_LIST_EMAILS',- 'SLACK_POST_MESSAGE',-]);--const mcpServer = composio.provider.createMcpServer(tools, composio.tools.execute);--for await (const message of query({- prompt: 'Check my latest emails and post a summary to #general on Slack',- options: {- mcpServers: { composio: mcpServer },- },-})) {- console.log(message);-}-```--### Custom Server Name--```typescript-const provider = new ClaudeCodeAgentsProvider({- serverName: 'my-composio-tools',- serverVersion: '2.0.0',-});-```+The Claude Agent SDK provides tools to agents through MCP (Model Context Protocol) servers. `ClaudeAgentSDKProvider` converts each Composio tool definition into an MCP tool and routes execution back through Composio, so `createSdkMcpServer` can serve them in process; no separate server to run.-## License+## Links-ISC+- [Composio quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)+- [Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview)diff --git a/ts/packages/providers/cloudflare/README.md b/ts/packages/providers/cloudflare/README.mdindex ad7c514b2..4d65f386f 100644--- a/ts/packages/providers/cloudflare/README.md+++ b/ts/packages/providers/cloudflare/README.md@@ -1,166 +1,55 @@# @composio/cloudflare-The Cloudflare AI provider for Composio SDK, providing seamless integration with Cloudflare's AI capabilities and Workers AI.--## Features--- **Workers AI Integration**: Seamless integration with Cloudflare Workers AI-- **Streaming Support**: First-class support for streaming responses-- **Model Support**: Support for all Cloudflare AI models (@cf/meta/llama-2-7b-chat-int8, etc.)-- **Edge Deployment**: Deploy and run AI models at the edge-- **Tool Execution**: Execute tools with proper parameter handling-- **Type Safety**: Full TypeScript support with proper type definitions+The Cloudflare provider formats Composio tools for Cloudflare Workers AI function calling (`AiTextGenerationToolInput`).## Installation```bash-npm install @composio/cloudflare-# or-yarn add @composio/cloudflare-# or-pnpm add @composio/cloudflare+npm install @composio/core @composio/cloudflare @cloudflare/workers-types```-## Quick Start--```typescript-import { Composio } from '@composio/core';-import { CloudflareProvider } from '@composio/cloudflare';--// Initialize Composio with Cloudflare provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- provider: new CloudflareProvider({- accountId: 'your-cloudflare-account-id',- apiToken: 'your-cloudflare-api-token',- }),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});-```--## Usage Examples--### Basic Chat Completion with Streaming--```typescript-import { Composio } from '@composio/core';-import { CloudflareProvider } from '@composio/cloudflare';-import { Ai } from '@cloudflare/ai';--// Initialize Composio-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new CloudflareProvider(),-});--// In your Worker-export default {- async fetch(request: Request, env: Env, ctx: ExecutionContext) {- const ai = new Ai(env.AI);- const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],- });-- const messages = [- { role: 'system', content: 'You are a helpful assistant.' },- { role: 'user', content: 'What can you do?' },- ];-- const stream = await ai.run('@cf/meta/llama-2-7b-chat-int8', {- messages,- tools,- stream: true,- });+Set `COMPOSIO_API_KEY` with your API key from [the dashboard](https://dashboard.composio.dev/settings). In a Worker, add it as a secret (`wrangler secret put COMPOSIO_API_KEY`) and bind Workers AI as `AI` in your `wrangler.toml`; no separate model API key is needed.- return new Response(stream, {- headers: {- 'content-type': 'text/event-stream',- },- });- },-};-```+## Quickstart-### Multi-Modal Example+Create a session for your user, pass its tools to `env.AI.run`, and execute any tool calls the model returns:```typescriptimport { Composio } from '@composio/core';import { CloudflareProvider } from '@composio/cloudflare';-import { Ai } from '@cloudflare/ai';--// Initialize Composio-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new CloudflareProvider(),-});-// In your Workerexport default {- async fetch(request: Request, env: Env, ctx: ExecutionContext) {- const ai = new Ai(env.AI);- const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],+ async fetch(request: Request, env: Env): Promise<Response> {+ const composio = new Composio({+ apiKey: env.COMPOSIO_API_KEY,+ provider: new CloudflareProvider(),});- // Image analysis- const imageResponse = await ai.run('@cf/microsoft/resnet-50', {- image: await request.arrayBuffer(),+ // Create a session for your user+ const session = await composio.create('user_123');+ const tools = await session.tools();++ const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {+ messages: [+ { role: 'system', content: 'You are a helpful assistant.' },+ { role: 'user', content: 'Summarize my emails from today' },+ ],+ // session.tools() returns a collection keyed by tool slug+ tools: Object.values(tools),});- // Use image analysis in chat- const messages = [- { role: 'system', content: 'You are a helpful assistant.' },- {- role: 'user',- content: 'What do you see in this image?',- context: { image_analysis: imageResponse },- },- ];+ const results = [];+ for (const toolCall of response.tool_calls ?? []) {+ results.push(await composio.provider.executeToolCall('user_123', toolCall, {}));+ }- const stream = await ai.run('@cf/meta/llama-2-7b-chat-int8', {- messages,- tools,- stream: true,- });-- return new Response(stream, {- headers: {- 'content-type': 'text/event-stream',- },- });+ return Response.json({ response, results });},};```-## API Reference--### CloudflareProvider Class--The `CloudflareProvider` class extends `BaseComposioProvider` and provides Cloudflare-specific functionality.--#### Methods--##### `executeToolCall(tool: ToolCall): Promise<string>`--Executes a tool call and returns the result.--```typescript-const result = await composio.provider.executeToolCall(toolCall);-```--## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License--ISC License+`executeToolCall` takes the `{ name, arguments }` tool calls that Workers AI emits, runs the matching Composio tool for that user, and returns the result as a JSON string.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/google/README.md b/ts/packages/providers/google/README.mdindex 3f3a8c188..f2aa37d19 100644--- a/ts/packages/providers/google/README.md+++ b/ts/packages/providers/google/README.md@@ -1,124 +1,71 @@# @composio/google-Google GenAI Provider for Composio SDK.--## Features--- **Google GenAI Integration**: Seamless integration with Google's Generative AI models (Gemini)-- **Function Calling Support**: Convert Composio tools to Google GenAI function declarations-- **Type Safety**: Full TypeScript support with proper type definitions-- **Execution Modifiers**: Support for transforming tool inputs and outputs-- **Flexible Authentication**: Support for custom authentication parameters-- **Streaming Support**: First-class support for streaming responses+Adapts Composio tools to Gemini function declarations for the Google GenAI SDK (`@google/genai`) and executes the function calls the model returns.## Installation```bashnpm install @composio/core @composio/google @google/genai-# or-yarn add @composio/core @composio/google @google/genai-# or-pnpm add @composio/core @composio/google @google/genai```-## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key-- `GEMINI_API_KEY`: Your Google AI API key--Optional environment variables:+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `GOOGLE_API_KEY` (from https://aistudio.google.com/apikey) in your environment.-- `GOOGLE_PROJECT_ID`: Your Google Cloud project ID (for custom deployments)-- `GOOGLE_LOCATION`: Your Google Cloud location (for custom deployments)+## Quickstart-## Quick Start+Create a session for your user, pass its tools to Gemini as function declarations, and run the loop: execute each function call with `composio.provider.executeToolCall`, feed the result back, and repeat until the model replies with text.```typescriptimport { Composio } from '@composio/core';import { GoogleProvider } from '@composio/google';-import { GoogleGenerativeAI } from '@google/genai';+import { GoogleGenAI, type Part } from '@google/genai';-// Initialize Google GenAI-const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);--// Initialize Composio with Google providerconst composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,provider: new GoogleProvider(),});+const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });-// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'calendar'],- limit: 10,-});-```--## Examples+// Create a session for your user+const session = await composio.create('user_123');+const tools = await session.tools();-Check out our complete example implementations:--- [Basic Google Integration](../../examples/google/src/index.ts)--## API Reference--### GoogleProvider Class--The `GoogleProvider` class extends `BaseNonAgenticProvider` and provides Google GenAI-specific functionality.--#### Methods--##### `wrapTool(tool: Tool): GoogleTool`--Wraps a Composio tool in the Google GenAI function declaration format.--```typescript-const wrappedTool = provider.wrapTool(composioTool);-```--##### `wrapTools(tools: Tool[]): GoogleGenAIToolCollection`--Wraps multiple Composio tools in the Google GenAI function declaration format.--```typescript-const wrappedTools = provider.wrapTools(composioTools);-```--##### `executeToolCall(userId: string, tool: GoogleGenAIFunctionCall, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<string>`--Executes a tool call from Google GenAI and returns the result as a JSON string.--```typescript-const result = await provider.executeToolCall('user123', functionCall, options, modifiers);-```+const chat = ai.chats.create({+ model: 'gemini-3-pro-preview',+ config: {+ tools: [{ functionDeclarations: tools }],+ },+});-#### Types+let response = await chat.sendMessage({+ message: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+});-```typescript-interface GoogleGenAIFunctionCall {- name: string;- args: Record<string, unknown>;+// Agentic loop: keep executing tool calls until the model responds with text+while (response.functionCalls && response.functionCalls.length > 0) {+ const parts: Part[] = [];+ for (const fc of response.functionCalls) {+ const result = await composio.provider.executeToolCall('user_123', {+ name: fc.name || '',+ args: (fc.args || {}) as Record<string, unknown>,+ });+ parts.push({+ functionResponse: {+ id: fc.id,+ name: fc.name,+ response: JSON.parse(result),+ },+ });+ }+ response = await chat.sendMessage({ message: parts });}-type GoogleTool = {- name: string;- description: string;- parameters: Schema;-};--type GoogleGenAIToolCollection = GoogleTool[];+console.log(response.text);```-## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License+## Tool execution-ISC License+Gemini function calling is non-agentic; the model returns function calls and you execute them. `GoogleProvider` exposes `executeToolCall(userId, functionCall, options?, modifiers?)`, which takes a `{ name, args }` pair and returns the tool result as a JSON string. The constructor takes no options.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Google provider docs](https://docs.composio.dev/docs/providers/google)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/langchain/README.md b/ts/packages/providers/langchain/README.mdindex 76a30e0d0..2e8720817 100644--- a/ts/packages/providers/langchain/README.md+++ b/ts/packages/providers/langchain/README.md@@ -1,207 +1,77 @@# @composio/langchain-The LangChain provider for Composio SDK, providing seamless integration with LangChain's ecosystem and tools.--## Features--- **LangChain Integration**: Seamless integration with LangChain's ecosystem-- **LCEL Support**: Full support for LangChain Expression Language (LCEL)-- **Streaming Support**: First-class support for streaming responses-- **Tool Execution**: Execute LangChain tools with proper parameter handling-- **Chain Integration**: Work with LangChain chains and agents-- **Type Safety**: Full TypeScript support with proper type definitions+The LangChain provider turns Composio tools into LangChain `DynamicStructuredTool` objects with built-in execution, ready for LangChain and LangGraph agents. In TypeScript, LangGraph is served by this same package.## Installation```bash-npm install @composio/core @composio/langchain @langchain/core @langchain/openai-# or-yarn add @composio/core @composio/langchain @langchain/core @langchain/openai-# or-pnpm add @composio/core @composio/langchain @langchain/core @langchain/openai+npm install @composio/core @composio/langchain @langchain/core @langchain/openai @langchain/langgraph```-## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key-- `OPENAI_API_KEY`: Your OpenAI API key (or other LLM provider's key)+Set `COMPOSIO_API_KEY` with your API key from [the dashboard](https://dashboard.composio.dev/settings), and `OPENAI_API_KEY` (or your LLM provider's key).-Optional environment variables:+## Quickstart-- `LANGCHAIN_TRACING_V2`: Enable LangChain tracing (set to "true")-- `LANGCHAIN_ENDPOINT`: Custom LangChain API endpoint-- `LANGCHAIN_API_KEY`: Your LangChain API key (for hosted services)--## Quick Start+Create a session for your user, fetch its tools, and wire them into a LangGraph agent:```typescript-import { Composio } from '@composio/core';-import { LangChainProvider } from '@composio/langchain';--// Initialize Composio with LangChain provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- provider: new LangChainProvider(),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});--// Get tools with version control-const versionedTools = await composio.tools.get('user123', {- toolkits: ['gmail'],- toolkitVersions: { gmail: '20250909_00' },-});--// Get a specific tool-const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');-```--## Examples--Check out our complete example implementations:--- [Basic LangChain Integration](../../examples/langchain/src/index.ts)-- [LCEL Example](../../examples/langchain/src/lcel.ts)-- [RAG Example](../../examples/langchain/src/rag.ts)-- [Streaming Example](../../examples/langchain/src/streaming.ts)--### Basic Chain with Streaming--```typescript-import { Composio } from '@composio/core';-import { LangChainProvider } from '@composio/langchain';-import { ChatPromptTemplate } from '@langchain/core/prompts';-import { StringOutputParser } from '@langchain/core/output_parsers';import { ChatOpenAI } from '@langchain/openai';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new LangChainProvider(),-});--// Get tools for the chain-const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],- limit: 10,-});--const model = new ChatOpenAI({- modelName: 'gpt-4',- streaming: true,-});--const prompt = ChatPromptTemplate.fromTemplate('Tell me a joke about {topic}');-const parser = new StringOutputParser();--const chain = prompt.pipe(model).pipe(parser);--// Stream the response-const stream = await chain.stream({- topic: 'programming',-});--for await (const chunk of stream) {- console.log(chunk);-}-```--### Tool Execution with Streaming Events--```typescript+import { HumanMessage, AIMessage } from '@langchain/core/messages';+import { ToolNode } from '@langchain/langgraph/prebuilt';+import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';import { Composio } from '@composio/core';-import { LangChainProvider } from '@composio/langchain';-import { ChatPromptTemplate } from '@langchain/core/prompts';-import { JsonOutputParser } from '@langchain/core/output_parsers';-import { ChatOpenAI } from '@langchain/openai';+import { LangchainProvider } from '@composio/langchain';const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new LangChainProvider(),+ provider: new LangchainProvider(),});-// Get tools for the chain-const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],-});+// Create a session for your user+const session = await composio.create('user_123');+const tools = await session.tools();-const model = new ChatOpenAI({- modelName: 'gpt-4',- streaming: true,-});+const toolNode = new ToolNode(tools);-const chain = model.pipe(new JsonOutputParser());-const eventStream = await chain.streamEvents(- `Output a list of the countries france, spain and japan and their populations in JSON format.`,- { version: 'v2' }-);--for await (const event of eventStream) {- const eventType = event.event;- if (eventType === 'on_chat_model_stream') {- console.log(`Chat model chunk: ${event.data.chunk.content}`);- } else if (eventType === 'on_parser_stream') {- console.log(`Parser chunk: ${JSON.stringify(event.data.chunk)}`);+const model = new ChatOpenAI({+ model: 'gpt-5.2',+ temperature: 0,+}).bindTools(tools);++function shouldContinue({ messages }: typeof MessagesAnnotation.State) {+ const lastMessage = messages[messages.length - 1] as AIMessage;+ if (lastMessage.tool_calls?.length) {+ return 'tools';}+ return '__end__';}-```-## Provider Configuration--The LangChain provider can be configured with various options:+async function callModel(state: typeof MessagesAnnotation.State) {+ const response = await model.invoke(state.messages);+ return { messages: [response] };+}-```typescript-const provider = new LangChainProvider({- // Default model configuration- model: new ChatOpenAI({- modelName: 'gpt-4',- streaming: true,- }),- // Custom execution modifiers- modifiers: {- beforeExecute: params => {- // Transform parameters before execution- return params;- },- afterExecute: response => {- // Transform response after execution- return response;- },- },- // Enable tracing- tracing: true,+const workflow = new StateGraph(MessagesAnnotation)+ .addNode('agent', callModel)+ .addEdge('__start__', 'agent')+ .addNode('tools', toolNode)+ .addEdge('tools', 'agent')+ .addConditionalEdges('agent', shouldContinue);++const app = workflow.compile();++const finalState = await app.invoke({+ messages: [+ new HumanMessage(+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'"+ ),+ ],});+console.log(finalState.messages[finalState.messages.length - 1].content);```-## API Reference--### LangChainProvider Class--The `LangChainProvider` class extends `BaseComposioProvider` and provides LangChain-specific functionality.--#### Methods--##### `executeToolCall(tool: Tool): Promise<string>`--Executes a LangChain tool call and returns the result.--```typescript-const result = await provider.executeToolCall(tool);-```--## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License--ISC License+Each tool is a standard `DynamicStructuredTool`, so it also works anywhere LangChain accepts tools: chains, LCEL pipelines, and `bindTools` on any chat model.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [LangChain provider docs](https://docs.composio.dev/docs/providers/langchain)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/llamaindex/README.md b/ts/packages/providers/llamaindex/README.mdindex 91aa1b3a9..696a9ce58 100644--- a/ts/packages/providers/llamaindex/README.md+++ b/ts/packages/providers/llamaindex/README.md@@ -1,154 +1,18 @@# @composio/llamaindex-Agentic Provider for Llamaindex in Composio SDK.--## Features--- **Seamless LlamaIndex Integration**: Tools are automatically compatible with LlamaIndex agents and workflows-- **Full Modifier Support**: Support for both schema and execution modifiers with beforeExecute/afterExecute hooks-- **Streaming Support**: Works with LlamaIndex streaming agents using `agentStreamEvent`-- **Tool Execution**: Execute tools with proper parameter handling and JSON schema validation-- **Type Safety**: Full TypeScript support with proper type definitions-- **Zod Schema Integration**: Automatic conversion from JSON Schema to Zod for LlamaIndex compatibility+The LlamaIndex provider turns Composio tools into LlamaIndex tools that execute themselves, ready to hand to a LlamaIndex agent.## Installation```bash-npm install @composio/llamaindex-# or-yarn add @composio/llamaindex-# or-pnpm add @composio/llamaindex-```--## Quick Start--```typescript-import { Composio } from '@composio/core';-import { LlamaindexProvider } from '@composio/llamaindex';--// Initialize Composio with Llamaindex provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- provider: new LlamaindexProvider(),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});-```--## Prerequisites--Before using the LlamaIndex provider, make sure you have:--1. **Composio API Key**: Get your API key from [Composio Dashboard](https://app.composio.dev)-2. **Environment Setup**: Set up your environment variables-3. **LlamaIndex Dependencies**: Install required LlamaIndex packages--```bash-# Install LlamaIndex dependencies-npm install @llamaindex/openai @llamaindex/workflow+npm install @composio/core @composio/llamaindex @llamaindex/openai @llamaindex/workflow```-```bash-# Set up environment variables-export COMPOSIO_API_KEY="your-composio-api-key"-export OPENAI_API_KEY="your-openai-api-key" # For LlamaIndex OpenAI integration-```--## Usage Examples--### Basic Example--```typescript-import { Composio } from '@composio/core';-import { LlamaindexProvider } from '@composio/llamaindex';--// Initialize Composio-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new LlamaindexProvider(),-});--// Get tools-const tools = await composio.tools.get('default', {- toolkits: ['gmail'],- limit: 10,-});--console.log(`Found ${tools.length} tools`);-```--### Complete Agent Example with HackerNews--```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';--// Initialize Composio with LlamaIndex provider-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new LlamaindexProvider(),-});--async function main() {- try {- console.log('🚀 Starting LlamaIndex Example...');-- // Get available tools with modifiers- const tools = await composio.tools.get(- 'default',- {- toolkits: ['hackernews'],- limit: 10,- },- {- beforeExecute: ({ toolSlug, toolkitSlug, params }) => {- console.log(`🔄 Executing tool ${toolSlug}/${toolkitSlug} with params:`, { params });- return params;- },- afterExecute: ({ toolSlug, toolkitSlug, result }) => {- console.log(`✅ Executed tool ${toolSlug}/${toolkitSlug} with result:`, { result });- return result;- },- }- );-- console.log(`✅ Found ${tools.length} tools`);+Set `COMPOSIO_API_KEY` with your API key from [the dashboard](https://dashboard.composio.dev/settings), and `OPENAI_API_KEY` (or your LLM provider's key).- // Create LlamaIndex agent with Composio tools- const hackernewsAgent = agent({- name: 'Hackernews Agent',- description: 'A helpful hackernews assistant',- llm: openai({ model: 'gpt-4o-mini' }),- systemPrompt:- 'You are a helpful hackernews assistant that helps users with their queries related to hackernews',- tools, // Composio tools are automatically compatible with LlamaIndex- });+## Quickstart- // Run the agent with streaming- const stream = await hackernewsAgent.runStream('Summarize the front page of hackernews');-- for await (const event of stream) {- if (agentStreamEvent.include(event)) {- process.stdout.write(event.data.delta);- }- }- } catch (error) {- console.error('❌ Error running example:', error);- }-}--main().catch(console.error);-```--### Using Tools with Different Toolkits+Create a session for your user, fetch its tools, and hand them to an agent:```typescriptimport { Composio } from '@composio/core';@@ -157,87 +21,28 @@ import { openai } from '@llamaindex/openai';import { agent } from '@llamaindex/workflow';const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,provider: new LlamaindexProvider(),});-// Get tools from multiple toolkits-const tools = await composio.tools.get('default', {- toolkits: ['gmail', 'googlecalendar', 'slack'],- limit: 20,-});+// Create a session for your user+const session = await composio.create('user_123');+const tools = await session.tools();-// Create a multi-purpose agent-const assistantAgent = agent({- name: 'Personal Assistant',- description: 'A helpful personal assistant',- llm: openai({ model: 'gpt-4' }),- systemPrompt:- 'You are a helpful personal assistant that can manage emails, calendar events, and slack messages.',+const myAgent = agent({+ llm: openai({ model: 'gpt-5.2' }),tools,});-// Use the agent-const response = await assistantAgent.run(- 'Schedule a meeting for tomorrow at 2 PM and send a slack message about it'+const result = await myAgent.run(+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'");-console.log(response);-```--## API Reference--### LlamaindexProvider Class--The `LlamaindexProvider` class extends `BaseAgenticProvider` and provides llamaindex-specific functionality.--#### Methods-##### `wrapTool(tool: Tool, executeTool: ExecuteToolFn): LlamaindexTool`--Wraps a single Composio tool in the LlamaIndex format with proper Zod schema conversion.--```typescript-const llamaindexTool = provider.wrapTool(composioTool, executeTool);--// The wrapped tool has LlamaIndex-compatible structure:-// - metadata.name: Tool slug-// - metadata.description: Tool description-// - metadata.parameters: Zod schema for parameters-// - call(): Function to execute the tool+console.log(result.data.result);```-##### `wrapTools(tools: Tool[], executeTool: ExecuteToolFn): LlamaindexTool[]`--Wraps multiple Composio tools for use with LlamaIndex agents.--```typescript-const llamaindexTools = provider.wrapTools(composioTools, executeTool);--// Use directly with LlamaIndex agents-const agent = agent({- name: 'My Agent',- llm: openai({ model: 'gpt-4' }),- tools: llamaindexTools, // Ready to use!-});-```--##### `wrapMcpServerResponse(data: McpUrlResponse): McpServerGetResponse`--Transforms MCP URL responses into the standard format with URL objects.--```typescript-const mcpServers = provider.wrapMcpServerResponse(urlResponse);-// Returns: [{ url: URL, name: string }, ...]-```--## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License--ISC License+The provider converts each tool's JSON Schema parameters to Zod and wires execution through Composio, so LlamaIndex can call the tools directly.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [LlamaIndex provider docs](https://docs.composio.dev/docs/providers/llamaindex)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/mastra/README.md b/ts/packages/providers/mastra/README.mdindex 51110e54c..6b28fe6af 100644--- a/ts/packages/providers/mastra/README.md+++ b/ts/packages/providers/mastra/README.md@@ -1,121 +1,65 @@# @composio/mastra-Agentic Provider for Mastra in Composio SDK.--## Features--- **Full Modifier Support**: Support for both schema and execution modifiers-- **Tool Execution**: Execute tools with proper parameter handling-- **Type Safety**: Full TypeScript support with proper type definitions-- **Agentic Capabilities**: Full support for autonomous agent behavior-- **Streaming Support**: First-class support for streaming responses-- **Custom Execution**: Support for custom tool execution strategies+The Mastra provider turns Composio tools into Mastra's tool format with built-in execution, ready to pass to a Mastra `Agent`.## Installation```bash-npm install @composio/core @composio/mastra-# or-yarn add @composio/core @composio/mastra-# or-pnpm add @composio/core @composio/mastra+npm install @composio/core @composio/mastra @mastra/core @ai-sdk/openai```-## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key-- `MASTRA_API_KEY`: Your Mastra API key+Set `COMPOSIO_API_KEY` with your API key from [the dashboard](https://dashboard.composio.dev/settings), and `OPENAI_API_KEY` (or your LLM provider's key).-Optional environment variables:+## Quickstart-- `MASTRA_API_URL`: Custom API base URL (defaults to Mastra's API)-- `MASTRA_DEBUG`: Enable debug logging (set to "true")--## Quick Start+Create a session for your user, fetch its tools, and hand them to an agent:```typescriptimport { Composio } from '@composio/core';import { MastraProvider } from '@composio/mastra';+import { Agent } from '@mastra/core/agent';+import { openai } from '@ai-sdk/openai';-// Initialize Composio with Mastra providerconst composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new MastraProvider({- apiKey: process.env.MASTRA_API_KEY,- }),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,+ provider: new MastraProvider(),});-```-## Examples+// Create a session for your user+const session = await composio.create('user_123');+const tools = await session.tools();-Check out our complete example implementations:--- [Basic Mastra Integration](../../examples/mastra/src/index.ts)--## API Reference--### MastraProvider Class--The `MastraProvider` class extends `BaseAgenticProvider` and provides Mastra-specific functionality.--#### Constructor--```typescript-new MastraProvider(options?: MastraProviderOptions)-```--Options:--- `apiKey`: Your Mastra API key-- `apiUrl`: Custom API base URL-- `debug`: Enable debug logging-- `modifiers`: Custom execution modifiers-- `executionStrategy`: Custom tool execution strategy--#### Methods--##### `wrapTool(tool: Tool, executeTool: ExecuteToolFn): MastraTool`+const agent = new Agent({+ id: 'my-agent',+ name: 'My Agent',+ instructions: 'You are a helpful assistant.',+ model: openai('gpt-5.2'),+ tools,+});-Wraps a tool in the Mastra format.+const { text } = await agent.generate([+ {+ role: 'user',+ content:+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",+ },+]);-```typescript-const tool = provider.wrapTool(composioTool, executeTool);+console.log(text);```-##### `wrapTools(tools: Tool[], executeTool: ExecuteToolFn): MastraToolCollection`+Each tool gets both an input and an output schema, so Mastra can validate tool results as well as arguments.-Wraps multiple tools in the Mastra format.+## Strict mode-```typescript-const tools = provider.wrapTools(composioTools, executeTool);-```--##### `executeToolCall(userId: string, toolCall: MastraToolCall, options?: ExecuteToolFnOptions): Promise<string>`--Executes a tool call from Mastra and returns the result.+Pass `strict: true` to drop every non-required property from each tool's input schema before Mastra compiles it:```typescript-const result = await provider.executeToolCall('user123', toolCall, {- connectedAccountId: 'account123',+const composio = new Composio({+ provider: new MastraProvider({ strict: true }),});```-## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License--ISC License--## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Mastra provider docs](https://docs.composio.dev/docs/providers/mastra)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/openai-agents/README.md b/ts/packages/providers/openai-agents/README.mdindex 0c6be6d1c..61ff81b87 100644--- a/ts/packages/providers/openai-agents/README.md+++ b/ts/packages/providers/openai-agents/README.md@@ -1,78 +1,56 @@# @composio/openai-agents-The OpenAI Agents API provider for Composio SDK, providing seamless integration with OpenAI's Agents API and tools.--## Features--- **OpenAI Agents Integration**: Seamless integration with OpenAI's Agents SDK-- **Tool Integration**: Easy integration of Composio tools with OpenAI Agents-- **Type Safety**: Full TypeScript support with proper type definitions-- **Strict Mode**: Support for strict mode tool parameter validation+Composio provider for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) (`@openai/agents`). It converts Composio tools into the Agents SDK's native tool format so your agents can act across 1000+ apps.## Installation```bash-npm install @composio/openai-agents @openai/agents-# or-yarn add @composio/openai-agents @openai/agents-# or-pnpm add @composio/openai-agents @openai/agents+npm install @composio/core @composio/openai-agents @openai/agents```-## Environment Variables+Set two environment variables:-Required environment variables:+- `COMPOSIO_API_KEY` from the [Composio dashboard](https://dashboard.composio.dev/settings)+- `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys)-- `COMPOSIO_API_KEY`: Your Composio API key-- `OPENAI_API_KEY`: Your OpenAI API key+## Quickstart-## Example+Create a session for your user, hand its tools to an agent, and run it:```typescript-import { OpenAIAgentsProvider } from '@composio/openai-agents';-import { Composio } from '@composio/core';-import { Agent, run } from '@openai/agents';+import { Composio } from "@composio/core";+import { OpenAIAgentsProvider } from "@composio/openai-agents";+import { Agent, run } from "@openai/agents";-const composio = new Composio({- provider: new OpenAIAgentsProvider(),-});+const composio = new Composio({ provider: new OpenAIAgentsProvider() });-// Fetch tools from Composio-const tools = await composio.tools.get('default', 'HACKERNEWS_GET_USER', {- beforeExecute: async (toolSlug, toolkitSlug, params) => {- console.log(`🔄 Executing tool ${toolSlug} from toolkit ${toolkitSlug}...`);- return params;- },- afterExecute: async (toolSlug, toolkitSlug, result) => {- console.log(`✅ Tool ${toolSlug} executed`);- return result;- },-});+// Each session is scoped to one of your users+const session = await composio.create("user_123");+const tools = await session.tools();-// Create an agent with the toolsconst agent = new Agent({- name: 'Hackernews assistant',- tools: tools,+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools,});-// Run the agent with a query-const result = await run(agent, 'Tell me about the user `pg` in hackernews');+const result = await run(agent, "Summarize my emails from today");+console.log(result.finalOutput);```-## Provider Configuration+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.-The OpenAI Agents provider can be configured with various options:+## Strict mode++Pass `strict: true` to enable strict JSON schema validation for tool parameters (see the [Agents SDK options reference](https://openai.github.io/openai-agents-js/guides/tools/#options-reference)):```typescript-const provider = new OpenAIAgentsProvider({- strict: true, // Enable strict mode for tool parameters-});+const provider = new OpenAIAgentsProvider({ strict: true });```-## Documentation--For more information about OpenAI Agents and how to use them, see:+## Links-- [OpenAI Strict Mode](https://openai.github.io/openai-agents-js/guides/tools/#options-reference)-- [OpenAI Agents SDK Documentation](https://openai.github.io/openai-agents-js/)-- [OpenAI Agents SDK GitHub](https://github.com/openai/openai-agents-js)+- [Composio quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)+- [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/)diff --git a/ts/packages/providers/openai/README.md b/ts/packages/providers/openai/README.mdindex f8a2c4c94..cf086ee42 100644--- a/ts/packages/providers/openai/README.md+++ b/ts/packages/providers/openai/README.md@@ -1,276 +1,73 @@# @composio/openai-The OpenAI provider for Composio SDK, providing seamless integration with OpenAI's models and function calling capabilities.--## Features--- **OpenAI Integration**: Seamless integration with OpenAI's models-- **Streaming Support**: First-class support for streaming responses-- **Function Calling**: Support for OpenAI's function calling feature-- **Tool Execution**: Execute tools with proper parameter handling-- **Type Safety**: Full TypeScript support with proper type definitions-- **Model Support**: Support for all OpenAI models (GPT-4, GPT-3.5-turbo, etc.)-- **Responses API Support**: First-class support for OpenAI's Responses API+Adapts Composio tools to OpenAI function calling, for both the Responses API and the Chat Completions API.## Installation```bash-npm install @composio/openai-# or-yarn add @composio/openai-# or-pnpm add @composio/openai-```--## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key-- `OPENAI_API_KEY`: Your OpenAI API key--Optional environment variables:--- `OPENAI_API_BASE`: Custom API base URL (for Azure OpenAI)-- `OPENAI_ORGANIZATION`: OpenAI organization ID--## Quick Start--```typescript-import { Composio } from '@composio/core';-import { OpenAIProvider, OpenAIResponsesProvider } from '@composio/openai';--// Initialize Composio with OpenAI provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- provider: new OpenAIProvider(), // For Chat Completions API- // OR- provider: new OpenAIResponsesProvider(), // For Responses API-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});--// Get a specific tool-const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');+npm install @composio/core @composio/openai openai```-## Examples+Set `COMPOSIO_API_KEY` (create one at https://dashboard.composio.dev/settings) and `OPENAI_API_KEY` (from https://platform.openai.com/api-keys) in your environment.-Check out our complete example implementations:+## Quickstart-- [Basic OpenAI Integration](../../examples/openai/src/index.ts)-- [Chat Completions Example](../../examples/openai/src/chat-completions.ts)-- [Assistants Example](../../examples/openai/src/assistants.ts)-- [Tools Example](../../examples/openai/src/tools.ts)-- [Responses API Example](../../examples/openai/src/responses-api/index.ts)--### Basic Chat Completion with Streaming+Create a session for your user, pass its tools to the Responses API, and run the tool-call loop until the model replies with text. `handleToolCalls` executes the tool calls and returns ready-to-send `function_call_output` items.```typescript-import { Composio } from '@composio/core';-import { OpenAIProvider } from '@composio/openai';import OpenAI from 'openai';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new OpenAIProvider(),-});--// Example API route-export async function POST(req: Request) {- const { messages } = await req.json();- const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],- });-- const stream = await openai.chat.completions.create({- model: 'gpt-4',- messages,- tools,- stream: true,- });-- return new Response(stream, {- headers: {- 'content-type': 'text/event-stream',- },- });-}-```--### Using the Responses API--```typescriptimport { Composio } from '@composio/core';import { OpenAIResponsesProvider } from '@composio/openai';-import OpenAI from 'openai';-const openai = new OpenAI();const composio = new Composio({provider: new OpenAIResponsesProvider(),});+const client = new OpenAI();-// Get tools from Composio-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();-// Generate initial response from OpenAI-const initialResponse = await openai.responses.create({- model: 'gpt-4.1',- input: 'Tell me about the user `pg` in hackernews',+let response = await client.responses.create({+ model: 'gpt-5.2',tools,-});--// Handle tool calls from response-const modelInputs = await composio.provider.handleResponse(- 'default',- initialResponse,- {},- {- beforeExecute: async (toolSlug, toolkitSlug, params) => {- console.log(`🔄 Executing tool ${toolSlug} from toolkit ${toolkitSlug}...`);- return params;+ input: [+ {+ role: 'user',+ content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",},- afterExecute: async (toolSlug, toolkitSlug, result) => {- console.log(`✅ Tool ${toolSlug} executed`);- return result;- },- }-);--// Submit tool outputs back to OpenAI-const finalResponse = await openai.responses.create({- model: 'gpt-4.1',- input: [...initialResponse.output, ...modelInputs],- tools,-});--// Process the final response-const finalContent = finalResponse.output[0];-if (finalContent.type === 'message' && finalContent.content[0].type === 'output_text') {- console.log(finalContent.content[0].text);-}-```--### Tool Execution with Streaming--```typescript-import { Composio } from '@composio/core';-import { OpenAIProvider } from '@composio/openai';-import OpenAI from 'openai';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new OpenAIProvider(),+ ],});-// Example API route that handles tool execution-export async function POST(req: Request) {- const { messages } = await req.json();- const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- });-- const stream = await openai.chat.completions.create({- model: 'gpt-4',- messages,+// Agentic loop: keep executing tool calls until the model responds with text+while (response.output.some(o => o.type === 'function_call')) {+ const results = await composio.provider.handleToolCalls('user_123', response.output);+ response = await client.responses.create({+ model: 'gpt-5.2',tools,- tool_choice: 'auto',- stream: true,+ previous_response_id: response.id,+ input: results,});+}- const chunks = [];- for await (const chunk of stream) {- if (chunk.choices[0]?.delta?.tool_calls) {- const toolCall = chunk.choices[0].delta.tool_calls[0];- const result = await composio.provider.executeToolCall(toolCall);- // Handle tool execution result- chunks.push(result);- } else {- chunks.push(chunk.choices[0]?.delta?.content || '');- }+// Print final response+for (const item of response.output) {+ if (item.type === 'message' && item.content[0].type === 'output_text') {+ console.log(item.content[0].text);}-- return new Response(chunks.join(''), {- headers: {- 'content-type': 'text/plain',- },- });}```-## Provider Configuration--The OpenAI providers can be configured with various options:--```typescript-// For Chat Completions API-const provider = new OpenAIProvider();--// For Responses API-const responsesProvider = new OpenAIResponsesProvider({- // Whether to enforce strict parameter validation- strict: true, // Default: false-});-```--## API Reference--### OpenAIProvider Class--The `OpenAIProvider` class extends `BaseComposioProvider` and provides OpenAI-specific functionality for the Chat Completions API.--#### Methods--##### `executeToolCall(tool: ToolCall): Promise<string>`--Executes a tool call and returns the result.--```typescript-const result = await provider.executeToolCall(toolCall);-```--### OpenAIResponsesProvider Class--The `OpenAIResponsesProvider` class extends `BaseNonAgenticProvider` and provides OpenAI-specific functionality for the Responses API.--#### Methods--##### `handleResponse(userId: string, response: OpenAI.Responses.Response, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>`--Handles tool calls from an OpenAI response and returns the tool outputs.--```typescript-const outputs = await provider.handleResponse('user123', response);-```--##### `handleToolCalls(userId: string, toolCalls: OpenAI.Responses.ResponseOutputItem[], options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>`--Handles specific tool calls from an OpenAI response.--```typescript-const outputs = await provider.handleToolCalls('user123', toolCalls);-```--##### `executeToolCall(userId: string, tool: OpenAI.Responses.ResponseFunctionToolCall, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers): Promise<string>`--Executes a single tool call and returns the result.--```typescript-const result = await provider.executeToolCall('user123', toolCall);-```--## Contributing+## Providers in this package-We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.+The package exports one provider per API surface:-## License+- `OpenAIResponsesProvider` targets the Responses API. `handleToolCalls(userId, response.output)` returns `function_call_output` items keyed by `call_id`; pair it with `previous_response_id` so you only resend new outputs each turn. The constructor accepts `{ strict?: boolean }` to enforce strict function schemas (default `false`).+- `OpenAIProvider` targets the Chat Completions API and is the Composio SDK default, so `new Composio()` with no provider uses it. `handleToolCalls(userId, chatCompletion)` returns ready-to-append `tool` messages; you keep the full message list yourself.-ISC License+Use the Responses provider for new agentic flows; reach for Chat Completions when extending an existing Chat Completions codebase. See the [docs page](https://docs.composio.dev/docs/providers/openai) for the Chat Completions loop.-## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [OpenAI provider docs](https://docs.composio.dev/docs/providers/openai)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/providers/vercel/README.md b/ts/packages/providers/vercel/README.mdindex bdb0d9fc3..e628c02eb 100644--- a/ts/packages/providers/vercel/README.md+++ b/ts/packages/providers/vercel/README.md@@ -1,244 +1,58 @@# @composio/vercel-The Vercel AI SDK provider for Composio SDK, providing seamless integration with Vercel's AI SDK and tools.--## Features--- **Vercel AI SDK Integration**: Seamless integration with Vercel's AI SDK-- **Streaming Support**: First-class support for streaming responses-- **Model Agnostic**: Works with any model supported by Vercel AI SDK (OpenAI, Anthropic, etc.)-- **UI Components**: Integration with Vercel's React components for chat interfaces-- **Tool Execution**: Execute tools with proper parameter handling and streaming-- **Type Safety**: Full TypeScript support with proper type definitions+Composio provider for the [Vercel AI SDK](https://sdk.vercel.ai) (`ai`). It converts Composio tools into the AI SDK's tool format with built-in execution: each wrapped tool carries its own `execute` function, so the AI SDK runs tool calls for you without a manual agentic loop.## Installation```bash-npm install @composio/vercel ai-# or-yarn add @composio/vercel ai-# or-pnpm add @composio/vercel ai-```--## Environment Variables--Required environment variables:--- `COMPOSIO_API_KEY`: Your Composio API key--Optional environment variables (based on model choice):--- `OPENAI_API_KEY`: Your OpenAI API key (if using OpenAI)-- `ANTHROPIC_API_KEY`: Your Anthropic API key (if using Anthropic)-- `GEMINI_API_KEY`: Your Google AI API key (if using Gemini)--## Quick Start--```typescript-import { Composio } from '@composio/core';-import { VercelProvider } from '@composio/vercel';--// Initialize Composio with Vercel provider-const composio = new Composio({- apiKey: 'your-composio-api-key',- provider: new VercelProvider(),-});--// Get available tools-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- limit: 10,-});--// Get tools with version control-const versionedTools = await composio.tools.get('user123', {- toolkits: ['gmail'],- toolkitVersions: { gmail: '20250909_00' },-});--// Get a specific tool-const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');-```--## Examples--Check out our complete example implementations:--- [Basic Vercel Integration](../../examples/vercel/src/index.ts)--### Basic Chat Completion with Streaming--```typescript-import { Composio } from '@composio/core';-import { VercelProvider } from '@composio/vercel';-import { useChat } from 'ai/react';--// Initialize Composio with Vercel provider-const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new VercelProvider()-});--// In your React component-function ChatComponent() {- const { messages, input, handleInputChange, handleSubmit } = useChat({- api: '/api/chat',- });-- return (- <div>- {messages.map(m => (- <div key={m.id}>- {m.role === 'user' ? 'User: ' : 'AI: '}- {m.content}- </div>- ))}-- <form onSubmit={handleSubmit}>- <input- value={input}- onChange={handleInputChange}- placeholder="Say something..."- />- <button type="submit">Send</button>- </form>- </div>- );-}--// In your API route (e.g. app/api/chat/route.ts)-import { streamText } from 'ai';-import { openai } from '@ai-sdk/openai';--export async function POST(req: Request) {- const { messages } = await req.json();- const tools = await composio.tools.get('user123', {- toolkits: ['gmail'],- });-- const result = streamText({- model: openai('gpt-4'),- messages,- tools,- });-- return result.toDataStreamResponse();-}+npm install @composio/core @composio/vercel ai @ai-sdk/anthropic```-### Tool Execution with Streaming+`@ai-sdk/anthropic` powers the example below; swap in any AI SDK model package.-```typescript-import { Composio } from '@composio/core';-import { VercelProvider } from '@composio/vercel';-import { streamText } from 'ai';--const composio = new Composio({- apiKey: process.env.COMPOSIO_API_KEY,- provider: new VercelProvider(),-});+Set two environment variables:-// Example API route that handles tool execution-export async function POST(req: Request) {- const { messages } = await req.json();- const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- });-- const stream = streamText({- model: openai('gpt-4'),- messages,- tools,- callbacks: {- onToolCall: async tool => {- // Execute the tool and return result- return await composio.provider.executeToolCall(tool);- },- },- });-- return stream.toDataStreamResponse();-}-```+- `COMPOSIO_API_KEY` from the [Composio dashboard](https://dashboard.composio.dev/settings)+- `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys) (or the key for your chosen model provider)-## Provider Configuration+## Quickstart-The Vercel provider can be configured with various options:+Create a session for your user, pass its tools to the AI SDK, and cap the run with `stopWhen`:```typescript-const provider = new VercelProvider({- // Default model configuration- model: openai('gpt-4'),- // Custom execution modifiers- modifiers: {- beforeExecute: params => {- // Transform parameters before execution- return params;- },- afterExecute: response => {- // Transform response after execution- return response;- },- },-});-```+import { anthropic } from "@ai-sdk/anthropic";+import { Composio } from "@composio/core";+import { VercelProvider } from "@composio/vercel";+import { generateText, stepCountIs } from "ai";-### Strict Mode+const composio = new Composio({ provider: new VercelProvider() });-When using tools with Vercel AI SDK, you might need to ensure that all tool parameters are marked as required. This is because Vercel AI SDK's function calling implementation requires all fields to be marked as required. You can enable strict mode when fetching tools to automatically remove all non-required properties from both input and output parameters:+// Each session is scoped to one of your users+const session = await composio.create("user_123");+const tools = await session.tools();-```typescript-// Get tools with strict mode enabled-const tools = await composio.tools.get('user123', {- toolkits: ['gmail', 'googlecalendar'],- strict: true, // This will remove all non-required properties from tool parameters+const { text } = await generateText({+ model: anthropic("claude-sonnet-4-6"),+ tools,+ prompt: "Summarize my emails from today",+ stopWhen: stepCountIs(10),});-// Use these tools with Vercel AI SDK-const stream = streamText({- model: openai('gpt-4'),- messages,- tools, // These tools will only have required parameters-});+console.log(text);```-For more information about strict mode in function calling, see [OpenAI's documentation](https://platform.openai.com/docs/guides/function-calling#strict-mode).--## API Reference+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.-### VercelProvider Class+## Strict mode-The `VercelProvider` class extends `BaseComposioProvider` and provides Vercel AI SDK-specific functionality.--#### Methods--##### `executeToolCall(tool: ToolCall): Promise<string>`--Executes a tool call and returns the result.--```typescript-const result = await provider.executeToolCall(toolCall);-```--##### `handleToolCalls(stream: AIStream): AsyncGenerator<AIStreamEvent>`--Handles tool calls from a stream and yields events.+Some models reject tool schemas that contain optional parameters. Pass `strict: true` to drop every non-required property from each tool's input schema before it reaches the AI SDK:```typescript-for await (const event of provider.handleToolCalls(stream)) {- // Handle events-}+const composio = new Composio({ provider: new VercelProvider({ strict: true }) });```-## Contributing--We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.--## License--ISC License--## Support+## Links-For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).+- [Vercel AI SDK provider docs](https://docs.composio.dev/docs/providers/vercel)+- [Composio quickstart](https://docs.composio.dev/docs/quickstart)+- [Composio documentation](https://docs.composio.dev)diff --git a/ts/packages/slim/README.md b/ts/packages/slim/README.mdindex c41fb00cc..f4d44584b 100644--- a/ts/packages/slim/README.md+++ b/ts/packages/slim/README.md@@ -2,7 +2,7 @@Slim build of the Composio TypeScript core SDK.-`@composio/core` intentionally publishes SDK docs and TypeScript source for users who want an inspectable/debuggable package. `@composio/slim` publishes the same built runtime/type artifacts without the packaged `docs/` or `src/` trees.+`@composio/core` intentionally ships its TypeScript source and SDK docs inside the npm package so coding agents (and humans) can inspect and debug the SDK straight from `node_modules`. That inspectability costs install size. `@composio/slim` publishes the same built runtime and type artifacts without the packaged `src/` and `docs/` trees, so it installs smaller while behaving identically.```bashpnpm add @composio/slim@@ -14,4 +14,4 @@ import { Composio } from '@composio/slim';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });```-The API mirrors `@composio/core` for consumers that prefer a smaller installed package.+The API mirrors `@composio/core` for consumers that prefer a smaller installed package. See the [`@composio/core` README](https://github.com/ComposioHQ/composio/tree/next/ts/packages/core) for usage.