Ваш AI-агент умеет думать, но не умеет ничего делать. Может написать письмо — но не отправить. Создать задачу — но не положить её в Jira. Проанализировать PR — но не оставить комментарий в GitHub. Composio даёт агенту «руки» для работы с реальными сервисами.
Что это
Composio — developer-first платформа, которая подключает AI-агента к внешним сервисам: Gmail, Slack, GitHub, Notion, Linear, Jira, Salesforce и ещё более 1 000 тулкитов из коробки. Вместо того чтобы писать интеграции для каждого API вручную, вы подключаете Composio и получаете единый интерфейс. Агент сам находит нужные инструменты, авторизует пользователя и выполняет действия — всё через один SDK.
Зачем нужно
- Подключить агента к 1000+ сервисам без написания отдельной интеграции под каждый API.
- Управлять авторизацией централизованно: OAuth 2.0, API-ключи, Bearer-токены с refresh — без ручной возни.
- Использовать мета-инструменты вместо загрузки сотен tool-определений в контекст — экономия контекстного окна.
- Работать с любым AI-фреймворком: OpenAI, Anthropic, Gemini, LangChain, CrewAI, Vercel AI SDK, Mastra.
- Реагировать на события (новый email, новый PR, сообщение в Slack) через триггеры.
Как устроено
Архитектура Composio строится вокруг трёх концепций: сессии, мета-инструменты и авторизация.
Сессии
Каждый вызов composio.create(user_id) создаёт сессию — контекст, привязанный к конкретному пользователю. Сессия хранит:
- User ID — чьи credentials использовать.
- Доступные тулкиты — все по умолчанию или ограниченный набор.
- Auth-конфигурацию — какие connected accounts задействовать.
Сессии иммутабельны: если контекст меняется — создавайте новую.
Мета-инструменты
Вместо загрузки сотен tool-схем в контекст, Composio предоставляет набор мета-инструментов:
- COMPOSIO_SEARCH_TOOLS — поиск инструментов по описанию задачи.
- COMPOSIO_GET_TOOL_SCHEMAS — получение схем найденных инструментов.
- COMPOSIO_MANAGE_CONNECTIONS — управление авторизацией.
- COMPOSIO_MULTI_EXECUTE_TOOL — выполнение инструментов с credentials пользователя.
- COMPOSIO_REMOTE_WORKBENCH — Python-песочница для обработки данных.
Агент не получает сотни определений разом — он сначала ищет нужный инструмент, потом запрашивает его схему и только потом вызывает. Это экономит контекстное окно и снижает вероятность ошибок.
Авторизация
Когда инструменту нужен доступ к сервису, агент генерирует Connect Link — страницу, где пользователь подтверждает авторизацию. После этого credentials сохраняются и работают во всех будущих сессиях.
На практике: вы просите агента создать issue в GitHub, он отвечает «нужно подключить GitHub, авторизуйтесь здесь», вы кликаете — и дальше всё работает без дополнительных шагов.
Когда использовать
Таблица «ситуация → подходит / не подходит»:
| Ситуация | Подходит? | Почему |
|---|---|---|
| Агент должен работать с Gmail / Slack / Notion / Linear / GitHub | Да | Все эти сервисы встроены в платформу, авторизация управляется автоматически. |
| Нужен MCP-сервер для Claude Desktop или Cursor | Да | Один MCP-эндпоинт для всех тулкитов, без отдельных пакетов. |
| Агент работает с большими объёмами данных, обработка в контексте не лезет | Да | Remote Workbench — удалённая Python-песочница для тяжёлых операций. |
| Нужна реакция на события (новый email, PR, сообщение) | Да | Триггеры поддерживаются из коробки. |
| Нужен только один конкретный API без гибкости | Нет | Прямой SDK конкретного сервиса будет проще и дешевле. |
| 20 000 вызовов в месяц хватит на production | Нет | Бесплатного тарифа хватит только на прототипирование; для серьёзной нагрузки — $29/мес. |
Пример
Быстрый старт: Native Tools (Python + OpenAI Agents).
pip install python-dotenv composio composio-openai-agents openai-agentsAPI-ключи: COMPOSIO_API_KEY в настройках Composio, OPENAI_API_KEY в OpenAI.
from dotenv import load_dotenv
from composio import Composio
from agents import Agent, Runner
from composio_openai_agents import OpenAIAgentsProvider
load_dotenv()
composio = Composio(provider=OpenAIAgentsProvider())
session = composio.create(user_id="user_123")
tools = session.tools()
agent = Agent(
name="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 — для Claude Desktop, Cursor и других MCP-клиентов.
from composio import Composio
composio = Composio()
session = composio.create(user_id="user_123")
mcp_url = session.mcp.url
mcp_headers = session.mcp.headersДостаточно передать session.mcp.url и session.mcp.headers — никаких дополнительных пакетов не нужно.
Поддерживаемые фреймворки
| Фреймворк | Python | TypeScript |
|---|---|---|
| OpenAI Agents | Да | Да |
| Claude Agent SDK | Да | Да |
| Google Gemini | Да | Да |
| LangChain / LangGraph | Да | Да |
| Vercel AI SDK | Нет | Да |
| CrewAI | Да | Нет |
| LlamaIndex | Да | Да |
| Mastra | Нет | Да |
Ограничения
| Ограничение | Пояснение |
|---|---|
| Бесплатный тариф — 20 000 tool calls в месяц, чего хватит только на прототипирование. | Для production-нагрузок нужен платный план. |
| Rate limits — Free — 1 000 вызовов/час, Paid — до 100 000 вызовов/час. | На пиковых нагрузках может стать узким местом. |
| Сессии иммутабельны | при смене контекста нужно создавать новую, а не модифицировать существующую. |
| Не все фреймворки поддерживаются в обоих языках | Vercel AI SDK и Mastra — только TypeScript, CrewAI — только Python. |
| Сторонние тулкиты зависят от качества обёрток | перед критичной интеграцией проверяйте описание инструмента. |
| При высокой нагрузке стоимость выходит за пределы бесплатного тарифа быстро | учитывайте в планировании затрат. |
Антипаттерны
| Антипаттерн | Почему опасно |
|---|---|
| Не делать — модифицировать сессию после создания. | Сессия иммутабельна, изменения приведут к ошибкам авторизации. |
| Не делать — загружать все 1000+ тулкитов в контекст сразу. | Используйте COMPOSIO_SEARCH_TOOLS — агент сам найдёт нужные. |
| Не делать — использовать бесплатный тариф для production. | 20 000 вызовов — это прототипирование, не боевая нагрузка. |
| Не делать — подключать Composio ради одного-единственного сервиса. | Прямой SDK конкретного API будет проще и дешевле. |
Чеклист
| Проверка | Что сделать |
|---|---|
| COMPOSIO_API_KEY получен, OPENAI_API_KEY (или ключ другого провайдера) тоже настроен | composio + провайдер для выбранного фреймворка. |
| Сессия создаётся с реальным user_id, туллкиты ограничены только нужными сервисами | пользователь подтвердил авторизацию в нужных сервисах. |
| COMPOSIO_SEARCH_TOOLS используется для динамического поиска, а не жёстко прописанные tool-схемы | |
| Объём вызовов оценён по сценарию, выбран подходящий тариф (Free / Ridiculously Cheap / Serious Business) | |
| Remote Workbench подключён, если в сценарии есть обработка больших объёмов данных | |
| Triggers настроены для событийных сценариев (новый email / PR / сообщение в Slack) |