Skip to main content
Source: packages/oracle-runtime/src/plugins/composio/
AttributeValue
Feature keycomposio
Visibilityon-demand
Stabilitystable
Categoryintegration
Default stateAuto-detect (env: COMPOSIO_API_KEY)
Depends on—

​
Summary

Hundreds of SaaS tools (Gmail, GitHub, Linear, Slack, Google Calendar, Notion, Jira, HubSpot, …) invoked on behalf of the user through Composio. Tools are discovered dynamically per request: the plugin mints a UCAN invocation addressed to the composio-worker, opens a session for the current user, and exposes each returned tool to the agent. Auth is UCAN-only — if minting fails the plugin contributes zero tools that turn.

​
Environment variables

VarRequiredDescription
COMPOSIO_API_KEYyesComposio API key. Triggers auto-detect.
COMPOSIO_BASE_URLnoDefaults to https://composio.ixo.earth.
NETWORKnoRead but not owned (declared by the core base env schema). Forwarded as the x-ixo-network header so the composio-worker routes to the right IXO environment.

​
What it contributes

Composio is a tool router, not a 1:1 catalog. Per request the session returns a small fixed set of directly-callable meta-tools; the thousands of app-specific tools (e.g. GMAIL_SEND_EMAIL, COMPOSIO_SEARCH_FINANCE) are not bound to the agent — they are discovered and then executed through the router.
  • Tools (the four router meta-tools):
    • COMPOSIO_MANAGE_CONNECTIONS — check / start a toolkit’s auth connection (returns a redirect_url when the user must connect).
    • COMPOSIO_SEARCH_TOOLS — describe an action in natural language to find the exact tool slug(s).
    • COMPOSIO_GET_TOOL_SCHEMAS — fetch the exact input schema for one or more discovered slugs.
    • COMPOSIO_MULTI_EXECUTE_TOOL — run one or more discovered tools by slug. App-specific tools are executed here, never bound directly.
  • Sub-agents: none.
  • Middleware: none.
  • HTTP routes: none.
  • Shared state: none.
The exact tool set is returned dynamically by the composio-worker session, so it can vary by user/connection. The plugin pins only the COMPOSIO_MULTI_EXECUTE_TOOL argument envelope (see below) — every slug lives in Composio’s registry, not in the runtime.

​
Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { composio: false }, // never load
  // features: { composio: true }, // force load (will fail env validation if COMPOSIO_API_KEY missing)
  // features: { composio: 'auto' }, // run autoDetect (default)
});

​
The discover → execute flow

App-specific tools are never callable directly. The agent follows a fixed four-step flow (this is the whenToUse guidance that ships in the manifest and reaches the model):
  1. Connect — for any connected-app action, call COMPOSIO_MANAGE_CONNECTIONS with the toolkit FIRST. If it returns a redirect_url, surface it as a clickable markdown link and stop. (Pure search tools — the COMPOSIO_SEARCH_* family — need no connection.)
  2. Discover — call COMPOSIO_SEARCH_TOOLS, describing the action in natural language, to find the exact tool slug(s).
  3. Inspect (if unsure) — call COMPOSIO_GET_TOOL_SCHEMAS with those slugs to fetch their exact input schema.
  4. Execute — call COMPOSIO_MULTI_EXECUTE_TOOL with the discovered slug(s).
The execute envelope is strict — exactly tools + sync_response_to_workbench, with each call wrapped as tool_slug + arguments: 
{
  "tools": [
    { "tool_slug": "COMPOSIO_SEARCH_FINANCE", "arguments": { "query": "Bitcoin price USD today" } }
  ],
  "sync_response_to_workbench": false
}
Never pass a tool name as a top-level key (e.g. { "COMPOSIO_SEARCH_FINANCE": {...} }) — always wrap it inside the tools array.

​
When to use it

  • User asks to send, read, or search emails (Gmail, Outlook).
  • User asks to create or modify issues, pull requests, or stars (GitHub, Linear, Jira).
  • User asks to manage calendar events, files, or documents in a SaaS app.
  • Web, news, finance, academic, or trend searches — the COMPOSIO_SEARCH_* family covers these and needs no connection.
  • No native skill covers the requested action — discover what Composio offers with COMPOSIO_SEARCH_TOOLS before giving up.

​
When NOT to use it

  • A native skill or sub-agent already covers the action — prefer the skill.
  • Normal conversation or general question with no external SaaS interaction.
  • NEVER fabricate or guess any URL yourself — the only valid auth link is the redirect_url returned by COMPOSIO_MANAGE_CONNECTIONS.

Identity and auth

How UCAN invocations are minted per request.

Visibility tiers

Why composio is on-demand instead of always.