CubeLabs

1. Introducción a Composio

Composio (ComposioHQ/composio) es un SDK open-source que actúa como puente entre los modelos de lenguaje (LLMs) y las herramientas del mundo real. Su propuesta de valor es clara: "Skills that evolve for your Agents" — habilidades que evolucionan para tus agentes.

En lugar de tener que escribir integraciones manuales para cada API (Gmail, GitHub, Slack, Google Sheets, Notion, Jira...), Composio te proporciona un catálogo unificado de más de 1.000 toolkits listos para usar. Cada toolkit expone acciones que tu agente puede invocar directamente.

2. Instalación y Configuración

Composio ofrece SDKs en Python y TypeScript. Aquí veremos ambas opciones.

Python (recomendado para empezar)

pip install composio

Para usar con OpenAI Agents:

pip install composio_openai_agents openai-agents

TypeScript

npm install @composio/core

Para OpenAI Agents en TS:

npm install @composio/openai-agents @openai/agents

Configuración de API Key

Composio requiere una API key para gestionar la autenticación con los servicios externos. Obtén tu key en app.composio.dev y configúrala:

export COMPOSIO_API_KEY=tu_api_key_aqui

Inicialización básica:

from composio import Composio

composio = Composio(
    # api_key="tu-api-key"  # opcional si tienes la variable de entorno
)

Verificación de instalación

python3 -c "from composio import Composio; print('Composio OK')"

3. Conceptos Fundamentales: Tools, Toolkits y Actions

Composio organiza su ecosistema en tres niveles:

El flujo típico es:

1. Seleccionas qué toolkits necesitas
2. Obtienes las tools (acciones convertidas al formato del framework)
3. Pasas las tools a tu agente de IA
4. El agente invoca las acciones automáticamente según las instrucciones

# Obtener tools de un toolkit específico
tools = composio.tools.get(
    user_id="usuario@ejemplo.com",
    toolkits=["HACKERNEWS"]
)

4. Primer Agente con OpenAI Agents (Python)

Construyamos un agente que consulta las últimas noticias de HackerNews usando Composio y OpenAI Agents.

pip install composio_openai_agents openai-agents

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

composio = Composio(provider=OpenAIAgentsProvider())
user_id = "user@acme.org"
tools = composio.tools.get(
    user_id=user_id,
    toolkits=["HACKERNEWS"]
)

agent = Agent(
    name="Hackernews Assistant",
    instructions="Eres un asistente experto en HackerNews.",
    tools=tools,
)

async def main():
    result = await Runner.run(
        starting_agent=agent,
        input="¿Cuál es el último post de HackerNews?"
    )
    print(result.final_output)

asyncio.run(main())

5. Toolkits Populares: GitHub, Gmail, Slack, Notion

Composio incluye toolkits para los servicios más utilizados. Veamos cómo usar los principales:

GitHub — Gestión de repositorios y PRs

tools = composio.tools.get(
    user_id=user_id,
    toolkits=["GITHUB"]
)
# El agente podrá listar issues, crear PRs, revisar código, etc.

Gmail — Envío y lectura de correos

tools = composio.tools.get(
    user_id=user_id,
    toolkits=["GMAIL"]
)

Slack — Mensajería de equipo

tools = composio.tools.get(
    user_id=user_id,
    toolkits=["SLACK"]
)

Notion — Bases de conocimiento

tools = composio.tools.get(
    user_id=user_id,
    toolkits=["NOTION"]
)

6. Autenticación y Connected Accounts

Uno de los puntos fuertes de Composio es su sistema centralizado de autenticación. Cada conexión con un servicio externo se gestiona como una Connected Account.

Autenticación vía API Key

Algunos servicios (como HackerNews) no requieren autenticación adicional. Otros, como Gmail o GitHub, necesitan OAuth.

Usando el cliente Composio para autenticación

from composio import Composio, App

composio = Composio()

composio.get_redirect_url(
    app=App.GMAIL,
    user_id="usuario@ejemplo.com"
)
# Devuelve una URL de OAuth para autenticar

Verificar cuentas conectadas

connected = composio.connected_accounts.get(
    user_id="usuario@ejemplo.com"
)
print(connected)

7. Composio con Anthropic y LangChain

Composio no se limita a OpenAI Agents. Veamos cómo integrarlo con otros frameworks populares.

Con Anthropic (Claude)

pip install composio_anthropic anthropic

from composio import Composio
from composio_anthropic import AnthropicProvider
from anthropic import Anthropic

composio = Composio(provider=AnthropicProvider())
tools = composio.tools.get(
    user_id=user_id,
    toolkits=["GITHUB"]
)

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Lista mis PRs abiertos"}]
)

Con LangChain

pip install composio_langchain langchain

from composio import Composio
from composio_langchain import ComposioToolSet

toolset = ComposioToolSet()
tools = toolset.get_tools(
    user_id=user_id,
    toolkits=["SLACK", "GMAIL"]
)

# Usar con cualquier agente de LangChain

8. Agentes Multi-Herramienta y Workflows

El verdadero poder de Composio emerge cuando combinas múltiples toolkits en un mismo agente.

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

composio = Composio(provider=OpenAIAgentsProvider())

tools = composio.tools.get(
    user_id="dev@acme.org",
    toolkits=["GITHUB", "GMAIL", "SLACK", "GOOGLESHEETS"]
)

agent = Agent(
    name="DevOps Assistant",
    instructions="""Eres un asistente de DevOps.
Puedes:
- Revisar PRs y issues en GitHub
- Enviar correos con resúmenes vía Gmail
- Notificar en Slack cuando algo requiere atención
- Registrar métricas en Google Sheets""",
    tools=tools,
)

async def main():
    result = await Runner.run(
        starting_agent=agent,
        input="Revisa los PRs abiertos, haz un resumen, envíalo por correo al equipo y notifica en Slack"
    )
    print(result.final_output)

asyncio.run(main())

9. Composio con CrewAI y AutoGen

Composio también se integra con frameworks multi-agente como CrewAI y AutoGen.

Con CrewAI

pip install composio_crewai crewai

from composio_crewai import ComposioToolSet
from crewai import Agent, Crew

toolset = ComposioToolSet()
github_tools = toolset.get_tools(
    user_id=user_id,
    toolkits=["GITHUB"]
)
slack_tools = toolset.get_tools(
    user_id=user_id,
    toolkits=["SLACK"]
)

dev_agent = Agent(
    role="Developer",
    goal="Revisar y gestionar PRs",
    tools=github_tools
)
notifier = Agent(
    role="Notifier",
    goal="Comunicar novedades al equipo",
    tools=slack_tools
)

crew = Crew(agents=[dev_agent, notifier], tasks=[...])

Con AutoGen

pip install composio_autogen pyautogen

from composio_autogen import ComposioToolSet

toolset = ComposioToolSet()
tools = toolset.get_tools(
    user_id=user_id,
    toolkits=["HACKERNEWS", "GITHUB"]
)

10. Buenas Prácticas y Despliegue en Producción

Al llevar agentes de Composio a producción, considera estos aspectos:

Seguridad y manejo de claves

• Nunca hardcodees API keys — usa variables de entorno o un gestor de secretos
• Usa connected accounts para centralizar la autenticación OAuth
• Scopes mínimos — solo solicita los permisos que realmente necesita tu agente

Manejo de errores y rate limits

try:
    tools = composio.tools.get(user_id=user_id, toolkits=["GITHUB"])
except Exception as e:
    print(f"Error: {e}")
    # Reintentos con backoff exponencial

Optimización de costes

• Cachea respuestas de APIs que no cambian frecuentemente
• Selecciona solo los toolkits necesarios
• Usa simulaciones antes de ejecutar acciones destructivas