Sessions and tools for your agent

A session scopes an agent to one user, the toolkits it may use and their connections. session.tools() returns tools in your provider's format.

composio = Composio(allow_tracking=False)
session = composio.create(user_id="cust_7f3a", toolkits=["github", "gmail"])
tools = session.tools()

response = client.chat.completions.create(model="gpt-4.1-mini", messages=messages, tools=tools)
results = composio.provider.handle_tool_calls(session=session, response=response)

import inspect

from composio import Composio

composio = Composio(api_key="not-a-real-key", allow_tracking=False)
parameters = inspect.signature(composio.create).parameters
print([name for name in parameters][:8])
print(type(composio.provider).__name__)

create takes the user_id and optional limits: which toolkits and tools, which auth_configs and connected_accounts to use, and whether the agent may start connections itself with manage_connections. The default provider is OpenAIProvider, so tools is a list in OpenAI's function format, and composio.provider.handle_tool_calls runs the calls in an OpenAI response. Packages such as composio-anthropic, composio-langchain and composio-crewai format the same tools for their frameworks.

Meta tools

A session does not hand the model hundreds of app tools. By default it gives a few meta tools that search for the right app tool, start a connection if the user has none, and execute it, all at run time. toolkits and tools on create limit what those meta tools can reach, so for a customer deployment, list only the toolkits the task needs.

Reusing a session

session_id = session.session_id          # store with the conversation
session = composio.use(session_id)        # later, in another request