> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ixo.world/llms.txt
> Use this file to discover all available pages before exploring further.

# composio

> External SaaS tools (Gmail, GitHub, Linear, Slack, Notion, Jira, …) invoked on behalf of the user.

**Source:** [`packages/oracle-runtime/src/plugins/composio/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/composio/)

| Attribute     | Value                                 |
| ------------- | ------------------------------------- |
| Feature key   | `composio`                            |
| Visibility    | `on-demand`                           |
| Stability     | `stable`                              |
| Category      | `integration`                         |
| Default state | Auto-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

| Var                 | Required | Description                                                                                                                                                    |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPOSIO_API_KEY`  | yes      | Composio API key. Triggers auto-detect.                                                                                                                        |
| `COMPOSIO_BASE_URL` | no       | Defaults to `https://composio.ixo.earth`.                                                                                                                      |
| `NETWORK`           | no       | Read 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.

<Note>
  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.
</Note>

## Opt out / Opt in

```ts theme={"system"}
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`:

```json theme={"system"}
{
  "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`.

## Where to read next

<CardGroup cols={2}>
  <Card title="Identity and auth" icon="id-card" href="/build-an-oracle/develop/identity-and-auth">
    How UCAN invocations are minted per request.
  </Card>

  <Card title="Visibility tiers" icon="layer-group" href="/build-an-oracle/understand/visibility-tiers">
    Why composio is `on-demand` instead of `always`.
  </Card>
</CardGroup>