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

Composio подключает ИИ-агента к внешним сервисам и берёт на себя поиск инструментов, авторизацию пользователей и выполнение действий. Основной способ интеграции — сессии через SDK или размещённый эндпоинт протокола Model Context Protocol (MCP).

Что такое Composio

Composio — платформа инструментов и управляемой авторизации для ИИ-агентов. На актуальной странице тарифов заявлено более 1 500 тулкитов: Gmail, Slack, GitHub, Notion, Linear, Jira, Salesforce и другие.

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

Платформа поддерживает два основных режима:

• нативные инструменты через SDK — для приложений на Python или TypeScript с провайдером под используемый агентный фреймворк;
• MCP — один размещённый эндпоинт сессии для совместимого клиента, без пакета провайдера.

Как устроена работа

flowchart LR
    A["Ваше приложение"] --> B["Создание сессии для user ID"]
    B --> C["Тулкиты, авторизация и состояние"]
    C --> D["Нативные инструменты через SDK"]
    C --> E["MCP-эндпоинт session.mcp"]
    D --> F["Поиск и выполнение инструментов"]
    E --> F
    F --> G["Gmail, Slack, GitHub, Notion и другие сервисы"]
    C --> H["Опциональная удалённая песочница"]

Сессия и user ID

Стандартная точка входа для агентной интеграции — composio.create(user_id). Сессия отвечает за обнаружение инструментов, авторизацию и выбор версий тулкитов. Сохранённую сессию можно возобновить через composio.use().

Используйте стабильный идентификатор пользователя из своей базы. Email хуже подходит для этой роли, поскольку может измениться. Не используйте общее значение вроде default для разных пользователей в продакшене.

В сессионном режиме выполняйте найденные действия через саму сессию: session.execute(...) или провайдер, которому передана сессия. Передача только user ID в обработчик провайдера включает другой, прямой путь выполнения, на котором сессионные мета-инструменты работать не будут.

Авторизация

Управляемая авторизация Composio (Composio-managed auth) позволяет подключать аккаунты во время работы агента. Пользователь проходит авторизацию нужного сервиса, после чего подключённый аккаунт можно использовать в следующих сессиях.

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

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

Сессия может предоставлять небольшой набор системных инструментов для поиска, получения схем, управления подключениями и выполнения действий. Для заранее известного фиксированного набора используйте пресет direct tools: MCP-клиент увидит только явно разрешённые инструменты без поиска и других мета-инструментов.

Прямое выполнение (direct execution) вне сессии остаётся поддерживаемым низкоуровневым интерфейсом. Оно подходит для детерминированных сценариев, где приложение заранее выбирает инструмент. Для такого вызова требуется указать версию тулкита. Сессии удобнее для агентов, которые находят нужное действие во время работы. По актуальным тарифам прямое выполнение вне сессии может создавать дополнительную плату.

Удалённая песочница

Песочница — постоянное Python-окружение для массовой обработки данных и многошаговой логики. Она включается для конкретной сессии через sandbox: { enable: true }. Агент запускает Python через COMPOSIO_REMOTE_WORKBENCH, а shell-команды — через COMPOSIO_REMOTE_BASH_TOOL.

Импорты, переменные и состояние памяти сохраняются между вызовами внутри сессии. Файлы в /mnt/files/ переживают перезапуск окружения; приложение загружает и скачивает их через экспериментальный интерфейс session.experimental.files.

Доступные вычислительные размеры:

Прежнее название workbench остаётся поддерживаемым алиасом. Имена мета-инструментов не изменились.

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

Подключение через SDK

Храните COMPOSIO_API_KEY в переменной окружения или хранилище секретов, не добавляя значение в репозиторий.

# .env
# Подставьте значения из панели Composio и у провайдера модели.
COMPOSIO_API_KEY=<ключ из панели Composio>
OPENAI_API_KEY=<ключ провайдера модели>

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: "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="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)

Пакет провайдера выбирают по фреймворку; поставщик модели здесь вторичен. Например, OpenAI Agents требует composio_openai_agents или @composio/openai-agents.

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

Передайте mcp: true при создании сессии. URL и обязательные заголовки появятся в 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

При возобновлении сессии флаг нужно передать снова:

• TypeScript: composio.use(sessionId, { mcp: true });
• Python: composio.use(session_id, mcp=True).

MCP удобен переносимостью, но у него есть ограничения:

• хуки beforeExecute, afterExecute и преобразование схемы modifySchema не выполняются, поскольку клиент вызывает размещённый сервер напрямую;
• локальные пользовательские инструменты и тулкиты, привязанные к процессу приложения, через этот эндпоинт недоступны.

Если нужно перехватывать, изменять или дополнительно проверять вызовы, используйте нативные инструменты через провайдер.

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

1. Создайте сессию для тестового пользователя и убедитесь, что session.tools() возвращает ожидаемый набор инструментов.
2. Запросите действие в сервисе. При отсутствии подключённого аккаунта пройдите предусмотренный Composio процесс авторизации.
3. После успешного подключения повторите запрос и проверьте, что действие выполняется с выбранным аккаунтом.
4. Проверьте наблюдаемый результат на стороне сервиса: созданный объект, черновик письма или другой ожидаемый результат.

Для проверки REST API используйте текущую версию v3.1:

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

Ответ 401 указывает на проблему с ключом или настройками авторизации. При 429 прочитайте Retry-After и повторите запрос после указанной задержки.

REST API и лимиты запросов

На 10 сентября 2026 года текущая версия REST API — v3.1 по адресу https://backend.composio.dev/api/v3.1. Версия v3 остаётся поддерживаемой предыдущей версией и использует закреплённые версии тулкитов по умолчанию.

В v3.1 для пяти endpoint инструментов без явного параметра версии выбирается актуальная версия тулкита: GET /tools, GET /tools/{tool_slug}, POST /tools/execute/{tool_slug}, POST /tools/execute/{tool_slug}/input и POST /tools/scopes/required. Последний endpoint доступен только в v3.1. В v3 без параметра версии используется закреплённая версия 00000000_00.

Лимит применяется ко всей организации в фиксированном минутном окне. Справочник лимитов описывает общий бюджет для выполнения инструментов, connected accounts, триггеров и остальных аутентифицированных endpoint.

Для существующих интеграций v3 в переданном справочнике указаны такие значения:

Для v3.1 перед расчётом бюджета сверяйте текущую страницу лимитов: числовая таблица выше относится к справочнику предыдущей v3 и полезна прежде всего для существующих интеграций.

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

Полезные сценарии

Ассистент для почты и задач

Задача: разобрать новые письма и создать задачи. Условие запуска: в каталоге есть нужные операции Gmail и трекера, а у пользователя подключены соответствующие аккаунты. Агент находит инструменты, проходит авторизацию при необходимости и выполняет действия в одной сессии. Наблюдаемый результат — созданные задачи в трекере.

Ограничение: сценарий требует подходящих операций и разрешений; если сервис или нужное действие отсутствуют в каталоге, сначала выберите другой способ интеграции.

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

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

Ограничение: до разработки проверьте наличие нужных операций и полей в каталоге Composio. Без них сценарий потребует собственного API-слоя или другого инструмента.

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

Задача: разобрать большую таблицу или почтовую выгрузку. Агент помещает данные в /mnt/files/, обрабатывает их в песочнице и вызывает инструменты пачками. Наблюдаемый результат — подготовленный файл или выполненная серия операций в целевом сервисе.

Ограничение: песочница подходит для объёмной и многошаговой работы, но создаёт отдельные расходы по действующей тарифной сетке; для одной небольшой операции она может быть избыточной.

MCP для внешнего клиента

Задача: дать внешнему MCP-клиенту доступ к инструментам сессии. Приложение создаёт сессию с mcp: true и передаёт клиенту URL вместе с заголовками. При direct-tools preset клиент видит только явно разрешённые инструменты. Наблюдаемый результат — инструменты появляются в клиенте и выполняют выбранное действие.

Ограничение: MCP не передаёт локальные пользовательские инструменты и обходит SDK-хуки вокруг вызовов. Для перехвата или изменения вызовов используйте нативные инструменты через провайдер.

Тарифы на 10 сентября 2026 года

Новая сетка действует для регистраций с 15 августа 2026 года. Клиенты, зарегистрированные раньше, сохраняют прежний план до 31 декабря 2026 года. Платные premium tools применяются ко всем клиентам с 10 сентября 2026 года.

Базовая ставка перерасхода на Pro для вызовов через собственное приложение, API-ключ или MCP составляет $0,0003 за вызов инструмента и $0,003 за событие триггера после включённых объёмов. Неиспользованный ежемесячный кредит не переносится.

Для собственного приложения, API-ключа или MCP доступен полный бесплатный объём. Вызовы через Composio-managed apps используют до 20 000 из 100 000 бесплатных вызовов, после чего применяется отдельная ставка. Для таких приложений бесплатно до 1 000 подключённых аккаунтов; на платном плане сверх этого указана цена $0,10 за аккаунт.

Некоторые возможности оплачиваются как дополнения:

Premium tools, использующие размещённые Composio учётные данные для платных сторонних провайдеров, тарифицируются по стоимости провайдера с комиссией платформы 5%. Инструменты, работающие с собственными учётными данными провайдера, оплачиваются только как обычные вызовы инструментов Composio. Перед внедрением сверяйте расчёт с актуальной страницей тарифов и панелью своего проекта.

Ограничения и когда выбрать другой подход

• Каталог широк, но покрытие API у разных тулкитов неодинаково. Сначала найдите конкретные операции в каталоге.
• Сессия, размещённый MCP и песочница работают через инфраструктуру Composio. Требования к изоляции, хранению и собственным ключам нужно согласовать до работы с регулируемыми данными.
• Лимит запросов общий для организации, поэтому один интенсивный процесс может повлиять на остальные интеграции.
• MCP обходит локальные хуки SDK и не передаёт размещённому серверу инструменты, работающие только внутри вашего процесса.
• Тариф зависит от способа авторизации и выполнения: сессия, direct execution, managed app, proxy и sandbox считаются по-разному.

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

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

Ссылки

• 🌐 Сайт: composio.dev
• 📖 Документация: docs.composio.dev
• 🔌 Сессии через MCP: docs.composio.dev/docs/sessions-via-mcp
• 🧪 Удалённая песочница: docs.composio.dev/docs/sandbox/remote
• 📋 Лимиты API v3.1: docs.composio.dev/reference/rate-limits.md
• 📋 Лимиты API v3, предыдущая версия: docs.composio.dev/reference/v3/rate-limits
• 🔧 Каталог тулкитов: composio.dev/toolkits
• 💰 Тарифы: composio.dev/pricing
• 🐙 GitHub: github.com/ComposioHQ/composio

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

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

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

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