Composio — интеграционная платформа для AI-агентов

Composio подключает ИИ-агента к внешним сервисам: почте, мессенджерам, репозиториям, трекерам, CRM. Вместо десятков самописных интеграций вы получаете один SDK, авторизацию пользователей на стороне платформы и удалённую песочницу для тяжёлых операций.

Что это такое

Composio — платформа интеграций для ИИ-агентов. Она даёт агенту 1 000+ готовых тулкитов (Gmail, Slack, GitHub, Notion, Linear, Jira, Salesforce, Google Sheets и другие), внутри которых более 20 000 отдельных инструментов, и берёт на себя авторизацию конечных пользователей.

Ключевая единица работы — сессия. Вы создаёте её для конкретного пользователя своего продукта, передаёте агенту набор мета-инструментов, и дальше агент сам ищет нужный инструмент, просит пользователя подключить аккаунт и выполняет действие. Схемы тысяч инструментов не загружаются в контекст модели.

Платформа работает в двух режимах: через SDK для Python и TypeScript с адаптерами под ваш фреймворк или через hosted MCP-эндпоинт для Claude, Cursor, ChatGPT и других MCP-клиентов.

Целевая картина: как устроена работа

flowchart LR
    A["Ваше приложение"] --> B["composio.create(userId)"]
    B --> C["Сессия: userId, тулкиты, авторизация, состояние"]
    C --> D["Мета-инструменты агента"]
    C --> E["MCP-эндпоинт session.mcp.url"]
    D --> F["COMPOSIO_SEARCH_TOOLS: поиск инструмента"]
    F --> G["COMPOSIO_MANAGE_CONNECTIONS: Connect Link"]
    G --> H["COMPOSIO_MULTI_EXECUTE_TOOL: выполнение"]
    H --> I["Gmail, Slack, GitHub, Notion, 1000+ сервисов"]
    C --> J["Удалённая песочница: Python и bash"]

Сессия

Сессия — это runtime-контекст одного агентного запуска. Каноничный способ создать её в обоих SDK — composio.sessions.create(...); короткие формы composio.create(...) и composio.use(...) остаются поддерживаемыми, а прежний алиас composio.tool_router помечен устаревшим. Сессия связывает четыре вещи:

• userID — чьи подключённые аккаунты используются;
• доступ к инструментам — весь каталог по умолчанию либо ограниченный набор тулкитов, инструментов или тегов;
• авторизацию — managed auth, кастомные auth-конфиги, выбор конкретного подключённого аккаунта;
• состояние исполнения — логи, память инструментов, состояние MCP, файлы песочницы.

Сессии живут на сервере и не истекают. Для многошагового диалога сохраните session.session_id и переиспользуйте его через composio.use(), а не создавайте новую сессию на каждый ход. Состав сессии можно менять на месте методом session.update(), передав другие тулкиты, auth-конфиги или подключённые аккаунты.

Мета-инструменты

Вместо тысяч tool-схем агент получает небольшой фиксированный набор системных инструментов:

Вызовы мета-инструментов делят общий контекст: агент ищет инструмент в одном шаге и выполняет его в следующем, не теряя состояние. Если набор инструментов известен заранее, есть два варианта. preload.tools отдаёт нужные инструменты сразу и оставляет мета-инструменты на месте — этого хватает в большинстве случаев (требуется @composio/core от 0.9.0 или composio от 0.13.0). Пресет direct tools загружает все разрешённые фильтрами инструменты и при этом по умолчанию отключает мета-инструменты, включая управление подключениями и песочницу: если они нужны, их включают явно через manage_connections и sandbox в конфигурации сессии.

Авторизация

Когда инструменту нужен доступ к сервису, сессия генерирует Connect Link — страницу, где пользователь подтверждает подключение. Ссылку можно получить программно через session.authorize() или отдать это агенту через COMPOSIO_MANAGE_CONNECTIONS. Composio берёт на себя OAuth-редиректы, обмен токенов и их обновление. После первого подключения аккаунт сохраняется и переиспользуется в следующих сессиях без повторной авторизации.

Для OAuth-тулкитов по умолчанию работает managed app самой Composio. Своё приложение подключают, когда нужны собственный бренд, набор scope или экран согласия.

Песочница

Песочница — постоянное Python-окружение с доступом к инструментам Composio, вызовом моделей, загрузкой файлов и HTTP-запросами. Состояние (импорты, переменные, файлы) сохраняется между вызовами внутри сессии. Она нужна там, где длинный ответ инструмента незачем тащить в контекст модели: агент читает файлы, ищет по выгрузке, пишет код и вызывает инструменты пачками.

Под капотом это постоянный Jupyter-ноутбук. У песочницы есть файловый маунт /mnt/files/, который выживает при перезапуске окружения; файлы заливаются и забираются через session.experimental.files. Вычислительный размер задаётся ключом sandbox.sandbox_size: standard (1 vCPU, 1 ГБ), medium (2 vCPU, 2 ГБ), large (4 vCPU, 4 ГБ), xlarge (8 vCPU, 8 ГБ), по умолчанию standard. Песочница включена в сессии по умолчанию и на 1 августа 2026 не тарифицируется, но документация предупреждает о будущем биллинге по тиру и времени работы. Если исполнять код не нужно, отключите её через sandbox: { enable: false }: оба мета-инструмента исчезнут из сессии, а прямые вызовы песочницы будут возвращать 400.

Основные возможности

Подключение и интеграция

Два способа подключения:

Ключи и переменные окружения

Получите COMPOSIO_API_KEY в дашборде, ключ модели — у своего провайдера. Держите значения в .env или в секретах среды исполнения и не коммитьте их в репозиторий.

# .env
COMPOSIO_API_KEY=<ключ из dashboard.composio.dev/settings>
OPENAI_API_KEY=<ключ из platform.openai.com>

Быстрый старт: TypeScript и OpenAI Agents

npm install @composio/core @composio/openai-agents @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 session = await composio.create("user_123")
const tools = await session.tools()

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful assistant. Use Composio tools to take action.",
  tools,
})

const result = await run(agent, "Summarize my emails from today")
console.log(result.finalOutput)

Быстрый старт: Python и OpenAI Agents

pip install composio composio-openai-agents openai-agents

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner

composio = Composio(provider=OpenAIAgentsProvider())

# Сессия всегда привязана к одному пользователю вашего продукта
session = composio.create(user_id="user_123")
tools = session.tools()

agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful assistant. Use Composio tools to take action.",
    tools=tools,
)

result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")
print(result.final_output)

Подключение по MCP

MCP-эндпоинт включается флагом при создании сессии. Без него session.mcp не появится.

from composio import Composio

composio = Composio()
session = composio.sessions.create(user_id="user_123", mcp=True)

mcp_url = session.mcp.url
mcp_headers = session.mcp.headers

import { Composio } from "@composio/core"

const composio = new Composio()
const session = await composio.create("user_123", { mcp: true })

const mcpUrl = session.mcp.url
const mcpHeaders = session.mcp.headers

Для возобновления сохранённой сессии флаг передаётся повторно: composio.use(sessionId, { mcp: true }) в TypeScript и composio.use(session_id, mcp=True) в Python. Пакет провайдера для MCP не нужен.

CLI

curl -fsSL https://composio.dev/install | bash
composio login

Дальше composio search ищет инструменты, composio execute выполняет их, composio link подключает аккаунты, composio run запускает сценарии на TypeScript. CLI удобен как локальная поверхность для кодинг-агентов вроде Claude Code и Codex.

Поддерживаемые фреймворки

Если вашего фреймворка нет в списке, можно написать собственный провайдер или отказаться от провайдеров и подключиться по MCP. TypeScript SDK с версии 0.12.0 поставляется только в ESM: нужен Node.js 22.22.3 или новее, require("@composio/core") больше не работает. Python SDK поддерживает Python 3.10+. Актуальные версии на 30 июля 2026 — composio 0.18.1 и @composio/core 0.14.1.

Проверка результата

Минимальный сценарий, который показывает, что связка живая.

1. Ключ работает. Запрос к API должен вернуть 200:

   curl -s -o /dev/null -w "%{http_code}\n" \
     https://backend.composio.dev/api/v3/tools \
     -H "x-api-key: $COMPOSIO_API_KEY"

2. Агент запускается. Скрипт из быстрого старта выполняется без ошибок импорта и авторизации, session.tools() возвращает непустой список.
3. Авторизация проходит. На первом запросе к сервису агент отвечает, что нужно подключить аккаунт, и отдаёт Connect Link. После подтверждения повторный запрос выполняется без новой авторизации.
4. Действие видно в сервисе. Наблюдаемый признак успеха — результат на стороне сервиса: созданный issue в GitHub, отправленное письмо, новая страница в Notion.
5. Вызов виден в логах. В дашборде Composio на вкладке логов исполнения есть запись с полным запросом и ответом инструмента.

API, лимиты и заголовки

• Базовый URL: https://backend.composio.dev/api/v3; часть новых эндпоинтов (tool router, connected accounts) уже опубликована как v3.1.
• Авторизация: заголовок x-api-key для проектных ключей, x-org-api-key для организационных.
• Proxy Execute отключён на v3: нужен v3.1 или свежий SDK. Возможность стала опциональной и включается на конкретном API-ключе; у ключей появились whitelisting IP и постепенно раскатываются скоупы.
• Лимиты запросов: считаются на организацию в фиксированном окне одной минуты, общий бюджет на все эндпоинты.

Каждый ответ содержит заголовки X-RateLimit, X-RateLimit-Remaining, X-RateLimit-Window-Size, а при 429 ещё и Retry-After. Схемы инструментов и другие статичные данные стоит кэшировать на своей стороне, чтобы не расходовать на них бюджет запросов.

Практические сценарии

Ассистент с доступом к рабочим инструментам

Агент работает с Gmail, Slack и Notion. Пользователь просит показать непрочитанные письма и создать по каждому задачу. Агент находит нужные инструменты, отдаёт Connect Link для неподключённых сервисов и выполняет цепочку действий в рамках одной сессии.

Ассистент разработки

Агент подключён к GitHub и Linear. Триггер на новый pull request запускает разбор изменений, агент создаёт задачу с результатами и отправляет короткое резюме в рабочий чат.

Массовая обработка выгрузок

Агенту нужно разобрать несколько тысяч писем или строк таблицы. Вместо загрузки выгрузки в контекст модели он работает в песочнице: складывает данные в файлы, пишет Python для агрегации и вызывает инструменты пачками через COMPOSIO_MULTI_EXECUTE_TOOL.

MCP-подключение для десктопного клиента

Сессия с флагом mcp: true даёт URL, который подключается к Claude, Cursor или ChatGPT. Пользователь управляет репозиториями, чатами и страницами прямо из клиента, без собственного кода на своей стороне.

Тарифы и лимиты

Данные на 1 августа 2026, тарификация меняется 15 августа.

Бесплатного плана достаточно для прототипа и тестов. Для боевой нагрузки разумная точка входа — $29 в месяц с оплатой перерасхода по факту. У ранних стартапов есть отдельная программа с кредитами на платформу, условия смотрите на composio.dev/startups.

Ограничения и когда не подходит

• Каталог неоднороден. 1 000+ тулкитов покрывают разный объём API: у одного сервиса сотня инструментов, у другого пять. Проверьте нужные операции в каталоге тулкитов до того, как строить на них продукт.
• Данные идут через инфраструктуру платформы. Компания зарегистрирована в США, изоляция в собственном контуре доступна только на Enterprise через VPC или on-prem. Для регулируемых данных это ключевой вопрос.
• Лимит общий на организацию. Один шумный воркер способен съесть бюджет запросов всего проекта.
• Песочница ограничена по времени. Жёсткий лимит 180 секунд на исполнение, длинные задачи придётся разбивать на шаги.
• Модель работы уже менялась. За год платформа прошла путь от прямого исполнения инструментов через experimental tool router и отдельные MCP-серверы к сессиям. Код, написанный по старым гайдам, требует миграции.
• Тарифы нестабильны. Смена тарификации 15 августа 2026 означает, что расчёт стоимости нужно перепроверять перед внедрением.

Если задача сводится к нескольким интеграциям с фиксированным набором действий, собственный тонкий слой на официальных API обойдётся дешевле и предсказуемее.

Сравнение с альтернативами

Данные по конкурентам взяты из их публичных материалов на 1 августа 2026 и требуют проверки перед выбором.

Выбор упрощается так: Composio берут, когда нужен широкий каталог и быстрая сборка агента; Arcade — когда авторизация и governance важнее охвата; Pipedream — когда рядом с агентом нужна классическая автоматизация процессов.

Обновления Composio за 2026 год

Если вы читали материал в апрельской версии, изменилось следующее:

• Tool Router вырос в сессии. Экспериментальный composio.experimental.tool_router стал стабильной функцией, а затем основным способом работы: сессия создаётся вызовом create(), переиспользуется через use() и обновляется через update().
• Отдельные MCP-серверы под тулкит устарели. MCP теперь живёт в сессии, флаг mcp: true обязателен.
• Workbench переименован в sandbox. Ключ конфигурации sandbox, старое имя работает как алиас, имена мета-инструментов не изменились.
• Появился новый мета-инструмент COMPOSIO_REMOTE_BASH_TOOL для shell-команд в песочнице.
• Уточнились лимиты. Официальная документация задаёт 2 000–10 000 запросов в минуту на организацию в зависимости от плана.
• Legacy-роуты MCP Config закрыли анонимный доступ. С июня 2026 запросы к ним требуют API-ключ или заголовок Authorization: Bearer, документация советует переходить на composio.create.
• У песочницы появились вычислительные тиры от standard до xlarge и постоянный маунт /mnt/files/.
• TypeScript SDK стал ESM-only в версии 0.12.0: минимальный Node.js — 22.22.3.
• Появился CLI как отдельная поверхность для терминала и кодинг-агентов.

Чеклист быстрой проверки

Ссылки

• 🌐 Сайт: composio.dev
• 📖 Документация: docs.composio.dev
• 🧩 Как работают сессии: docs.composio.dev/docs/how-composio-works
• 🔌 Сессии через MCP: docs.composio.dev/docs/sessions-via-mcp
• 🛠 Мета-инструменты: docs.composio.dev/toolkits/meta-tools
• 📋 API Reference и лимиты: docs.composio.dev/reference
• 🔧 Каталог тулкитов: composio.dev/toolkits
• 💰 Тарифы: composio.dev/pricing
• 🐙 GitHub: github.com/ComposioHQ/composio
• 🧭 Гайды миграции: docs.composio.dev/docs/migration-guide

Следующий шаг

• Статья: Агенты как новый SaaS: полный разбор для тех, кто строит продукт на ИИ

Связанные материалы

• Статья: Как собрать свою первую команду ИИ-агентов
• Блог: ChatGPT Work теперь заходит в сервисы под вашим логином
• База знаний: Как подключить почту к ChatGPT: штатные приложения, MCP поверх IMAP, автоматизации и unified API

Подключение агента к рабочим сервисам почти всегда упирается не в модель, а в авторизацию, права и порядок вызовов. Разговор будет полезен командам, которые уже собрали прототип агента и думают, как довести его до продакшена.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov