Instant Tools

Instant Tools let your Session run supported tools without an end-user provider connection. A Composio hosted account provides access for eligible tools. Premium usage charges for those calls come from your organization's available balance.

Experimental access

This feature requires a project setting that is not yet self-service. Email support@composio.dev to enable it for your project and confirm which tools and rates are available. Session configuration cannot override a project where the setting is off.

Once the project setting is enabled, new Sessions can use eligible Instant Tools by default, even if premium_usage is omitted. Set premium_usage=False in Python or premiumUsage: false in TypeScript when creating a Session that must not incur premium usage charges.

Find eligible tools

Instant tool coverage is per tool, not per toolkit. The current toolkit listing API does not return instant tool availability or offer an instant tool filter. Its no_auth and composio_managed_auth_schemes fields mean different things and should not be used as substitutes. During Experimental access, ask support@composio.dev for the supported tools and rates before allowing them in a production Session.

Create a Session

After your project is enabled, create a Session. This example makes Exa available and permits premium usage for its eligible tools:

from composio import Composio

composio = Composio()
session = composio.sessions.create(
    user_id="user_123",
    toolkits=["exa"],
    premium_usage={
        "toolkits": {"enable": ["exa"]},
        "return_premium_charge": True,
    },
)

Top-level toolkits controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. premium_usage.toolkits (or premiumUsage.toolkits in TypeScript) separately restricts which eligible tools can incur premium usage charges. Omitting premium_usage.toolkits does not restrict premium usage: eligible tools remain available when the project and Session permit them. return_premium_charge defaults to false and only controls whether the actual charge appears in the immediate tool response. An Instant toolkit can still contain tools that need a connected account; hosted account coverage is tool-specific.

Find and run a tool

Pass session.tools() to your agent as in the Quickstart, so it can discover and run eligible tools. If your agent uses MCP, expose the same Session through session.mcp as described in Using sessions via MCP. The premium usage policy applies to that Session in either path; your agent does not need a separate premium usage setting.

tools = session.tools()  # Pass these to your agent framework.

To run a known tool yourself, use the Session's execute method:

result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentation"})

Check the current tool input schema before constructing arguments. A tool appearing in a toolkit does not mean hosted account access is available for that tool. Confirm supported tools and rates during Experimental access.

Control premium usage

premium_usage is a Session policy (premiumUsage in TypeScript). It does not enable a toolkit that top-level toolkits excludes, and it does not change a connected account you explicitly selected.

The toolkit filter and per-tool filter intersect. A tools.exa rule alone does not disable premium usage for other eligible toolkits. Use premium_usage.toolkits when you need a toolkit allowlist. Each filter accepts either enable or disable, not both.

The examples below use Python and REST field names. In TypeScript, use premiumUsage and returnPremiumCharge.

Session value	Effect
Omitted or `{}`	Permits premium usage for eligible tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default.
`false`	Disables premium usage for that Session. Your own connected-account routes remain available.
`{ "toolkits": { "enable": ["exa"] } }`	Permits premium usage only for listed toolkits. Use `disable` instead to exclude selected toolkits.
`{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }`	Narrows premium usage to selected tools within a toolkit.
`{ "return_premium_charge": true }`	Requests the actual `premium_charge` in an eligible Session tool response. This changes charge visibility, not permission to spend.

For example, keep Exa and Firecrawl available, but permit premium usage only for EXA_SEARCH:

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["exa", "firecrawl"],
    premium_usage={
        "toolkits": {"enable": ["exa"]},
        "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
    },
)

To stop premium usage on an existing Session, update its policy:

session.update(premium_usage=False)

On patch, omitted premium_usage fields keep their existing values. Supplying an object after false enables this Session policy again, provided the project allows it.

Know which account runs the tool

A hosted account is a provider account held by Composio for specific tools. It is different from Composio-managed auth, where Composio supplies OAuth application credentials but your user still connects their own account. Composio-managed auth alone does not make a tool Instant.

If you select a connected account explicitly, that route wins and does not fall back to the hosted account on failure. Otherwise, available user, shared, or developer connections take priority over a hosted account. If the chosen tool is not supported by a hosted account, it follows the normal connection flow.

Hosted accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its premium_usage policy.

See Configuring Sessions for general toolkit and tool filters and the create Session API reference for the complete request schema.

Edit this page on GitHub