--- canonical_url: "https://docs.composio.dev/kb/guide/toolkits-gemini" markdown_url: "https://docs.composio.dev/kb/guide/toolkits-gemini.md" product: "platform" version: null last_updated: null --- # Gemini (/kb/guide/toolkits-gemini) Use this guide to choose supported Gemini models, handle generated media, connect through MCP, and troubleshoot provider compatibility. ## Choose supported models and handle generated media [#choose-supported-models-and-handle-generated-media] **Use current Gemini model names.** If Gemini tool calls fail with older model names, switch to a currently supported Gemini model. For example, use `gemini-2.5-flash` instead of the older `gemini-1.5-flash`; model availability changes over time. **Choose a supported Veo model for video generation.** For Gemini video generation, use supported Veo models such as `veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`, `veo-3.0-generate-001`, or `veo-3.0-fast-generate-001`. If the default model fails, explicitly pass a current supported Veo model. **Wait for asynchronous video generation to complete.** Gemini video generation is asynchronous. Pass the `operation_name` returned by `GEMINI_GENERATE_VIDEOS` to `GEMINI_WAIT_FOR_VIDEO`, which polls for completion and returns the generated video file. The older `GEMINI_GET_VIDEOS_OPERATION` action is deprecated. **Disable automatic file handling when outputs should remain as URLs or content.** Composio SDKs automatically handle file upload/download by default. For Gemini generated images or similar file outputs, disable automatic file handling with `autoUploadDownloadFiles: false` / `auto_upload_download_files=False` where supported, or update to a version that supports that option. ## Connect Gemini through MCP and frameworks [#connect-gemini-through-mcp-and-frameworks] **Use Tool Router with any compatible MCP client.** Tool Router can be used with any MCP client or framework/LLM that supports tool calling or MCP. For Gemini, initialize Composio with `GeminiProvider`, create a session, then connect to the session MCP URL and headers using a streamable HTTP MCP client. **Isolate Gemini CLI-specific MCP failures.** If a Composio MCP server URL returns tools but Gemini CLI still fails, the issue may be in the Gemini client. Try the latest Gemini CLI version and, if needed, compare with another MCP client to isolate whether the failure is client-specific. **Use LangChain MCP tools with any capable model.** Composio MCP tools with LangChain are not limited to OpenAI. They can work with any LLM/framework path that supports LangChain function calling capabilities, including Gemini and Claude. ## Check provider compatibility and tool-call accounting [#check-provider-compatibility-and-tool-call-accounting] **Account for no-auth toolkit calls like regular tool calls.** Gemini no-auth toolkit calls are logged like other toolkit calls and can be tracked in Composio tool logs. Confirm the current plan's tool-call accounting when answering billing questions because pricing can change. **Check Google's schema limitations when otherwise-valid tools fail.** Gemini models/providers can have schema compatibility issues because Gemini uses OpenAPI-style schema handling rather than full JSON Schema support in some paths. If a schema works in OpenAI/Claude but fails in Gemini, check provider schema limitations and upgrade Composio/provider SDKs where fixes exist. **Verify current language-specific provider support.** Composio supports Google Gemini and Vertex AI providers. Verify the current SDK version and provider documentation when answering implementation-specific questions because language-specific support changes over time. --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Changelog](https://docs.composio.dev/docs/changelog.md) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference) --- # Composio SDK — Notes for AI Code Generators **Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code. **Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code. --- ## 1. Recommended Integration: Sessions Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed). ### Native Tools ```python # ✅ CORRECT — Python (defaults to OpenAI) from composio import Composio composio = Composio() session = composio.create(user_id="user_123") tools = session.tools() # Pass tools to your agent/LLM framework ``` ```typescript // ✅ CORRECT — TypeScript (defaults to OpenAI) import { Composio } from "@composio/core"; const composio = new Composio(); const session = await composio.create("user_123"); const tools = await session.tools(); // Pass tools to your agent/LLM framework ``` For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_` for Python, `@composio/` for TypeScript. ### MCP Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed. --- ## 2. Integration Notes - `composio.create(user_id)` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; `user_id` goes to `composio.create()` — individual tool calls in session mode don't take one. - Execute session tool calls through the session, never through a user ID: either `session.execute(tool_slug, arguments=...)` / `session.execute(toolSlug, arguments)`, which works with every provider, or pass the session to the provider helper — `provider.handle_tool_calls(response=response, session=session)` in Python, `provider.handleToolCalls(session, response)` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: `executeToolCall(session, call)` in TypeScript, `session=session` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with `"can only be called inside a tool-router session"`. - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits. - Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is `composio_openai_agents` / `@composio/openai-agents` (importing `composio_openai` / `@composio/openai` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API). - **Direct execution** (`composio.tools.get()`, `composio.tools.execute()`, `provider.handle_tool_calls()` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning). --- # 3. Calling the REST API directly ## REST API version The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples. `https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate. ## Tool-endpoint version defaults on v3.1 On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned `00000000_00` version. `POST /tools/scopes/required` is v3.1-only. | Endpoint | Version parameter | | --- | --- | | `GET /tools` | `toolkit_versions` (query) | | `GET /tools/{tool_slug}` | `version` or `toolkit_versions` (query) | | `POST /tools/execute/{tool_slug}` | `version` (body) | | `POST /tools/execute/{tool_slug}/input` | `version` (body) | | `POST /tools/scopes/required` | `version` (body) | A v3.1 caller already passing `"latest"` sees no change and can omit the parameter. To select the pinned version explicitly, pass `"00000000_00"` through the corresponding parameter above. This version-default change is limited to the five endpoints above. --- ## Terminology Migration (old → current) If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.** | Old term (v1/v2) | Current term (v3) | In code | |---|---|---| | entity ID | user ID | `user_id` parameter | | actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* | | apps / appType | toolkits | e.g., `github` is a *toolkit* | | integration / integration ID | auth config / auth config ID | `auth_config_id` parameter | | connection | connected account | `connected_accounts` namespace | | ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` | | toolset | provider | e.g., `OpenAIProvider` | If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.