Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add python custom tools references
Dhawal Upadhyay06abd13c370e
diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdxindex de9dfde0f..b10bbb230 100644--- a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx@@ -227,13 +227,13 @@ For more best practices, see [How to Build Tools for AI Agents: A Field Guide](hUse `session.customTools()` / `session.customToolkits()` in TypeScript or `session.custom_tools()` / `session.custom_toolkits()` in Python to list registered tools and toolkits. Registered tool slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.-Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python SDK Reference](/reference/sdk-reference/python)+Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)## Programmatic executionUse `session.execute()` to run custom tools directly, outside of an agent loop (e.g. `session.execute("GET_USER_PROFILE")`). Custom tools execute in-process; remote tools are sent to the backend automatically.-Reference: [Tool Router API Reference](/reference/api-reference/tool-router) · [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python SDK Reference](/reference/sdk-reference/python)+Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)## SessionContext@@ -262,4 +262,4 @@ Every custom tool's `execute` function receives `(input, ctx)`. The `ctx` objectIn Python, `parameters` dictionaries accept both `in` and `type`; this guide uses `in` to match the TypeScript examples.-Reference: [TypeScript SessionContextImpl](/reference/sdk-reference/typescript/session-context-impl) · [Python SDK Reference](/reference/sdk-reference/python)+Reference: [TypeScript SessionContextImpl](/reference/sdk-reference/typescript/session-context-impl) · [Python SessionContextImpl](/reference/sdk-reference/python/session-context-impl)diff --git a/docs/content/reference/sdk-reference/python/index.mdx b/docs/content/reference/sdk-reference/python/index.mdxindex dd26dc36e..afba64b9d 100644--- a/docs/content/reference/sdk-reference/python/index.mdx+++ b/docs/content/reference/sdk-reference/python/index.mdx@@ -30,6 +30,8 @@ uv add composio| [`ConnectedAccounts`](/reference/sdk-reference/python/connected-accounts) | Manage connected accounts. This class is used to manage connected accounts in t... || [`AuthConfigs`](/reference/sdk-reference/python/auth-configs) | Manage authentication configurations. || [`MCP`](/reference/sdk-reference/python/mcp) | MCP (Model Control Protocol) class. Provides enhanced MCP server operations Thi... |+| [`ToolRouterSession`](/reference/sdk-reference/python/tool-router-session) | Tool router session containing session information and methods. Generic Paramet... |+| [`SessionContextImpl`](/reference/sdk-reference/python/session-context-impl) | Concrete implementation of SessionContext. One instance is created per session ... |## Quick Startdiff --git a/docs/content/reference/sdk-reference/python/meta.json b/docs/content/reference/sdk-reference/python/meta.jsonindex afc5ea0c3..10db45dcd 100644--- a/docs/content/reference/sdk-reference/python/meta.json+++ b/docs/content/reference/sdk-reference/python/meta.json@@ -7,6 +7,8 @@"triggers","connected-accounts","auth-configs",- "mcp"+ "mcp",+ "tool-router-session",+ "session-context-impl"]}\ No newline at end of filediff --git a/docs/content/reference/sdk-reference/python/session-context-impl.mdx b/docs/content/reference/sdk-reference/python/session-context-impl.mdxnew file mode 100644index 000000000..59d90b1da--- /dev/null+++ b/docs/content/reference/sdk-reference/python/session-context-impl.mdx@@ -0,0 +1,53 @@+---+title: SessionContextImpl+description: Concrete implementation of SessionContext. One instance is created per session (singleton) and shared across all custom tool invocations. When ``c...+---++## Methods++### execute()++Execute any tool from within a custom tool. Routes to sibling local tools in-process when available, otherwise delegates to the backend API. Returns the same response model as ``session.execute()``.++```python+def execute(tool_slug: str, arguments: Dict[str, Any]) -> SessionExecuteResponse+```++**Parameters**++| Name | Type |+|------|------|+| `tool_slug` | `str` |+| `arguments` | `Dict[str, Any]` |++**Returns**++`SessionExecuteResponse`++---++### proxy_execute()++Proxy API calls through Composio's auth layer. Returns the same response model as ``session.proxy_execute()``.++```python+def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> SessionProxyExecuteResponse+```++**Parameters**++| Name | Type |+|------|------|+| `toolkit` | `str` |+| `endpoint` | `str` |+| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |+| `body?` | `Any` |+| `parameters?` | `List[Dict[str, Any \| None]]` |++**Returns**++`SessionProxyExecuteResponse`++---++[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/session_context.py#L87)diff --git a/docs/content/reference/sdk-reference/python/tool-router-session.mdx b/docs/content/reference/sdk-reference/python/tool-router-session.mdxnew file mode 100644index 000000000..a3db0598f--- /dev/null+++ b/docs/content/reference/sdk-reference/python/tool-router-session.mdx@@ -0,0 +1,165 @@+---+title: ToolRouterSession+description: "Tool router session containing session information and methods. Generic Parameters: TTool: The individual tool type returned by the provider. TToo..."+---++## 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.++```python+def tools(modifiers: 'Modifiers' | None = ...) -> TToolCollection+```++**Parameters**++| Name | Type |+|------|------|+| `modifiers?` | `'Modifiers' \| None` |++**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.++```python+def authorize(toolkit: str, callback_url: str | None = ...) -> ConnectionRequest+```++**Parameters**++| Name | Type |+|------|------|+| `toolkit` | `str` |+| `callback_url?` | `str \| None` |++**Returns**++`ConnectionRequest`++---++### toolkits()++Get toolkit connection states for the session.++```python+def toolkits(toolkits: List[str | None] = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...)+```++**Parameters**++| Name | Type |+|------|------|+| `toolkits?` | `List[str \| None]` |+| `next_cursor?` | `str \| None` |+| `limit?` | `int \| None` |+| `is_connected?` | `bool \| None` |+| `search?` | `str \| None` |++---++### search()++Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.++```python+def search(query: str, model: str | None = ...)+```++**Parameters**++| Name | Type |+|------|------|+| `query` | `str` |+| `model?` | `str \| None` |++---++### execute()++Execute a tool within the session. For custom tools, accepts the original slug (e.g. "GREP") or the full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process; remote tools are sent to the Composio backend. Both paths return a ``SessionExecuteResponse`` with ``data``, ``error``, and ``log_id`` attributes.++```python+def execute(tool_slug: str, arguments: Dict[str, Any | None] = ...) -> SessionExecuteResponse+```++**Parameters**++| Name | Type |+|------|------|+| `tool_slug` | `str` |+| `arguments?` | `Dict[str, Any \| None]` |++**Returns**++`SessionExecuteResponse`++---++### custom_tools()++List all custom tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.++```python+def custom_tools(toolkit: str | None = ...) -> List[RegisteredCustomTool]+```++**Parameters**++| Name | Type |+|------|------|+| `toolkit?` | `str \| None` |++**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.++```python+def custom_toolkits() -> List[RegisteredCustomToolkit]+```++**Returns**++`List[RegisteredCustomToolkit]`++---++### proxy_execute()++Proxy an API call through Composio's auth layer.++```python+def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> SessionProxyExecuteResponse+```++**Parameters**++| Name | Type |+|------|------|+| `toolkit` | `str` |+| `endpoint` | `str` |+| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |+| `body?` | `Any` |+| `parameters?` | `List[Dict[str, Any \| None]]` |++**Returns**++`SessionProxyExecuteResponse` — Proxied API response++---++[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py#L47)diff --git a/python/scripts/generate-docs.py b/python/scripts/generate-docs.pyindex 86e686d37..6d04a457f 100644--- a/python/scripts/generate-docs.py+++ b/python/scripts/generate-docs.py@@ -52,6 +52,13 @@ EXPECTED_CLASSES = {"MCP": "mcp",}+# Additional public-facing classes worth documenting even though they are not+# exposed as direct properties on ``Composio``.+ADDITIONAL_CLASSES = {+ "ToolRouterSession": "core.models.tool_router_session",+ "SessionContextImpl": "core.models.session_context",+}+# Modules to search for classesCLASS_MODULES = ["core.models.tools",@@ -491,6 +498,27 @@ def main():except (KeyError, AttributeError):continue+ # Add standalone public-facing classes that are not surfaced via a direct+ # ``composio.<property>`` access pattern.+ for class_name, module_name in ADDITIONAL_CLASSES.items():+ try:+ parts = module_name.split(".")+ current = package+ for part in parts:+ current = current.members[part]++ if class_name in current.members:+ cls = current.members[class_name]+ if isinstance(cls, griffe.Class):+ classes_to_doc[class_name] = {+ "cls": cls,+ "access": None,+ "prop": None,+ }+ print(f" Found {class_name}")+ except (KeyError, AttributeError):+ continue+# Generate docs for each classdocumented_classes = []