Session

Properties

Methods

tools()

Get provider-wrapped tools for execution with your AI framework. Returns tools configured for this session, wrapped in the format expected by your AI provider (OpenAI, Anthropic, LangChain, etc.). When custom tools are bound to the session, execution of COMPOSIO_MULTI_EXECUTE_TOOL is intercepted: local tools are executed in-process, remote tools are sent to the backend.

def tools(modifiers: 'Modifiers' | None = ...) -> TToolCollection

Parameters

Returns

TToolCollection

authorize()

Authorize a toolkit for the user and get a connection request. Initiates the OAuth flow and returns a ConnectionRequest with redirect URL.

def authorize(toolkit: str, callback_url: str | None = ..., alias: str | None = ..., experimental: session_link_params.Experimental | None = ...) -> ConnectionRequest

Parameters

Returns

ConnectionRequest

toolkits()

Get toolkit connection states for the session.

def toolkits(toolkits: List[str | None] = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails

Parameters

Returns

ToolkitConnectionsDetails

search()

Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.

def search(query: str, model: str | None = ...) -> SessionSearchResponse

Parameters

Returns

SessionSearchResponse

execute()

Execute a tool within the session. For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the original slug (e.g. "GREP") when that original slug is unique across the session's custom tools and toolkits. Custom tools are executed in-process; remote tools are sent to the Composio backend.

def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str | None = ...) -> ToolRouterSessionExecuteResponse

Parameters

Returns

ToolRouterSessionExecuteResponse

custom_tools()

List all custom tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.

def custom_tools(toolkit: str | None = ...) -> List[RegisteredCustomTool]

Parameters

Returns

List[RegisteredCustomTool] — Array of registered custom tools

custom_toolkits()

List all custom toolkits registered in this session. Returns toolkits with their tools showing final slugs.

def custom_toolkits() -> List[RegisteredCustomToolkit]

Returns

List[RegisteredCustomToolkit]

proxy_execute()

Proxy an API call through Composio's auth layer.

def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> ToolRouterSessionProxyExecuteResponse

Parameters

Returns

ToolRouterSessionProxyExecuteResponse — Proxied API response

update()

Partially update the session configuration. Only the fields provided are changed; omitted fields are preserved. For each policy block None removes the stored override (which can increase access: toolkits=None restores the unrestricted default, while toolkits={"enable": []} denies every app toolkit and is sent as-is). Supplied tools, auth_configs and connected_accounts maps replace the stored map entirely. Inside manage_connections, callback_url=None removes only the stored callback URL. Experimental premium_usage accepts False to disable billed access or an object to set its filters; it does not accept None. Any object, even one that only sets return_premium_charge, re-enables premium usage on a Session set to False. By default the request carries no precondition: the last writer wins. Pass expected_config_version (for example this object's config_version) to make the update conditional: the API then applies it only when the stored version still matches, and a concurrent change raises SessionConfigConflictError (HTTP 409) instead of being overwritten. The API must support the expected_config_version field; otherwise it rejects the request with a 400. expected_config_version=False is the same as omitting it. The PATCH is never retried by the transport, so a 409 is reported exactly once. On conflict this object stays unchanged: re-fetch the session with composio.sessions.use(session_id) and retry against the fresh config_version. config, config_version and preload are refreshed in place only after a successful response, and the updated config is returned. workbench is a backwards-compatible alias for sandbox. Prefer sandbox in new code. All other parameters use the same types as the generated client.tool_router.session.patch() method.

def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ..., premium_usage: Union[Literal[False], ToolRouterPremiumUsageConfig, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools | None], 'Omit'] = ..., tags: Union[session_patch_params.Tags | None, 'Omit'] = ..., auth_configs: Union[Dict[str, str | None], 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str | None]], 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | None, ToolRouterUpdateManageConnectionsConfig | None, 'Omit'] = ..., sandbox: Union[session_patch_params.Workbench | None, 'Omit'] = ..., workbench: Union[session_patch_params.Workbench | None, 'Omit'] = ..., multi_account: Union[session_patch_params.MultiAccount | None, ToolRouterUpdateMultiAccountConfig | None, 'Omit'] = ..., preload: Union[session_patch_params.Preload | None, 'Omit'] = ..., search: Union[session_patch_params.Search | None, 'Omit'] = ..., execute: Union[session_patch_params.Execute | None, 'Omit'] = ..., experimental: Union[session_patch_params.Experimental | None, ToolRouterUpdateExperimentalConfig | None, 'Omit'] = ..., expected_config_version: Union[int, None, Literal[False]] = ...) -> ToolRouterSessionConfig

Parameters

Returns

ToolRouterSessionConfig

list_config_history()

List the configuration history of this session, newest first. Every update() records a new config version; this returns those versions with cursor-based pagination.

def list_config_history(query: session_config_history_params.SessionConfigHistoryParams = ...) -> session_config_history_response.SessionConfigHistoryResponse

Parameters

Returns

session_config_history_response.SessionConfigHistoryResponse — The config versions under .items plus pagination fields.

Example

history = session.list_config_history(limit=10)
for entry in history.items:
    print(entry.version, entry.is_current)

delete()

Delete this session. Deleted sessions immediately stop being retrievable or executable. An already-deleted session surfaces the backend 404.

def delete() -> ToolRouterSessionDeleteResponse

Returns

ToolRouterSessionDeleteResponse

View source